common: support custom, extra information for build's version

[babeltrace.git] / version / README.adoc

= Babeltrace's version extra information

This directory contains files and a directory to add information to the
version of a Babeltrace build. The CLI (`--version` option) and library
can provide this information.

The following directory and files are scanned at `src/common/version.i`
generation time, which occurs at **every build**:

`extra_version_name`::
    If it exists, the first line of this file is the extra name of the
    custom version.

`extra_version_description`::
    If it exists, the file's contents is the extra description of the
    custom version.
+
This should contain a description of local modifications applied to the
source tree. A distribution packager can use this file, for example, to
specify what changes were applied locally.
+
All characters except alphanumeric ones, whitespaces, `.`, and `,` are
replaced with `-`.

`extra_patches`::
    If it exists, this directory contains patch files applied to the
    source tree.
+
Each file name is included when generating `src/common/version.i`,
except `README.adoc`.
+
All characters except alphanumeric ones, whitespaces, and `.` are
replaced with `-`.