Socket timeout
--------------

The timeout of the connections to egg and configuration servers can be
configured in the buildout section. Its value is configured in seconds::

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... socket-timeout = 5
    ... develop = recipes
    ... parts = debug
    ...
    ... [debug]
    ... recipe = recipes:debug
    ... op = timeout
    ... """)

    >>> print_(system(buildout), end='')
    Setting socket time out to 5 seconds.
    Develop: '/sample-buildout/recipes'
    Installing debug.
    op timeout
    recipe recipes:debug

If the ``socket-timeout`` is not numeric, a warning is issued and the default
timeout of the Python socket module is used::

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... socket-timeout = 5s
    ... develop = recipes
    ... parts = debug
    ...
    ... [debug]
    ... recipe = recipes:debug
    ... op = timeout
    ... """)

    >>> print_(system(buildout), end='')
    Default socket timeout is used !
    Value in configuration is not numeric: [5s].
    <BLANKLINE>
    Develop: '/sample-buildout/recipes'
    Updating debug.
    op timeout
    recipe recipes:debug

Uninstall recipes
-----------------

As we've seen, when parts are installed, buildout keeps track of files
and directories that they create. When the parts are uninstalled these
files and directories are deleted.

Sometimes more clean-up is needed. For example, a recipe might add a
system service by calling ``chkconfig --add`` during installation. Later
during uninstallation, ``chkconfig --del`` will need to be called to
remove the system service.

In order to deal with these uninstallation issues, you can register
uninstall recipes. Uninstall recipes are registered using the
``zc.buildout.uninstall`` entry point. Parts specify uninstall recipes
using the ``uninstall`` option.

In comparison to regular recipes, uninstall recipes are much
simpler. They are simply callable objects that accept the name of the
part to be uninstalled and the part's options dictionary. Uninstall
recipes don't have access to the part itself since it may be
impossible to instantiate at uninstallation time.

Here's a recipe that simulates installation of a system service, along
with an uninstall recipe that simulates removing the service::

    >>> write(sample_buildout, 'recipes', 'src', 'service.py',
    ... """
    ... import sys
    ... class Service:
    ...
    ...     def __init__(self, buildout, name, options):
    ...         self.buildout = buildout
    ...         self.name = name
    ...         self.options = options
    ...
    ...     def install(self):
    ...         sys.stdout.write("chkconfig --add %s\\n"
    ...                          % self.options['script'])
    ...         return ()
    ...
    ...     def update(self):
    ...         pass
    ...
    ...
    ... def uninstall_service(name, options):
    ...     sys.stdout.write("chkconfig --del %s\\n" % options['script'])
    ... """)

To use these recipes we must register them using entry points. Make
sure to use the same name for the recipe and uninstall recipe. This is
required to let buildout know which uninstall recipe goes with which
recipe::

    >>> write(sample_buildout, 'recipes', 'setup.py',
    ... """
    ... from setuptools import setup
    ... entry_points = (
    ... '''
    ... [zc.buildout]
    ... mkdir = mkdir:Mkdir
    ... debug = debug:Debug
    ... service = service:Service
    ...
    ... [zc.buildout.uninstall]
    ... service = service:uninstall_service
    ... ''')
    ... setup(name="recipes", entry_points=entry_points)
    ... """)

Here's how these recipes could be used in a buildout::

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... develop = recipes
    ... parts = service
    ...
    ... [service]
    ... recipe = recipes:service
    ... script = /path/to/script
    ... """)

When the buildout is run the service will be installed::

    >>> print_(system(buildout), end='')
    Develop: '/sample-buildout/recipes'
    Uninstalling debug.
    Installing service.
    chkconfig --add /path/to/script

The service has been installed. If the buildout is run again with no
changes, the service shouldn't be changed::

    >>> print_(system(buildout), end='')
    Develop: '/sample-buildout/recipes'
    Updating service.

Now we change the service part to trigger uninstallation and
re-installation::

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... develop = recipes
    ... parts = service
    ...
    ... [service]
    ... recipe = recipes:service
    ... script = /path/to/a/different/script
    ... """)

    >>> print_(system(buildout), end='')
    Develop: '/sample-buildout/recipes'
    Uninstalling service.
    Running uninstall recipe.
    chkconfig --del /path/to/script
    Installing service.
    chkconfig --add /path/to/a/different/script

