Release Kits

The Greenstone release kits automate the task of creating a releases of Greenstone2, Greenstone3 or the documented example collections. They are basically a collection of ant scripts which encode the process for creating a release, but they also contain the ant-installer software for creating jar installers, wrapper code to turn jar installers into native executables, some custom ant tasks, and some canned resources which go into realeases. They do things like download source code from svn and compile it, delete files not needed for distributions, create the executable installers, and produce iso images for distribution on the web and cd rom.

A current list of release kits can always be found at this URL: http://trac.greenstone.org/browser/main/trunk/release-kits/kits

Note:

• In my examples, I use rk3 to demonstrate use of a release kit. Please adjust the examples for the release kit you are using.

Prerequisites

You will need the following properly installed on your system before you can use the release kits:

• A good Java JDK (from Sun, 1.4+)
• Apache ant
• C/C++ compiler (g++ for linux, Microsoft Visual Studio .NET 2003 for windows, xcode for mac)
• svn
• (Under Linux) Set the LANG environment variable to use UTF-8, e.g., export LANG=en_NZ.UTF-8

Installation

The release kits are installed together. To install, simply checkout and compile:

svn co <nowiki>http://svn.greenstone.org/main/trunk/release-kits</nowiki>
cd release-kits
ant (or: ant compile)

Now add release-kits/bin to your PATH.

To check if the release kit is properly installed, type:

rk3 -cmd

If all is well you will get an ant command as output. (The -cmd flag asks the release kit what and command it will execute, without actuall executing it.)

• Create an empty directory for the release. This is where the release files, including many intermediate files, will be stored. Make sure it is on a volume with plenty of free space - typically you should allow for about 2GB. You can delete the release directory once the products have been safely copied elsewhere.

• Create and edit the file rk3-build.properties inside the release directory. (Adjust the name for the release kit you are using.) In this file, we define some properties for the release. Define properties with name:value, one per line. Run the release kit with argument 'properties' for a list of required and optional properties.

• Cd into the new release directory, and run the release kit by typing its name on the command line (all lowercase):

$ rk3

The release kit will tick away for a while. Afterwards you will be left with a number of subdirectories in the release directory. The subdirectory products contains the final release. Enjoy!

Any additional arguments given to the release kit will be passed to ant, so you can easily specify ant properties or targets on the command line. E.g.:

rk3 create-installer (executes only the create-installer target)

rk3 -Dversion=2.90 (override the version property with the value 2.90)

rk2 creates binary releases of Greenstone2 on linux, mac and windows. When run, it detects the current operating system and makes a release for that operating system.

There are four top level targets for all Greenstone3 release kits. They are:

1 compile
2 create-distribution
3 create-installer
4 wrap

Each is explained in detail below.

• compile

This target compiles the native binary executables and the documentation for the release. It checks out the Greenstone3 source code from the repository into a folder called greenstone3. It then compiles it by running ant, automatically editing files, and so on. It basically simulates what an svn user would do to compile Greenstone3 but with a few small differences. One such difference is that it compiles everything statically.

When running ant, this target uses a special build script which is part of the release kit, called operations-on gs3home.xml. This file replaces dist-resources/build.xml which used to be in the repository.

• create-distribution

This target compiles all the java classes used in Greenstone3, and creates a clean Greenstone3 directory structure which holds the compiled java classes and the compiled binaries and documentation from the previous step. It exports the Greenstone3 source code to distribution/greenstone3. It then compiles all the java classes, including those for GLI and the indexers, by running ant, using the special operations-on gs3home.xml script. It copies the compiled binary executables and documentation from greenstone3 to the appropriate places in distribution/greenstone3. It also deletes some files useful only on other operating systems, and some files only for greenstone2.

• create-installer

This target creates an executable jar installer for Greenstone3, and puts it in a directory called installer. It uses the files in distribution/greenstone3. It uses the ant-installer package included with the release kit.

• wrap

This target wraps the executable jar installer in a native executable, and puts it in a directory called wrapped-installer. It also creates another copy with a bundled JVM.

• shared/core - the core shared code for release kits.
• shared/linux, shared/windows, or shared/mac - shared file specific to the OS.
• shared/greenstone2 or shared/greenstone3 - shared files specific to the Greenstone version.

The release kits are bundled with the software ant-installer which creates executable jar installers. The customisation of the installer is done in three files:

• kits/*/installer/antinstaller-config.xml -
• kits/*/installer/build.xml - This is an ant script which is executed on the user's machine after they have gone through the GUI mentioned above and selected the installation options. It does the actual copying of files onto the user's machine, changes permissions etc. The main attraction of the ant-installer software, and the reason we use it for releases, is that it allows us to execute an ant script on the user's machine during install, which means we can capitalise on ant's existing library.
• shared/core/ant-scripts/create-installer.xml - This script runs the <installer> ant task (provided by the ant-installer software) which creates the jar installer.

The cdrom release kit (cdrk2) is different to the other release kit because it depends on the products of other release kits (namely rk2 and derk).

The CDROM release has to work on all three operating systems, so it cannot be produced on a single machine (the release kits don't cross-compile). But rk2 already has logic for compiling and tidying up Greenstone2, and derk the same for the documented example collections. To avoid duplicating this functionality in cdrk2, the rk2 and derk release kits have a target which creates an archive of everything cdrk2 needs from them to create the cdrom. Rk2 is run on windows, mac and linux, and derk on linux, and a 'cdrom-components' archive is created in the products folder for each. These files are then be copied to a linux machine, where cdrk2 is run. Cdrk2 contains only the simple logic of expanding these archives and creating an iso from them.

The target tree for LiRK3 looks like this:

1 compile:
     1.1 checkout-greenstone3:
     1.2 set-version-number-property:
     1.3 dist-prepare-unix:
     1.4 tweak-configure-scripts:
          1.4.1 mgpp-add-static:
          1.4.2 mg-add-static:
          1.4.3 gs2buildextra-add-static:
     1.5 dist-update-unix:
     1.6 dist-configure-unix:
     1.7 tweak-makefiles:
          1.7.1 wv-add-static:
          1.7.2 xlhtml-add-static:
          1.7.3 ppthtml-add-static:
          1.7.4 rtftohtml-add-static:
          1.7.5 gdbm-add-static:
     1.8 dist-build-unix:
     1.9 fix-wget:
     1.10 linux-strip-execs:
     1.11 prepare-documentation:
2 create-distribution:
     2.1 export-greenstone3:
     2.2 dist-set-version-number-property:
     2.3 create-distributions-1:
     2.4 create-distributions-2:
     2.5 create-distributions-3:
     2.6 copy-over-build-xml:
     2.7 insert-user-manual:
     2.8 insert-compiled-binaries:
3 create-installer:
4 wrap:
     4.1 setup-for-wrapping:
     4.2 compile-wrapper:
     4.3 clean-up-after-wrapping:

This is a high-level overview of the tree.

1 compile:
2 create-distribution:
3 create-installer:
4 wrap:

This target compiles the native binary executables and the documentation for the release. It checks out the Greenstone3 source code from the repository into a folder called greenstone3. It then compiles it by running ant, and automatically editing files and so on. It basically simulates what an svn user would do to compile Greenstone3 but with a few small differences. For example, it compiles everything statically.

When running ant, this target uses a special build script which is part of the LiRK3 program, called operations-on gs3home.xml, which replaces dist-resources/build.xml.

This target compiles all the java classes used in Greenstone3, and creates a clean Greenstone3 directory structure which holds the compiled java classes and the compiled binaries and documentation from the previous step. It exports the Greenstone3 source code to distribution/greenstone3. It then compiles all the java classes, including those for GLI and the indexers, by running ant, using the special operations-on gs3home.xml script. Finally, it copies the compiled binary executables and documentation from greenstone3 to the appropriate places in distribution/greenstone3.

This target creates an executable jar installer for Greenstone3, and puts it in a directory called installer. It uses the files in distribution/greenstone3. It uses the ant-installer package included with the release kit.

This target wraps the executable jar installer in a native linux executable, and puts it in a directory called wrapped-installer. In the future it will also create another copy with a bundled JVM.

The java installer for linux from the sun website is a self extracting executable - it does not have a gui installer interview process. Therefore, it was convenient to just create a regular tar with the same contents and ship that with the executable with bundled java. It is extracted into the temp directory on the user's machine when they execute the installer executable, whether java is found on their machine or not. Then, the installer jar is launched (using their java if they have it, otherwise the one in the temp directory). When the user hits 'install', java is copied from the temp directory into their greenstone installation (GSDL3HOME/packages/jre).