Vertoo User's Guide

Max Ischenko <mfi at>
Last Updated: Wed Aug 6 10:30:37 2003

This documents describes Vertoo architecture, configuration and usage. As the Vertoo is intended for developers, documentation is rather terse and you can find missing information by reading the source code. ;)


To avoid misunderstanding the following small vocabulary is established:

the project you are working on. Includes source code, documentation and other auxillary files.

part of the project with individual versioning scheme. Large or complex projects often release several independant modules, each with it's own versioning scheme. Simple projects typically defines single module, whose version is used as a project version.

Versioning scheme
format of the version (or naming) scheme used to enumerate project's releases. A scheme is consists from a number of components.

Version component
A logical part of the version.

Dependant files
files that must be updated by Vertoo when module's version is changed.

Design and architecture

A central notion in Vertoo is version. Project is viewed as one or more modules each of them having it's own version. Along with version, each module contains a list of files which would be updated by the Vertoo and optional SCM configuration if you going to use some SCM system like CVS.

Version is defined as an ordered list of components, or version parts. A part has value (like 2 or pre1) and type. Currently, only two types are supported: basic and missing. You could change part's value with Vertoo commands set and set-part.

Basic type could store number or arbitrary string value. If value is a number then you could increment it. "Missing" type is supposed to be used as a placeholder for part which has no value now but may have had a value later. For example, suppose you release versions 1.1, 1.2, etc. but when a critical bug is fixed you could release version 1.2.1. To describe this configuration you could define part "release" of type "missing".

Vertoo also supports part's dependencies. This means that you can declare, for example: "reset minor part when major is incremented" or "reset build part when any part is incremented". Dependencies are described in your configuration file.


Configuration is specified with two files:, with current version information, and vertoo.config which describes project's modules, their versioning schemes and dependent files.

At the beginning you must create these two files by hand. Afterwards, file would be automatically updated by Vertoo and file vertoo.config does not need changes at all. Unless, of course, you want to make changes to your project's configuration. Then you'll need to update one or both of these files again.

Version formatting

When you describe your project's configuration there is a number of places that requires a version template that is evaluated at run-time for particular version string. It's semantic is similar to the ubiquitous printf, albeit a bit more complex due to conditinals and recursive expansions.

The following text sequences have the special meaning in the template:

All other text is left unchanged. Currently version template is used in these places: Note about schemes: scheme is just a predefined version template. you could register your own scheme with registry.registerScheme and refer to them inside a template by @name syntax.

This file contains current values of the version's components for each of the project module.

Empty lines and lines starting with # are ignored. Each non-empty line must have the following format:

  <module-name> = <part-name>:<part-value>; [<part-name>:<part-value>;]+

Module name and part names are case insensitive while part's values are case sensitive. Any number of whitespace characters are allowed around = sign and between parts. Note, however that whitespace (if any) between : and ; are considered to be a part of the <part-value>.

A part value x or none denotes "missing" part. Any other string value defines a part of type "basic".


Currently this is plain Python script which is evaluated by Vertoo at run-time. I'm planning to implement a "real" configuration language a bit later, when I would know enough about what and how will be described. Introduction of the configuration language would mean the end to the alpha-version period as well.

There is no documentation yet, please see vertoo.config from the distribution or the example below.


Vertoo is run by the script. There are a number of commands and options available, which you could see by running without arguments.

Basically, commands can be divided into several groups:

Status commands
show, check
Operational commands
incr, set, set-part
SCM integration
tag, commit
When you want to safely try out any particular command, use -n/--dry-run option. This would ensure that no external change will occur (like changing a file or issuing SCM command).

If you have several modules in your project option -m/--module allows to select one or more module to work with (by default all modules are processed). For some commands (set and set-part) you would almost always have to use this option because different modules usually use different versioning schemes and these commands' arguments depend on it.

Option -d/--show-diff would allow you to see changes that are made in files. Option -v/--verbose is useful when you encounter a problem or want to track Vertoo's bug. When used, more debug information is printed and full Python traceback is printed in case of errors.


Suppose we have a project Foobar of version 0.8.3 and files main.c and README includes version info that we would like to be updated automatically by Vertoo.

Here are the configuration files that must be created:

    foobar = major:0; minor:8; release:3


   registry.registerScheme('full', '%major.%minor.%release')
   main = ModuleInfo('foobar', [
     FileInfo("README", [
       AnchorInfo('simple', 1,
         arguments(pattern="Foobar %v", format="%major.%minor")),
     FileInfo("main.c", [
       AnchorInfo('simple', 1,
         arguments(pattern="version[] = %Q;", format="@full")),
   modules = [main]

Notice that version components could be reffered with %name syntax and to specify text that must match in a file use %v, %q or %Q syntax (this corresponds to version string plain, in single quotes and in double quotes).

After these files are created you could use to update version data (using incr or set commands). File would be automatically updated by Vertoo, as well as dependant files

   $ incr minor
   increment module main version from 0.8.3 to 0.9.1
   Update files with version 0.9.1 OK
   $ cat README
   This is Foobar 0.9.
   $ grep version main.c
   const char* version[] = "0.9.1";

Programming interface (API)

Vertoo is designed in such a way that it could be easily used as ordinary Python module by another Python program. This could be helpful if you want to integrate Vertoo into your build system (like SCons).

The interface is very similar to the command-line one. You call method with command name (like set, show, etc.), optional command arguments and optional custom option values.

Sample usage:

  import vertoo.cmdline
  v = vertoo.cmdline.Vertoo()'show')'incr', ['minor'], {'show_diff':1})

Top || Homepage