Logo54.196.182.102 
  News  Recent  Stats  Forums  Contact
  Menu
 Username

 Password


   Register here

 Main menu
   BBCode test
 
 Content
   About OpenAmiga
   Guidelines
   Definitions
   SVN Access
   Licenses
   IRC channel
   Links
   ToDo List
   List Content
 
 Projects
   Suggested (0)
   Open (11)
   Assigned (28)
   Pending (0)
   Finished (7)
   Closed (4)
 
 Categories
   Cli (2)
   Datatype (9)
   Drivers (3)
   System (16)
   Workbench (16)
  Version strings
[Print][View Files]
Guideline - Amiga version strings
<- Back to guidelines

Content
    
- Intro
- Version format
- Bump Rev utility
- Code examples
- What not to do


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

Open Amiga project website, Created in 2008 by Björn Hagström