[pypy-commit] pypy.org extradoc: Document more package.py.

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: extradoc
Changeset: r557:137a96636f8c
Date: 2014-12-24 11:48 +0100
http://bitbucket.org/pypy/pypy.org/changeset/137a96636f8c/

Log:	Document more package.py.

diff --git a/download.html b/download.html
--- a/download.html
+++ b/download.html
@@ -246,6 +246,8 @@
 machine with insufficient RAM!  It will just swap forever.  See
 notes below in that case.)</p>
 </li>
+<li><p class="first">If you want to install this PyPy as root, please read the next section.</p>
+</li>
 </ol>
 <p>Notes:</p>
 <ul>
@@ -282,6 +284,15 @@
 python package.py --help #for information
 python package.py --archive-name pypy-my-own-package-name
 </pre>
+<p>It is recommended to use package.py because custom scripts will
+invariably become out-of-date.  If you want to write custom scripts
+anyway, note an easy-to-miss point: some modules are written with CFFI,
+and require some compilation.  If you install PyPy as root without
+pre-compiling them, normal users will get permission errors.  This means
+you need to run for example <tt class="docutils literal">pypy <span class="pre">-c</span> “import gdbm”</tt> during the
+installation process (see the exact list in <a class="reference external" href="https://bitbucket.org/pypy/pypy/src/default/pypy/tool/release/package.py">package.py</a>).  Users
+seeing a broken installation of PyPy can also fix it after-the-fact, if
+they have sudo rights, by running <tt class="docutils literal">sudo pypy <span class="pre">-c</span> “import gdbm”</tt>.</p>
 </div>
 <div class="section" id="checksums">
 <h1>Checksums</h1>
diff --git a/source/download.txt b/source/download.txt
--- a/source/download.txt
+++ b/source/download.txt
@@ -252,6 +252,8 @@
    machine with insufficient RAM!  It will just swap forever.  See
    notes below in that case.)
 
+6. If you want to install this PyPy as root, please read the next section.
+
 Notes:
 
 * It is recommended to use PyPy to do translations, instead of using CPython,
@@ -297,6 +299,18 @@
     python package.py --help #for information
     python package.py --archive-name pypy-my-own-package-name 
 
+It is recommended to use package.py because custom scripts will
+invariably become out-of-date.  If you want to write custom scripts
+anyway, note an easy-to-miss point: some modules are written with CFFI,
+and require some compilation.  If you install PyPy as root without
+pre-compiling them, normal users will get permission errors.  This means
+you need to run for example ``pypy -c "import gdbm"`` during the
+installation process (see the exact list in `package.py`_).  Users
+seeing a broken installation of PyPy can also fix it after-the-fact, if
+they have sudo rights, by running ``sudo pypy -c "import gdbm"``.
+
+.. _`package.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/tool/release/package.py
+
 Checksums
 ---------