Now we remove the service part, and add another part::

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... develop = recipes
    ... parts = debug
    ...
    ... [debug]
    ... recipe = recipes:debug
    ... """)

    >>> print_(system(buildout), end='')
    Develop: '/sample-buildout/recipes'
    Uninstalling service.
    Running uninstall recipe.
    chkconfig --del /path/to/a/different/script
    Installing debug.
    recipe recipes:debug

Uninstall recipes don't have to take care of removing all the files
and directories created by the part. This is still done automatically,
following the execution of the uninstall recipe. An upshot is that an
uninstallation recipe can access files and directories created by a
recipe before they are deleted.

For example, here's an uninstallation recipe that simulates backing up
a directory before it is deleted. It is designed to work with the
``mkdir`` recipe introduced earlier::

    >>> write(sample_buildout, 'recipes', 'src', 'backup.py',
    ... """
    ... import os, sys
    ... def backup_directory(name, options):
    ...     path = options['path']
    ...     size = len(os.listdir(path))
    ...     sys.stdout.write("backing up directory %s of size %s\\n"
    ...                      % (path, size))
    ... """)

It must be registered with the ``zc.buildout.uninstall`` entry
point. Notice how it is given the name ``mkdir`` to associate it with
the ``mkdir`` recipe::

    >>> write(sample_buildout, 'recipes', 'setup.py',
    ... """
    ... from setuptools import setup
    ... entry_points = (
    ... '''
    ... [zc.buildout]
    ... mkdir = mkdir:Mkdir
    ... debug = debug:Debug
    ... service = service:Service
    ...
    ... [zc.buildout.uninstall]
    ... uninstall_service = service:uninstall_service
    ... mkdir = backup:backup_directory
    ... ''')
    ... setup(name="recipes", entry_points=entry_points)
    ... """)

Now we can use it with a ``mkdir`` part::

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... develop = recipes
    ... parts = dir debug
    ...
    ... [dir]
    ... recipe = recipes:mkdir
    ... path = my_directory
    ...
    ... [debug]
    ... recipe = recipes:debug
    ... """)

Run the buildout to install the part::

    >>> print_(system(buildout), end='')
    Develop: '/sample-buildout/recipes'
    Uninstalling debug.
    Installing dir.
    dir: Creating directory my_directory
    Installing debug.
    recipe recipes:debug

