Overview
VersionNum is the standard version-description file used by many RISC OS projects in the build environment. This appendix isolates the format and its conventions so that version-file maintenance can be referenced independently of the more general filename and filesystem rules.
VersionNum structure
VersionNum file format
VersionNum is the standard version-description file used by many RISC OS projects. It is a C-style header made up of comments and #define directives, so it can be included directly by C, C++, CMHG, CMunge, and other preprocessable source files. The same definitions are also consumed by riscos-vtranslate when generating versioned text resources.
Overall structure
A conventional VersionNum file contains:
- a comment header recording the tool, version, and timestamp that generated the file;
- a short notice that the file is maintained automatically;
- a group of CMHG-oriented definitions without quotes, for use in module help strings and similar preprocessed text. CMHG directives are not C and do not accept quoted string literals: a value such as 0.05 is substituted by simple textual concatenation into the CMHG source, so it must appear unquoted there even though the equivalent C-style definition below is quoted;
- a group of normal C-style version definitions, some numeric and some string-valued.
A typical generated file looks like this:
/* VTranslate (0.05) 17:13:12 21/01/2001
*
* This file is automatically maintained, do not edit manually.
*
*/
#define Module_MajorVersion_CMHG 0.05
#define Module_MinorVersion_CMHG
#define Module_Date_CMHG 21 Jan 2001
#define Module_MajorVersion "0.05"
#define Module_Version 5
#define Module_MinorVersion ""
#define Module_Date "21 Jan 2001"
#define Module_FullVersion "0.05"
#define Module_FullVersionAndDate "0.05 (21 Jan 2001)"
Common definitions
The most common definitions are:
| Macro | Meaning |
|---|---|
| Module_MajorVersion_CMHG | Unquoted major.minor form for CMHG or CMunge preprocessing. |
| Module_MinorVersion_CMHG | Unquoted minor version suffix for CMHG use; often empty. |
| Module_Date_CMHG | Unquoted release date for CMHG or CMunge preprocessing. |
| Module_MajorVersion | Quoted major.minor version string, such as "0.05". |
| Module_Version | Integer form of the version, normally the hundredths value without a decimal point. |
| Module_MinorVersion | Quoted minor-version suffix, often an empty string. |
| Module_Date | Quoted release date string. |
| Module_FullVersion | Quoted full version string assembled from the major and minor parts. |
| Module_FullVersionAndDate | Quoted full version string with the date appended in parentheses. |
Projects may include additional definitions, but these names are the normal ones expected by companion tools and resource templates.
Module_Version is derived from Module_MajorVersion as int(MajorVersion × 100 + 0.49), where MajorVersion is read as a floating-point value, not split into separate major/minor integers. For the maintained x.yy format this gives the expected result of the digits run together ("1.04" becomes 104, "1.20" becomes 120, not 1020), because the minor part is always exactly two decimal digits; it is not simply (major × 100) + minor as separate integers, which would give the wrong answer for a minor version below 10 written without its leading zero.
Usage conventions
The file is normally managed by riscos-vmanage rather than edited by hand. The maintained version number format is x.yy, where the major version is a single digit and the minor version is two decimal digits.
Tools use the file in different ways:
- C, C++, CMHG, and CMunge sources usually include VersionNum directly and refer to the macro names in preprocessed text;
- riscos-vtranslate uses the macro names as substitution keys, so {Module_FullVersionAndDate} expands to the corresponding macro value;
- riscos-vmanage update can derive companion files such as VersionAsm, VersionBas,ffb, and VersionFortran from it.
riscos-vmanage has no separate lint or validate subcommand (its full command set is init, increment/inc, update, and set). Running riscos-vmanage update against a file that does not contain a recognisable version number does not fail. It silently treats the version as 0.00 and overwrites the file with a freshly generated one, with no warning. A hand-edited VersionNum should therefore be checked by eye, or by diffing against the previous committed version, rather than relying on any tool to catch a mistake.