Table of Contents
This page is in the 'old' namespace, and was imported from our previous wiki. We recommend checking for more up-to-date information using the search box.
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.
Installing the Release Kits
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 http://svn.greenstone.org/main/trunk/release-kits 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.)
Using a Release Kit to Create a Release
- 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)
Inside the Release Kits
| release-kits/build.xml | This is the ant script which compiles the release kits themselves (when you run ant in the top-level release-kits directory). It is not a big part of the release kits and probably won't need to change that often. Only java code is compiled by this script so you can "compile once, run anywhere". |
|---|---|
| release-kits/bin | Contains all the "binaries" (which are actually scripts) for the release kits. The extensionless files are used on Linux and Mac. Only rk is a bash script and the rest are symlinks to rk; the rk script can work out which release kit was requested by the name it was called by. The .bat files are used on windows, and similarly only rk.bat has any real code in it, with the others simply passing off to rk.bat. |
| release-kits/shared/core/ant-installer | This is the ant-installer software. The source code is slightly modified from the original ant-installer package. For this reason, and also for convenience, it is included with the release kits. |
| release-kits/shared/core/ant-tasks | Contains various ant tasks needed for the release kits. Those tasks in the greenstone subdirectory are written by the greenstone team, the rest are third-party tasks. Some of these tasks are actually placed into releases by the release kit during a build, to be used on the end-user's machine. |
| release-kits/shared/core/icon | Contains the icons for the installers binaries. Ie, for the Greenstone-2.xx-windows.exe installer Greenstone-2.xx-MacOS.app installer. |
| release-kits/shared/core/installer-classes | Contains canned files which will be put directly into the installer jar. Things like the header image for the installer and some icons. |
| release-kits/shared/windows/installer-classes | Contains canned files which will be put directly into the installer jar, but only on windows. The windows installer needs to create shortcuts, and get the necessary ant tasks from this directory. (move to ant-tasks) |
* 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
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.