Now we remove the part from the configuration file::

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... develop = recipes
    ... parts = debug
    ...
    ... [debug]
    ... recipe = recipes:debug
    ... """)

When the buildout is run the part is removed, and the uninstall recipe
is run before the directory is deleted::

    >>> print_(system(buildout), end='')
    Develop: '/sample-buildout/recipes'
    Uninstalling dir.
    Running uninstall recipe.
    backing up directory /sample-buildout/my_directory of size 0
    Updating debug.
    recipe recipes:debug

Now we will return the registration to normal for the benefit of the
rest of the examples::

    >>> write(sample_buildout, 'recipes', 'setup.py',
    ... """
    ... from setuptools import setup
    ... entry_points = (
    ... '''
    ... [zc.buildout]
    ... mkdir = mkdir:Mkdir
    ... debug = debug:Debug
    ... ''')
    ... setup(name="recipes", entry_points=entry_points)
    ... """)


Command-line usage
------------------

A number of arguments can be given on the buildout command line.  The
command usage is::

  buildout [options and assignments] [command [command arguments]]

The following options are supported:

``-h`` (or ``--help``)
    Print basic usage information.  If this option is used, then all
    other options are ignored.

``-c`` filename
    The ``-c`` option can be used to specify a configuration file, rather than
    ``buildout.cfg`` in the current directory.


``-t`` socket_timeout
   Specify the socket timeout in seconds.

``-v``
    Increment the verbosity by 10.  The verbosity is used to adjust
    the logging level.  The verbosity is subtracted from the numeric
    value of the log-level option specified in the configuration file.

``-q``
    Decrement the verbosity by 10.

``-U``
    Don't read user-default configuration.

``-o``
    Run in off-line mode.  This is equivalent to the assignment
    ``buildout:offline=true``.

``-O``
    Run in non-off-line mode.  This is equivalent to the assignment
    ``buildout:offline=false``.  This is the default buildout mode.  The
    ``-O`` option would normally be used to override a true offline
    setting in a configuration file.

``-n``
    Run in newest mode.  This is equivalent to the assignment
    ``buildout:newest=true``.  With this setting, which is the default,
    buildout will try to find the newest versions of distributions
    available that satisfy its requirements.

``-N``
    Run in non-newest mode.  This is equivalent to the assignment
    ``buildout:newest=false``.  With this setting, buildout will not seek
    new distributions if installed distributions satisfy its
    requirements.

Assignments are of the form::

  section_name:option_name=value

or::

  option_name=value

which is equivalent to::

  buildout:option_name=value

Options and assignments can be given in any order.

Here's an example::

    >>> write(sample_buildout, 'other.cfg',
    ... """
    ... [buildout]
    ... develop = recipes
    ... parts = debug
    ... installed = .other.cfg
    ... log-level = WARNING
    ...
    ... [debug]
    ... name = other
    ... recipe = recipes:debug
    ... """)

Note that we used the installed buildout option to specify an
alternate file to store information about installed parts::

    >>> print_(system([buildout, '-c', 'other.cfg', 'debug:op1=foo', '-v']), end='')
    Develop: '/sample-buildout/recipes'
    Installing debug.
    name other
    op1 foo
    recipe recipes:debug

Here we used the ``-c`` option to specify an alternate configuration file,
and the ``-v`` option to increase the level of logging from the default,
*WARNING*.

Options can also be combined in the usual Unix way, as in::

    >>> print_(system([buildout, '-vcother.cfg', 'debug:op1=foo']), end='')
    Develop: '/sample-buildout/recipes'
    Updating debug.
    name other
    op1 foo
    recipe recipes:debug

Here we combined the ``-v`` and ``-c`` options with the configuration file
name.  Note that the ``-c`` option has to be last, because it takes an
argument::

    >>> os.remove(os.path.join(sample_buildout, 'other.cfg'))
    >>> os.remove(os.path.join(sample_buildout, '.other.cfg'))

The most commonly used command is ``install``, and it takes a list of
parts to install. If any parts are specified, only those parts are
installed.  To illustrate this, we'll update our configuration and run
the buildout in the usual way::

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... develop = recipes
    ... parts = debug d1 d2 d3
    ...
    ... [d1]
    ... recipe = recipes:mkdir
    ... path = d1
    ...
    ... [d2]
    ... recipe = recipes:mkdir
    ... path = d2
    ...
    ... [d3]
    ... recipe = recipes:mkdir
    ... path = d3
    ...
    ... [debug]
    ... recipe = recipes:debug
    ... """)

    >>> print_(system(buildout), end='')
    Develop: '/sample-buildout/recipes'
    Uninstalling debug.
    Installing debug.
    recipe recipes:debug
    Installing d1.
    d1: Creating directory d1
    Installing d2.
    d2: Creating directory d2
    Installing d3.
    d3: Creating directory d3

    >>> ls(sample_buildout)
    -  .installed.cfg
    d  bin
    -  buildout.cfg
    d  d1
    d  d2
    d  d3
    d  develop-eggs
    d  eggs
    d  parts
    d  recipes

    >>> cat(sample_buildout, '.installed.cfg')
    ... # doctest: +NORMALIZE_WHITESPACE
    [buildout]
    installed_develop_eggs = /sample-buildout/develop-eggs/recipes.egg-link
    parts = debug d1 d2 d3
    <BLANKLINE>
    [debug]
    __buildout_installed__ =
    __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
    recipe = recipes:debug
    <BLANKLINE>
    [d1]
    __buildout_installed__ = /sample-buildout/d1
    __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
    path = /sample-buildout/d1
    recipe = recipes:mkdir
    <BLANKLINE>
    [d2]
    __buildout_installed__ = /sample-buildout/d2
    __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
    path = /sample-buildout/d2
    recipe = recipes:mkdir
    <BLANKLINE>
    [d3]
    __buildout_installed__ = /sample-buildout/d3
    __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
    path = /sample-buildout/d3
    recipe = recipes:mkdir

