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.


Up to date for GS3.10, checked 20 Feb 2021.
This page is up to date for 3.06 (5 November 2014). Much of it was checked again to be up to date after 3.08.


====== Advanced Installation ======
For most users, the main Greenstone download (also called the "binary") with default settings is sufficient, and is very [[en:beginner:install_basic|easy to install]]. However, there are some instances where you may want or need to go through a more advanced installation process:

  * If you want to compile up Greenstone for a particular OS that we don't provide the binaries for 
  * If you had any issues with the pre-compiled binaries for your operating system
  * If you want to locally patch up or modify the source code of a particular release that otherwise works fine for you
  * If you want up-to-date code


^Installation Option^Currency of Code^Code type^Description^
|**Binary** (the main download)|Release-Specific|Binary|This is the official, pre-compiled version of the software. It is platform-specific, and what most Greenstone users use.  |
|**Source component**|Release-Specific|Source Top-Up|if you already have the binary installed, you can top it up with the source component which provides the code that you can compile. Note that the source component belongs with a particular binary. This means it is static code (code as it was when the associated binary was released), not the latest version of the source code.|
|**Source distribution**|Release-Specific|Source|if you want to compile the code for a particular binary release without installing the binary first, you can get the source distribution. Once more, this is static code: the code as it was when the binary was released. This is useful if you want to compile up Greenstone for a particular OS that we don't provide the binaries for, or if you had any issues with the pre-compiled binaries for your OS. It's also handy for if you want to locally patch up or modify the source code of a particular release that otherwise works fine for you.|
|**Source via SVN**|Up-to-date|Source|SVN hosts the latest version of the Greenstone code. This is handy to get if you want to compile up Greenstone yourself and ensure you have the latest code in doing so.|


  * [[en:developer:compiling_greenstone|Compiling Greenstone]]


**Important Note:** Before proceeding, you're to set all instructed environment variables in the same terminal, unless explicitly stated otherwise.

===== Windows =====

Prerequisites for compiling the source component and source distribution on Windows:
  * Java JDK 6.x or later. For compiling on Windows 64 bit, need the 64 bit version of JDK. For compiling Greenstone 3.06 and onwards, need JDK 7.x or later.
  * PERL: if you're using GS3.07 or earlier, get ActivePerl for Windows. From GS3.08 onwards, binaries and source distributions come with a [[http://trac.greenstone.org/browser/main/trunk/release-kits/shared/windows/perl.zip|Strawberry Perl]] located in the GS3's ''gs2build\bin\windows\perl'' folder.
  * Visual Studio 8 or later (Visual Studio 12 on 64 bit Windows 10 worked too.)
  * (If you want to compile GS2 or GS3 with debugging on, you will need Microsoft SDK)
  * Additionally //for Greenstone3//: Apache ANT

You will need to set up your environment to locate and use the above. For this purpose, it's handy to create a bat file that you can always run before compiling Greenstone. A template bat file follows. Adjust it to contain the paths to your installations of the above. We'll call this bat file **''setupenv.bat''** and refer to it as such below.
<!-- TODO: add in line for Microsoft SDK -->

<code>
@echo off

:: Script to set up Java, ant, perl
:: And set up Visual Studio for compiling the C/C++ in GS2 and GS3

:: First: change to using Windows short filenames to allow spaces in the filepath when compiling 
:: For this, need to cd into the folder where this script lives using the short filename path to this folder
:: %0 is this script
:: %~dp gives the full path to the folder containing this script.
:: %~s gives the windows short filename version
:: Combine to get what we want.
:: Note that this will leave the DOS prompt pointing to short filename of the folder
cd "%~sdp0"


set JAVA_HOME=C:\Program Files\Java\jdk1.7.0_25
if not exist "%JAVA_HOME%" (
echo %JAVA_HOME% not found. Exiting...
goto done
)

:: From GS3.08 onwards, a Strawberry Perl is included with binaries and source distributions
:: in your GS3's gs2build\bin\windows\perl folder
set PERLPATH=C:\Users\Me\perl

:: If you're compiling Greenstone 3, you'll also need ANT
:: Note that GS3 binaries ship with Ant, located in ''packages\ant''
:: For GS3 source distributions, download your own ANT and extract it and set
:: the environment variable below and adjust the PATH.
set ANT_HOME=C:\Users\Me\ant

:: Add the bin folders of Perl and Java (and Ant for GS3) to your PATH
set PATH=%PERLPATH%\bin;%ANT_HOME%\bin;%JAVA_HOME%\bin;%PATH%

:: If you want to compile GS2 with debugging on, you also need MS SDK and the following line:
:: call "C:\Program Files\Microsoft SDKs\Windows\v6.1\Bin\SetEnv.cmd"

:: Set up Visual studio environment. vcvars<num>.bat may be called vsvars<num>.bat
:: Running VS in 64 bit mode doesn't work for GS2, need to run in 32 bit mode. 
:: (It may be apache httpd that needs 32 bit mode to compile.)
:: For now only VS9.0 (VS2008) works

:: FOR COMPILING GS2 on WINDOWS:
:: OR FOR COMPILING GS3 ON 32 BIT WINDOWS:
:: (if using 64 bit windows to compile GS3, comment out the following line by prefixing with two colons)
call "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat"


:: FOR COMPILING GS3 ON 64 BIT WINDOWS, 
:: only confirmed to work with MS Visual Studio versions 9.0 and 12 so far:
:: (if using 64 bit windows, uncomment the following line by removing the two colons at its start)
:: call "C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat" amd64

