README

                    GDL - GNU Data Language
                    =======================

A free IDL (Interactive Data Language) compatible incremental compiler
(capable of running programs written in IDL/GDL).
IDL is a registered trademark of Harris Geospatial (see: http://harrisgeospatial.com/).

This README may well be outdated. See README.md on Github: http://github.com/gnudatalanguage/gdl  and the associate Wiki.

HOMEPAGE:
=========

http://github.com/gnudatalanguage/gdl


FEATURES:
=========

Full syntax compatibility with IDL up to version 7.1...
...    and trying to be up-to-date with 8.x, see below.

All IDL language elements up to IDL version 7.1 are supported, including:

Pointer, objects, structs,
arrays, system variables,
common blocks, assoc variables,
all operators, all datatypes,
_EXTRA, _STRICT_EXTRA and _REF_EXTRA keywords...

GDL provides all of the GUI support (widgets) of IDL (see below) but none of the Compound Widgets. 

Supported IDL 8.0 language elements:

FOREACH loop
negative array indices
garbage collection pointers and objects
call methods on an object using "." (e. g. object.aMemberProcedure,arg1)
empty arrays and !NULL system variable
automatic promotion of FOR loop variable types
LIST and HASH types

Not yet supported:
simplified property access on objects (e. g. object.aProperty = value & print,object.aProperty)

In general GDL should run correctly an IDL procedure, even one from the /lib folder of an IDL distribution.
(Note that most of theses procedures---some can be found on the web---have not yet been rewritten for GDL, help is welcome.).

The file input output system is fully implemented including full support of F77_UNFORMATTED.

netCDF files are fully supported.
HDF4 files are supported.
Basic support for HDF5 files.

DICOM files are supported via the GDLffDICOM object (http://idl.barnett.id.au/idl-projects)
(files in the src/pro/dicom subdirectory).

Overall nearly 500 library routines are implemented.
For a list enter HELP,/LIB at the command prompt and look for
library routines written in GDL in the src/pro subdirectory.

Graphical output is almost completely implemented (no object-graphics). 
The PLOT, OPLOT, PLOTS, XYOUTS, SURFACE, CONTOUR and TV commands (along with WINDOW, 
WDELETE, SET_PLOT, WSET, TVLCT, LOADCT) are working (most keywords,
!P system variable tags and multi-plots are supported) for X windows,
z-buffer and postscript output.

GDL has an interface to python.
Python can be embedded into GDL and GDL can be compiled as a
python module. See the file PYTHON.txt for details.

For the thread pool OpenMP is utilized if the compiler supports it.


REQUIREMENTS:
=============

In short:
Mandatory libraries:
gsl         http://www.gnu.org/software/gsl
zlib        http://www.zlib.net/

Optional libraries (ON by default) :
X11 (on unix)
pnglib
readline    http://ftp.gnu.org/pub/gnu/readline/readline-4.3.tar.gz
Eigen3       http://eigen.tuxfamily.org
GraphicsMagick http://www.graphicsmagick.org  (preferably to ImageMagick http://www.imagemagick.org)
netCDF *)   ftp://ftp.unidata.ucar.edu/pub/netcdf
HDF4 *)     
HDF5        https://www.hdfgroup.org/downloads/hdf5/
FFTW        http://www.fftw.org/download.html
python      http://www.python.org
PROJ        (consult the MAP_INSTALL file)
UDUNITS2    http://www.unidata.ucar.edu/software/udunits/
ECCODES     https://github.com/ecmwf/eccodes
shapelib    http://shapelib.maptools.org/ (consult the MAP_INSTALL file)
wxWidgets   http://www.wxwidgets.org/
glpk        https://www.gnu.org/software/glpk/  : only to have the linear programming function SIMPLEX() available.
libTiff

Optional libraries (OFF by default) :
MPI

Only with python:
numpy          http://numpy.org/

*) please see below for potential problems using netCDF and HDF4

COMPILING:
----------
  If you install the libraries as precompiled
  packages rather than compiling them from sources, please note that
  depending on your distribution, you may need development packages
  as well. Examples are (for Fedora):
  GraphicsMagick-devel
  GraphicsMagick-c++-devel

  Look at the *INSTALL* files.

LINE EDITING:
-------------
  Better than IDL, GDL has modern line editing and line history features.
  The GNU readline library 4.3 is needed (actually GDL should compile
  without, but its very inconvenient to use that way, furthermore
  proper event handling for graphic windows requires readline).
  You can get it at:
  http://ftp.gnu.org/pub/gnu/readline/readline-4.3.tar.gz
  
