.. This file is part of everyapp.bootstrap.
.. Copyright (C) 2010-2012 Krys Lawrence
..
.. everyapp.bootstrap is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by the
.. Free Software Foundation, either version 3 of the License, or (at your
.. option) any later version.
..
.. everyapp.bootstrap is distributed in the hope that it will be useful, but
.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.. or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
.. more details.
..
.. You should have received a copy of the GNU General Public License along with
.. this program.  If not, see <http://www.gnu.org/licenses/>.

.. index:: bootstrap.py, usage; bootstrap.py
.. _bootstrap.py:

bootstrap.py
============

.. only:: not man

   This |file| provides detailed usage information for the |bootstrap.py|
   command.

.. index::
   pair: bootstrap.py; synopsis

Synopsis
--------

python |bootstrap.py| [OPTIONS]

.. index::
   pair: bootstrap.py; description

Description
-----------

|bootstrap.py| is an enhanced virtualenv_ bootstrap script generated by the
|mkbootstrap| command.  The script creates a virtualenv_ environment, installs
additional packages and runs additional commands, as configured, in order to
set up a development environment for the project to which it belongs.

Additional packages can be installed using either pip_, easy_install_ or both.
The list of packages to install, any customized command-line option defaults
and the list of additional post-install commands to run are all configured in a
related configuration file, usually called |bootstrap.cfg|.

.. index::
   pair: bootstrap.py; options

Options
-------

|bootstrap.py| accepts several command-line options that are described below.
Most of the options are the same as virtualenv_ itself or a standard
virtualenv_ bootstrap script, but some have been replaced, modified or added to
enhance behaviour.

.. NOTE::

   All the options below can also be set in |bootstrap.cfg|.

.. only:: latex

   .. WARNING::

      The long versions of the options below should be prefixed by two
      hyphens (``--``) not one.  The PDF version of this documentation does not
      render the double hyphens correctly.

Standard virtualenv Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following options are unchanged from their normal virtualenv_ behaviour.

.. option:: --version

   This option tells |bootstrap.py| to just show program's version and then
   exit.

.. option:: -h, --help

   This option tells |bootstrap.py| to just show program usage information and
   then exit.  It lists all the options described here along with simple
   descriptions.

.. option:: -v, --verbose

   Increase the verbosity of program output.  This is the opposite of the |-q|
   option.  The more times this option is repeated, the higher the verbosity
   level.

   .. NOTE::

      The verbosity level is not currently passed on to pip_ or easy_install_.

.. option:: -q, --quiet

   Decrease verbosity of the program output.  This is the opposite of the |-v|
   option.  The more times this option is repeated, the lower the verbosity
   level.

   .. NOTE::

      The verbosity level is not currently passed on to pip_ or easy_install_.

.. option:: -p PYTHON_EXE, --python PYTHON_EXE

   Use this options to specify the Python_ interpreter to use, e.g.,
   ``--python=python2.5`` will use the |python2.5| interpreter to create the
   new environment.  The default is the interpreter used to run |bootstrap.py|.

.. option:: --clear

   Use this option to clear out the |lib| directory of any files from previous
   runs of |bootstrap.py|.

   .. NOTE::

      According to the virtualenv_ source code, this option does not clear out
      the |bin| or any other directories, however, despite what is implied by
      the message provided by in |--help| option.

.. option:: --system-site-packages

   By default virtualenv_ configures the virtual environment to not include
   access to the system's global |site-packages| directory.  Use this option to
   reverse that choice and give access to the global |site-packages| directory
   to the virtual environment.

.. option:: --relocatable

   Use this option to make an **EXISTING** virtualenv_ environment relocatable.
   This option fixes up scripts and makes all ``.pth`` files, making paths
   relative.

   .. NOTE::

      Do not use this option the first time running |bootstrap.py|.  Call
      |bootstrap.py| a second time with this option, to achieve the desired
      result.

   .. WARNING::

      The authors of *everyapp.bootstrap* have not tried using this option in
      the context of |bootstrap.py|.  YMMV_.

.. option:: --extra-search-dir SEARCH_DIRS

   This options sets the directory in which to look for
   setuptools_/distribute_/pip_ distributions. You can add any number of
   additional :option:`--extra-search-dir` paths.  By default the latest
   distributions are downloaded from PyPI_.

.. option:: --never-download

   Force virtualenv_ to never download anything from the network.  Instead,
   it will fail if local distributions of setuptools_/distribute_/pip_ are not
   present.  You can combine this option with the :option:`--extra-search-dir`
   to set the location of the local distributions to install.

