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) |
| release-kits/shared/core/language-strings/*.properties | The language strings for the installer and uninstaller. |
| release-kits/shared/core/lib | Contains some java libraries required by the release kit, and a properties file containing the names of the months in different languages. |
| release-kits/shared/core/uninstaller | Contains the uninstaller java code and associated scripts. Also contains scripts for compiling the uninstaller and some simple mock greenstone installations for testing it. |
| release-kits/kits/kit-name/ant-scripts/build.xml | The entry point ant script for each release kit is found in kits///kit-name///ant-scripts/build.xml. It imports other ant scripts to build up functionality. All release kits import shared/core/ant-scripts/shared.xml. Greenstone2 release kits (rk2, sork2 and cdrk2) import shared/greenstone2/ant-scripts/greenstone2-shared.xml, and Greenstone3 release kits (rk3, sork3) import shared/greenstone3/ant-scripts/greenstone3-shared.xml. Release kits may import other scripts, either from the shared area or from its own kits///kit-name///ant-scripts directory. Also inside a release kit's build.xml is the default target, which controls the overall sequence of the release kit. The default target either calls a sequence of other targets, or has ant code directly inside it. |
| release-kits/kits/kit-name/installer/antinstaller-config.xml | This file describes the installer 'interview' process, ie, the sequence of pages to click through during installation. It chooses which licence to display to the user and controls what information is gathered from the user (but it does not specify how that information is used). |
| release-kits/kits/kit-name/installer/build.xml | This is an ant script which is executed on the user's machine after they have gone through the installer interview process. It does the actual copying of files onto the user's machine, changes permissions etc. |
| release-kits/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. We can specify here what extra files we want to go into the jar (remember the installer jar is a jar file like any other). This file is in the core since the method for creating the jar is the same for Greenstone2 and Greenstone3. |
| release-kits/shared/core/ant-scripts/wrap.xml | This script creates native executable installers out of the jar installers (e.g., on windows it creates an exe). The method of wrapping is quite different for each operating system, so look at the script more details. This file is in the core since the method for wrapping the jar is the same for Greenstone2 and Greenstone3. |
| release-kits/shared/linux/wrapper.cpp | The linux wrapper code. The simplest wrapper of the three with no icon or splash screen. Simply provides logic for extracting the jre and the jar installer and firing up the installer. |
| release-kits/shared/mac/Wrapper.app | The mac wrapper app. Mac apps are just folders with a .app extension and a particular layout of sub-folders and files. This is the template for the installer app, which is copied and tweaked, and the installer jar inserted to create an native "executable" installer for the Mac. This app is then further wrapped in a dmg image, as a folder is not a suitible product for distribution over the web. |
| release-kits/shared/windows/wrapper/* | The windows wrapper. Contains c++ code, splash screen images including progress indicators, and a template resource script. |
Kit-Specific Information
rk2
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.
rk3
sork2 and sork3
derk
cdrk2
What's in the Release Kits
- 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.
Installers
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
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.