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]
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]
setuptools = 0.6c11
zc.buildout = 1.5.0
Now, when the buildout is run, there will be no output:
$ bin/buildout
It’s worth noting that 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]
setuptools = 0.6c11
zc.buildout = 1.5.0
Now, 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]
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]
package-a = 1.0
# Required by:
# package-a==1.0
package-b = 2.0
setuptools = 0.6c11
zc.buildout = 1.5.0b2
zc.recipe.egg = 1.2.3b2
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]
package-a = 1.0
# Required by:
# package-a==1.0
package-b = 2.0
setuptools = 0.6c11
zc.buildout = 1.5.0b2
zc.recipe.egg = 1.2.3b2
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