Unix/GNU Windows

   
By Alexis Wilke
Started in Dec. 2006
   Home       Documentation       Download       Bugs   

Current
wpkg
Version:
0.5



Change Log
  

There are many versions dealt with in a package and this page will tries to answer all of the questions in that regard.


Format

First there is a description of how one can write a package version. It is important to understand that you cannot write a version with any random character. The different software which have to deal with a version number need to be able to sort packages in the right order using their version numbers.

Rational: In order for the packager to know whether it is installing a newer or older version, it is necessary for it to know exactly whether one version is smaller or larger than the other. This gives the packager the possibility to down-grade and up-grade your software.

A version is composed of one to three parts, the simplified syntax is:

	[epoch:]source_version[-revision]

The epoch and revision numbers are optional simple decimal numbers ([0-9]). The source version can include multiple numbers ([0-9]) and letters ([a-zA-Z]) separated by periods (.). The following explains what each part is used for.

  • epoch
  • The epoch is one integer number ([0-9]+) assumed to start at zero (0) followed by a colon (:).

    The epoch is used when a newer version would otherwise compare as older in regard to any one older version of the package. The epoch is tested first. Within an epoch, the source_version much be unique and must properly identify the order of the packages.

    When is this necessary? Say you find a package with version 1.3. You decide to create a package for UniGW and name it 1.3. Later, the author of the source makes a small fix and calls the newer version 1.31. Again, you can create a new package and use that version 1.31. Some time later, the author comes up with a new version. This one is named 1.4. If you want to keep the author version (which is the usual way to do things), you still need to make sure that wpkg recognizes 1.4 as newer than 1.31. This is done with the epoch. 1.3 and 1.31 are considered as being 0:1.3 and 0:1.31 respectively. You can therefore create a newer version 1:1.4.

    It is rather rare that you will need to use the epoch, so before you do that, think about it.

  • source_version
  • This version is usually what the source tarball uses as its version. It is also called the upstream version. The source version can include digits ([0-9]), letters ([a-zA-Z]) and periods (.). If the source package uses any other character, it will need to be transformed to fit this scheme.

    It is suggested that you should not use a source_version composed exclusively of zeroes (i.e. 0, 0.0, 0.0.0, etc.)

    wpkg, for instance, started with source version 0.1.

  • revision
  • The revision is an integer ([0-9]+) preceded by a minus (-). The default is 1 (i.e. you do not need to put -1 at the end of a version).

    The revision is used as the revision number of the package. It is assumed to start at 1 and goes up incrementally each time you change the control information of the package (i.e. each time you change something in the control file other than the version of the package.)

    It is useful each time you find a bug in your package and create a new package from the same source tarball. It usually is reset each time you change the source version (some people prefer to keep increasing the revision number since that represents the version of their package.)

    The revision number cannot be set to 0.

    Comparison1

    To compare two versions between each others, the system compares each part of the version one by one always starting from the left.

    The comparison stops as soon as a part is not equal. The result of that non-equal part comparison is the result of the whole version comparison. If all the parts are equal, then the versions are equal.

    Note: In this case you may instead want to correct the source version and either use:
    • 1.30 and 1.40 for main versions, or
    • 1.3.1 for the intermediate release.
    Yet, in some cases, this can also be really confusing!

    There are two types of parts: major and minor. The system compares minor parts one by one within one major part before to move on to the next major part.

    • Major
    • The major parts one those separated the colon (:), period (.) and minus (-) characters.

      Note, however, that the epoch and revision parts of two versions are always compared together. Thus, if the source_version is missing some entries in one of the input versions, empty strings for letters and zeroes (0) for numerical comparisons are appended except for the revision. When a revision is missing one (1) is used instead of zero (0).

      	2:5.3.2a-5 compared with 5.3
      	becomes
      	2:5.3.2a-5 compared with 0:5.3.0-1
      	                               /\
      	       empty string compared against "a"
      
    • Minor
    • Each major part is composed of one or more minor parts. One minor part is either a string of letters ([a-zA-Z]+) or a decimal number composed exclusively of digits ([0-9]+).

      In the following figure, the third major part is ab57pre. It is composed of three minor parts: ab, 57 and pre.


    Fig 1. how a version string is cut in pieces

    The strings of letters in minor parts are compared lexically not taking the case in account (i.e. 'a' equals 'A'.) When one version has a string minor part and not the other, the other is assumed to have an empty string minor part (""). A string minor part has priority over an integer minor part.

    	1.a3 > 1.4 because "a" > ""
    	1.3a < 1.4 because 3 < 4
    	1.abc < 1.b because "abc" < "b"
    

    The decimal numbers in minor parts are compared numerically. Leading zeroes are ignored. When the minor part of one of the versions is empty or undefined, it is considered to be the decimal number zero.

    	1.2 > 1.0.5 because 2 > 0
    	3.5.0 = 3.5 since the 3rd part in 3.5 is considered to be 0
    	2.5a < 2.5a1 because 0 < 1
    	4.2a34 < 4.2a100 because 34 < 100
    

    To compare the full version A 2:3p.g.2q3-5 against the version B 2:3p.g.2q4 we generate the following table:

    Note: You cannot simply test two strings for equality since the version strings "1.2.0" and "1.2" are not equal if directly compared with strcmp() but will be found as equal with the version comparison.
    Name Major Minor Result
    A B A B
    Epoch 2 2 2 2 equal
    Source
    Major
    3p 3p 3 3 equal
    p p equal
    Source
    Minor
    g g g g equal
    Source
    Bug Fixes
    2q3 2q4 2 2 equal
    q q equal
    3 4 A < B(1)
    Revision 5 5 1(2) 1(2)
    (1) comparison stops here
    (2) defaults to 1 when not included

    When it is necessary to compare a version such as 1.2 with 1.2.3, it is assumed that 1.2 represents 1.2.0 and thus is older. For this reason, it is important to keep the epoch and revision numbers clearly separate from the source version. The following table shows the comparison between the version A 3:2.5.7.4-2 and version B 3:2.5-2.

    Name A B Result
    epoch 3 3 equal
    source_version 2 2 equal
    source_version 5 5 equal
    source_version 7 0 A > B
    source_version 4 0
    revision 2 2

    As we can see, the comparison stops as soon as one of the numbers does not match. The result of the whole comparison is the result of that specific pair of numbers. Note that the two missing sub-versions in 3:2.5-2 are replaced by 0.

    Package

    Each package has a version. This version is saved in the Version field of the control file.

    This is the version used to know whether you are upgrading or downgrading a package you are trying to install. It is also the version used to compare between modules to know whether you have a compatible version of a required package.

    Depends

    Note 1: Debian also support the character plus (+) in their versions. That character would need to be considered as larger than 'z' and 'Z'. At this time, there does not seem much of a need to include that character in a version, however. Thus wpkg will not accept a plus in a version.
    WARNING: The Depends field is not checked in version 0.1 of wpkg.

    Most packages will have a list of sub-packages they depend on. For instance, the DLL version of the z library depends on the base mingw package which includes the MinGW DLL library. And the international version of bison depends on gettext to print out messages properly.

    The Depends field is a list of package names optionaly followed by a minimum, maximum, equal or range of versions for that package. When such a version is specified, it is compared against the Version field of the named package.

      Depends: sswf (>= 1.6.1)
      means the following test must be true
      installed_packages["sswf"].version >= 1.6.1
    

    Build-Depends

    WARNING: The Build-Depends field is not checked in version 0.1 of wpkg.

    Like Depends, you have a Build-Depends field which lists packages with their versions. This part is used whenever you want to build the package to make sure that you have all the necessary tools to build the package successfully.

    .deb file

    The .deb files have a version embedded in them. That version is currently 2.0 (which is also what dpkg currently supports.) This version is written on one line including one new-line character (\n only, no \r!). That one line is saved in a file named debian-binary. This debian-binary file is added first in the .deb package.

    It is assumed that all versions of wpkg which support a version 2, will be capable of supporting all the versions 2.x (2.0, 2.1, 2.2, etc.)

    To check the version of a .deb file, use the --info command. The version is displayed as the Debian package version. Because this is mainly for the different wpkg tools to check for compatibility, there is no great interface to extract this version (and it should not be necessary anyway.)

    wpkg

    Of course, wpkg, the tool, also has a version of its own. You can query the wpkg version with the --version option.

    The wpkg version is composed of two decimal numbers separated by a period as in 0.1.

    It is likely that the wpkg packages will also be as simple since in most cases the maintainer of wpkg will make sure the package is working as expected. Yet, once in a while, you may see a revision number on the package name (as in: wpkg_0.1-2_win32-i386.deb)