Now we'll update our configuration file::

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... develop = recipes
    ... parts = debug d2 d3 d4
    ...
    ... [d2]
    ... recipe = recipes:mkdir
    ... path = data2
    ...
    ... [d3]
    ... recipe = recipes:mkdir
    ... path = data3
    ...
    ... [d4]
    ... recipe = recipes:mkdir
    ... path = ${d2:path}-extra
    ...
    ... [debug]
    ... recipe = recipes:debug
    ... x = 1
    ... """)

and run the buildout specifying just ``d3`` and ``d4``::

    >>> print_(system([buildout, 'install', 'd3', 'd4']), end='')
    Develop: '/sample-buildout/recipes'
    Uninstalling d3.
    Installing d3.
    d3: Creating directory data3
    Installing d4.
    d4: Creating directory data2-extra

    >>> ls(sample_buildout)
    -  .installed.cfg
    d  bin
    -  buildout.cfg
    d  d1
    d  d2
    d  data2-extra
    d  data3
    d  develop-eggs
    d  eggs
    d  parts
    d  recipes

Only the ``d3`` and ``d4`` recipes ran.
``d3`` was removed and ``data3`` and ``data2-extra``
were created.

The ``.installed.cfg`` is only updated for the recipes that ran::

    >>> cat(sample_buildout, '.installed.cfg')
    ... # doctest: +NORMALIZE_WHITESPACE
    [buildout]
    installed_develop_eggs = /sample-buildout/develop-eggs/recipes.egg-link
    parts = debug d1 d2 d3 d4
    <BLANKLINE>
    [debug]
    __buildout_installed__ =
    __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
    recipe = recipes:debug
    <BLANKLINE>
    [d1]
    __buildout_installed__ = /sample-buildout/d1
    __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
    path = /sample-buildout/d1
    recipe = recipes:mkdir
    <BLANKLINE>
    [d2]
    __buildout_installed__ = /sample-buildout/d2
    __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
    path = /sample-buildout/d2
    recipe = recipes:mkdir
    <BLANKLINE>
    [d3]
    __buildout_installed__ = /sample-buildout/data3
    __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
    path = /sample-buildout/data3
    recipe = recipes:mkdir
    <BLANKLINE>
    [d4]
    __buildout_installed__ = /sample-buildout/data2-extra
    __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
    path = /sample-buildout/data2-extra
    recipe = recipes:mkdir

Note that the installed data for ``debug``, ``d1``, and ``d2`` haven't
changed,
because we didn't install those parts, and that the ``d1`` and ``d2``
directories are still there.

Now, if we run the buildout without the install command::

    >>> print_(system(buildout), end='')
    Develop: '/sample-buildout/recipes'
    Uninstalling d2.
    Uninstalling d1.
    Uninstalling debug.
    Installing debug.
    recipe recipes:debug
    x 1
    Installing d2.
    d2: Creating directory data2
    Updating d3.
    Updating d4.

We see the output of the debug recipe, and that ``data2`` was created.  We
also see that ``d1`` and ``d2`` have gone away::

    >>> ls(sample_buildout)
    -  .installed.cfg
    d  bin
    -  buildout.cfg
    d  data2
    d  data2-extra
    d  data3
    d  develop-eggs
    d  eggs
    d  parts
    d  recipes

Alternate directory and file locations
--------------------------------------

The buildout normally puts the ``bin``, ``eggs``, and ``parts`` directories in
the directory containing the configuration file. You can
provide alternate locations, and even names for these directories::

    >>> alt = tmpdir('sample-alt')

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... develop = recipes
    ... parts =
    ... develop-eggs-directory = %(developbasket)s
    ... eggs-directory = %(basket)s
    ... eggs-directory-version = v2
    ... bin-directory = %(scripts)s
    ... parts-directory = %(work)s
    ... """ % dict(
    ...    developbasket = os.path.join(alt, 'developbasket'),
    ...    basket = os.path.join(alt, 'basket'),
    ...    scripts = os.path.join(alt, 'scripts'),
    ...    work = os.path.join(alt, 'work'),
    ... ))

    >>> print_(system(buildout), end='')
    Creating directory '/sample-alt/basket/v2'.
    Creating directory '/sample-alt/scripts'.
    Creating directory '/sample-alt/work'.
    Creating directory '/sample-alt/developbasket'.
    Develop: '/sample-buildout/recipes'
    Uninstalling d4.
    Uninstalling d3.
    Uninstalling d2.
    Uninstalling debug.

    >>> ls(alt)
    d  basket
    d  developbasket
    d  scripts
    d  work

    >>> ls(alt, 'developbasket')
    -  recipes.egg-link

