GLE Readme
==========

This document contains instructions on how to compile, install, and run GLE4.

Supported platforms: Windows, Linux, Mac OS/X, Unix, OS/2.

Contents
--------

1. What is GLE?
2. Installing a GLE binary
2.1 Installing GLE on Windows
2.2 Installing GLE on OS/2
3. Running GLE
4. Compiling GLE from the source code
4.1 Compiling on Windows (with Microsoft Visual C++)
4.2 Compiling on Windows (with GCC)
4.3 Compiling on Linux/Cygwin/Unix
4.4 Compiling on Mac OS/X
4.5 Compiling on OS/2 (with GCC 3.2.1)
4.6 Notes for all platforms
5. Source code organization
6. License (BSD)

1. What is GLE?
---------------

GLE is a graphics language that produces postscript, EPS, PDF, PNG, or JPG output from a simple script file. The GLE scripting language is full featured with variables, subroutines, logic control, looping, and graphing tools. It is great for plotting and charting data.

GLE can create very complex output with text and graphics (including graphs and charts) from a simple plain text file.

GLE is open source so you can modify it to meet your needs.

GLE is a full featured programing language that includes variables, subroutines, logic control, looping, a graphing tool, and more to produce high quality postscript output. It has a full range of facilities for producing publication-quality graphs, diagrams, posters and slides. GLE provides LaTeX quality fonts together with a flexible graphics module which allows the user to specify any feature of a graph (down to the line width of the sub ticks, for example). Complex pictures can be drawn with user-defined subroutines and simple looping structures. Essentially, GLE is a programming language and if you are used to writing software, using LaTeX, or any other non-WYSIWYG tools, then you will enjoy using GLE. 

More information is available at <http://www.gle-graphics.org/>.

2. Installing a GLE binary
--------------------------

GLE is available as binary installation packages (one for each supported platform) or as source code. The source code must be compiled before it can be installed. To compile GLE from source on different platforms, see Section 4. This section describes how a GLE binary can be installed.

2.1 Installing GLE on Windows
-----------------------------

The easiest way to install GLE on Windows is to download the self installing executable. The self installing executable is named gle_<version>_exe_win32.exe. By double-clicking this file in Windows Explorer, it will guide you through the installation of GLE on Windows.

Some versions of GLE are also available as a Windows binary compressed in a ZIP file. Installing such a version is more complex. New users are advised to try the self installing executable first.

Installing GLE from the ZIP file gle_<version>_exe_win32.zip:

1) Unzip gle_<version>_exe_win32.zip to e.g., "C:\Program Files" using WinZip or a similar tool for extracting ZIP files. This will create the following directory tree where you unzipped the files.

gle4
gle4\bin
gle4\font
gle4\lib

2) Add "C:\Program Files\Gle4\bin to your PATH environment variable. Change the "C:\Program Files" if you have installed GLE in a different folder.

Note: to set the PATH environment variable on Windows XP, proceed as follows. Open the "Control Panel" from the start menu, select "System". Navigate to the "Advanced" tab and click the "Environment Variables" button. Click the variable "PATH" and click the "Edit" button. Add to the "Value" field the location of gle.exe, i.e., "C:\Program Files\Gle4\bin". Note that different folders in the PATH are separated with ";".

3) Make GLE find its installation directory and optionally also the directories of other programs it may use (i.e., GhostScript and LaTeX). This is accomplished by running "gle -finddeps [path]" in a command prompt, where path is the place to search ("C:\Program Files" is the default).

Note: the command prompt is usually available in the start menu under "All Programs" in the "Accessories" folder. The icon for the command prompt is usually "C:\". Alternatively, the command prompt can be started by choosing "Run" in the start menu and by typing "cmd" in the "Open:" field.

Enter the command "gle -finddeps" at the command prompt.

C:>gle -finddeps
Finding dependencies in: C:\Program Files: ........................
Found: gle.exe in 'C:\Program Files\gle4\bin'
Found: gswin32c.exe in 'C:\Program Files\Tools\gs\gs\gs8.00\bin'
Found: latex.exe in '?'
Found: dvips.exe in '?'

In the example above, GLE has found out that it is installed in "C:\Program Files\gle4" and that GhostScript (http://www.cs.wisc.edu/~ghost/doc/AFPL/index.htm) is in "C:\Program Files\Tools\gs\gs\gs8.00\bin". Note that this version of GLE does not require you to set GLE_TOP. Once the installation directory has been found, it is stored in the registry for further use.

Note: if GLE does not run, then you might have set the PATH incorrectly.

4) LaTeX is usually not installed in "C:\Program Files", so a second -finddeps is required to locate it. The following example assumes the MiKTeX distribution is installed.

C:>gle -finddeps "C:\MiKTeX"
Finding dependencies in: C:\MiKTeX: ...........................
Found: gle.exe in 'C:\Program Files\gle4\bin'
Found: gswin32c.exe in 'C:\Program Files\Tools\gs\gs\gs8.00\bin'
Found: latex.exe in 'C:\MiKTeX\Main\miktex\bin'
Found: dvips.exe in 'C:\MiKTeX\Main\miktex\bin'

Note that both GhostView and LaTeX are optional. For creating simple .eps graphs, they are not required, i.e., GLE will still work if you see question marks for gswin32c.exe, latex.exe and dvips.exe.

5) You are all set. Information on how to run GLE is available in Section 3.

2.2 Installing GLE on OS/2
--------------------------

