A minimal example would be to have a buildout.cfg as follows:
[buildout]
extensions = buildout-versions
parts =
Since no versions have been pinned in a versions section, when the buildout is run the output would indicate those versions that were picked:
$ bin/buildout
Versions had to be automatically picked.
The following part definition lists the versions picked:
[versions]
buildout-versions = 1.2
setuptools = 0.6c11
zc.buildout = 1.5.0
That output can be used to update the buildout.cfg:
[buildout]
extensions = buildout-versions
versions = versions
parts =
[versions]
buildout-versions = 1.2
setuptools = 0.6c11
zc.buildout = 1.5.0
Now, when the buildout is run, there will be no output:
$ bin/buildout
If you want to make sure that a buildout is only run with a specific version of python, then you can specify this in the versions section:
[buildout]
extensions = buildout-versions
versions = versions
parts =
[versions]
python = 2.6
buildout-versions = 1.2
setuptools = 0.6c11
zc.buildout = 1.5.0
This check is a substring check of the value specified, so you can be as specific as you want. If you need a bug fix that appeared in Python 2.6.2, you could specify python as 2.6.1. If you need Enthought’s python distribution, you could specify python as EPD 7.1-2.
The following buildout.cfg contains a python version that doesn’t match the python used to run the buildout:
[buildout]
extensions = buildout-versions
versions = versions
parts =
[versions]
python = 1.0
buildout-versions = 1.2
setuptools = 0.6c11
zc.buildout = 1.5.0
When this file is used, buildout will fail with an error:
$ bin/buildout
While:
Installing.
Loading extensions.
Error: python version specified not found in sys.version: 1.0
Packages being developed will never be considered as unpinned. Take the following buildout.cfg as an example:
[buildout]
extensions = buildout-versions
develop = sample_package
parts =
When the buildout is run, sample_package will not be reported:
$ bin/buildout
Develop: '.../sample_package'
Versions had to be automatically picked.
The following part definition lists the versions picked:
[versions]
buildout-versions = 1.2
setuptools = 0.6c11
zc.buildout = 1.5.0
A buildout.cfg may specify a package-a and pin it’s version, as in the following example:
[buildout]
extensions = buildout-versions
find-links = <our index>
parts = sample
versions = versions
[versions]
buildout-versions = 1.2
package-a = 1.0
setuptools = 0.6c11
zc.buildout = 1.5.0
zc.recipe.egg = 1.2.0
[sample]
recipe = zc.recipe.egg
eggs = package-a
However, package-a may depend on package-b, which isn’t pinned. When run, Buildout Versions will point this out and give an explanation of what package depends on it:
$ bin/buildout
Installing sample.
Getting distribution for 'package-a==1.0'.
Got package-a 1.0.
Getting distribution for 'package-b'.
Got package-b 2.0.
Versions had to be automatically picked.
The following part definition lists the versions picked:
[versions]
# Required by:
# package-a==1.0
package-b = 2.0
It can be convenient to separate out the pinned versions into their own file. Buildout Versions supports this by allowing a file to which version information will be written to be specified in the buildout_versions_file option of the [buildout] section:
[buildout]
extensions = buildout-versions
buildout_versions_file = versions.cfg
find-links = <our index>
parts = sample
[sample]
recipe = zc.recipe.egg
eggs = package-a
When the above buildout is run, output is still written to the console:
$ bin/buildout
Installing sample.
Versions had to be automatically picked.
The following part definition lists the versions picked:
[versions]
buildout-versions = 1.2
package-a = 1.0
setuptools = 0.6c11
zc.buildout = 1.5.0b2
zc.recipe.egg = 1.2.3b2
# Required by:
# package-a==1.0
package-b = 2.0
This information has been written to 'versions.cfg'
However, the details of packages that weren’t pinned will also be written to versions.cfg, which will contain:
[versions]
buildout-versions = 1.2
package-a = 1.0
setuptools = 0.6c11
zc.buildout = 1.5.0b2
zc.recipe.egg = 1.2.3b2
# Required by:
# package-a==1.0
package-b = 2.0
The resulting versions.cfg can then be used in the buildout as follows:
[buildout]
extensions = buildout-versions
buildout_versions_file = versions.cfg
extends = versions.cfg
versions = versions
find-links = <our index>
parts = sample
[sample]
recipe = zc.recipe.egg
eggs = package-a
Since all the package versions are pinned, running this buildout will result in no output:
$ bin/buildout
Installing sample.
A common way of working is to have multiple files containing version specifications layered on top of each other. For example, the versions.cfg above might look like:
[buildout]
extends = base_versions.cfg
[versions]
package-a = 1.0
The example doesn’t pin package-a, so when the buildout is run, there will be output:
$ bin/buildout
Installing sample.
Versions had to be automatically picked.
The following part definition lists the versions picked:
[versions]
# Required by:
# package-a==1.0
package-b = 2.0
This information has been written to 'versions.cfg'
Buildout Versions will also append the missing version to versions.cfg, resulting in it containing the following:
[buildout]
extends = base_versions.cfg
[versions]
package-a = 1.0
# Added by Buildout Versions at 2010-07-30 15:44:45.023559
# Required by:
# package-a==1.0
package-b = 2.0
Setuptools, which Buildout uses for its package management, is agnostic to the capitalisation of distributions. Buildout, however, is case sensitive when it pins versions. Buildout Versions fixes this problem.
For example, if PackageC depends on PackageD, but expresses this dependency as packaged, Buildout would normally ignore any version pins specified for PackageD, even though a version fo PackageD would be successfully installed.
So, with a buildout.cfg as follows:
[buildout]
find-links = <our index>
parts = sample
versions = versions
[versions]
PackageC = 3.0
PackageD = 4.0
[sample]
recipe = zc.recipe.egg
eggs = PackageC
Buildout will pick the wrong version of PackageD:
$ bin/buildout
Installing sample.
Getting distribution for 'PackageC==3.0'.
Got PackageC 3.0.
Getting distribution for 'packaged'.
Got PackageD 5.0.
The buildout.cfg should be changed to use Buildout Versions as follows:
[buildout]
extensions = buildout_versions
find-links = <our index>
parts = sample
versions = versions
[versions]
buildout-versions = 1.2
setuptools = 0.6c11
zc.buildout = 1.5.0
zc.recipe.egg = 1.2.0
PackageC = 3.0
PackageD = 4.0
[sample]
recipe = zc.recipe.egg
eggs = PackageC
Now, the correct version of PackageD will be used:
$ bin/buildout
Installing sample.
Getting distribution for 'packaged==4.0'.
Got PackageD 4.0.