| Web site: | http://openamiga.org Open Amiga - Projects | 20241211 22:15 | | Content ID: | 16 | | | Content title: | Version strings | |
Guideline - Amiga version strings
<- Back to guidelines
Content
Intro
| |
This guideline outlines the amiga version string as originally defined by Commodore in the Amiga Style Guide. All OpenAmiga software must follow this guideline.
To add a version string to your program you must make sure that the binary contains a string of characters that represent the version string. All version tools then parse your binary, byte by byte, to find the version string that you have defined for it.
|
Version format
| |
VERSTAG - version
"\0$VER: programname version.revision (dd.mm.yyyy) comment\0"
| programname | - Name of your program | | version | - A number representing the version | | revision | - A number representing the revision | | dd | - Day of month (1-31) | | mm | - Month of year (1-12) | | yyyy | - Year using four digits | | comment | - Optional comment, for readability only |
The program name represents the name of your program and must not contain any spaces. You can use an underscore in place of a space and beyond that use alphanumeric characters for the rest of the program name.
Version and revision are two separate integers. The dot between them does not indicate that they should be interpreted as a decimal number. The dot character is simply used to separate the two numbers.
Both the version and revision must follow numerically increasing values. Ie. 1.2, 1.3, 1.4 etc. 1.36 is numerically higher than 1.4.
When the version number is increased, the revision number is reset to 1.
Note that the date component differs from pre OS4 versions. Older version strings uses a two digit representation of the year but that is now obsolete. The four digit string was added with OS3.9.
The date must always be enclosed in parentheses as shown above and each number separated by a dot. Do not use any other characters, such as space characters, inside the parentheses.
"$VER" represents a cookie and must have a leading zero character.
Also, as always, C strings should always have a trailing zero to make sure that no data after the string is parsed.
Example:
"\0$VER: myprog 1.2 (5.9.2008) Updated this and that\0"
ROMTAG - version
ROMTAG version strings in mostly used for libraries. They have the same format as a VERSTAG version string but without the leading cookie and zero character. Also add a carriage return and newline character before the trailing zero character.
"programname version.revision (dd.mm.yyyy) comment\r\n\0"
Example:
"myprog 1.2 (5.9.2008)\r\n\0"
|
Bump Rev utility
| |
If you are unsure on what your next version should be after updating your software then you can use the bumprev program.
Bumprev creates a set of files of its own format which are included in your C/C++ program.
In order to create the files initially, a line like: "BumpRev -v 1 -r 2 myprog" should be used in a command shell pointed at the source directory. This creates the files, and sets the version and revision information to 1.2
When you want to update your revision you can simply enter "BumpRev -r 3" in a shell and the version files are updated with the version and date information automatically.
For more information about BumpRev download it from OS4Depot and read the documentation.
|
Code examples
| |
C/C++ programs
#define VERSTAG "\0$VER: firefox 1.0 (5.9.2008) It finally compiled!"
or
#define VSTRING "firefoxlib 1.0 (5.9.2008) It finally compiled!\r\n"
Trailing zero characters are added when compiling as per normal C/C++ standards
Note that the version string might be stripped away during the build process due to optimization if it's never referenced by your program. It's therefore recommended that you add a reference to it in your source:
STRPTR USED ver = (STRPTR)VERSTAG;
or
STRPTR USED ver = (STRPTR)VSTRING;
|
What not to do
| |
Software originally targeting other OS'es, such as Linux, often use a version format that is alien to the Amiga version format. Don't use the alien format inside Amiga version strings. Instead create a new version string that represents the version.revision of your port.
Example list of illegal version string usages:
x.y.z
1.3 followed by 1.31 followed by 1.4
1.3b - only numbers are allowed
|
|