You can also specify an alternate buildout directory::

    >>> rmdir(alt)
    >>> alt = tmpdir('sample-alt')

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... directory = %(alt)s
    ... develop = %(recipes)s
    ... parts =
    ... """ % dict(
    ...    alt=alt,
    ...    recipes=os.path.join(sample_buildout, 'recipes'),
    ...    ))

    >>> print_(system(buildout), end='')
    Creating directory '/sample-alt/eggs/v5'.
    Creating directory '/sample-alt/bin'.
    Creating directory '/sample-alt/parts'.
    Creating directory '/sample-alt/develop-eggs'.
    Develop: '/sample-buildout/recipes'

    >>> ls(alt)
    -  .installed.cfg
    d  bin
    d  develop-eggs
    d  eggs
    d  parts

    >>> ls(alt, 'develop-eggs')
    -  recipes.egg-link

Logging control
---------------

Three buildout options are used to control logging:

``log-level``
   specifies the log level

``verbosity``
   adjusts the log level

``log-format``
   allows an alternate logging format to be specified

We've already seen the log level and verbosity.  Let's look at an example
of changing the format::

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... develop = recipes
    ... parts =
    ... log-level = 25
    ... verbosity = 5
    ... log-format = %(levelname)s %(message)s
    ... """)

Here, we've changed the format to include the log-level name, rather
than the logger name.

We've also illustrated, with a contrived example, that the log level
can be a numeric value and that the verbosity can be specified in the
configuration file.  Because the verbosity is subtracted from the log
level, we get a final log level of 20, which is the *INFO* level::

    >>> print_(system(buildout), end='')
    INFO Develop: '/sample-buildout/recipes'

Predefined buildout options
---------------------------

