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.

An installation guide with screenshots is available here:
<http://www.gle-graphics.org/tut/windows.html>

During installation GLE will search for installed programs such as GhostScript and LaTeX. GLE does not require these for its most basic operations, but it does so for more advanced features such as producing PDF output and processing scripts including LaTeX expressions. This process runs in a black window and the output should be similar to the following.

Running GLE -finddeps "C:\Program Files" (locate GLE fonts and optionally Ghosts cript/LaTeX): ................................................................................
................................................................................
................................................................................
Found: GLE 4.0.11 in C:\Program Files\Gle4\4.0.11\bin\gle.exe
Found: GLE 4.0.12 in C:\Program Files\Gle4\4.0.12\bin\gle.exe (*)
Found: latex.exe in '?'
Found: pdflatex.exe in '?'
Found: dvips.exe in '?'
Found: gswin32c.exe in 'C:\Program Files\Tools\gs8.53\gs8.53\bin\gswin32c.exe'
Press enter to continue ...

In this example, GLE has detected that GhostScript is installed on my computer, but it did not detect LaTeX. More information on using GLE with LaTeX is given below. For now, just focus the window saying "Press enter to contunue..." and press enter. Next click Finish on the installer screen.

GLE should now have added a new entry titled GLE to your start menu. Clicking it pops up a menu showing the options "Command Prompt", "Readme", "Uninstall", and "Website". Click on "Command Prompt" to open a command prompt. Now type the command "gle" and press enter.

C:\Program Files\Gle4\4.0.12\samples> gle
GLE version 4.0.12
Usage: gle [options] filename.gle
More information: gle /help

GLE should respond as in the example above. If you instead get the message "'gle' is not recognized as an internal or external command, operable program or batch file", then the folder containing "gle.exe" was not correctly added to your system's search path during installation.

If the version number printed by GLE is not correct, then a previous version of GLE may be installed on your computer. Either uninstall that version or remove it from your system's search path (you will still be able to run it through the -v option, as discussed in the reference manual).

I will now show you how to change the search path. This is a list of folders that Windows searches for executable programs when you try to run a particular program from the command prompt. Note that normally the GLE installer should have done this for you. Only perform the next step if you saw an error message or incorrect GLE version in the previous step.

Select "Control Panel" from the start menu and click "System". Navigate to the "Advanced" tab and click the "Environment Variables" button. Select the variable "PATH" and click the "Edit" button. Add to the "Value" field the location of the GLE executable "gle.exe". This location is the installation folder you specified during installation with "\bin" added at the end, for example, C:\Program Files\Gle4\4.0.12\bin. Note that different folders in the PATH are separated with the symbol ";". You might need to change the value of PATH in either the "User" or the "System" variables.

If you have LaTeX installed on your computer, you also need to perform the next step. LaTeX is usually not installed in "C:\Program Files", so GLE does not detect it automatically during installation. Open the command prompt and run "gle -finddeps LATEXPATH", with LATEXPATH the location of your LaTeX installation. The following example assumes that the MiKTeX distribution is installed (http://www.miktex.org/).

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.

You are all set. Information on how to run GLE is available in Section 3 and in the manual.

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
gle\font\*

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

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

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>

There is also an installation guide / introductory tutorial available for Windows here:
<http://www.gle-graphics.org/tut/windows.html>

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

Both the Windows and Unix build process use makefiles. Visual Studio project files 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.

Unless you are using the autoconf method (Section 4.3.1),
	HAVE_LIBTIFF = 1
	HAVE_LIBPNG = 1
must be enabled in config.i (to disable bitmap 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
----------------------------------

4.3.1 Compiling on Linux/Cygwin/Unix using autoconf
---------------------------------------------------

To install GLE system-wide:

	./configure
	make
	su
	make install

To install GLE in your home directory:

	./configure --prefix=$HOME/apps
	make
	make install

4.3.2 Compiling on Linux/Cygwin/Unix using Makefile.gcc (old method)
--------------------------------------------------------------------

	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 WORDS_BIGENDIAN" to the CXXFLAGS line of config.gcc

	Note: adding "-D WORDS_BIGENDIAN" is not required when using autoconf.

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}

      (Or upgrade to a newer version of gcc.)

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 build/font directory 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 build/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.