.. option:: --prompt PROMPT

   Use this option to give an alternative prompt prefix for tghe virtual
   environment.

Customized Options
^^^^^^^^^^^^^^^^^^

The following options have been added or customized by *everyapp.bootstrap* to
replace some virtualenv_ options and add additional functionality.

.. option:: --setuptools

   This is the opposite of the virtualenv_ ``--distribute`` option.  By default
   |bootstrap.py| enables the ``--distribute`` option, which tells virtualenv_
   to install distribute_ instead of setuptools_ in the virtual environment.
   Use this option to reverse that choice so that setuptools_ is installed
   instead.

.. option:: --zip-setuptools

   This is the opposite of the virtualenv_ ``--unzip-setuptools`` option.  By
   default |bootstrap.py| enables the ``--unzip-setuptools`` option, which
   tells virtualenv_ to unzip the distribute_ or setuptools_ EGG_ in
   |site-packages| instead of leaving it as a compressed EGG_ file.  Use this
   option to reverse that choice so that distribute_ or setuptools_ is left
   compressed.

.. option:: --pip-install-options OPTIONS

   |bootstrap.py| can be configured to install additional packages using pip_.
   Use this option to set additional command line options for the
   ``pip install`` command. (Default is ``""``.)  Set this to the string of
   options just as you would give on the command-line.

.. option:: --easy_install-options OPTIONS

   |bootstrap.py| can be configured to install additional packages using
   easy_install_.  Use this option to set additional command line options for
   the ``easy_install`` command. (Default is ``"-Z"``, which tells
   easy_install_ to always unzip EGG_ files.)  Set this to the string of
   options just as you would give on the command-line.

.. index::
   pair: bootstrap.py; examples

Examples
--------

The simplest and most common usage is to just run |bootstrap.py| after a fresh
checkout/clone of a project, in it's root directory.  For example::

  cd /path/to/project/root
  python bootstrap.py

This will create the virtualenv_ environment in the project root (i.e. the
current directory), install additional packages and run additional commands, as
configured, necessary to set up the development environment for the project.

.. index::
   pair: bootstrap.py; output

Output
------

Running |bootstrap.py| will result in output in several phases.  They are:

1. Indication that a configuration file was found.
2. The normal output from virtualenv_ creating the virtual environment.
3. A list of the packages that will be installed using pip_.
4. The normal output of pip_ installing the packages.
5. A list of the packages that will be installed using easy_install_.
6. The normal output of easy_install_ installing the packages.
7. Indication that post-setup commands will be run.
8. The normal output from running all the commands in sequence.

.. index::
   pair: bootstrap.py; files
   pair: bootstrap.py; directories

Files and Directories
---------------------

|bootstrap.cfg|
  The configuration file for |bootstrap.py|
|bin| **or** |Scripts|
  The directory created by virtualenv_ for commands and executables.
|lib/pythonX.Y| **or** |Lib|
  The directory created by virtualenv_ for Python_'s standard library.
|lib/pythonX.Y/site-packages| **or** |Lib\site-packages|
  The directory created by virtualenv_ for the virtual environment's local
  packages.
|lib64|
  A symlink_ created by virtualenv_ on 64-bit |POSIX| systems that points to
  the above-mentioned |lib| directory.

.. index::
   pair: bootstrap.py; environment variables

Environment Variables
---------------------

Since |bootstrap.py| is basically a customized version of virtualenv_, it uses
all the same environment variables that are used by virtualenv_.

.. SEEALSO::

   The `virtualenv documentation`_ for details.

.. index::
   pair: bootstrap.py; exit status

Exit Status
-----------

0
  Successful program execution
1
  Operational error
2
  Error parsing command-line options
3
  * Attempt to run virtualenv_ in an (obsolete) *workingenv* environment, or
  * Using a home directory that contains a space on Windows and not having
    pywin32_ installed, or
  * The Python_ executable specified with |--python| does not exist
100
  Error running Python_ interpreter due to it's ``sys.prefix`` value not being
  what is expected
101
  Attempt to run under a Python_ version less than 2.3
200
  Error parsing the configuration file

.. NOTE::

   Other exit codes are possible as they can come from sub-processes like
   installing distribute_, etc.

.. .. index::
..    pair: bootstrap.py; notes
..
.. Notes
.. -----
..
.. (None.)

.. .. index::
..    pair: bootstrap.py; history
..
.. History
.. -------
..
.. (None.)

.. bottom

.. .. index::
..    pair: bootstrap.py; acknowledgements
..
.. Acknowledgements
.. ----------------
..
.. (See THANKS.txt.)