GRAPHICS AND DEPENDENCIES:
--------------------------
  For the graphics support of GDL, we use a trimmed version of the plplot library.
 
MATH FUNCTIONS & MORE:
-----------------------
  GDL uses the GNU Scientific Library (GSL).
  Please see file HACKING if you want to write functions extending GDL (i. e.
  add a library subroutine) which use GSL for proper handling of GSL
  obects in GDL.
  You find it at:
  http://www.gnu.org/software/gsl

MAKE GDL FASTER:
----------------
  GDL uses Eigen for fast matrix multiplication. (optional)

  The Eigen library version 3.1 or later is highly recommended for a performance
  boost, expecially on multi-cores. To be found at: http://eigen.tuxfamily.org, 
  but is probably installed on your computer and will be found by the installer.
  Of course, acceleration is only visible when optimisation (-O3) is turned on.

  The simpliest way to compile with it is to copy all the header files
  under sub-directory src/Eigen. Another solution is to provide full path
  to the include files (i.e. using:
  cmake . -DCMAKE_INSTALL_PREFIX=/home/toto/Eigen3.1.4/ )

  The FFTW library is (optionally) used for the FFT function.
  It is available at: http://www.fftw.org/download.html
  Using FFTW results in an about double as fast FFT function.
  Take care that you have to compile the "normal" and the "single"
  version of the library (resp. libfftw3.a and libfftw3f.a).
  First one is the default. You have to activate the single flag
  (./configure --enable-single) when recompiling FFTw3.
  If FFTw is not used, the default (GSL) fft routine is used instead.
  
  

WIDGETS:
--------
  GDL supports GUI (widget) programming (initial effort by Joel Gales rewritten by Gilles Duvert)
  using the wxWidgets library. It is required by default.
  If you don't want to use it, use -DWXWIDGETS=off (CMake)
  wxWidgets can be obtained from:
  http://www.wxwidgets.org/downloads
  
  The wxWidget version must be 2.8.1 or higher. 
  
  The WIDGET_*... functions are all implemented (use HELP,/LIB for an overview). Only a few
  rarely seen options have not been written yet (please report in case of need). They have
  not been tested outside the linux "mageia" distribution yet, so errors and crashes are possible.
  Most procedures using widgets available (e.g., in the astrolib library) use so-called
  "compound widgets" (CW_xxxxx functions that are written in IDL, like CW_FIELD). Those have not
  been rewritten in GDL (and some have not been thoroughly tested). Those are not present
  in the GDL distribution (copyright issues), must be obtained separately (google is your friend) and put
  in the GDL path before use.

DATA FORMATS:
=============

  HDF4 Files:
  ----------
    The HDF4 format is (not completely yet) supported (thanks to Joel Gales).
    If you want to use it, you need the HDF library (here HDF
    always means version 4).
    Note that if you plan to use netCDF also, it might be necessary to
    install HDF4 before netCDF due to same named but different header
    files which are overwritten by the HDF4 version otherwise.
    HDF4 is required by default. If you don't want to use it, use 
    -DHDF=off (CMake)
    Note that HDF in turn needs other libraries. Check out the
    homepage for more information:
    https://support.hdfgroup.org/products/hdf4/
    The HDF library can be downloaded from:
    https://support.hdfgroup.org/ftp/HDF/releases/

  HDF5:
  -----
    Basic support for HDF5 is now provided (thanks to Peter Messmer).
    If you want to use it, you need the HDF5 library.
    It is required by default. If you don't want to use it, use 
    -DHDF5=off (CMake)
    Note that HDF5 in turn needs other libraries. Check out the
    homepage for more information:
    http://portal.hdfgroup.org/display/HDF5/HDF5
    The HDF5 library can be downloaded from:
    https://support.hdfgroup.org/ftp/HDF5/releases/

  NETCDF:
  -------
    The netCDF format is fully supported (thanks to Christopher Lee). If
    you want to use netCDF, you need the netCDF library (even if HDF4 is
    used, the netCDF library is needed, as the HDF library does not
    contain all needed netCDF functions. Note that it might be necessary
    to install netCDF after HDF4 due to same named, but different header
    files. If the header files of HDF4 and netCDF are in different directories 
    make sure, that the directory containing netCDF's version gets searched first,
    i.e. put an explicit path for netCDF even if it is in the default include path,
    i.e.: -DNETCDFDIR=/usr (CMake)) 
    netCDF is used by default. If you don't want to use it, use 
    -DNETCDF=off (CMake)
    as a command line option to 'cmake'.
    netCDF is available from:
    ftp://ftp.unidata.ucar.edu/pub/netcdf

  From the HDF4 INSTALL file:
     To use the HDF/MFHDF libraries (libdf.a, libmfhdf.a) with the original
     netCDF library (libnetcdf.a), the HDF4 distribution must be configured 
     with the --disable-netcdf configuration flag.  This will rename the HDF 
     version of the C interface (ncxxx) of the HDF4 netCDF APIs to sd_ncxxx 
     and will disable the HDF4 NC Fortran interfaces to avoid name clashes 
     with the original netCDF C and Fortran APIs from libnetcdf.a.  

  IMAGE FORMATS:
  --------------
    In order to read and write images in several formats
    (e.g. JPEG, PNG), GDL uses GraphicsMagick or (but more reluctantly) ImageMagick.
    It is required by default. See http://www.graphicsmagick.org