Buildouts have a number of predefined options that recipes can use
and that users can override in their configuration files.  To see
these, we'll run a minimal buildout configuration with a ``debug`` logging
level.  One of the features of ``debug`` logging is that the configuration
database is shown::

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... parts =
    ... """)

    >>> print_(system([buildout, '-vv']), end='') # doctest: +NORMALIZE_WHITESPACE
    Installing 'zc.buildout', 'wheel', 'pip', 'setuptools'.
    ...
    Configuration data:
    [buildout]
    allow-hosts = *
    allow-picked-versions = true
    allow-unknown-extras = false
    bin-directory = /sample-buildout/bin
    develop-eggs-directory = /sample-buildout/develop-eggs
    directory = /sample-buildout
    eggs-directory = /sample-buildout/eggs/v5
    eggs-directory-version = v5
    executable = python
    find-links =
    install-from-cache = false
    installed = /sample-buildout/.installed.cfg
    log-format =
    log-level = INFO
    newest = true
    offline = false
    parts =
    parts-directory = /sample-buildout/parts
    prefer-final = true
    python = buildout
    show-picked-versions = false
    socket-timeout =
    update-versions-file =
    use-dependency-links = true
    verbosity = 20
    versions = versions
    [versions]
    zc.buildout = >=1.99
    zc.recipe.egg = >=1.99
    <BLANKLINE>

All of these options can be overridden by configuration files or by
command-line assignments.  We've discussed most of these options
already, but let's review them and touch on some we haven't discussed:

``abi-tag-eggs``
    Add an `ABI tag
    <https://www.python.org/dev/peps/pep-0425/#abi-tag>`_ to the
    directory name given by the ``eggs-directory`` option.  This is
    useful when switching between python implementations when details
    of the implementation aren't reflected in egg names.  It also has
    the side benefit of making eggs directories smaller, because eggs
    for different Python versions are in different directories.

``allow-hosts``
    On some environments the links visited by ``zc.buildout`` can be forbidden
    by paranoid firewalls. These URLs might be in the chain of links visited
    by ``zc.buildout`` as defined by buildout's ``find-links`` option, or as
    defined by various eggs in their ``url``, ``download_url``,
    ``dependency_links`` metadata.

    The fact that ``package_index`` works like a spider and might visit links
    and go to other locations makes this even harder.

    The ``allow-hosts`` option provides a way to prevent this, and
    works exactly like the one provided in ``easy_install``.

    You can provide a list of allowed hosts, together with wildcards::

        [buildout]
        ...

        allow-hosts =
            *.python.org
            example.com

    All URLs that do not match these hosts will not be visited.

``allow-picked-versions``
    By default, the buildout will choose the best match for a given
    requirement
    if the requirement is not specified precisely (for instance, using the
    ``versions`` option.  This behavior corresponds to the
    ``allow-picked-versions`` being set to its default value, ``true``.  If
    ``allow-picked-versions`` is ``false``, instead of picking the best match,
    buildout will raise an error.  This helps enforce repeatability.

``bin-directory``
   The directory path where scripts are written.  This can be a
   relative path, which is interpreted relative to the directory
   option.

``develop-eggs-directory``
   The directory path where development egg links are created for software
   being created in the local project.  This can be a relative path,
   which is interpreted relative to the directory option.

``directory``
   The buildout directory.  This is the base for other buildout file
   and directory locations, when relative locations are used.

``eggs-directory``
   The directory path where downloaded eggs are put.  It is common to share
   this directory across buildouts.
   This can be a relative path, which is
   interpreted relative to the directory option.

   .. warning::

     Eggs in this directory should *never* be modified.

``find-links``
    You can specify more locations to search for distributions using the
    ``find-links`` option. All locations specified will be searched for
    distributions along with the package index as described before.

    Locations can be URLs::

      [buildout]
      ...
      find-links = http://download.zope.org/distribution/

    They can also be directories on disk::

      [buildout]
      ...
      find-links = /some/path

    Finally, they can also be direct paths to distributions::

      [buildout]
      ...
      find-links = /some/path/someegg-1.0.0-py2.3.egg

    Any number of locations can be specified in the ``find-links`` option::

      [buildout]
      ...
      find-links =
          http://download.zope.org/distribution/
          /some/otherpath
          /some/path/someegg-1.0.0-py2.3.egg

``install-from-cache``
    A download cache can be used as the basis of application source releases.
    In an application source release, we want to distribute an application
    that
    can be built without making any network accesses.  In this case, we
    distribute a buildout along with a download cache, and tell the buildout
    to install
    from the download cache only, without making network accesses.  The
    buildout ``install-from-cache`` option can be used to signal that packages
    should be installed only from the download cache.

``installed``
   The file path where information about the results of the previous
   buildout run is written.  This can be a relative path, which is
   interpreted relative to the directory option.  This file provides
   an inventory of installed parts with information needed to decide
   which if any parts need to be uninstalled.

``log-format``
   The format used for logging messages.

``log-level``
   The log level before verbosity adjustment

``newest``
    By default buildout and recipes will try to find the newest versions of
    distributions needed to satisfy requirements.  This can be very time
    consuming, especially when incrementally working on setting up a buildout
    or working on a recipe.  The buildout ``newest`` option can be used to to
    suppress this.  If the ``newest`` option is set to false, then new
    distributions won't be sought if an installed distribution meets
    requirements.  The ``newest`` option can also be set to false using the -N
    command-line option.  See also the ``offline`` option.

``offline``
    The ``offline`` option goes a bit further than the ``newest`` option.
    If the
    buildout ``offline`` option is given a value of ``true``, the buildout and
    recipes that are aware of the option will avoid doing network access.
    This
    is handy when running the buildout when not connected to the internet.  It
    also makes buildouts run much faster. This option is typically set using
    the buildout ``-o`` option.

``parts``
   A whitespace-separated list of parts to be installed.

``parts-directory``
   A working directory that parts can used to store data.

``prefer-final``
    Currently, when searching for new releases, the newest available
    release is used.  This isn't usually ideal, as you may get a
    development release or alpha releases not ready to be widely used.
    You can request that final releases be preferred using the
    ``prefer-final`` option in the ``buildout`` section::

      [buildout]
      ...
      prefer-final = true

    When the ``prefer-final`` option is set to ``true``, then when searching
    for
    new releases, final releases are preferred.  If there are final
    releases that satisfy distribution requirements, then those releases
    are used even if newer non-final releases are available.  The buildout
    ``prefer-final`` option can be used to override this behavior.

    In buildout version 2, final releases will be preferred by default.
    You will then need to use a ``false`` value for ``prefer-final`` to get
    the newest releases.

``use-dependency-links``
    By default buildout will obey the setuptools ``dependency_links`` metadata
    when it looks for dependencies. This behavior can be controlled with
    the ``use-dependency-links`` buildout option::

      [buildout]
      ...
      use-dependency-links = false

    The option defaults to ``true``. If you set it to ``false``, then
    dependency links are only looked for in the locations specified by
    ``find-links``.

``verbosity``
   A log-level adjustment.  Typically, this is set via the ``-q`` and ``-v``
   command-line options.
