Greenstone Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
======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|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:
<code>
svn co <nowiki>http://svn.greenstone.org/main/trunk/release-kits</nowiki>
cd release-kits
ant (or: ant compile)
</code>
Now add //release-kits/bin// to your PATH.

To check if the release kit is properly installed, type:
<code>rk3 -cmd</code>

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):
<code>$ rk3</code>
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 <nowiki>kits///kit-name///ant-scripts/build.xml</nowiki>. 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 <nowiki>kits///kit-name///ant-scripts</nowiki> 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==== 

===Overview of Greenstone3 Release Kits===
There are four top level targets for all Greenstone3 release kits. They are:

<code>
1 compile
2 create-distribution
3 create-installer
4 wrap
</code>

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.
===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.

===== LiRK3 =====
==== The Target Tree ====
The target tree for LiRK3 looks like this:

<code>
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:
</code>

This is a high-level overview of the tree.
<code>
1 compile:
2 create-distribution:
3 create-installer:
4 wrap:
</code>

====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//, 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//.

====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. Finally, it copies the compiled binary executables and documentation from //greenstone3// to the appropriate places in //distribution/greenstone3//.

====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 linux executable, and puts it in a directory called //wrapped-installer//. In the future it will also create another copy with a bundled JVM.