MAP PROJECTIONS and GEOPHYSICS:
----------------
  GDL contains now a complete support to MAP projection,
  using the PROJ library (www.proj.org). Please see MAP_INSTALL file.
  Note that GDL gives access to all proj.org projections instead of the 20 or so of IDL.

  GDL uses libshp (shapelib) to implement MAP_CONTINENTS - see MAP_INSTALL.
  A valid GDL install should provide map files in <installation_directory>/resources/maps.

PYTHON INTERFACE:
-----------------
  GDL has an interface to python (see http://www.python.org). 
  GDL can be used as a python module and python can be used from
  within GDL. See INSTALL for details on how to build each version.
  As so far there are only two example GDL extensions written in python its
  use is optional for now but required by default. If you don't want to use
  it, use  
  --DPYTHON=no
  as a command line option to 'cmake'.
  If you want to use it you need python and the python package Numpy.
  (http://numpy.scipy.org/).
  The GDL cmake script will determine the installed python version
  automatically. For this the python executable must be installed.
  Note: For embedding python as it is done by GDL, the python dynamic
  library is needed which is *not* build by default. You need to run
  'configure' for python with the '--enable-shared' option. Please see
  the python README file for details.
  For nice graphical output the python package matplotlib
  (http://matplotlib.sourceforge.net) is used in one of the examples.
  See the file PYTHON.txt for more details.

OTHER SUPPORT LIBRARIES:
------------------------
GDL supports unit converion in IMSL_CONSTANT using the UDUNITS-2
library (http://www.unidata.ucar.edu/software/udunits/)
If you want to use it, use --with-udunits=DIR

GDL supports the GRIB file format - see README_GRIB (optional)

GDL is developed using ANTLR 2.7,   
but unless you want to change the grammar (*.g files) you don't need
ANTLR (for building GDL). All relevant ANTLR files are included in the package.
For editing however, there are several antlr-grammar (*.g) files among the
sources. ANTLR generates from this grammar-files c++ source files.
ANTLR generated files should not be changed directly as the changes
would be undone if someone regenerates those files. Instead the relevant
grammar file (mentioned in the header of the generated file) must be edited
and run through ANTLR. All source files generated by ANTLR start with a capital
character. All regular source files start with a small character.
For more information on ANTRL see: http://www.antlr.org


INSTALLATION:
=============

Please see the *INSTALL* file(s) for details.

Since we do have the script for prepare then compile and test GDL,
it is really easy to compile then install it from source files.
You can also refer to the wiki https://github.com/gnudatalanguage/gdl/wiki

For french readers, please have a look to
http://aramis.obspm.fr/~coulais/IDL_et_GDL/memo_GDL.html
which explain how to install GDL and most libraries
from scratch and without being root.


CONTRIBUTIONS:
==============

GDL is actively developed, but due to the vast amount of subroutines
to implement, GDL is still in beta state.
Even though it is commonly used by clever people for several tasks, there are many
things to be done.
Bug reports, feedback in general and interested people who would
like to join this project are welcome.
Extensions to GDL can be made in C++, GDL or python.
 
Urgent things to do are:
THE DOCUMENTATION!
Testing and test routines written in GDL,


HACKING:
========

please see file HACKING for details.
There you find also information about LINKIMAGE.


CONTACT:
========

Comments are welcome. Let us know what you use GDL for. Or if you don't,
why not. Which functionality are you missing/would appreciate most for
coming versions.

For bug reports, suggestions, comments and volunteering, please
use the issue-tracking tool at: https://github.com/gnudatalanguage/gdl


LICENSE:
========

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

(It should be included in this package in the file COPYING )