[Checkins] SVN: zc.buildout/trunk/ Refined documentation.
Jim Fulton
cvs-admin at zope.org
Thu Jun 15 09:53:33 EDT 2006
Log message for revision 68652:
Refined documentation.
Fixed small bug in handling of custom installed.cfg location.
Changed:
U zc.buildout/trunk/README.txt
U zc.buildout/trunk/src/zc/buildout/buildout.py
U zc.buildout/trunk/src/zc/buildout/buildout.txt
U zc.buildout/trunk/todo.txt
-=-
Modified: zc.buildout/trunk/README.txt
===================================================================
--- zc.buildout/trunk/README.txt 2006-06-15 12:13:36 UTC (rev 68651)
+++ zc.buildout/trunk/README.txt 2006-06-15 13:53:30 UTC (rev 68652)
@@ -8,7 +8,7 @@
settings.
The word "buildout" refers to a description of a set of parts and the
-software to create ans assemble them. It is often used informally to
+software to create and assemble them. It is often used informally to
refer to an installed system based on a buildout definition. For
example, if we are creating an application named "Foo", then "the Foo
buildout" is the collection of configuration and application-specific
Modified: zc.buildout/trunk/src/zc/buildout/buildout.py
===================================================================
--- zc.buildout/trunk/src/zc/buildout/buildout.py 2006-06-15 12:13:36 UTC (rev 68651)
+++ zc.buildout/trunk/src/zc/buildout/buildout.py 2006-06-15 13:53:30 UTC (rev 68652)
@@ -119,6 +119,9 @@
if not os.path.exists(d):
os.mkdir(d)
+ options['installed'] = os.path.join(options['directory'],
+ options['installed'])
+
def _dosubs(self, section, option, value, data, converted, seen):
key = section, option
r = converted.get(key)
Modified: zc.buildout/trunk/src/zc/buildout/buildout.txt
===================================================================
--- zc.buildout/trunk/src/zc/buildout/buildout.txt 2006-06-15 12:13:36 UTC (rev 68651)
+++ zc.buildout/trunk/src/zc/buildout/buildout.txt 2006-06-15 13:53:30 UTC (rev 68652)
@@ -1,19 +1,36 @@
-Defining Buildouts
-==================
+Buildouts
+=========
+The word "buildout" refers to a description of a set of parts and the
+software to create and assemble them. It is often used informally to
+refer to an installed system based on a buildout definition. For
+example, if we are creating an application named "Foo", then "the Foo
+buildout" is the collection of configuration and application-specific
+software that allows an instance of the application to be created. We
+may refer to such an instance of the application informally as "a Foo
+buildout".
+
This document describes how to define buildouts using buildout
configuation files and recipes. There are two ways to set up the
-buildout software and create a buildout:
+buildout software and create a buildout instance:
1. Install the zc.buildout egg with easy_install and use the buildout
script installed in a Python scripts area.
-2. Use the buildout bootstrap script to install both the setuptools
- and zc.buildout eggs into your buildout. This allows you to use
- the buildout software without modifying a Python install.
+2. Use the buildout bootstrap script to create a buildout that
+ includes both the setuptools and zc.buildout eggs. This allows you
+ to use the buildout software without modifying a Python install.
The buildout script is installed into your buildout local scripts
area.
+Often, a software project will be managed in a software repository,
+such as a subversion repository, that includes some software source
+directories, buildout configuration files, and a copy of the buildout
+bootstrap script, To work on the project, one would check out the
+project from the repository and run the bootstrap script which
+installs setuptools and zc.buildout into the checkout as well as any
+parts defined.
+
We have a sample buildout that has already been created for us. It
has the absolute minimum information. We have bin, eggs and parts
directories, a configuration file, and an .installed,cfg that contains
@@ -27,20 +44,15 @@
d parts
The bin directory contains scripts. In the examples shown here, we've
-used a hybrid approach for creating the to ease automated setup. We
-have a buildout script in our buildout script directory, but the eggs
-actually live elsewhere.
+used a hybrid approach for creating the buildout to ease automated
+setup. We have a buildout script in our buildout script directory,
+but the zc.buildout and setuptools eggs actually live elsewhere.
>>> ls(sample_buildout, 'bin')
- buildout
>>> ls(sample_buildout, 'eggs')
-Buildouts are defined using configuration files. These are in the
-format defined by the Python ConfigParser module, with an extension
-that we'll describe later. When a buildout is run, it looks for the
-file buildout.cfg in the directory where the buidout is run.
-
The parts directory is initially empty:
>>> ls(sample_buildout, 'parts')
@@ -50,6 +62,19 @@
install it in the part directory. Part data is stored in a
subdirectory of the parts directory with the same name as the part.
+Buildouts are defined using configuration files. These are in the
+format defined by the Python ConfigParser module, with extensions
+that we'll describe later. By default, when a buildout is run, it
+looks for the file buildout.cfg in the directory where the buidout is
+run.
+
+The minimal configuration file has a buildout section that defines no
+parts:
+
+ >>> cat(sample_buildout, 'buildout.cfg')
+ [buildout]
+ parts =
+
The file .installed.cfg contains information about previously installed
parts. Because this is a new buildout, this file isn't very
interesting:
@@ -58,19 +83,12 @@
[buildout]
parts =
-The minimal configuration file has a buildout section that defines no
-parts:
-
- >>> cat(sample_buildout, 'buildout.cfg')
- [buildout]
- parts =
-
A part is simply something to be created by a buildout. It can be
almost anything, such as a Python package, a program, a directory, or
-a confguration file.
+even a confguration file.
A part is created by a recipe. Recipes are always installed as Python
-eggs. They can be downloaded from an package server, such as the
+eggs. They can be downloaded from a package server, such as the
Python Package Index, or they can be developed as part of a project.
Let's create a recipe as part of the sample project. We'll create a
recipe for creating directories.
@@ -115,22 +133,34 @@
section. We normalize the path and save it back into the options
directory.
-**IMPORTANT**: Any time we use data from another section, it is important
-to reflect that data in the recipe options, as this data is used to
-decide if a part configuration has changed and a part needs to be
-reinstalled.
+Any time we use data from another section, it is important to reflect
+that data in the recipe's options when the recipe is constructed.
+When a buildout is run, it compares part-configuration data stored in
+the installed.cfg file and the part-configuration data loaded from the
+configuration files as modified by recipe constructors to decide if
+the configuration of a part has changed. If the configuration has
+changed, or if the recipe has changed, then the part is uninstalled
+before reinstalling it. The buildout only looks at the part's
+options, so any data used to configure the part needs to be reflected
+in the part's options. It is the job of a recipe constructor to make
+sure that the options include all relevent data.
+Of course, parts are also uninstalled if they are no-longer used.
+
The install method is responsible for creating the part. In this
case, we need the path of the directory to create. We'll use a
path option from our options dictionary.
We made the method chatty so that we can observe what it's doing.
+XXX use python logging module!
We return the path that we installed. If the part is unistalled or
reinstalled, then the path returned will be removed by the buildout
machinery. A recipe install method is expected to return None, a
string, or an iterable of strings containing paths to be removed if a
-part is uninstalled.
+part is uninstalled. For most recipes, this is all of the uninstall
+support needed. A recipe can provide custom uninstall support as will
+be described later.
We need to provide packaging information so that our recipe can be
installed as an egg. We need to define a setup script for this:
@@ -145,7 +175,15 @@
... )
... """)
-Here we've defined a package with an entry_point. Entry points provide
+This setup script is incomplete. It doesn't describe what is to be
+included in a distribution. This is fine if we never actually create
+a distribution. If recipes are going to be used only internally in a
+buildout, then we needn't include distribution information. If we
+wanted to use the same recipes in multiple buildouts, then we'd need
+to include proper distribution data. To find out more about creating
+distributions, see the setuptools documentation.
+
+Our setup script defines an entry point. Entry points provide
a way for an egg to define the services it provides. Here we've said
that we define a zc.buildout entry point named default. Recipe
classes must be exposed as entry points in the zc.buildout group. we
@@ -153,7 +191,8 @@
somewhat special because it allows a recipe to be referenced using a
package name without naming an entry point.
-We also need a README.txt for our recipes to avoid a warning:
+We also need a README.txt for our recipes to avoid an annoying warning
+from distutils, on which setuptools and zc.buildout are based:
>>> write(sample_buildout, 'recipes', 'README.txt', " ")
@@ -179,7 +218,7 @@
absolute. If relative, they are treated as relative to the buidlout
directory. They can be directory or file paths. If a file path is
given, it should point to a Python setup script. If a directory path
-is given, it should point to a directory containing a setup.py.
+is given, it should point to a directory containing a setup.py file.
Development eggs are installed before building any parts, as they may
provide locally-defined recipes needed by the parts.
@@ -308,7 +347,8 @@
... """)
We've rearranged the script a bit to make the entry points easier to
-edit.
+edit. In particular, entry points are now defined as a configuration
+string, rather than a dictionary.
Let's update our configuration to provide variable substitution
examples:
@@ -335,12 +375,14 @@
In this example, we've used ConfigParser substitutions for file2 and
file3. This type of substitution uses Python string format syntax.
-Valid names are option in the same section and options defined in the
-DEFAULT section. We used a string-template substitution for file1.
-This type of substituion uses the string.Template syntax. Names
-substited are qualified option names, consisting of a section name and
-option name joined by a colon.
+Valid names are options in the same section and options defined in the
+DEFAULT section.
+We used a string-template substitution for file1. This type of
+substituion uses the string.Template syntax. Names substited are
+qualified option names, consisting of a section name and option name
+joined by a colon.
+
Now, if we run the buildout, we'll see the options with the values
substituted.
@@ -417,7 +459,7 @@
represent a product and the extending buildout might be a
customization.
-Here is a more eleborate example.
+Here is a more elaborate example.
>>> import tempfile
>>> extensions = tempfile.mkdtemp()
@@ -435,7 +477,6 @@
... name = buildout
... """ % dict(e2=os.path.join(extensions, 'e2.cfg')))
-
>>> write(sample_buildout, 'b1.cfg',
... """
... [buildout]
@@ -532,10 +573,11 @@
debug sections in several of the input files by virtue of being in
their DEFAULT sections.
-- Relative file names are determined relative to the directory
- containing the referencing configuration file. The files eb.cfg and
- ee.cfg were found in the extensions directory because they were
- referenced from a file in that directory.
+- Relative file names in extended and extended-by options are
+ interpreted relative to the directory containing the referencing
+ configuration file. The files eb.cfg and ee.cfg were found in the
+ extensions directory because they were referenced from a file in
+ that directory.
User defaults
-------------
@@ -580,25 +622,38 @@
section_name:option_name=value
-for example, as in:
+for example:
+ >>> write(sample_buildout, 'other.cfg',
+ ... """
+ ... [buildout]
+ ... develop = recipes
+ ... parts = debug
+ ... installed = .other.cfg
+ ...
+ ... [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(os.path.join(sample_buildout, 'bin', 'buildout')
- ... + ' debug:op1=foo'),
- name ee
- op buildout
+ ... + ' -c other.cfg debug:op1=foo'),
+ name other
op1 foo
- op2 b1 2
- op3 b2 3
- op4 b2 4
- op5 eb 5
- op6 ee 6
op7 7
recipe recipes:debug
+ >>> os.remove(os.path.join(sample_buildout, 'other.cfg'))
+ >>> os.remove(os.path.join(sample_buildout, '.other.cfg'))
+
Currently, the default and only command is 'install' and it takes a
-list of parts to install. if any parts are specified, then only those
-parts are installed. To illustrate this, we'll update our
-configuration and run the buildout in the usual way:
+list of parts to install. if any parts are specified, then they must
+be listed in the buildout parts option and 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',
... """
@@ -793,8 +848,8 @@
d parts
d recipes
-Alternate directory locations
------------------------------
+Alternate directory and file locations
+--------------------------------------
The buildout normally puts the bin, eggs, and parts directories in the
directory in the directory containing the configuration file. You can
Modified: zc.buildout/trunk/todo.txt
===================================================================
--- zc.buildout/trunk/todo.txt 2006-06-15 12:13:36 UTC (rev 68651)
+++ zc.buildout/trunk/todo.txt 2006-06-15 13:53:30 UTC (rev 68652)
@@ -26,6 +26,16 @@
- Logging
+- Some way to freeze versions so we can have reproducable buildouts.
+
+- Part dependencies
+
+- custom uninstall
+
+- spelling :)
+
+- example using -c. Example redefining .installed.cfg
+
Issues
- Want to be able to control whether eggs get unzipped when they ae
More information about the Checkins
mailing list