2.83 Release Notes
From GreenstoneWiki
Release Name: 2.83
Release Date: 24 November 2009
Released: Windows, GNU/Linux, Mac OS/X and Source distributions of Greenstone v2.83
This is a release designed to be used with the new edition of "How to build a digital library".
Contents |
Installation Instructions
Binary distribution
Upon downloading the installer, run the executable: On Windows and Mac you need to double-click it to launch the installation dialog, on Linux you first need to set the downloaded executable's permissions to executable before you can run it from the terminal. It may take some time for the Greenstone installation dialog to appear. Once the installation dialog displays, you generally need to keep pressing the Next button until it is finished. However, when it asks for the location to install Greenstone in, make sure to choose a location on your file system for which you have access privileges.
When the installation process is finished, you can run the Greenstone Server or the Greenstone Librarian Interface (GLI):
1. On Windows, the included Greenstone Server can be launched from the shortcut in the Start menu. On Mac and Linux, use a terminal (in Macs this is found under Applications > Utilities > Terminal) to go into the Greenstone installation directory and run
./gs2-server.sh
The small Greenstone Server Interface (GSI) dialog will display. Pressing its Enter Library button will open a browser onto your Greenstone Digital Library home page.(*)
Note: The Windows version of Greenstone includes two server applications: server.exe and an apache web server. (Linux and Mac versions of Greenstone include only the apache web server). By default, the server.exe application is launched when you use the Windows Start menu shortcut to launch the server. To use the apache web server included with the Windows version of Greenstone, you would first have to rename the server.exe executable found in your Greenstone installation folder. Then you can run the apache web server by double-clicking the gs2-server.bat file that's also located in your Greenstone installation folder (or you can use the MS-DOS prompt to run this batch file).
By default, your Greenstone pages served using the apache web server will not be viewable from other machines. To change this, go to File > Settings in the Greenstone Server Interface dialog, and tick "Allow external connections". Click OK to save the settings, then press the Restart Library button. (**)
2. The Greenstone Librarian Interface (GLI) can be run from the Windows Start menu. On Mac and Linux, use a terminal to go into the Greenstone installation directory and run
./gli/gli.sh
First, as in (1) above, the Greenstone Server Interface (GSI) dialog will appear. Eventually the Greenstone Librarian Interface (GLI) dialog will appear. Refer to the Greenstone tutorials for examples of using the GLI to create collections of documents. Once you have finished creating a collection, you can preview it by pressing the Preview button from GLI's Create tab. It will open your Greenstone collection in the web browser.(*) (**)
(*) If the web page displays a "Forbidden" message instead, go back to the GSI dialog, and use its File > Settings menu to change the Address Resolution method to one of the other options there. Then press the Restart Library Button in the main GSI dialog and see whether the browser page it opens now is the Greenstone home page. Otherwise try another Address Resolution option from the GSI dialog's Settings menu and see whether the pages are visible now.
(**) If you have your own external web server that you wish to use, then in your Greenstone installation directory, rename the folder apache-httpd to something else. Alternatively, you can rename the file gs2-server.sh (if on Linux/Mac) or gs2-server.bat (if on Windows) to something else.
3. The Client-GLI is the version of the Greenstone Librarian Interface that can be run on different machine from the one that is running the Greenstone server. To be able to run the Client-GLI application, you will need Java 1.4.2 or greater installed and you will need to have:
- Java's bin folder on your PATH
- JAVA_HOME set to point to your Java installation folder
If you follow Java's installation instructions, they will direct you on how to add the Java installation's bin folder to your system's PATH environment variable and how to set the JAVA_HOME environment variable.
If on Windows, you can run client-GLI from its shortcut in the Start Menu. On Linux and Mac systems, you would use a terminal to go into your Greenstone installation folder and then run
./gli/client-gli.sh
When the client-GLI starts up, a small dialog appears asking you to enter the URL of the remote Greenstone server's gliserver.pl file. This URL generally has the form: http://<host>:<port>/greenstone/cgi-bin/gliserver.pl, where you have to fill in the host and port values for the remote Greenstone server. After clicking OK, the client-GLI application window will appear. Client-GLI looks and works just like the GLI, except that most of the document processing takes place on the remote machine where the Greenstone server is running.
Source Components and Source Distributions
There's two ways to get Greenstone 2.83's source code in a compressed format (zip or tar.gz file):
1. If you didn't install a Greenstone binary version, you would get the Greenstone Source Distribution which contains the (uncompiled) source code.
2. If you downloaded and installed the Greenstone binary version already, you would only need to top up your installation with the source code by getting the Source Component. You would then unzip this in your Greenstone directory: On Windows, right-clicking on the zip file and choosing to extract its contents to this location should be sufficient. To extract to the correct location on Linux and Mac systems, you would need to use a Terminal to run "tar -xvzf Greenstone-2.83-source-component.tar.gz" from your Greenstone installation directory. Then all the tar.gz file's contents will end up inside the appropriate folders.
To compile the Greenstone source code, you would need
- XCode for Macs,
- the GNU compiler for Linux and
- Visual C++ (Visual Studio) and Microsoft/Windows Platform SDK for Windows machines.
To configure and compile on Mac and Linux machines, open a Terminal and run the following three commands from the Greenstone installation directory (each of them will take some time, but you can skip the first if you downloaded the Source Component):
./configure --enable-apache-httpd make make install
If you do not wish to compile up the included apache web server, leave the --enable-apache-httpd out of step 1. (See also the section "Additonal notes to compiling manually" below.)
To compile on Windows,
1. Edit the start of the makegs2.bat file in your Greenstone installation directory to contain
- the path to the setenv.cmd file of your Microsoft/Windows Platform SDK installation
- and the path to your Visual Studio's vcvars32.bat file (or vsvars32.bat file for later versions).
2. Then run the makegs2.bat file from the DOS prompt. Type Y to extract the necessary files. When it asks you what you want to compile, either type 3 to compile up the server.exe web server, or type 4 to compile up the apache web server included with Greenstone.
Further Notes on Installation and Running
Apache Notes
Greenstone binary releases come with Apache precompiled and install it by default into Greenstone/apache-httpd.
- Currently there is no option not to install apache. To uninstall it, delete the Greenstone/apache-httpd folder and the gs2-server.sh/bat. To disable the use of it, rename the apache-httpd folder to something else (then you can rename it back if you change your mind later).
- If you have an existing Apache web server installed and you want to set it up to serve this Greenstone, copy the appropriate bits out of Greenstone's Apache httpd.conf file into the one for your existing apache. Then disable/uninstall Greenstone's Apache as above.
- If you want to use an alternative webserver, then set it up appropriately, and disable the Greenstone Apache.
- If you have Apache installed previously for the sole purpose of serving Greenstone, then you may like to uninstall it and use the one installed by Greenstone.
Perl 5.8.9 for Linux
On some newer distributions of Linux (such as Ubuntu), Perl version 5.10.x or later is installed on the system. This can be incompatible with perl scripts run manually or which are run by the Greenstone Librarian Interface (GLI). Perl 5.8.9 is still compatible, and so a version for Linux has been put into a tar.gz and made available at http://www.greenstone.org/bin-linux-perl-5.8.9.tar.gz.
If you are running the Greenstone perl scripts (manually or via GLI) on Linux and it complains about perl-related errors, download this tar.gz file, put it into your Greenstone installation folder. Then open a terminal to go into that folder and run
tar -xvzf bin-linux-perl-5.8.9.tar.gz
The above will put perl 5.8.9 inside Greenstone's bin/linux folder. To make sure your Greenstone installation subsequently uses this Perl and not the default one installed on your machine, you will first need to use your terminal to go into the Greenstone installation directory and run
source setup.bash
before running any perl scripts manually and before running GLI. If you run scripts manually (from the command line), run them as:
perl -S <scriptname> <any arguments>
Additional notes to compiling manually
On Windows, use a DOS prompt to go into your Greenstone installation folder. You will need Visual C++ (of Visual Studio) and the Windows/Microsoft Platform SDK installed. FIRST run the Platform SDK's SetEnv.Cmd. THEN run Visual C++'s vcvars32.bat (or vsvars32.bat). Now you can compile manually:
- To compile up server.exe, run the following commands (each takes several minutes)
nmake /f win32.mak nmake /f win32.mak LOCAL_LIBRARY=1
- If you only want to compile up the apache web server, type:
nmake /f win32.mak APACHE_HTTPD=1
- If you wish to clean the files generated during compilation (both intermediate files and binaries), type:
nmake /f win32.mak clean
On Linux and Mac, configuring and compiling generally takes the form:
./configure make make install
- By default, Greenstone is compiled with accent folding turned on. To disable it, you would run the configure step as follows:
./configure --disable-accentfold
As stated in the installation instructions, to compile the included apache web server, the configure step needs to be:
./configure --enable-apache-httpd
- You can get rid of the files generated by compilation by using a Terminal to go into your Greenstone installation folder and running:
make clean
To clean all the files generated during both compilation AND configuration (all config files, other intermediate files and binaries), you would run the following instead:
make distclean
Additional notes to running Greenstone
On Windows, running the Greenstone Librarian Interface (GLI) or the Greenstone Server Interface (GSI) manually from a DOS prompt could be useful in diagnosing anything that goes wrong as it keeps any messages that were displayed during program execution visible in the DOS window.
To run GLI or GSI from the DOS prompt, first go into your Greenstone installation directory and then
- to run the GSI, type:
gs2-server.bat
- to run GLI, type:
gli\gli.bat
Notes on using a Terminal or DOS prompt
On Macs, the Terminal is an application that can be found under Applications > Utilities > Terminal.
On Windows, you can start up a DOS prompt by going to Start > Run and then typing cmd.
To go to your Greenstone installation directory using your terminal, you would type:
cd <here you'd type the full path to your Greenstone installation folder>
On Windows you would use backslashes (\) and on Linux and Mac, you would use forward slashes (/) in file paths.
On Linux and Mac, to run a shell script (Greenstone's shell scripts are files that end on *.sh or *.bash), you would precede the scriptname with a ./
On Windows, to run a batch script (files that end on *.bat), just type its name out in full.
E.g. on Windows:
cd C:\Greenstone gs2-server.bat
E.g. on Linux or Mac:
cd /home/me/greenstone ./gs2-server.sh
Working with Remote Greenstone and the GLI-Client
These instructions are more Greenstone 2.83-specific than the general instructions for setting up Greenstone 2 as a remote server.
1. If the path to your Greenstone installation contains any spaces (i.e. if any of the containing folders wherein your Greenstone is ultimately located contain spaces in their names), please open cgi-bin/gsdlsite.cfg in a plain text editor and make sure that thevalue for GSDLHOME line contains quotes around it. E.g.
gsdlhome "C:\Program Files\Greenstone2"
Save any changes.
2. Rename server.exe in your Greenstone installation folder to something else, say "_server.exe".
This is because you will need to use the included Apache web server for the remote Greenstone. By renaming the default library server in Greenstone 2, Greenstone will next look for the apache web server.
3. Now run the Apache web server included with your Greenstone, by opening a DOS prompt and typing the path to your Greenstone 2 installation and then running the gs2-server script. E.g.
cd C:\Program Files\Greenstone2 gs2-server.bat
Alternatively, you could use Windows Explorer to locate the gs2-server.bat file in your Greenstone2 installation folder and double click that file.
4. A dialog (the Greenstone Server Interface) will display. Press its central Enter Library button.
It will open a browser and take you to a page like:
http://localhost/greenstone/cgi-bin/library.cgi
(OR: http://<YOUR-MACHINE-NAME:YOURPORT>/greenstone/cgi-bin/library.cgi
where if port were the default 80 it won't be displayed, e.g.
http://<YOUR-MACHINE-NAME:YOURPORT>/greenstone/cgi-bin/library.cgi)
5. Replace the "library.cgi" part of the URL in the browser to "gliserver.pl?cmd=check-installation":
E.g. http://localhost/greenstone/cgi-bin/gliserver.pl?cmd=check-installation
(OR: http://<YOUR-MACHINE-NAME:YOURPORT>/greenstone/cgi-bin/gliserver.pl?cmd=check-installation)
At the end of the browser page, it is imperative that it says something like:
"Installation OK!"
6. Once again, open a DOS prompt. Type the following, but make sure to type the path to *your* Greenstone2 installation (the example below uses C:\Program Files\Greenstone2\collect):
cacls "C:\Program Files\Greenstone2\collect" /P Everyone:F
7. Use the browser to go to your Greenstone home web page again.
- Now click on the Administration Page link and add a new user:
- Click the Add a New User link to the left
- You'll be requested for the admin username (type "admin") and password
8. Enter the username and password for the new user.
- In the Groups field, type "personal-collections-editor".
- Press the Submit button.
9. Open a new DOS prompt. Either in this or another machine (assuming you want the Greenstone server on one machine and the client on another), g to the gli folder of your Greenstone 2 installation, and run client-gli.bat. E.g.
cd C:\Program Files\Greenstone2\gli client-gli.bat
10. A dialog will eventually appear asking you for the URL of the Remote Greenstone server's gliserver.pl file.
- If your client-gli is running from a different machine to where your Greenstone server is running, you need to specify the name of that remote machine hosting the Greenstone server:
http://<YOUR-MACHINE-NAME:YOURPORT>/greenstone/cgi-bin/gliserver.pl
- If the client-gli is running on the same machine, you can generally type "localhost":
http://localhost/greenstone/cgi-bin/gliserver.pl
11. It will next ask you for a username and password. Type the values you entered for the new user you creatred in step 8.
12. The client-GLI dialog should finally open, and it will look the same as the usual (local) GLI.
Important Changes
2.83 incorporates a few changes and bug fixes since 2.82, including:
- ex.metadata is now valid in collection configuration files. Previously, GLI could handle ex. metadata, but would strip off the ex before writing the config file. Now, ex is valid in the config file too.
- On MAC (and Linux), the expat library file is now being compiled up from the local Apache installation and is now included with Greenstone. The DYLD_LIBRARY_PATH and LD_LIBRARY_PATH include the path to the generated expat library file. This fixes an earlier bug where the path to the expat lib was pointing to the wrong location. It also had other side effects in that any expat library file found could have a version incompatible with the one required by Greenstone.
- Fixes to resumption token support in the OAI server (thanks to DL Consulting)
- new macro _collectionspecificscript_. Can be used in a collection's extra.dm file to add custom javascript to all pages. Use instead of _pagescriptextra_ if you want to add javascript to what is already there, rather than overwriting it.
- incremental build: will now recognise a newly added metadata.xml file, and will reimport all other files in the same directory. Many other minor bug fixes.
- sorting the build using -sortmeta option to import.pl fixed (wasn't working in 2.82). The -reversesort option has been moved from import.pl to ArchivesInfPlugin, as sorting happens when this plugin reads in the archiveinf-doc.gdb file.
- new macro _queryterms_, which is a space separated list of search terms. Like _cgiargq_ but without term and field modifiers. eg if _cgiargq_ was "[snail]:TX & [smith]:AU", then _queryterms_ would be "snail smith". Use in format statements for searching in PDFs instead of using _cgiargq_, eg:
<a href=\"_httpcollection_/index/assoc/[archivedir]/doc.pdf#search="_queryterms_"\">
- There is now an Apache web server (web library) included with the Windows version of Greenstone 2 as well, matching the Apache web library that comes with the Linux and Mac versions of the previous Greenstone 2 release (2.82). NOTE: Previously this web server was referred to as the "local library server" for the Linux machines, but now that we have the same available on both Windows and Linux, and since server.exe is called the "local library server" on Windows, the apache web server will be referred to as the built-in (apache) web library.
- On Linux, the Greenstone Server Interface (GSI) dialog now has an "Address Resolution Method" panel that mimics what's already there in Greenstone 2's local library server for Windows (server.exe). It allows the user to choose between the address being resolved using hostname, hostIP, localhost and the default homeIP (127.0.0.1). The GSI dialog for the apache web server now also allows the user to set the "allow external connections" property.
- introduction of _optgloballinks_ macro to style.dm, similar to _optnavigationbar_, to allow optional placement of this structural element (home, help, pref buttons)
- The depositor now supports users that belong to collection specific groups (e.g. demo-collection-editor) in addition to all-collections-editor
- A new script, csv-usernames-to-db.pl, allows batch submission of usernames and passwords to the users database file. An alternative to adding them one by one through the admin pages.
- Exporting can now be incremental like importing.
- MARCXML exporting now works on Windows
- Setting a default level in GLI in index panel now works at runtime.
- Fixed some memory bugs causing crashes on Windows, thanks to DL Consulting
- Fixed a bug where the OAI plugin wouldn't associate the metadata with the source document
- Fixed a bug where the OpenDocument plugin wouldn't recognize any Open Office files.
- MetadataEXIFPlugin renamed to EmbeddedMetadataPlugin to better reflect what it can do.
- Fixed a bug where any user could access any collection regardless of groups
Known Issues and Patches
The windows release was compiled on Windows Vista. It appears that some functionality is broken when running on Windows XP, for example, the depositor, and particular commands for oaiserver. Here are 2.83-windows-library.cgi and 2.83-windows-oaiserver.cgi to download which have been compiled on Windows XP. They should be copied into Greenstone's cgi-bin folder, and renamed to library.cgi or oaiserver.cgi, respectively. 2.83-windows-server.exe should be copied into the top Greenstone folder, and renamed to server.exe.
Updated Translations
Thanks to the following people for updated translations since 2.82:
- Prof. A. Neelameghan of the Sarada Ranganathan Endowment for Library Science, Bangalore for Kannada and Tamil translations
- Prof. Adalgisa Pinheiro for Brazilian Portuguese translations
- Claudia Wanderley for Brazilian Portuguese translations
- K.N. Prasad of the Sarada Ranganathan Endowment for Library Science, Bangalore for Kannada and Tamil translations
- K.S. Raghavan of the Sarada Ranganathan Endowment for Library Science, Bangalore for Kannada and Tamil translations
- Lavji N. Zala for Gujarati translations
- S.K. Lalitha of the Sarada Ranganathan Endowment for Library Science, Bangalore for Kannada and Tamil translations
- Shubhada Nagarkar for Marathi translations
- Prof. Vara Lakshmi for Telugu translations
- Dr. Wmen for Tamil translations
A special thanks to Veronica Liesaputra, a most dedicated Greenstone friend, who has done more than her own work of developing the excellent Realistic Book tool (and plugin to Greenstone). She has lugged round her Mac laptop well beyond the call of duty to help debug and test this release of Greenstone, and spent hours of her time with us over many days, so that 2.83 may work on Mac Tigers as well.