:done
</code>
To make it easier for developers, a batch file containing placeholders you can adjust is already prepared and discussed at [[http://wiki.greenstone.org/doku.php?id=en:developer:windows_source_install|Source Installation on Windows]].
==== Source Component ====
<tabbox Greenstone3>
**Note:** Greenstone 3 does not at present compile successfully if it was installed in a place containing spaces. The solution is to move the installed GS3 folder out into a different location, one without spaces in the filepath, //before// compiling. Once compiling is done, you can move your installed GS3 folder back to its original location.

  - Get the source component zip file from the downloads page.
  - Unzip it directly into your Greenstone installation folder, make sure not to create intermediary folders. If Windows prompts you about whether you want existing folders merged (and existing files replaced), tick the box to confirm for all and click in the affirmative.
  - Open a DOS prompt to run the following scripts and commands:
  - Set up the environment for compiling Greenstone by running the setupenv.bat script described further above: ''setupenv.bat''. For 64-bit Windows, make sure to set JAVA_HOME to a 64-bit JDK7, add its bin folder to the PATH, and to ''call vsvarsall.bat amd64'' of your Visual Studio (version 9 has been tested to work).
  - Go into your Greenstone installation folder, ''cd C:\path\to\greenstone3'', and run ''gs3-setup.bat''. This will allow Greenstone to unzip zip files. It will also provide an ANT installation in case you don't have one, since the GS3 binary comes with ant.
  - The Java Runtime (JRE) included with Greenstone 3 binaries is a 32 bit Java 7 runtime. This means that //if the Windows machine that you're recompiling the binary with the source component on is not 32 bit Java 7 too//, then you will need to do the following before compiling \\
     * rename ''packages\jre'' to something else, so that when Greenstone runs after compiling, it uses your system Java rather than the old 32 bit JRE v7.
     * run ''ant distclean'' from the toplevel Greenstone installation folder, to clear all the older compile products created by compiling with 32 bit Java 7.\\ If you see a failure message about being unable to delete a file called 'cp.jar', run ''del \path\to\cp.jar'' manually from the command line for the exact file path listed. Then re-run ''ant distclean''. There are several cp.jar files in different locations of the GS3 installation, any or all of which can cause this failure message. So keep repeating the cycle of re-running ''ant distclean'' then manually running ''del'' on any cp.jar file listed in any failure message, until the ''ant distclean'' step finally succeeds (so without failure messages). This issue may be due to Windows having filelocks on the ''cp.jar'' files.
     * you may also want to want to delete ''gli\jar'' and ''gli\classes\org'', if they exist, to clear up GLI before recompiling.     
  - Finally, you can compile Greenstone 3. Still in your Greenstone installation folder, run ''ant install''.

**To run GS3 after re-compiling:**

To run GLI after recompiling your binary on a 64 bit Windows machine, you need the same version of JDK or JRE (and for the same bit architecture, 32 or 64 bit) as that you used to compile up Greenstone 3. You will need this Java's ''bin'' subfolder on your PATH. You'll also need the ''bin'' subfolder of ANT on the PATH.

**Note if you want to use the bundled JRE for Windows 64 bit:**

To run GLI after recompiling your binary on a 64 bit Windows machine, you need JDK 7 (or JRE 7) for 64 bit set up in your environment, since the JRE included with the Greenstone Windows binary is for 32 bit, as the Greenstone Windows binary itself is 32 bit. Otherwise, the problem seen when running the 64-bit recompiled GS3 server with the 32-bit JRE included in GS3 binaries is a tomcat error explaining the discrepancy between the two architectures.

Therefore, to run GLI after compiling GS3 for 64 bit, add the bin folder of JRE 7 for 64 bit to the PATH, or set JAVA_HOME to JDK 7 64 bit and add its bin folder to the PATH. Then run GLI in this environment.
<tabbox Greenstone2>
  - Get the source component zip file from the downloads page.
  - Unzip it in your Greenstone installation. If Windows prompts you about whether you want existing folders merged (and existing files replaced), tick the box to confirm for all and click in the affirmative.
  - Open a DOS prompt
  - Set up the environment for compiling Greenstone by running the setupenv.bat script described further above: ''setupenv.bat''
  - Go into your Greenstone installation: ''cd C:\path\to\greenstone2''
  - Run the makegs2 script: ''makegs2.bat'' for 32 bit windows or ''makegs2x64.bat'' for 64 bit windows
  - It will prompt you about whether to extract certain important files. Type Y to do so.
  - It will next present you with various compilation options. You want to type 4 ("All") to tell it to compile everything.
  - It will take some minutes to compile after which, if there are no errors, you can start running GLI or the gs2-server.
  - If you want to recompile GLI go into your Greenstone's gli subfolder: ''cd gli''. Next, type: ''makegli.bat''. To recompile the GLI jar files, such as used for Remote Greenstone situations, type: ''makejar.bat''.


**Note:** Building collections that use lucene as their indexer requires Java. If you compiled up GS2 using a later version of Java than the version of JRE included in the binary (Java 7), then building a lucene collection may produce error messages about incompatible java versions. In such a case, rename your GS2 installation ''packages/jre'' subfolder so that Greenstone no longer finds the bundled JRE. Before re-running GLI to rebuild your lucene collection, ensure that the Java you compiled GS2 with is in the environment (so that JAVA_HOME set to it and its ''bin'' folder is on the PATH). Remember to use the same Java environment to launch this GS2 installation's applications in future.
</tabbox>
==== Source Distribution ====
<tabbox Greenstone3>
  - Get the source distribution zip file from the downloads page.
  - //Unzip it in a location with no spaces in the filepath.//
  - Open a DOS prompt to run the following scripts and commands:
  - Set up the environment for compiling Greenstone by running the setupenv.bat script described above: ''setupenv.bat''. (For 64-bit Windows, make sure the script sets JAVA_HOME to a 64-bit JDK7, and adds its ''bin'' folder to the PATH, and that the script then calls ''vsvarsall.bat amd64'' of your Visual Studio. VS Version 9 has been tested to work.)
  - Go into your Greenstone 3 installation folder, ''cd C:\path\to\Greenstone3\'', and run ''gs3-setup.bat''.
  - Now you can finally compile Greenstone 3. Still in your Greenstone installation folder, run ''ant install''.
  - It can take several minutes to compile up.

**Notes for Windows 64 bit:**

To run GLI or the gs3-server after compiling the source code on a 64 bit Windows machine, you need your environment to be set up with JDK 7+ (or JRE 7+) for 64-bit and Ant: set the JAVA_HOME environment variable to your 64 bit JDK and add the JDK's ''bin'' folder to the PATH. Also set the ANT_HOME environment variable and add its ''bin'' folder to the PATH. Then run GLI or gs2-server in this environment using the gli.bat and gs2-server.bat scripts. 
<tabbox Greenstone2>
  - Get the source distribution zip file from the downloads page.
  - Unzip it
  - Open a DOS prompt
  - Set up the environment for compiling Greenstone by running the setupenv.bat script described above: ''setupenv.bat''
  - Go into your Greenstone installation: ''cd C:\path\to\Greenstone2''
  - Run the makegs2 script: ''makegs2.bat'' for 32 bit windows or ''makegs2x64.bat'' for 64 bit windows
  - It will prompt you about whether to extract certain important files. Type Y to do so.
  - It will next present you with various compilation options. You want to type 4 ("All") to tell it to compile everything.
  - It will take some minutes to compile after which, if there are no errors, you can start running the gs2-server.
  - If you want to run GLI as well, this will need to be compiled. To compile it, go into your Greenstone's gli subfolder: ''cd gli''. Next, type: ''makegli.bat''. Once it's done, you can run gli from the commandline with ''gli.bat'' from inside the gli folder, or with ''gli\gli.bat'' from the toplevel Greenstone installation folder.
  - If you wish to compile up the GLI jar files, such as for Remote Greenstone situations, run the following from within the gli folder: ''makejar.bat''.
  - You will need to enable the Administration pages if you want access to them. Do so by editing your Greenstone installation's ''etc/main.cfg'' file. Change the ''status'' field value from ''disabled'' to ''enabled''. In that case, you may also want to change the admin password for the Adminstration pages. Use a DOS prompt to run: ''gsicontrol.bat configure-admin'' which will allow you to (re)set the password for username ''admin'' (the default admin password is the same as the username).
  - If you don't already have an imagemagick installed and want to have //imagemagick// in your GS installation, as imagemagick is used to create thumbnail and screenview size images from your full size images, then grab the pre-compiled imagemagick Windows binary from http://trac.greenstone.org/export/head/gs2-extensions/imagemagick/trunk/imagemagick-windows.zip and unzip it into your compiled up GS2 source distribution folder's ''bin\windows'' subfolder, so that you end up with an ''imagemagick'' folder in there. Make sure it hasn't created an extra level of an ''imagemagick'' subfolder on extraction, like ''bin\windows\imagemagick\imagemagick''. (The dll files should be at the ''bin\windows\imagemagick'' level.)
</tabbox>


==== Uptodate source code from SVN ====

Prerequisites for compiling on Windows:
  * Java JDK 6.x or later
  * PERL (ActivePerl for Windows
  * Visual Studio 8 or later
  * (If you want to compile GS2 or GS3 with debugging on, you will need Microsoft SDK)
  * Additionally: Apache ANT for Greenstone3

In addition to the Prerequisites for compiling Greenstone on Windows listed above, to install Greenstone from SVN source on Windows, you need to [[en:developer:install_svn|install svn]].

(**NOTE:** Some of the prerequisite packages are available from greenstone's svn and are put into a subfolder called ''local''. For instructions on compiling up from source using the ''local'' folder, refer to the [[en:developer:windows_source_install|Windows source installation]] page\\ Otherwise, proceed with the following.)

SVN, ANT, and JAVA must be put on PATH and Visual Studio must be set up for compiling the C/C++ code,
which can be accomplished using the file ''vcvars<number>.bat'', or ''vcvarsall.bat'' passing in ''amd64'' for 64 bit windows.

<tabbox Greenstone3>
Run the following:
<code>
svn co http://svn.greenstone.org/main/trunk/greenstone3
ant
ant prepare
ant install
</code>
<tabbox Greenstone2>
Then run:
<code>
makegs2.bat
</code>
  * Choose yes twice
  * Choose step 4 to compile ALL without debugging
</tabbox>

For more detailed instructions on source installation, please refer to the 
[[en:developer:windows_source_install|Windows]] source installation page.


===== Linux/Mac =====
In order to install Greenstone from source on Linux, you need to have the following installed:
  * [[en:developer:install_svn|SVN]]
  * ANT
  * Java JDK. JDK 7 for Greenstone 3.06 and onwards. \\ **WARNING:** But **do not use Oracle's JDK version 1.8.0_//161//** as it is problematic: failing to compile GS3 and also failing to successfully run the [[http://wiki.greenstone.org/doku.php?id=en:release:3.09_release_notes&s[]=191#troubleshooting|solr web servlet]] in GS3 binaries. We found that Oracle's JDK versions 1.8.0_144 and **1.8.0_//191// worked** for us.
  * C/C++ compiler: XCode on Mac, gcc/g++ on Linux

==== Source Component ====
<tabbox Greenstone3>
  - Download and extract the Source Component for your Operating System into the top-level folder of your Greenstone 3 binary installation. For Linux/Mac, download the tar.gz version as zip doesn't preserve necessary file permissions.
  - Set up ant and Java: set JAVA_HOME (to JDK 7 for Greenstone 3.06, JDK 8 for Greenstone 3.11 onwards) and add its ''bin'' folder to the PATH. If you're on a 64 bit machine, you'll need a JDK for 64 bit machines, if you're on a 32 bit machine, you will need a JDK for 32 bit machines. Set ANT_HOME and add its ''bin'' folder to the PATH. If you don't already have ant installed, the Greenstone 3 binary comes with one in its ''packages/ant'' folder. Set that to ANT_HOME, and add its ''bin'' subfolder to the PATH.\\ <code>
export JAVA_HOME=/path/to/your/jdk7
export ANT_HOME=/path/to/GS3/packages/ant
export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH
</code>**If you're on Mac OS version 10.11/El Capitan**, set CFLAGS, CXXFLAGS and JNIFLAGS as follows: \\ <code>export CFLAGS="$CFLAGS -I$JAVA_HOME/include -I$JAVA_HOME/include/darwin"
export CXXFLAGS="$CXXFLAGS $CFLAGS"
export JNICFLAGS="$JNICFLAGS $CFLAGS"</code> **Since GS3.08 and until GS3.10**, if you're on 64 bit linux, you will also need to add -fPIC to the CFLAGS and CXXFLAGS environment variables: \\ <code>export CFLAGS="-fPIC $CFLAGS"
export CXXFLAGS="-fPIC $CXXFLAGS"</code>If at any point you run ''source ./gs3-setup.sh'' before compiling, you will have to set up the Java JDK environment again, because the ''gs3-setup'' script will make the included JRE the default Java.
  - The Java Runtime (JRE) included in binaries from Greenstone 3.07 onward is version 7 and version 8 for Greenstone 3.11 onward. For 32 bit linux binaries, the included JRE is 32 bit and for 64 bit linux binaries the JRE is 64 bit. //If you have set up a system Java of a version different from the JRE included//, then \\
     * rename the ''packages\jre'' folder to something else, so that when Greenstone runs after compiling, it uses your system Java rather than the old 32 bit JRE v7.
     * run ''ant distclean'' from the toplevel Greenstone installation folder, to clear all the older compile products that were compiled with Java 7.
     * you may also want to want to delete ''gli/jar'' and ''gli/classes/org'', if they exist, to clear up GLI before recompiling.
  - Most of the linux and mac machines we tested require the gnome-lib extension. Without it, if compilation fails with an error message about ''wvware'', then it means you need the gnome-lib extension. \\ The Greenstone 3 binaries on Mac come with a reduced gnome-lib-minimal that is not sufficient for compiling. Move this out of the way first: rename or move away your Greenstone 3 installed folder's ''gs2build/ext/gnome-lib-minimal'' folder. \\ You can grab the gnome-lib-minimal package by visiting http://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk, selecting the link to the ''gnome-lib-minimal'' version for your operating system and architecture, then clicking on the download link on the subsequent page. Download it into your Greenstone 3's ''gs2build/ext'' folder.
  - Use the terminal to extract the downloaded gnome-lib-minimal extension and set up the gnome-lib environment for compiling as follows:\\ <code>
cd gs2build/ext
tar -xvzf gnome-lib-minimal-<your-OS-version>.tar.gz
cd gnome-lib-minimal
source ./devel.bash
cd ../../..
</code>
  - In the same terminal, you can now finally run ''ant install'' //from the toplevel folder// of the Greenstone 3 installation to start compiling. It can take several minutes. \\ **Note:** If at this stage, compilation fails at Perl's XMLParser with [[http://gentoo.2317880.n4.nabble.com/PREFIX-revolutions-in-the-bootstrapping-world-td181438.html|the error message]] "Only one of PREFIX or INSTALL_BASE can be given. Not both.", then in the same terminal check if the INSTALL_BASE environment variable is set, and if it is, unset it (and PERL_MM_OPT if it was set to this) and re-run ''ant install'':\\ <code>
> env | grep INSTALL
PERL_MM_OPT=INSTALL_BASE=/something.../
> export INSTALL_BASE=
> export PERL_MM_OPT=
> ant install</code>


**Note:**

The gnome-lib environment may conflict with graphical applications on Linux systems. After compiling, open a fresh terminal to run GLI or other graphical applications. But make sure the new terminal has the environment set up for Java and Ant too before running any Greenstone applications like the Greenstone Server (gs3-server) and GLI.


<tabbox Greenstone2>
  - Download the Source Component tar.gz file that matches with your Greenstone binary version, and put it in your Greenstone installation folder. For Linux/Mac, you want the tar.gz version because the zip version doesn't preserve necessary file permissions.
  - Use a terminal to extract the downloaded file's contents into your Greenstone installation folder: \\ <code>cd <your greenstone folder>
tar -xvzf <source-componentfile>
</code>
  - Move the ''ext/gnome-lib-minimal'' out of the way or rename it to something else.
  - If you want to compile up gnome-lib yourself, skip this step. If you want to use a pre-compiled gnome-lib binary (to save on all the time of compiling gnome-lib), download the gnome-lib-minimal package for your OS by visiting http://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk \\ Then unzip the downloaded gnome-lib minimal package into your ''greenstone2-home/ext'' folder.
  - Make sure JAVA_HOME is set and the bin folders for Java and Perl are on your PATH.
  - Run the following, which will get gnome-lib and compile it up as it's compiling your Greenstone: \\ <code> ./makegs2.sh gnome-lib
cd gli
./makegli.sh
./makejar.sh
</code> \\ **Note** that some Linux machines don't need gnome-lib at all, in which case, the first compilation step above would just be ''./makegs2.sh''. To tell whether your Linux machine needs gnome-lib, try compiling it without it first. If compilation fails during wvware, then you need gnome-lib. The Mac Mountain Lion and Leopard machines we tested it on required gnome-lib. \\ Note also that, starting with GS2.87 releases, -fPIC is automatically prepended to the CFLAGS environment variable on //64-bit// unix systems by the ./makegs2.sh script, as this tends to be needed for compiling. 


INSTRUCTIONS FOR OLDER VERSIONS OF GREENSTONE:

  * Go to **the folder where you unpacked the Greenstone binary distribution**. For example, if this folder were called gsdl-2.80-unix:
<code>> cd gsdl-2.80-unix</code>

  * Run Install Shield again:
<code>> ./setupLinux.bin</code>

  * You already have Greenstone installed, therefore when it asks you whether you want to install it as a web server choose **Custom Setup**.

  * Untick everything. Tick only the **Source Code** option. If it asks you whether you want to overwrite files you already have, press the **No to All** button.

  * Go into $GSDLHOME -- the folder where you installed Greenstone. 
<code>> cd $GSDLHOME</code>
See if there is a folder called **indexers**. If there is none (as is the case with Greenstone 2.80, but it is intended to be included in future Greenstone binary releases), then you need to get it. To get it from SVN (and into the $GSDLHOME folder where you now are):
<code>> svn co http://svn.greenstone.org/indexers/trunk indexers</code>
If you don't know what subversion/SVN is or don't have it installed, then you need to get the indexers folder by downloading the entire Source Distribution and compiling that, see the [[en:user_advanced:installation|source install]] page.

  * Now that you are in $GSDLHOME and have the indexers folder in it, you can **compile it all** by typing the following in an xterm (note that each step can take a few minutes):
<code>> ./configure
> make all
> make install
</code>
All going well, this would have compiled it. If you had any difficulties during compilation, see the [[en:user_advanced:installation|source install]] page.

  * Still in $GSDLHOME, **set up the environment for Greenstone**:
<code>> source setup.bash</code>

  * To get the Greenstone Librarian Interface (GLI) working, you need to compile that. So go into the gli folder, which is located in $GSDLHOME, and **compile GLI**:
<code>> cd gli
> ./makegli.sh
> ./makejar.sh
</code>
(The above would have compiled GLI and then the last line created the executable jar file from the compiled files.) 


You can run GLI with:
<code>> ./gli.sh</code>
Unfortunately there's **a non-intrusive bug** in Greenstone 2.80's GLI when installed from the source included in the binary distribution. If upon running GLI, you see the following on your xterm:
<code>Running the Greenstone Librarian Interface...
/usr/share/themes/Clearlooks/gtk-2.0/gtkrc:60: Engine "clearlooks" is unsupported, ignoring
Version: 2.80

Exception in thread "AWT-EventQueue-0" java.lang.NullPointerException
        at javax.swing.plaf.synth.SynthContext.getPainter(SynthContext.java:181)
        ....
</code>
You can correct the problem above, by 
  * going to the directory $GSDLHOME/gli/src/org/greenstone/gatherer
  * opening its file GathererProg.java in a text editor
  * and replacing the line 
<code>UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());</code>
with:
<code>UIManager.setLookAndFeel("javax.swing.plaf.metal.MetalLookAndFeel");</code>
  * Save the file you just edited. 
  * Finally, you need to recompile GLI again as explained just above.

  * Assuming your web server is set up and running, you can **view the pages Greenstone serves from the browser** at http://WebServerName:WebServerPort/gsdl/cgi-bin/library 


where the WebServerName and WebServerPort are what you specified when you [[en:user_advanced:gs2_server| set up your web server]]. 
</tabbox>
==== Source Distribution ====


In the terminal:
  * set JAVA_HOME. For GS3, also set ANT_HOME \\ To set these, you can find out where java is installed on your unix system by first running ''where java''. Doing so should display a system location. Then run ''ls -la <java-location>'' using that location value. If the result of this ''ls'' operation shows that the location is a symlink, run ''ls -la <symlink>'' on the symlink, until all symlinks are exhausted and you get to an actual location on the file system. Having found the actual location of java, you don't want the ''bin'' directory, but its containing folder. Set this as JAVA_HOME. Locate and set ANT_HOME in similar manner.
  * Add svn/bin to PATH
  * Add JAVA_HOME/bin to PATH
  * For GS3, also add ANT_HOME/bin to PATH
It may be easiest to create a bash script to set the above environment variables. Then you could run that script before compiling and, in a separate terminal, before running Greenstone applications.

<code>
export ANT_HOME=/path-to-your/ant
export JAVA_HOME=/path-to-your/java
export PATH=/path-to-your/svn/bin:$JAVA_HOME/bin:$ANT_HOME/bin:$PATH
</code>

<tabbox Greenstone3>
  - Download the Source Distribution for your Operating System and extract it into the location where you want Greenstone installed. For Linux/Mac, download the tar.gz version as zip doesn't preserve necessary file permissions.
  - Make sure JAVA_HOME is set (to JDK 7 for Greenstone 3.06, JDK 8 from Greenstone 3.11 onwards) and that its ''bin'' folder is added to the PATH. If you're on a 64 bit machine you need a JDK for 64 bit machines, if you're on a 32 bit machine, you will need a JDK for 32 bit machines. Also set ANT_HOME to an ant installation and add its ''bin'' folder to the PATH.
  - Most of the linux and mac machines we tested require the gnome-lib extension. Without it, if compiling fails with an error message about ''wvware'', then it means you need the gnome-lib extension. You can grab it by visiting http://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk, selecting the link to the ''gnome-lib-minimal'' version for your operating system and architecture, then clicking on the download link on the subsequent page. Download it into your extracted Greenstone 3's ''gs2build/ext'' folder.
  - Use the terminal to extract the downloaded gnome-lib-minimal extension and set up the gnome-lib environment for compiling as follows:\\ <code>
cd gs2build/ext
cd gnome-lib
# gnome-lib can take longer to compile.
# Alternatively, if you had internet access and
# had grabbed and extracted the gnome-lib-minimal tarball as above, then:
#tar -xvzf gnome-lib-minimal-<your-OS-version>.tar.gz
#cd gnome-lib-minimal
source ./devel.bash
cd ../../..
</code>
  - **If you're on Mac OS version 10.11/El Capitan**, set CFLAGS, CXXFLAGS and JNIFLAGS as follows: \\ <code>export CFLAGS="$CFLAGS -I$JAVA_HOME/include -I$JAVA_HOME/include/darwin"
export CXXFLAGS="$CXXFLAGS $CFLAGS"
export JNICFLAGS="$JNICFLAGS $CFLAGS"</code> **Since GS3.08 and upto and including GS3.10**, if you're on 64 bit linux, you will also need to add -fPIC to the CFLAGS and CXXFLAGS environment variables: \\ <code>export CFLAGS="-fPIC $CFLAGS"
export CXXFLAGS="-fPIC $CXXFLAGS"</code>
  - In the same terminal, you can now finally run ''ant install'' from //the toplevel folder// of your extracted Greenstone 3 installation to start compilation. It can take several minutes. \\ **Note:** If at this stage, compilation fails at Perl's XMLParser with [[http://gentoo.2317880.n4.nabble.com/PREFIX-revolutions-in-the-bootstrapping-world-td181438.html|the error message]] "Only one of PREFIX or INSTALL_BASE can be given. Not both.", then in the same terminal check if the INSTALL_BASE environment variable is set, and if it is, unset it (and PERL_MM_OPT if it was set to this) and re-run ''ant install'':\\ <code>
> env | grep INSTALL
PERL_MM_OPT=INSTALL_BASE=/something.../
> export INSTALL_BASE=
> export PERL_MM_OPT=
> ant install</code>

**Note:**

The gnome-lib environment may conflict with graphical applications on Linux systems. After compiling, open a fresh terminal to run GLI or other graphical applications. Make sure the new terminal has the environment set up for Java and Ant too before running any Greenstone applications like the Greenstone Server (gs3-server) and GLI.


<tabbox Greenstone2>
  - Download the Source Distribution and extract it. For Linux/Mac, please use the tar.gz version as zip doesn't preserve necessary file permissions.
  - If you want to compile up gnome-lib yourself, skip this step. If you want to use a pre-compiled gnome-lib binary (to save on all the time of compiling gnome-lib), download the gnome-lib-minimal package for your OS by visiting http://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk \\ Then unzip the downloaded gnome-lib minimal package into your greenstone2-home/ext 
  - Make sure JAVA_HOME is set and the bin folders for Java and Perl are on your PATH.
  - Run the following, which will get gnome-lib and compile it up as it's compiling your Greenstone.\\ <code>
./makegs2.sh gnome-lib imagemagick
cd gli
./makegli.sh
./makejar.sh
</code> \\ **Note** that some Linux machines don't need gnome-lib at all, in which case, the first compilation step above would just leave out the ''gnome-lib'' parameter when running the ''makegs2.sh'' script above. To tell whether your Linux machine needs gnome-lib, try compiling it without it first. If compilation fails during wvware, then you need gnome-lib. The Mac Mountain Lion and Leopard machines we tested it on required gnome-lib.\\ **Note** that if you already have imagemagick installed on your system or don't need it, you can leave out the ''imagemagick'' parameter to the ''makegs2.sh'' script.
  - You will need to enable the Administration pages if you want access to them. Do so by editing your Greenstone installation's ''etc/main.cfg'' file. Change the ''status'' field value from ''disabled'' to ''enabled''. In that case, you may also want to change the admin password for the Adminstration pages. Use a DOS prompt to run: ''gsicontrol.bat configure-admin'' which will allow you to (re)set the password for username ''admin'' (the default admin password is the same as the username).

</tabbox>
==== Uptodate source code from SVN ====

<tabbox Greenstone3>

  - Make sure you have SVN installed and on your Path
  - Make sure you have set up Ant and Java in the environment too: set JAVA_HOME (to JDK 7+) and add its ''bin'' folder to the PATH. If you're on a 64 bit machine, you'll need a JDK for 64 bit machines, if you're on a 32 bit machine, you will need a JDK for 32 bit machines. Set ANT_HOME and add its ''bin'' folder to the PATH.\\ <code>
export JAVA_HOME=/path/to/your/jdk7
export ANT_HOME=/path/to/your/ant
export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH
</code>\\ **NOTE:** Some of the prerequisite packages are available from greenstone's svn and are put into a subfolder called ''local''. For instructions on compiling up from source using the ''local'' folder, refer to the [[http://wiki.greenstone.org/doku.php?id=en:developer:unix_source_install|Unix source installation page]]. Otherwise, proceed with the following.
  - Checkout the code: <code>
svn co http://svn.greenstone.org/main/trunk/greenstone3
</code>
  - Generate the file ''build.properties'' with: <code>
ant 
</code>\\ Now, if necessary, you can customise the port/hostname fields in the newly generated toplevel file ''build.properties''.
  - Most Linux systems and probably all the newer Mac systems require //gnome-lib// for successful compilation. If you wish to //compile gnome-lib// along with GS3, uncomment the following line in ''build.properties'' to activate it <code>
checkout.gnomelib.ext=true
</code>\\ Skip this step if you don't want to //compile// the gnome-lib extension when compiling GS3, but prefer to use a pre-compiled ''gnome-lib'' to speed up the process, in which case you'll carry out step 9 later.
  - If you want to compile imagemagick from source on Unix systems (though for Mac you can also use the precompiled imagemagick binary*), uncomment the following line in ''build.properties'' to activate it <code>
checkout.imagemagick.ext=true
</code>\\ **This is not successfully compiling at present on MacOS High Sierra (10.13.4).** So use the precompiled imagemagick binary* for that instead.
  - **If you're on Mac OS version 10.11/El Capitan or later**, set CFLAGS, CXXFLAGS and JNIFLAGS as follows: \\ <code>export CFLAGS="$CFLAGS -I$JAVA_HOME/include -I$JAVA_HOME/include/darwin"
export CXXFLAGS="$CXXFLAGS $CFLAGS"
export JNICFLAGS="$JNICFLAGS $CFLAGS"</code> Since GS3.08, **if you're on 64 bit linux**, you will need to add -fPIC to the CFLAGS and CXXFLAGS environment variables: \\ <code>export CFLAGS="-fPIC $CFLAGS"
export CXXFLAGS="-fPIC $CXXFLAGS"</code>
  - Finally, you can start the steps for building GS3 from SVN: <code>
ant prepare</code>
  - This step is only applicable if you had decided on using a //pre-compiled// ''gnome-lib'' in step 5. In that case, visit http://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk and there click on the link for the ''gnome-lib-**minimal**-'' zip/tarball for your operating system. On the next page, click on the download link to download the zip/tarball file, then move this downloaded file into ''gs2build/ext''. After that, unpack and set up your gnome-lib-minimal for compiling as follows: \\ <code>cd gs2build/ext
tar -xvzf gnome-lib-minimal-<your-OS-version>.tar.gz
cd gnome-lib-minimal
source ./devel.bash
cd ../../..
</code>
  - You can now run the compile step: <!--<code>
cd ext 
source devel.bash
cd /back/to/greenstone3-home
</code>
--> <code>
ant install
</code>

* If you want imagemagick and ghostscript on a mac, check out the precompiled binaries from svn **after** the ''ant prepare'' step

<code>
cd gs2build
svn co http://svn.greenstone.org/main/trunk/binaries/mac/intel/imagemagick bin/darwin/imagemagick
svn co http://svn.greenstone.org/main/trunk/binaries/mac/intel/ghostscript bin/darwin/ghostscript
</code>

<tabbox Greenstone2>
  - First grab all the source code from SVN by running the following commands in your terminal \\ <code>
svn co http://svn.greenstone.org/main/trunk/greenstone2 greenstone2
cd greenstone2
svn co http://svn.greenstone.org/main/trunk/gli
</code>
  - If you want to compile up gnome-lib yourself, skip this step. If you want to use a pre-compiled gnome-lib binary, download the gnome-lib-minimal package for your OS by visiting http://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk \\ Then unzip the downloaded gnome-lib minimal package into your greenstone2-home/ext 
  - Compile up Greenstone: \\ <code>
./makegs2.sh gnome-lib
cd gli
./makegli.sh
./makejar.sh
</code>
  - You will need to enable the Administration pages if you want access to them. Do so by editing your Greenstone installation's ''etc/main.cfg'' file. Change the ''status'' field value from ''disabled'' to ''enabled''. In that case, you may also want to change the admin password for the Adminstration pages. Use a DOS prompt to run: ''gsicontrol.bat configure-admin'' which will allow you to (re)set the password for username ''admin'' (the default admin password is the same as the username).
</tabbox>



For more detailed instructions on installation, please refer to the [[en:developer:linux_source_install|Linux]]
and [[en:developer:mac_source_install|Mac OS]] source installation pages.

==== Running the installer in text-only mode ====
  - If you're on Linux or Mac, give the binary of the installer execute permissions
  - Then run it by passing in the -textonly flag, as shown below.
  - Follow the instructions on the screen thereafter. If you mistype at any stage, press ctrl-C to start again.

<code>
> ./Greenstone-3.06rc1-linux-x64 -textonly
</code>

**NOTE:** Previously, the instructions for running the installer in text-only mode were incorrect. They advised running the installer wrongly using ''./Greenstone-3.06rc1-linux-x64 text-only'', which rather triggered the default behaviour of the installer software (antinstaller) for a different kind of text-only installation rather than triggering the Greenstone installer's specific -textonly mode. Unfortunately, the wrong route would not install the bundled JRE into the Greenstone installation, despite requiring the Greenstone user to run the ''java'' command in the very next step of the install.

===== Installation for a networked lab environment =====

To support use of Greenstone 3 in a networked lab environment, it is possible to adjust the configuration settings of the installation to have one shared installation of the software, but allow individual
users to build and serve collections from their own area of the file system.  We refer to this as a "dispersed GS3" setup.  
More specifically, it is appropriate for a situation where your Greenstone 3 is to be distributed across 3 locations of your Windows machine: an installation location which is read-only regular users, and to which only the administrator has write permissions; a user-web location that is writable and specific to a user; and a temporary (typically local) file system area the user has read/write permissions to.  

In the following text we describe the setup procedure for Windows, with 
Greenstone installed in C:/Program Files/.  The same capability will work in networked situations 
for MacOS and Linux labs, choosing an appropriate directory such as /usr/local/Greenstone3 
as the location to install the GS3 software to. 

For one computer, here's how you can have Greenstone installed centrally (e.g. Program Files), but then have each different user when working at that computer have their own instance of the Greenstone 3 sites, collections, and customisations of the interface.

Install GS3 as an administrator using the binary installer. Then set the following 4 properties in build.properties:

  * set ''using.user.web=true''
  * set ''web.home=${user.home}/greenstone3/web''\\ [[https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html|Java's user.home property]] should resolve to a writable user location, e.g  web.home will work out to be something like C:/Users/me/greenstone3/web). You can decide on other locations within ${user.home}, as you choose. For example, you can set web.home=${user.home}/gs3/myweb. \\ Or if your lab setup is such that you're mounting each user's account at H: at each log in, then just set web.home=H:/gs3/web. Then, whenever any user is logged in, their collection data will be in H:/gs3/web. So web.home in such a case may look static and fixed to somewhere in H: in the build.properties file, but it's actually not static, since it changes to refer to different users' accounts based on who is logged in.
  * set ''gsdl3home.isreadonly=true''
  * set ''gsdl3.writablehome=${java.io.tmpdir}/greenstone/web'' 

Set all the property values exactly as above, except ''web.home'', which you should customise to point to a location that is writable by the GS3 user where the user can create collections. File path separators should be URL style slashes, so forward slash, /.

Now if you replicate the installation to other machines in the lab, your users can log into any machine and continue working with Greenstone3.

<!--
greenstone-307.cmd file contains:

@goto %1

:start

robocopy /e /purge /np image "C:\Program Files\Greenstone3" /log:image.log

if %ERRORLEVEL% GEQ 4 fail

robocopy /e /xx /np patches "C:\Program Files\Greenstone3" /log:patches.log

if %ERRORLEVEL% GEQ 4 fail

robocopy /e /purge /np startmenu "%ALLUSERSPROFILE%\Start Menu\Programs\Greenstone 3" /log:startmenu.log

if %ERRORLEVEL% GEQ 4 fail

done

-->

===== Source Code Stability =====
Note: This page is aimed at Greenstone developers.

The source code stability system attempts to provide developers with a constant stable code base for development even as the main trunk passes between stable and unstable states. If you are doing development on a working copy of the trunk, but the trunk has bugs which prevent it compiling or running, then it can be very hard to test your changes. Rather than spend time inquiring into those bugs, the stability system gives you a way to temporarily roll your working copy back to the last stable state. Once you have finished testing your changes, you can then roll you working copy forward again and commit your changes. Except in the case where other developers have made significant changes to the trunk, your changes will start working once the trunk is stable again.

The stability system works by periodically checking out the trunk and testing it for stability, then creating a 'stable' tag if and only if the trunk passes these stability tests. For now the stability tests are as simple as checking that the release kits on all three main operating systems were able to successfully create a release from the trunk. In the future, these checks could be extended to include regression tests, installer tests, tests to the runtime system and anything else which might further 'prove' the stability of the trunk. Stable tags related to Greenstone2 are named 'stable' and stable tags related to Greenstone3 are named 'stable3'.

To make your working copy stable, change to the root directory of the working copy and run one of these commands:
<code>
 (For Greenstone2): svn switch http://svn.greenstone.org/gsdl/stable
 (For Greenstone3): svn switch http://svn.greenstone.org/greenstone3/stable3
</code>
Or to checkout a fresh stable working copy, run one of these commands:
<code>
 (For Greenstone2): svn checkout http://svn.greenstone.org/gsdl/stable gsdl
 (For Greenstone3): svn checkout http://svn.greenstone.org/greenstone3/stable3 greenstone3
</code>

Then test your changes and/or keep working on them. Once you are ready to commit your changes, switch back to the trunk:
<code>
 (For Greenstone2): svn switch http://svn.greenstone.org/gsdl/trunk
 (For Greenstone3): svn switch http://svn.greenstone.org/greenstone3/trunk
</code>
And commit as normal.

**Note**: The stable tags are read-only. (Only the nightly tasks that create the stable tags can write to them.) This is for good reason; allowing commits to the stable tag would be lost the next time the trunk was tagged as stable.

The projects 'gli', 'gs2build', 'indexers' and 'documentation' also have stable tags. 
You can execute a command like the following to switch to the stable tag for one of 
these projects:

''svn switch <nowiki>http://</nowiki>svn.greenstone.org/**//project-name//**/stable[3]''

And switch back with:

''svn switch <nowiki>http://</nowiki>svn.greenstone.org/**//project-name//**/trunk''

**Note**: Though the stable branches are in separate locations in the repository, they should be considered as one unit. To get a //bona fide// stable working copy, each project which made up the working copy would have to be switched to the stable tag of the project. Mixing of 'stable' and 'stable3' tags would also prevent a working copy from being a //bona fide// working copy.





===== Moving a Greenstone installation =====
For Linux, you will need to uninstall your Greenstone first and then reinstall it in the new location.

For Windows:
In the case of GS2.83, if you move your Greenstone2 installation folder to some other location, make sure that you relocate it such that there are no spaces in its new path. For instance, "C:\Program Files\myfolder\greenstone2" contains a space between "Program" and "Files", which is not supported in version 2.83. In future versions of Greenstone, the spaces will not be a problem.

Once you've moved your Greenstone installation, there are a few further things to do to get it to work again:
  - Open your Greenstone 2 installation's cgi-bin\gsdlsite.cfg file and change the value for the GSDLHOME property to reflect the new path to your Greenstone installation.
  - To get the local library server (server.exe) to work from the new location: if your top-level Greenstone installation folder contains the files llssite.cfg and glisite.cfg, delete these. (Note that you should not delete the template files llssite.cfg.in and glisite.cfg.in!) If running the local library server has any issues with Internet Explorer, go to the local library's File>Settings menu and change the Other Browser setting to use Firefox.
  - To get the Apache web server included with Greenstone to work: delete the file lib\java\log4j.properties. (Doing so will ensure that if you execute the gs2-server.bat file--which launches the Greenstone Server Interface--this properties file will be regenerated with the correct value for gsdlhome.)