INSTALL

Building & Installing GtkFortran
================================

The build install system uses 'cmake'.

This is has been tested on Debian (Wheezy, Sid) and Pardus (2011)
Linux installations.

To do an "out of source" build from the top-level directory on a
Unix/Linux system: 
    mkdir build
    cd build
    cmake ..
    make
    sudo make install

cmake variables are set by using -D<variable>=<value>
for example to change the default install directory from /usr/local to /usr:
cmake -DCMAKE_INSTALL_DIR=/usr ..

Useful variables that are specific to gtk-fortran are:
       EXCLUDE_PLPLOT -- set this to disable building the plplot
         integration even if plplot is found
       INSTALL_EXAMPLES -- set this to install the source code of the
         examples into
         ${CMAKE_INSTALL_DATAROOTDIR/gtk-fortran/examples<gtkversion>,
         this would for example be useful if you were making a binary
         package of gtk-fortran.
       NO_BUILD_EXAMPLES -- set this to prevent compiling the example
         programs, also mostly useful for packagers.

To interactively control the build, use 'ccmake' in place of 'cmake'

**************************************************************************
* Following the install path and name changes on 25 Nov 11, it is
* strongly recommended to uninstall any current installation, and then 
* clean out the build directory and re-run cmake
*     cd build
*     sudo make uninstall
*     rm -r *   ## MAKE SURE YOU ARE IN THE BUILD DIRECTORY BEFORE
*     	    	## DOING THIS
*     cmake ..
**************************************************************************

Dependencies:
-------------

GtkFortran needs Gtk 2.24 or better (it will mostly work with 2.22) and
the associated libraries. For 2.xx use the "master" git tree, for 3.x
use "gtk3".

To build with gfortran, version 4.6 or better is needed (in 4.4 &
4.5 c_funloc doesn't work correctly, at least for Fortran routines with
the bind(c) attribute).

For g95, the 15 January 2013 snapshot or later is required.

The build system needs cmake 2.8.5 or better.

doxygen and plplot are used if available.

GTK3:
-----

For the Gtk3 version, a FindGTK3.cmake module is included in the
distribution, it is placed in the cmake subdirectory which should be
added to the module search path by the top-level CMakeLists.txt rules.

N.B. FindGTK3.cmake has been tested on Debian Sid, Ubuntu 12.04 and
Manjaro, it is possible that other systems may have different naming
conventions (If you have problems look for the lines with several
asterisks in the comments, as these are the places where I think there
could be issues [i.e. where I was guessing until it worked]).

Known issues
------------

On Gtk3, there is a warning

    -- Some or all of the gtk libraries were not found. (missing:  GTK3_GDKCONFIG_INCLUDE_DIR) 
that appears harmless and is probably a failing of the FindGTK3.cmake file.

On Gtk3, building with the Debug options all the examples fail with a 
floating-point exception as soon as the pointer is moved over the widget, 
cause unknown.

With the debug options enabled, the cairo examples fail because of an array
bounds violation (due to the use of a length 0 for some arrays when 
extracting from a C-pointer).

The gtkbuilder examples cannot be run from make tests because the directories
are not right to find gtkbuilder.glade

Building your application
=========================

On Linux and Unix systems the build system generates a pkg-config file
and installs it. So building a single source file application should be
as simple as:

    gfortran my_app.f90 `pkg-config --cflags --libs gtk-fortran`

If you have made a default install to /usr/local you *may* need to run:

    export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
(Or
    setenv PKG_CONFIG_PATH /usr/local/lib/pkgconfig
if you use csh or one of its derivatives)

this will depend on your distribution, Ubuntu looks there by default,
Pardus and Manjaro don't.