VersionTool

VersionTool is a tiny utility that extracts version information from a .cabal file and from darcs, and then, inserts it into a source file. This is useful to enable your application (or library) to print (or return) precise version information that is automagically in sync with the information in the .cabal file.

Requirements

Your project needs to fulfil the following modest requirements to use VersionTool:

• Your project should require the availability of a Haskell system. VersionTool is written in Haskell 98 using a very basic set of hierarchical libraries, so any Haskell system should do. By default VersionTool uses a #! invocation of runhaskell to run itself. This certainly works with GHC and Hugs. I am not sure about other Haskell systems, but you can also run VersionTool in any other way you please.
• Your projects should use Cabal. (Strictly speaking, you only need to maintain a rudimentary .cabal file with version information, but all Haskell software should really use Cabal anyway.)
• You should use darcs for version control. (Strictly speaking, you could uncomment the darcs functionality in VersionTool and just use it for the version information in the .cabal file.)

Integrating VersionTool into your Project

Follow these simple steps:

• Download VersionTool.hs and place it into the root directory of your working copy of your project.
• Make VersionTool.hs executable (i.e., chmod a+x VersionTool.hs in a Unix shell.)
• Add the requirement to make VersionTool.hs executable to your build instructions for users getting the source from darcs, as darcs does not preserve permissions. For an example, see λFeed's INSTALL file.
• If the name of the source file you want VersionTool to add the version information to is Version.hs, rename it to Version.hs.in (using the darcs mv command) and add the version markers described in detail further down this page. See λFeed's Config.hs.in as an example for using the markers.
• Now, whenever you build your project (or before you create a tar ball for a release), and typically before you run Cabal's ./Setup.hs configure, you execute ./VersionTool.hs Version.hs, which will create the file Version.hs from Version.hs.in. (Don't forget to add this step to your build instructions.)
• Optionally, you can add two new version fields to your .cabal file, namely --Versnick and --Versdate as described below. If you don't do this, everything will work fine regardless, but VersionTool will issue a warning that the fields are missing.

That's it!

Detailed Usage of VersionTool

The name of the source file that is to be rewritten with the version information must be passed as the only argument to VersionTool. If that file's name is Version.hs, there must be a template file Version.hs.in containing version information markers indicating where VersionTool should to enter the version information. The markers are the following:

@VERSION@

Version number, typically in XX.YY.ZZ format (from Version entry in Cabal file)

@VERSNICK@

Version nickname, a string that may contain white space (from non-standard --Versnick entry in Cabal file)

@VERSDATE@

Date of version, typically in DD MMM YYYY format (from non-standard --Versdate entry in Cabal file)

@PATCHLEVEL@

Number of darcs patches after a tag including the value of @VERSION@, in plN format

@CONTEXT@

First entry of darcs changes --context

@CONFDATE@

Date when VersionTool ran, in DD MMM YYYY format

VersionTool replaces these markers by H98 string literals. See λFeed's Config.hs.in as an example for using the markers.

VersionTool allows the Cabal file to have two extra entries not recognised by Cabal itself. These entries start with the Cabal comment characters `--' to avoid confusing Cabal.

VersionTool uses darcs to find a tag containing the version number @VERSION@. If it finds such a tag, the number of patches added, since that tag, determine the patchlevel. If it does not find such a tag, it tags the repository with Version @VERSION@ and the patchlevel is pl0.

Code

Download version 1.0 of VersionTool.hs. VersionTool is available under the very permissive BSD3 license.