Introduction

Versionize is a simple tool that automatically updates the build number and/or the date and time of compilation of a project.

Usually you'll have a file where you define the version number, the build number, and the date and time of compilation. When you program in C/C++ language, this is usually a header file containing a number of macros defined with the "#define" preprocessor command.

These macro definitions can be recognized by Versionize which can update them as directed by the user.

If Versionize is controlled by the compilation tools, you can have the desired macros automatically updated when the project is being built.

Usually you would want to launch Versionize at the start of the build process to update time and date of compilation and launch it again at the end of the process, so that the build number is updated if the compilation was successful.

Distribution

Versionize is open source so you can use and distribute the code and the executables in any form you like. If you like, I will be happy to include modifications on the code back on the original source so others may benefit from them. Versionize should compile correctly with any C compiler on any platform. Executables for AmigaOS (68k) and Windows are also included in the package. They were tested on AmigaOS 3.x and WindowsXP but should work just everywhere.

Usage

Usage: versionize [opt1...]

Basic operations

If you don't specify any option when launching Versionize, Versionize tries to open the file version.h in the current path; if Versionize manages to open it, it looks for macros defined with the C preprocessor command #define. In particular it looks for the macros BUILD_NUMBER, BUILD_TIME and BUILD_DATE.

If Versionize can find the BUILD_NUMBER macro, the following characters in that line are interpreted as a number and replaced by that number incremented by one. If Versionize detect that the macro was defined between double quotes, it replicates them so that the string format is preserved. For example if the file version.h contains the line:

#define BUILD_NUMBER 1

#define BUILD_NUMBER 2

If the file version.h contains the line:

#define BUILD_NUMBER "103"

#define BUILD_NUMBER "104"

If Versionize can find the BUILD_TIME macro, the following characters in that line are deleted and replaced by the current time in local format. The local format of time is statically decided at Versionize compilation time (usually it is in hh:mm:ss format). If Versionize detects that the macro was defined between double quotes, it replicates them so that the string format is preserved. For example if the file version.h contains the line:

#define BUILD_TIME 10:23:12

#define BUILD_TIME 10:25:37

if Versionize was launched at around 10:25. If the file version.h contains the line:

#define BUILD_TIME "10:23:12"

#define BUILD_TIME "10:25:37"

If Versionize can find the BUILD_DATE macro, the following characters in that line are deleted and replaced by the current date in local format. The local format of date is statically decided at Versionize compilation time (usually it is in mm/dd/yy format). If Versionize detect that the macro was defined between double quotes, it replicates them so that the string format is preserved. For example if the file version.h contains the line:

#define BUILD_DATE 07/03/04

#define BUILD_DATE 07/05/04

if Versionize was launched on the 5th of July in 2004. If the file version.h contains the line:

#define BUILD_DATE "07/03/04"

#define BUILD_DATE "07/05/04"

Customizing Versionize behaviour

You can specify a number of options to change the default behaviour of Versionize.

You can make Versionize to update macros in a file other than version.h. Just specify the file name (and path, if needed) with the -f option. We suggest to include the macros in a short file to avoid Versionize wasting significative time while processing the file.

You can change the name of the macros that Versionize is trying to update. Just specify any or all of the build number, time and date macros with the -n, -t and -d options.

You can force Versionize to update the build number only or the time and date of compilation only instead of both. Use the "-m n" option to update the build number only and the "-m t" option to update time and date only.

You can change the format in which time and date are displayed. Just specify the desired template strings with the -T and -D options. These strings can contain any number of tokens (see the table below) to customize the output format. The only limit is the size of the template that can be of 256 characters maximum.

You can provide a file that specifies localized names for months, week day and AM/PM equivalent. Use the "-l localefile" option to specify the file name (and path, if needed). See "Localization of Versionize" paragrah if you need details on locale file format.

For example, if we have the file version_defines.h with the following (partial) code:

If, on the 7th of July in 2004 at 11:13:27, we execute Versionize with the following command:

versionize -f version_defines.h -m t -d VERSION_BUILDDATE -t VERSION_BUILDTIME -D "Built on %a. %-d %B %Y" -T "%I:%M %p"

the file version_defines.h is modified as following:

If soon after we execute Versionize with the following command:

versionize -f version_defines.h -m n -n VERSION_BUILDNUMBER

the file version_defines.h is modified as following:

If, on the 7th of July in 2004 at 11:13:27, we execute Versionize on the original version_defines.h with the following command:

versionize -f version_defines.h -m t -d VERSION_BUILDDATE -t VERSION_BUILDTIME -D "Compilato %A %-d %B %Y" -T "%H:%M" -l italian

where italian is the example locale file provided with Versionize, the file version_defines.h is modified as following:

Templates

You can use the following tokens in date and time templates:

Use the %-t format for any token t to prevent zero padding. For example, put %-d in the date template to output the month day from 1 to 31 without zero padding. This behaviour applies for %d, %H, %I, %j, %m, %M, %S, %w, %y and %Y tokens only; using the %-t format on other tokens produces the same result that the %t format produces.

The tokens %a, %A, %b, %B and %p will produce localized output when the "-l localefile" option is used, as specified in the file localefile.

Localization of Versionize

You can provide a file that specifies localized names for months, week day and AM/PM equivalent with the "-l localefile" option. In this file, the following line must be used to define the localized name of nth month (with n between 1 and 12):

COMPLETEMONTH<any spaces>n<any spaces>"localized month name"

The following line must be used to define the localized short name of nth month (with n between 1 and 12):

SHORTMONTH<any spaces>n<any spaces>"localized month short name"

The following line must be used to define the localized name of nth week day (with n between 1 and 7):

COMPLETEWEEKDAY<any spaces>n<any spaces>"localized week day name"

The following line must be used to define the localized short name of nth week day (with n between 1 and 7):

SHORTWEEKDAY<any spaces>n<any spaces>"localized week day short name"

The following line must be used to define the localized name of AM equivalent:

AMEQUIVALENT<any spaces>"localized AM equivalent"

The following line must be used to define the localized name of PM equivalent:

PMEQUIVALENT<any spaces>"localized PM equivalent"

These lines of text can be in any order and interposed with text and comments. Provide ALL the localized strings that you are going to use, because, otherwise, empty strings will replace the tokens. The file italian is provided as example: