Using Tools: 7 Grev

| Up: GEOS SDK TechDocs | Up | Prev: 6 Goc | Next: 8 mkmf

GEOS supports two version numbers for each geode. The first of these is the release number, used to uniquely identify the release of the geode. The protocol number tracks the external interface of the file. This is used to determine what versions of related geodes can be used together. The kernel will use these numbers to prevent loading of incompatible executable files.

The grev utility generates proper revision numbers. Normally, it is called automatically by pmake , so if you are just making a small change to a file, you need not call it directly. However, you may wish to. When using grev, you must think about how major a change you are making; a large change means that you should change an earlier number of the release number. A change from 1.2.3.4 to 2.0.0.0 should signal a larger step than a change to 1.2.3.5.

The pmake program uses grev to automatically create revision numbers for geodes; it passes these values to Glue, which in turn places the protocol and revision numbers in the .geo and .sym files.

There are three widely used methods for incrementing release numbers with respect to public releases (for which a specific release number is desired for marketing, say "2.0.0"). The problem comes because it is not known until after a release has been built whether it will be the release or not (since bugs may be found).

The first method is to keep separate public release numbers and internal release numbers. This is awkward and confusing and is generally done when it is too late to do anything else.

The second method is to number successive revisions "1.14.0.12", "1.14.0.13", "1.14.0.14" and so on until the final revision is made which is numbered "2.0.0.0". The problem with this is that one never quite knows whether or not a revision is the final one (since bugs may be found).

The third method is to number successive revisions "2.0.0.12", "2.0.0.13", "2.0.0.14" and so on. The released "2.0.0" revision is then the last engineering revision starting with "2.0.0.X". The disadvantage of this method is that it can seem non-obvious at first and requires a little bookkeeping to know the engineering number of the released version.

The protocol number is changed whenever the external interface for the file changes. For the kernel and for libraries the protocol reflects the order as well as the parameters and behavior of external entry points. For applications the protocol reflects the object names, types and attributes. Changes that do not affect the external interface (changing the implementation of a routine, changing the moniker or hints of an object) do not change the protocol number.

The major protocol number reflects incompatible changes in interface, such as rearranging the order of entry points. The minor protocol number reflects upwardly compatible changes in the protocol (such as adding an entry point at the end of a jump table or using a bit formerly marked as "reserved").

Each executable file contains protocol compatibility information (a protocol number) for all other executable files on which it depends. For example, a simple application might be compatible with kernel protocol "34.2" and UI protocol "19.7". Thus the application is compatible with kernels "34.2" through "34.65535" and with UIs "19.7" through "19.65535".

A protocol number is also stored with each state file to determine if the state can be recovered by the currently running application.

The grev tool uses a file (normally marked with a .rev suffix) in the geode's development directory to keep track of the revision number. The file is organized chronologically, with later entries at the beginning of the file. It contains

Using the grev utility:

In the Nokia 9000i SDK version 2 (refer to versions), the .rev file may be in the local or in the "Installed" branch. It is suggested that developers keep a local .rev file so that they don't have to make revisions to the branch by hand.

The grev utility uses the following syntax:

     grev <option> <rev filename> [<comment>|-P|-R] -s
It is necessary to pass the -s flag to save the protocol change. There are few circumstances where this flag is not needed.

<options> may be one of the following:

new file [" comment "|-P|-R]
Create a new revision record, listing comment as an initial revision for the base (0.0.0.0 release, 0.0 protocol). This command may only be executed in the geode's development directory. The -P option causes grev to give minimal output, printing only the protocol number. The -R option causes grev to print only the revision number. These last two options are normally used by pmake to extract the relevant numbers.
info file
Print the current release and protocol from the revision file.
getproto file
Print only the current protocol from the revision file.
newprotomajor file [" comment "|-P|-R]
NPM file [" comment "|-P|-R]
Increase the major protocol number by one, setting the minor number to zero. The comment argument is listed as the reason for the change in the file. The -P and -R options work as they do for grev new .
newprotominor file [" comment "|-P|-R]
npm file [" comment "|-P|-R]
Increase the minor protocol number by one. The comment string is listed as the reason for the change in the file. The -P and -R options work as they do for grev new .
newrev file number1.number2.number3 [" comment "|-P|-R]
Increase release number from A.B.C.D to number1.number2.number3.0. The comment is listed as the reason for the change. The -P and -R options work as they do for grev new .
newchange file [" comment "|-P|-R]
Up release number from A.B.C.D to A.B.C+1.0. The comment is listed as the reason for the change. The -P and -R options work as they do for grev new .
neweng file [" comment "|-P|-R]
Increase release number from A.B.C.D to A.B.C.D+1. The comment is listed as the reason for the change. The -P and -R options work as they do for grev new .
<rev filename> is the name of the revision file (ending in .REV).

<comment> is an optional comment embedded in quotes.

-P causes grev to give minimal output, printing only the protocol number. This flag is normally used by pmake to extract to protocol number.

-R causes grev to print only the revision number. pmake uses this flag to extract the version number.

-s, as noted above, causes the change to be saved to the revision file. If this flag is not passed, the change will only be displayed to the screen.

| Up: GEOS SDK TechDocs | Up | Prev: 6 Goc | Next: 8 mkmf