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 Index Page - from here you can access different versions of this page.
For most users, the main Greenstone download (also called the "binary") with default settings is sufficient, and is very easy to install. However, there are some instances where you may want or need to go through a more advanced installation process:
| 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. |
Important Note: Before proceeding, you're to set all instructed environment variables in the same terminal, unless explicitly stated otherwise.
Prerequisites for compiling the source component and source distribution on Windows:
gs2build\bin\windows\perl folder.
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.
@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
To make it easier for developers, a batch file containing placeholders you can adjust is already prepared and discussed at Source Installation on Windows.
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.
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).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.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.ant distclean from the toplevel Greenstone installation folder, to clear all the older compile products created by compiling with 32 bit Java 7.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.gli\jar and gli\classes\org, if they exist, to clear up GLI before recompiling. 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.
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.)cd C:\path\to\Greenstone3\, and run gs3-setup.bat.ant install.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.
Prerequisites for compiling on Windows:
In addition to the Prerequisites for compiling Greenstone on Windows listed above, to install Greenstone from SVN source on Windows, you need to 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 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.
Run the following:
svn co http://svn.greenstone.org/main/trunk/greenstone3 ant ant prepare ant install
For more detailed instructions on source installation, please refer to the Windows source installation page.
In order to install Greenstone from source on Linux, you need to have the following installed:
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.export JAVA_HOME=/path/to/your/jdk7 export ANT_HOME=/path/to/GS3/packages/ant export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH
If you're on Mac OS version 10.11/El Capitan, set CFLAGS, CXXFLAGS and JNIFLAGS as follows:
export CFLAGS="$CFLAGS -I$JAVA_HOME/include -I$JAVA_HOME/include/darwin" export CXXFLAGS="$CXXFLAGS $CFLAGS" export JNICFLAGS="$JNICFLAGS $CFLAGS"
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:
export CFLAGS="-fPIC $CFLAGS" export CXXFLAGS="-fPIC $CXXFLAGS"
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.
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.ant distclean from the toplevel Greenstone installation folder, to clear all the older compile products that were compiled with Java 7.gli/jar and gli/classes/org, if they exist, to clear up GLI before recompiling.wvware, then it means you need the gnome-lib extension. gs2build/ext/gnome-lib-minimal folder. 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.cd gs2build/ext tar -xvzf gnome-lib-minimal-<your-OS-version>.tar.gz cd gnome-lib-minimal source ./devel.bash cd ../../..
ant install from the toplevel folder of the Greenstone 3 installation to start compiling. It can take several minutes. ant install:> env | grep INSTALL PERL_MM_OPT=INSTALL_BASE=/something.../ > export INSTALL_BASE= > export PERL_MM_OPT= > ant install
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.
In the terminal:
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.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.
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
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.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.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 ../../..
export CFLAGS="$CFLAGS -I$JAVA_HOME/include -I$JAVA_HOME/include/darwin" export CXXFLAGS="$CXXFLAGS $CFLAGS" export JNICFLAGS="$JNICFLAGS $CFLAGS"
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:
export CFLAGS="-fPIC $CFLAGS" export CXXFLAGS="-fPIC $CXXFLAGS"
ant install from the toplevel folder of your extracted Greenstone 3 installation to start compilation. It can take several minutes. ant install:> env | grep INSTALL PERL_MM_OPT=INSTALL_BASE=/something.../ > export INSTALL_BASE= > export PERL_MM_OPT= > ant install
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.
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.export JAVA_HOME=/path/to/your/jdk7 export ANT_HOME=/path/to/your/ant export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH
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 Unix source installation page. Otherwise, proceed with the following.
svn co http://svn.greenstone.org/main/trunk/greenstone3
build.properties with: ant
Now, if necessary, you can customise the port/hostname fields in the newly generated toplevel file build.properties.
build.properties to activate it checkout.gnomelib.ext=true
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.
build.properties to activate it checkout.imagemagick.ext=true
This is not successfully compiling at present on MacOS High Sierra (10.13.4). So use the precompiled imagemagick binary* for that instead.
export CFLAGS="$CFLAGS -I$JAVA_HOME/include -I$JAVA_HOME/include/darwin" export CXXFLAGS="$CXXFLAGS $CFLAGS" export JNICFLAGS="$JNICFLAGS $CFLAGS"
Since GS3.08, if you're on 64 bit linux, you will need to add -fPIC to the CFLAGS and CXXFLAGS environment variables:
export CFLAGS="-fPIC $CFLAGS" export CXXFLAGS="-fPIC $CXXFLAGS"
ant prepare
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: cd gs2build/ext tar -xvzf gnome-lib-minimal-<your-OS-version>.tar.gz cd gnome-lib-minimal source ./devel.bash cd ../../..
ant install
* If you want imagemagick and ghostscript on a mac, check out the precompiled binaries from svn after the ant prepare step
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
For more detailed instructions on installation, please refer to the Linux and Mac OS source installation pages.
> ./Greenstone-3.06rc1-linux-x64 -textonly
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.