Since you are reading this you downloaded the do it yourself .zip package for gle installation. To install this package:

1) Unzipping gle-4.0.x.zip will create the following files.

gle\
gle\doc\readme		(you are reading this)
gle\doc\gle-manual.pdf
gle\gle.exe
gle\gcc321m.dll
gle\fbuild.exe
gle\makefmt.exe
gle\inittex.ini
gle\glerc.sample.os2
gle\font\*

2) Put gle.exe somewhere into your PATH and libc06b4.dll into your LIBPATH.

3) Add "SET GLE_TOP=x:/path/gle" to your config.sys.

4) The sample configuration file (glerc.sample.os2) can be used to change the defaults. Modify it and put a copy of it into your home directory: %HOME%\.glerc.

3. Running GLE
--------------

Running GLE is similar on all supported platforms.

Note that GLE is a command line application. It takes as input a GLE script file and outputs a eps, ps, pdf, jpg, or png file. GLE can not be run from inside a file manager such as Windows Explorer. Instead it should be started from a terminal (e.g., an X-terminal or console application in Linux or the command prompt in Windows).

To start GLE, open a terminal/command prompt and issue the command:

gle -d outputtype yourfile.gle

where outputtype is one of: eps, teps, ps, pdf, jpg, png

and yourfile.gle is the file containing the your GLE script.

E.g. (Windows):

---------------------------------------------------------

C:\Program Files\Gle4\samples>gle -d eps sample.gle
GLE 4.0.9c [sample.gle]-C-R-[sample.eps]

---------------------------------------------------------

Preview the output file sample.eps with GhostView (e.g., by browsing with your favorite file manager to in this case C:\Program Files\Gle4\samples and clicking sample.eps).

See the GLE manual for more information.
<http://glx.sourceforge.net/>

Or contact the GLE mailing list (glx-general) if you have any questions.
<https://lists.sourceforge.net/lists/listinfo/glx-general>

4. Compiling GLE from the source code
-------------------------------------

Both the Windows and Unix build process use makefiles. Visual Studio project files and Unix autoconf and automake are not supported. Makefiles and config files ending in .vc are for the Microsoft Visual C++ compiler. Makefiles and config files ending in .gcc are for the gcc compiler. Config files ending in .i and files ending in .txt such as files.txt are for both compilers and define common macros.

If you have another compiler or target system please add the makefiles and config files.  Note that each directory in the src directory needs its own makefile.

Note that GLE is written using C++.

To compile GLE with support for including bitmap files
	libtiff <www.libtiff.org> and
	libpng <www.libpng.org>
are required and in config.i
	HAVE_LIBTIFF = 1
	HAVE_LIBPNG = 1
must be enabled (to disable support, comment these out with '#')

4.1 Compiling on Windows (with Microsoft Visual C++)
----------------------------------------------------

	you must have the environment variable GLE_TOP point to the location
	of C:\Path\To\gle4\bin

	you must have the environment variable LIBTIFFDIR point to the location
	of the libtiff.h and .lib files

	you must have the environment variable LIBPNGDIR point to the location
	of the png.h and .lib files

	nmake -f Makefile.vc
	
4.2 Compiling on Windows (with GCC)
-----------------------------------

	You must have Cygwin installed. The resulting executable will however
	not depend on Cygwin. You can also build a "real" Cygwin version of GLE
	by following the instructions in Section 4.3.

	make -f Makefile.nocygwin
	make -f Makefile.nocygwin zipexe

4.3 Compiling on Linux/Cygwin/Unix
----------------------------------

	optionally change the values of
		INSTALL_DIR   (default =/usr/share/gle)
		INSTALL_BIN   (default =/usr/bin)
	in config.gcc

	export GLE_TOP=/path/to/gle4/bin

	make -f Makefile.gcc
	su
	make -f Makefile.gcc install

4.4 Compiling on Mac OS/X
-------------------------

	follow same instructions as for Linux/Cygwin/Unix
	but add "-D BIGINDIAN" to the CXXFLAGS line of config.gcc

4.5 Compiling on OS/2 (with gcc 3.2.1)
--------------------------------------

	change the values of
		INSTALL_DIR     (D:/UTILS/gle)
		INSTALL_BIN     (D:/UTILS/bin)
		ADD_DLLS	(D:/GCC.321/dll/gcc321m.dll)
		ADD_DOCS	(readme ../gle-refman/gle-manual.pdf)
                PROJECT_DIR     (E:/Works/Projects/CGLE/current/gle4)
        in config.os2

        make -f Makefile.os2

4.6 Notes for all platforms
---------------------------	
	
Note: If you get the following error:
      StringKeyHash.h:8: ext/hash_map: No such file or directory
      Then add -DGCC2 to EXTRA_DEFS in config.{gcc,os2,nocygwin}

The compilation process will built:

gle(.exe) : GLE main executable
fbuild(.exe) : makes *.fve fron *.gle using fbuild in the src\font directory
makefmt(.exe) : makes font files *.fmt from *.afm in the src\font directory

It will also run the fbuild and makefmt commands and put the
font files in the gle\bin\font along with the font.dat file

It will also run your newly built gle on the files
in the src\samples subdirectory

the clean target is also defined on all makefiles

5. Source code organization
---------------------------

the source code is contained in the src sub directory, where each module has its
own directory (and makefiles). binaries are put in the bin sub directory.

6. License (BSD)
----------------

Copyright (c).
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    * Neither the name of GLE nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

