Buildout command line, default settings and extending configurations
Command-line options
Buildout command-line:
- command-line options and option setting
- command and arguments
bin/buildout -U -c rpm.cfg install zrs
Option settings are of the form:
section:option=value
Any option you can set in the configuration file, you can set on the command-line. Option settings specified on the command line override settings read from configuration files.
There are a few command-line options, like -c to specify a configuration file, or -U to disable reading user defaults.
See the buildout documentation, or use the -h option to get a list of available options.
Buildout modes
- newest
- default mode always tries to get newest versions
- Turn off with -N or buildout newest option set to false.
- offline
- If enabled, then don't try to do network access
- Disabled by default
- If enabled, turn off with -o or buildout offline option set to false.
By default, buildout always tries to find the newest distributions that match requirements. Looking for new distributions can be very time consuming. Many people will want to specify the -N option to disable this. We'll see later how we can change this default behavior.
If you aren't connected to a network, you'll want to use the offline mode, -o.
~/.buildout/default.cfg
Provides default buildout settings (unless -U option is used):
[buildout] # Shared eggs directory: eggs-directory = /home/jim/.eggs # Newest mode off, reenable with -n newst = false [python24] executabe = /usr/local/python/2.4/bin/python [python25] executabe = /usr/local/python/2.5/bin/python
Unless the -U command-line option is used, user default settings are read before reading regular configuration files. The user defaults are read from the default.cfg file in the .buildout subdirectory of the directory specified in the HOME environment variable, if any.
In this example:
- I set up a shared eggs directory.
- I changed the default mode to non-newest so that buildout doesn't look for new distributions if the distributions it has meet it's requirements. To get the newest distributions, I'll have to use the -n option.
- I've specified Python 2.4 and 2.5 sections that specify locations of Python interpreters. Sometimes, a buildout uses multiple versions of Python. Many recipes accept a python option that specifies the name of a section with an executable option specifying the location of a Python interpreter.
Extending configurations
The extends option allows one configuration file to extend another.
For example:
base.cfg has common definitions and settings
dev.cfg adds development-time options:
[buildout] extends = base.cfg ...
rpm.cfg has options for generating an RPM packages from a buildout.
Bootstrapping from existing buildout
- The buildout script has a bootstrap command
- Can use it to bootstrap any directory.
- Much faster than running bootstrap.py because it can use an already installed setuptools egg.
Example: ~/bin directory
[buildout] parts = rst2 buildout24 buildout25 bin-directory = . [rst2] recipe = zc.recipe.egg eggs = zc.rst2 [buildout24] recipe = zc.recipe.egg eggs = zc.buildout scripts = buildout=buildout24 python = python24 [buildout25] recipe = zc.recipe.egg eggs = zc.buildout scripts = buildout=buildout25 python = python25
Many people have a personal scripts directory.
I've converted mine to a buildout using a buildout configuration like the one above.
I've overridden the bin-directory location so that scripts are installed directly into the buildout directory.
I've specified that I want the zc.rst2 distribution installed. The rst2 distribution has a generalized version of the restructured text processing scripts in a form that can be installed by buildout (or easy_install).
I've specified that I want buildout scripts for Python 2.4 and 2.5. (In my buildout, I also create one for Python 2.3.) These buildout scripts allow me to quickly bootstrap buildouts or to run setup files for a given version of python. For example, to bootstrap a buildout with Python 2.4, I'll run:
buildout24 bootstrap
in the directory containing the buildout. This can also be used to convert a directory to a buildout, creating a buildout.cfg file is it doesn't exist.
