	       General build instructions, 7th Feb 2011
	       ========================================

See NEWS and/or ChangeLog for version updates.

See below for platform specific build instructions.


External dependencies
=====================

In order to compile the Staden source tree you also need a few extra
libraries. Some of these may be considered as internal (eg io_lib),
but they are not included within this source tree and need to be
downloaded and installed before hand.

Packages required (newer versions should work; older versions may work
but are untested - please tell me if they work too).

* staden-io_lib	>=1.13.8
* tcl		>=8.4
* tk		>=8.4
* zlib		>=1.2.x
* liblzma	>=4.999 (optional[2])
* libpng	>=1.2.x (optional[1])
* curl		>=7.x (needed by io_lib)
* tklib		>=0.3? (for tablelist widget)
* itcl		>=3.2 (optional[3])
* itk		>=3.2 (optional[3])
* iwidgets	>=4.0 (optional[3])

[1] Libpng development packages are only needed for some obscure
output from Gap4: the editor Report Mutations function.

[2] liblzma-dev linux packages or the XZ utils source tarball includes
the liblzma library.  If present it may be used for Gap5 to perform
better compression, but it is not mandatory.

[3] itcl/itk/iwidgets are now needed only by the GUI for the
auto-finishing system used in Gap4 ("prefinish"). However it is a
run-time dependency and the package will build without these
installed. Note that if you link against Tcl/Tk 8.5 then the minimum
version of itcl/itk is 3.4 and not 3.2.

If your operating system separates out run-time from development files
then you will need both installed. For example on Debian you need
tcl8.5 and tcl8.5-dev packages (or tcl8.4 + tcl8.4-dev).

Other system prerequisites:

* C compiler (eg gcc, icc)
* C++ compiler (eg g++)
* FORTRAN compiler (eg g77, but see src/gap4/legacy_f2c.c and the
	            src/gap4/Makefile if this is an issue)
* GNU make
* TexInfo (for documentation only)
* Perl, Awk, Sed (for documentation only)

Note that if you are using gfortran then the GNU autoconf system does
not automatically detect the requirement of -lgfortran on link lines
while building libraries. To fix this add "LIBS=-lgfortran" on to the
end of your ./configure command.

Building the package consists of two main components: source code and 
documentation plus course material.


Source code
===========

The program source is all held within the src directory. It now uses
the GNU autoconf system on all systems, but we recommend using it in
the following manner.

    cd src
    mkdir build.myhost
    cd build.myhost
    ../configure [options]
    make

You may need to specify options to the configure script in order to
find certain third-party packages:

  --with-io_lib=DIR
	Specifies the prefix for an io_lib install.

  --with-zlib=DIR
	Specifies the prefix for a zlib install.

  --with-lzma=DIR
	Specifies the prefix for an XZ Utils install, containing the
	lzma library.

  --with-libcurl=DIR
	Specifies the prefix for a curl install.

  --with-tcl=DIR
	Specifies the directory containing a tclConfig.sh file.

  --with-tk=DIR
	Specifies the directory containing a tkConfig.sh file.

  --with-tclinclude=DIR
	If not found in the place specified in tclConfig.sh, this
	specifies the root directory of a tcl source tree (so it
	should have generic, unix, etc subdirectories).

  --with-tkinclude=DIR
	If not found in the place specified in tkConfig.sh, this
	specifies the root directory of a tcl source tree (so it
	should have generic, unix, etc subdirectories).

  --with-tklib=DIR
	Specifies the root directory of the tklib package; that is the
	package directory for tk extensions, written in pure tcl code,
	rather than the Tk library itself (which is specified using
	--with-tk).
	
You may also want to use the --prefix=DIR option to control the
install prefix (defaults to /usr/local/staden).

Note that on some systems it is not sufficient to simply use the
--with-x=y syntax, but you also need to setup LD_LIBRARY_PATH to
include the location of any run-time libraries prior to linking
against them. This shouldn't be an issue for libraries installed in
the default system locations.

Examples for standard systems follow. Try first with a minimum of
--with parameters and then read the summary at the end (if it gets
that far) to see whether it correctly detected the packages. You
should see something like this:

