Table of Contents
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
- 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
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)
- (Under Linux) Set the LANG environment variable to use UTF-8, e.g., export LANG=en_NZ.UTF-8
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:
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):
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
|release-kits/shared/windows/wrapper/*||The windows wrapper. Contains c++ code, splash screen images including progress indicators, and a template resource script.|
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.
Overview of Greenstone3 Release Kits
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.
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.
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.
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.
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 executable, and puts it in a directory called
wrapped-installer. It also creates another copy with a bundled JVM.
sork2 and sork3
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.
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.
The Target Tree
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.
Differences between linux release kit and other release kits
Wrapped executable with bundled java installer
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).