.. This file is part of everyapp.bootstrap.
.. Copyright (C) 2010 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.cfg, usage; bootstrap.cfg
.. _bootstrap.cfg:

bootstrap.cfg
=============

.. only:: not man

   This |file| provides detailed usage information for the |bootstrap.cfg|
   configuration file.

.. .. index::
..    pair: bootstrap.cfg; synopsis
..
.. Synopsis
.. --------
..
.. (N/A.)

.. index::
   pair: bootstrap.cfg; description

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

|bootstrap.cfg| is the configuration file used by the |bootstrap.py| script to
customize it's behaviour when creating a virtualenv_ environment for a project.
A default |bootstrap.cfg| is generated, along with the |bootstrap.py| script,
by the |mkbootstrap| command.

|bootstrap.cfg| allows one to do the following:

* Customize the default values of the command-line arguments to |bootstrap.py|,
* List additional Python_ distributions to be installed using pip_ and/or
  easy_install_, and
* List additional commands to execute once everything else has been set up.

The |bootstrap.cfg| file is an |ASCII| text file, similar in format to INI_
files in that it is separated into sections in the form of ``[section_name]``.
Each section, however, can require a different line format and is not
necessarily restricted to a set of ``key=value`` pairs.

.. only:: not man

   The full default generated |bootstrap.cfg| text can be read in
   |../everyapp/bootstrap/bootstrap.cfg|.

.. index::
   pair: bootstrap.cfg; sections

Sections
--------

Each section of the configuration file is described separately below:

[options]
^^^^^^^^^

In this section, one can override the default values of the command-line
options that |bootstrap.py| accepts.  The accepted options and their default
values are listed below.

The format for this section is ``key = value`` pairs, one pair per line.

**verbose = 0**
  This option corresponds to the |--verbose| command-line argument.  A higher
  values means more detailed output.
**quiet = 0**
  This option corresponds to the |--quiet| command-line argument.  A higher
  value means less detailed output.
**python =**
  This option corresponds to the |--python| command-line argument.
**clear = False**
  This option corresponds to the |--clear| command-line argument.  Set to it
  ``True`` to enable the option.
**prompt =**
  This option corresponds to the |--prompt| command-line argument.
**global_site_packages = False**
  This option corresponds to the |--global-site-packages| command-line
  argument.  Set it to ``True`` to enable the option.
**use_setuptools = False**
  This option corresponds to the |--setuptools| command-line argument.  Set it
  to ``True`` to enable the option.
**zip_setuptools = False**
  This option corresponds to the |--zip-setuptools| command-line argument.  Set
  it to ``True`` to enable the option.
**pip_install_options =**
  This option corresponds to the |--pip-install-options| command-line argument.
**easy_install_options = -Z**
  This option corresponds to the |--easy_install-options| command-line
  argument.

.. SEEALSO:: The |bootstrap.py| script documentation for more information on
   the specific purpose of each option.

.. NOTE:: Hyphens (``-``) in option names on the command-line are replaced with
   underscores (``_``) internally.  Use underscores in |bootstrap.cfg| as well.

[pip]
^^^^^

In this section, one can list any additional Python_ distributions to
install automatically in the virtual environment using pip_.  These would
normally only be the distributions needed for development support, not the
dependencies of the project itself (which would go in |setup.py|).

The format for this section is one distribution per line, each specified either
in :pep:`314`/:pep:`345` format using parentheses or in pip_-compatible format
without parentheses.  For example::

  pep8 (>=0.5,!=0.5.2,<0.6)

or::

  pep8>=0.5,!=0.5.2,<0.6

.. NOTE:: Not all distributions are compatible with pip_.  Use the
   ``[easy_install]`` section below for those that are not (or use it for all
   distributions).

[easy_install]
^^^^^^^^^^^^^^

In this section, like in the ``[pip]`` section above, one can list any
additional Python_ distributions to install automatically in the virtual
environment.  However, distribution listed in this section will be installed
using easy_install_.  Similarly, these would normally only be the distributions
needed for development support.

The format for this section is the same as that of the ``[pip]`` section above.

[commands]
^^^^^^^^^^

This section lets one automatically execute additional commands after the
virtual environment has been created and all the specified distributions have
been installed.

The format for this section is one command (with any arguments) per line.

.. NOTE:: One can use the ``$bin$`` token to indicate the virtual environment's
   |bin/| directory, which can have a different name on some platforms (e.g.
   |Scripts/| on Windows).  The trailing slash is also included.

For example::

  $bin$python setup.py develop

.. .. index::
..    pair: bootstrap.cfg; examples
..
.. Examples
.. --------
..
.. (None.)

.. .. index::
..    pair: bootstrap.cfg; output
..
.. Output
.. ------
..
.. (None.)

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

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

|bootstrap.cfg|
  The default location and name for the configuration file for |bootstrap.py|,
  relative to the project's root directory.
|etc/bootstrap.cfg|
  A common alternative location and name for the configuration file for
  |bootstrap.py|, relative to the project's root directory.

.. .. index::
..    pair: bootstrap.cfg; environment variables
..
.. Environment Variables
.. ---------------------
..
.. (None.)

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

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

.. bottom

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