Getting started¶
Initial setup¶
The first time we run versionah we must supply the initial version number, and optionally a name for the package:
$ versionah set -t c src/version.h 0.2.0
0.2.0
$ versionah set -t c -n my_app src/version.h 0.2.0
0.2.0
Makefile
usage¶
If your project currently uses make it is a simple task to add version bumping rules:
$(addprefix version-, major minor micro):
versionah bump src/version.h $(subst version-,, $@)
The above example makes it possible to call, for example,
version-minor to bump the minor component in src/version.h
.
libtool
example¶
It is quite easy to use the versioning information for libtool build rules in make files:
$(LIBRARY_NAME): $(LIBRARY_OBJS)
$(LIBTOOL) --mode=link $(CC) -o $(LIBRARY_NAME) $(LIBRARY_OBJS) \
-rpath $(libdir) \
-version-info `versionah display -d libtool src/version.h`
Using the version information as the libtool
interface age requires strict
practise in maintaining the semantics of your version data, but doing so
provides significant value to your users even if they aren’t using the library
interface.
Sphinx
example¶
If you generate your project’s documentation using Georg Brandl’s excellent Sphinx tool, then you have a few options for including the version information.
Import the data¶
If you’re storing your version data in Python format then you can simply import
the file, and access the data directly in your conf.py
:
from versionah import _version
# The short X.Y version.
version = ".".join(map(str, _version.tuple[:2]))
# The full version
release = _version.dotted
You may need to mangle sys.path
if you can’t import the version file
from your conf.py
. For example, in versionah
‘s conf.py
we add
the project root directory to sys.path
with the following snippet:
root_dir = os.path.sep.join(os.path.realpath(__file__).split(os.path.sep)[:-2])
sys.path.insert(0, root_dir)
Use the versionah output¶
Another option is to call versionah inside your conf.py
:
import subprocess
# The full version
release = subprocess.check_output(["versionah", "versionah/_version.py"])
# The short X.Y version.
version = ".".join(release.split(".")[:2])
The obvious drawback to this method is that it requires all users who wish to build the documentation to have versionah installed, and is therefore not recommended.
pod2man example¶
If you generate your documentation using perl‘s pod2man then
a sample Makefile
rule to include your program’s version information
would be:
man.1: man.pod
pod2man --section=1 --release="`versionah display -d dotted src/version.h`" \
--date="`versionah display -d date src/version.h`" $< $@