External packages used:
curl:      via /usr/bin/curl-config
zlib:      DIR (system)
curses:    DIR (system)
liblzma:   DIR /software/badger/opt/xz_utils
io_lib:    via /software/badger/bin/io_lib-config
Tcl:       via /usr/lib/tcl8.4/tclConfig.sh
Tk:        via /usr/lib/tk8.4/tkConfig.sh
tklib:     /software/badger/opt/tcl_packages/tklib0.5
Iwidgets:  /usr/lib/iwidgets4.0.1
Itcl:      /usr/lib/itcl3.2
Itk:       /usr/lib/itk3.2

As noted above, do not be concerned if it reports "***NOT FOUND***"
for some of the optional packages, in particularly iwidgets, itcl and
itk.


Linux / Debian
--------------

(My local build system, which produced the configure summary above.)

mkdir src/build.debian
cd src/build.debian
../configure \
    --with-tcl=/usr/lib/tcl8.4 --with-tk=/usr/lib/tk8.4 \
    --with-tklib=/software/badger/opt/tcl_packages/tklib0.5 \
    --with-lzma=/software/badger/opt/xz_utils \
    --with-io_lib=/software/badger \
    --prefix=$HOME/staden.install


Linux / Ubuntu 10
-----------------

Packages used (may be incomplete):

apt-get install g++
apt-get install zlib1g-dev
apt-get install tk-dev
apt-get install liblzma-dev
apt-get install tklib
apt-get install libcurl3-gnutls-dev
apt-get install libncurses5-dev


Linux / Fedora
--------------

Much the same as other linux systems, but I took note of the packages
I had to install:

yum install gcc
yum install gcc-c++
yum install zlib-devel
yum install tk-devel
yum install tklib
yum install curl-devel
yum install ncurses-devel
yum install libpng-devel
yum install libXt-devel (for X11/Intrinsic.h)

After compiling and installing you may see errors like this:

".../lib/staden/libtk_utils.so: cannot restore segment prot
after reloc: Permission denied"

This is due to SElinux being set to enforcing. The correct way to
resolve this is to use the chcon command as follows:

    chcon -t texrel_shlib_t /PREFIX/lib/staden/lib*

where PREFIX is the --prefix value used in autoconf.

(Alternatively SElinux can be made less picky by running
 "/usr/sbin/setenforce 0")

Note that if you are running a 64-bit system and have 32-bit
compatibility libraries installed then RedHat systems will try to
tempt configure scripts to use old 32-bit libraries in preference.

To solve this you can manually override the search paths. Eg:

../configure --with-tcl=/usr/lib64 --with-tk=/usr/lib64


Linux / Centos
--------------

yum install xz-devel
yum install tk-devel
yum install zlib-devel

Other packages as listed in Fedora, but appeared to be installed as
part of the base OS.

Note the comment under Fedora for building on 64-bit systems with
32-bit libraries.


Microsoft Windows
-----------------

1. Main source tree

The Windows build can use the same configure script as the Unix build,
provided you have the GNU tools installed. I used MinGW and Msys as
the compiler / environment, but it may build in other environments.
Please let me know of any necessary changes if you try this.

