diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/install.rst | 86 |
1 files changed, 49 insertions, 37 deletions
diff --git a/docs/narr/install.rst b/docs/narr/install.rst index b9c5fe6f7..c9452c597 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -14,15 +14,18 @@ under any version of Python before 2.4, and does *not* run under Python 3.X. .. warning:: To succesfully install :mod:`repoze.bfg`, you will need - an environment capable of compiling C code. See the documentation - about installing, e.g. ``gcc`` for your system. Additionally, the - Python development libraries for your Python version will need to - be installed and the ``lixbml2`` and ``libxslt`` development - libraries will need to be installed. These requirements are often - satisfied by installing the ``python-devel``, ``libxml2-devel`` and - ``libxslt-devel`` packages into your system. You will also need - :term:`setuptools` installed on within your Python system in order - to run the ``easy_install`` command. + an environment capable of compiling C code (e.g. ``XCode Tools`` + will need to be installed if you're using MacOS X, and ``gcc`` and + other build tools will need to be installed if you're using other + UNIXlike systems). See the system's documentation about installing + this software. Additionally, the Python development libraries for + your Python version will need to be installed and the ``lixbml2`` + and ``libxslt`` development libraries will need to be installed. + These requirements are often satisfied by installing the + ``python-devel``, ``libxml2-devel`` and ``libxslt-devel`` packages + into your system. You will also need :term:`setuptools` installed + on within your Python system in order to run the ``easy_install`` + command. At the time of this writing, ``repoze.bfg`` will not install on Windows systems unless you have development tools (e.g. *Visual C++*) @@ -36,8 +39,8 @@ installed. maillist <http://lists.repoze.org/listinfo/repoze-dev>`_ if you'd like to try to tackle the job of compilation and maintenance. -Creating a Virtualenv ---------------------- +Installing :mod:`repoze.bfg` +---------------------------- It is advisable to install :mod:`repoze.bfg` into a :term:`virtualenv` in order to obtain isolation from any "system" packages you've got @@ -72,34 +75,35 @@ setuptools for installation. To install setuptools by hand, first download `ez_setup.py <http://peak.telecommunity.com/dist/ez_setup.py>`_ then invoke it -using the Python interpreter you want to install setuptools into (you -may need to be the administrative user on your system to do so, -depending on the file permissions of your Python files). +using the Python interpreter you want to install setuptools into. .. code-block:: bash $ python ez_setup.py Once this command is invoked, setuptools should be installed on your -system. +system. If the command fails due to permission errors, you may need +to be the administrative user on your system to successfully invoke +the script. -Installing The ``virtualenv`` Package -------------------------------------- +Installing the ``virtualenv`` Package +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once you've got setuptools installed, you should install -:term:`virtualenv`. This is a package that creates a "virtual" Python -interpreter. Software installed into this interpreter will not -pollute the parent Python, which is useful for evaluation and -sandboxing. To install the :term:`virtualenv` package into your -setuptools-enabled Python interpreter, use the ``easy_install`` -command. +Once you've got setuptools installed, you should install the +:term:`virtualenv` package. To install the :term:`virtualenv` package +into your setuptools-enabled Python interpreter, use the +``easy_install`` command. .. code-block:: bash $ easy_install virtualenv -Creating a Virtual Python Environment -------------------------------------- +This command should succeed, and tell you that the virtualenv package +is now installed. If it fails due to permission errors, you may need +to install it as your system's administrative user. + +Creating the Virtual Python Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Once the :term:`virtualenv` package is installed in your Python, you can actually create a virtual environment. To do so, invoke the @@ -125,7 +129,7 @@ You should perform any following commands that mention a "bin" directory from within the ``bfgenv`` virtualenv dir. Installing :mod:`repoze.bfg` Into the Virtual Python Environment ----------------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After you've got your ``bfgenv`` virtualenv installed, you may install :mod:`repoze.bfg` itself using the following commands from within the @@ -141,8 +145,24 @@ virtualenv (``bfgenv``) directory: required. :mod:`repoze.bfg` software is maintained in its own index; :mod:`repoze.bfg` cannot be installed from PyPI. +This command will take longer than the previous ones to complete, as it +compiles a number of dependencies. + +What Gets Installed +~~~~~~~~~~~~~~~~~~~ + +When you ``easy_install`` :mod:`repoze.bfg`, various Zope libraries, +WebOb, Paste, PasteScript, and PasteDeploy libraries are installed. + +Additionally, as shown in the next section, PasteScript (aka *paster*) +templates will be registered that make it easy to start a new +:mod:`repoze.bfg` project. + +Troubleshooting +--------------- + If ``lxml`` Fails to Compile During ``easy_install`` ----------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the installation of :mod:`repoze.bfg` fails due to problems compiling ``lxml``, you should try installing ``lxml`` before @@ -155,7 +175,7 @@ Once that completes, you can start a subsequent ``easy_install`` of :mod:`repoze.bfg` as per the instructions above; it should then work. If You Can't Install Via ``easy_install`` (Alternate Installation) ------------------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you can't get :mod:`repoze.bfg` installed using ``easy_install`` because ``lxml`` fails to compile on your system, you can try the @@ -167,13 +187,5 @@ instead of your system packages, as version incompatibilities between system packages and ``lxml`` versions are typically to blame for compilation problems. -What Gets Installed -------------------- - -When you ``easy_install`` :mod:`repoze.bfg`, various Zope libraries, -WebOb, Paste, PasteScript, and PasteDeploy libraries are installed. -Additionally, as shown in the next section, PasteScript (aka *paster*) -templates will be registered that make it easy to start a new -:mod:`repoze.bfg` project. |