I used the automated mingw installer
(https://sourceforge.net/projects/mingw/files/) however it wasn't
entirely trouble free to get a working install.

You may also need to run "mingw-get install libz" to get a working
zlib with include files. (Mileage seems to vary per person on this
which is confusing; perhaps the installer is changing rapidly.)


2. src/windows/run

Once the main package has built, you'll also want to cd into the
src/windows/run directory and build that. This is a little executable
front end that replaces the bourne shell startup scripts used on unix
(eg the "gap4" or "trev" scripts and similar). The purpose is simply
to set up environment variables before running tclsh on the
appropriate GUI program.


3. WiX installer and .msi files

Install WiX somewhere. It can be found on sourceforge or via
google.  This takes an XML config and uses it to create a Microsoft
Installer file (.msi). 

You need a full Staden Package "make install" and any additional files
you wish manually placed there. I typically put tcl/tk in that
directory too and any additional run time libraries (zlib, lzma,
etc) to make the code self contained.

# See the README file in this directory too
cd src/windows/wix

# The c:/jkb/staden/install_root is the target of my --prefix earlier,
# but with proper windows-style drive letter naming.
#
# You may also need Strawberry Perl here as the msys one munges
# pathnames when it generates the .wxi file, which wix then will reject.
perl generate_wxs.pl c:/jkb/staden/install_root > staden_files.wxi

# This produces the staden.msi file
DISTROOT=/c/jkb/staden/install_root candle staden.wxs
light -ext WixUIExtension staden.wixobj


MacOS X
-------

[31st Oct 2013]

Fetch latest tcl/tk (8.6.1 at time of writing) and use the "unix"
build. Export MACOSX_DEPLOYMENT_TARGET=10.5 (environ) and Configure
with --prefix=$HOME/sys "CFLAGS=-arch i386 -arch x86_64".

Do a make, make install, and then copy in the ../license.terms file to the
$HOME/sys/lib/{tcl,tk}* directories too to comply with the
redistribution clause.

(Or maybe  -macosx_version_min 10.5.0 on cflags too)

Similarly for tcllib and tklib, do configure, make install, and copy
those licences as well.

Io_lib: as per tcl/tk above, but also add
--disable-dependency-tracking and --with-libcurl=$HOME/sys too. The
curl copy in $HOME/sys is needed purely for linking against to get a
dependency on an old API, but it can be removed from the distributed
tarball I believe.

The dependency tracking bit is there because it is incompatible with
cross compiling.



[older]

Tested on both 10.5 and 10.6.  Just use the configure script as per
any normal Unix system, but be aware of a few specifics regarding
tcl/tk.

Tk comes in two forms - a native Aqua look-and-feel (with Frameworks)
and an X11 version. The latter is simply the product of building
tcl/tk using the "unix" subdirectory instead of the "macosx"
directory.

*** NOTE: The staden package needs the X11 version of Tk ***

It's quite likely you will have the aqua Tk already installed too, and
configure will probably detect this first. In this case manually
specify the tcl & tk locations. Eg if using MacPorts:

./configure --with-tcl=/opt/local/lib --with-tk=/opt/local/lib

Macport packages used (not an exhaustive list):

tcllib 1.11
tklib 0.5
tcl/tk 8.5.9


MacOS X - native libs
---------------------

If you want to build a fat (universal) binary you will need to use the
native install of X11 libraries in /usr/X11R6/lib instead, as the
MacPort libraries are not cross-platform. To do this, you'll need to
build third party packages yourself, including tcl/tk in X11 mode.

As an example, in bourne shell syntax:

$ cd src/tcl8.5.9/unix
$ CFLAGS="-O -arch i386 -arch x86_64 -arch ppc -arch ppc64" ./configure --prefix=/nfs/sam_scratch/jkb/src/tcltk_inst
$ make; make install
$ cd ../../src/tk8.5.9/unix
$ CFLAGS="-O -arch i386 -arch x86_64 -arch ppc -arch ppc64" ./configure --prefix=/nfs/sam_scratch/jkb/src/tcltk_inst --with-tcl=/nfs/sam_scratch/jkb/src/tcltk_inst8.5/lib
$ make; make install

When compiling the Staden Package remember that there are one or two
C++ libraries too, so you need to redefine CXXFLAGS as CFLAGS on the
command line.

Tracking down problems can be tricky in fat binaries. A handy hint for
telling what dependencies and architectures binaries and libraries
have is to use otool.

$ otool -arch all -h libstaden-read.dylib
...
$ otool -L libstaden-read.dylib
...
$ lipo -info libstaden-read.dylib
...

A more verbose version of otool -L is otool -l. It's the same data.
However it lists the libraries the program wants to load and not the
libraries it finally resolves and does load. To see those use:

DYLD_PRINT_LIBRARIES=1 DYLD_PRINT_RPATHS=1 DYLD_PRINT_OPTS=1 ./bin/gap5


Documentation / Course notes
============================

These have now been moved to their own package named
"staden_doc-2.0.0b8-src.tar.gz" (and subsequent releases).

Please download this from sourceforge and read the building and
install documentation within there.
