This directory contains the following directories:

  libraries
     Starlink Fortran/C libraries

  applications
     Starlink Fortran/C applications

  etc
     Starlink initialisation scripts

  buildsupport
     Starlink support applications required to build configure-based
     Starlink applications.

  thirdparty
     Third party applications and libraries required to build
     Starlink classic applications

  pubs
     Starlink publications

  docs
     General documentation not associated with a particular application
     or library.


Building the Starlink source set from scratch
---------------------------------------------

To build the COMPLETE set of Starlink classic applications the following steps
are required.  If you wish to do more elaborate things, then you should refer
to Starlink document SSN/78, which also contains some FAQs.  Details of this
document are at the end of this README.

This procedure will not build the Starlink _Java_ applications.  They are
built separately, using the procedure described in Java README
(currently these are available from the git repository at
git://github.com/Starlink/starjava.git). You do not need to build any of
the Starlink classic applications to build the Java ones, unless you need to
rebuild the native parts of JNIAST, JNIHDS or SPLAT.

 Preparation
 -----------

 - Ensure the required software development tools and headers are installed
   on your system (see the "Prerequisites" section below)

 - Specify where you want the installed files to end up (_PREFIX) and
   where you want the build to find any previously installed Starlink
   tree (_STARLINK).  If there is no previously existing tree, then
   set the two variables to the same value.  Both variables default to
   /star.  You must have write access to the directory you name here.

   Here and below we use /local-star as an example; in the examples
   below substitute your own choice for this directory.

      % setenv STARCONF_DEFAULT_STARLINK /local-star  # csh
      % setenv STARCONF_DEFAULT_PREFIX   /local-star

   or

      % export STARCONF_DEFAULT_STARLINK=/local-star  # sh
      % export STARCONF_DEFAULT_PREFIX=/local-star

-  Set up the environmental variables to allow the latex documentation
   to build.

   This requires the $STARLATEXSUPPORT to be set the location of the
   applications/latexsupport directory, and the $TEXINPUTS variable to
   also contain this location. (Note that these are the absolute paths
   to this directory within the checked-out code, not the path to an
   installed directory).


      % setenv STARLATEXSUPPORT /my/code/checkout/applications/latexsupport
      % setenv TEXINPUTS $STARLATEXSUPPORT//:

   or
      % export STARLATEXSUPPORT=/my/code/checkout/applications/latexsupport
      % export TEXINPUTS=$STARLATEXSUPPORT//:

-  Delete any previous Starlink environment variables.

      % unsetenv INSTALL  # csh
      % unsetenv STARLINK

   or

      % unset INSTALL     # sh
      % unset STARLINK

   and also make sure that an old-style Starlink system is not in your
   PATH (since tools like messgen will get very confused).

   You may also run into difficulties if you have previously sourced
   the ${STARLINK}/etc/login and ${STARLINK}/etc/cshrc scripts that
   existed from a previous classic mk-build Starlink install, as
   even with $STARLINK removed from your PATH some applications may
   still get confused at build time.  If the login script in question
   is a `new' one, from a previous autoconf install, you will
   probably be fine (although you may need to remove installed
   manifest files).

 - Review any other environment variables that might affect the build.
   For example, the variables F77, FC and CC will force the build
   system to use the specified compilers.  In particular, the default
   IRAF installation sets the F77 variable to be a script which works
   happily in most cases, but which will _not_ work with libtool, and
   will cause the build to fail with opaque error messages about being
   `unable to infer tagged configuration'.  Unless you do wish to
   force certain compilers to be used, it is probably better to unset
   these variables before building the software.  See './configure
   --help' for a list of `some influential environment variables'.

   This is good time to get the compilers that you're going to use
   resolved, especially if you're not working on a GNU/Linux platform.
   See the platform specific instructions later in this file.

   At the time of writing (February 2009) it is known that the gfortran
   compiler will work, but only from GCC4.3 onwards. If this is picked up by
   default on your system you need to re-define FC and F77 to select another
   compiler. For other versions of GCC4 you will need to use g95 (thanks to
   Andy Vaught for his help with this), which is available from the g95 web
   site: www.g95.org. For GCC3 based systems g77 should be used.

 - Ensure that /tmp has sufficient free space and is writable.


 The build sequence
 ------------------

 To build the complete source distribution, you go through the steps:

   ./bootstrap
   make configure-deps
   ./configure -C
   make world

   cd thirdparty/perlsys/perlmods
   setenv STARLINK_DIR $STARCONF_DEFAULT_PREFIX
   ./build-modules.sh

 Each of these steps is described in detail below.

 - First bootstrap the system.

   This downloads third-party software, builds and installs the buildsupport
   system (the tools in the buildsupport directory, plus third-party
   applications autoconf, automake and libtool), and then goes on to generate
   the configure scripts which will be used in the next step.  The autoconf,
   automake and libtool applications have been patched specifically for
   building this tree so any versions shipped with the OS, or installed by
   you, will _not_ work.  These applications will be installed into
   $STARCONF_DEFAULT_PREFIX/buildsupport, so you should add
   $STARCONF_DEFAULT_PREFIX/buildsupport/bin to the front of your PATH
   at this point, BEFORE you run the ./bootstrap script.  In order for the
   `make' below to work, you also need to add the default bin
   directory to your PATH, so you should do that now.

      # csh-like
      % setenv PATH $STARCONF_DEFAULT_PREFIX/bin:$STARCONF_DEFAULT_PREFIX/buildsupport/bin:$PATH
      % ./bootstrap

   or

      # sh-like
      % PATH=$STARCONF_DEFAULT_PREFIX/bin:$STARCONF_DEFAULT_PREFIX/buildsupport/bin:$PATH
      % ./bootstrap

   This step takes a long while. Note that, although an important part of the
   ./bootstrap script is running autoreconf in the top-level directory,
   you should not run autoreconf yourself in this directory.

 - Build the configure dependencies.

   There are a _few_ components which have to be built and installed
   before the main tree is configured.  You will have been advised of
   this at the end of the bootstrap process above, but in case you
   missed that, the command is

      % make configure-deps

 - Configure and build everything.

   Now configure and build the system.  The dependencies within the
   Makefile ensure that everthing is built in the correct order.

      % ./configure -C   # -C means caching results
      % make world

   If you need to give ./configure some help to find include files and
   libraries (for example, you are on a Mac and have installed Fink in
   /sw or OpenDarwin in /opt/local, or are on a Sun and have extra
   software in /opt), then do so by setting (for example)
   CFLAGS=-I/opt/local/include and LDFLAGS=-L/opt/local/lib either in
   the environment or, better, as arguments to the ./configure script.
   Don't do this unless you discover you have to.

   Each of these steps can also take some non-trivial time.

 - Finally install the Perl modules.

   The Perl modules can be installed using the build-modules.sh script
   in the perlmods directory.  This script requires that the environment
   variable STARLINK_DIR be set to the Starlink installation into which
   you would like to install the Perl modules, i.e. $STARCONF_DEFAULT_PREFIX.

      % cd thirdparty/perlsys/perlmods
      % ./build-modules.sh

   This will install or update if needed the dependencies from CPAN and
   then install all the modules present in the perlmods directory itself.

 Additional hints
 ----------------

 - Disabling shared libraries

   If you wish to disable the building of shared libraries you should
   use the --disable-shared configure option when you give the
   ./configure command above.

      % ./configure -C --disable-shared

 - Disabling the documentation

   By default, the system will be configured so that all documentation
   is built at the same time as the software.  For this to work, you
   must have LaTeX installed on your machine.  Building the documentation
   is rather slow, and you can speed up the build somewhat by omitting it.
   You do that as follows:

      % ./configure -C --without-stardocs

 - Building a single library or application

   If you wish to build only as far as a given component, then specify
   it by giving the name of the associated `manifest' file.

      % make /local-star/manifests/ast

   This will build, and install under STARCONF_DEFAULT_PREFIX, this
   component and _everything it depends on to be built_.


Developing individual components
--------------------------------

Note that this sequence of

   ./bootstrap; make configure-deps; ./configure -C; make world

is indeed a `make world' command -- it builds everything in the repository
that has been brought into the configure-based system, and will fail if some
components have not been checked out.  If you wish to build or develop a
specific component, the instructions are slightly different.

 - Specify the _PREFIX and _STARLINK variables as before, though this
   time it might be appropriate to give them different values, if you
   want to build against one installation tree (_STARLINK), but
   install into another (_PREFIX).  As above, unset the INSTALL and
   STARLINK variables, and make sure there is no old-style Starlink
   system in your PATH.

 - If you have already built the buildsupport tools (autoconf,
   automake, libtool and starconf), then make sure these are in your
   PATH.  If they are not built, or if you are not sure they are
   up-to-date, you can build just these by going to the top-level of
   your checkout and giving the command

      % ./bootstrap --buildsupport

 - Now you can go into a specific directory and build the library or
   application as normal (a bootstrap is required in the directory if
   you are building from a subversion checkout)

      % ./bootstrap
      % ./configure -C
      % make
      % make install

 - After updating a component from the repository, it is possible that some
   generated files will be out of date (if configure.ac or Makefile.am
   had been updated).  Any required updating is generally handled
   automatically by makefile rules, but if you wish to guarantee that
   everything is up to date, then you can give the command
   `autoreconf'.  This does no harm in any case, since it does nothing
   if it is not required.  As noted above, the exception to this is
   that you should not run autoreconf in the top-level directory.


Updating the source set
-----------------------

The `make world' command will not _re_build the tree after you do an update
from the source repository, possibly unexpectedly.  For a detailed explanation
of why this is so, see the `General FAQs' in SSN/78, described below.

You should also run the ./update-modules script after performing an update
of the source set from the main repository. This will make sure that any
thirdparty code is also updated.


Platform specific build notes
-----------------------------

 - GNU/Linux

 Currently (February 2009) the source set is known to build on many different
 flavours of GNU/Linux and is actively developed using these. The only expected
 issue is that of Fortran compiler support (C, C++ and Fortran compilers are
 required to build the complete collection).

 After the release of GCC 4 the Fortran compiler "g77" has been replaced with a
 completely new "gfortran" (that now implements Fortran 90, 95 and some 2003
 features), which has not been compatible with Starlink Fortran until the
 release of version 4.3. Happily this turned out to be not a major problem
 (thanks to Andy Vaught) as the other free Fortran compiler "g95", is
 compatible. So to build the collection with a GCC 4+ compiler you'll either
 need a copy of "g95" which is available from  "www.g95.org", or more a very
 recent version of gfortran (this can be checked by running gfortran -v).

 To make sure you use the "g95" or "gfortran" compilers as required it is best
 to define the environment variables "FC" and "F77":

      % setenv FC g95                     # csh
      % setenv F77 g95
   or
      % export FC=g95                     # sh
      % export F77=g95

   or

      % setenv FC gfortran                # csh
      % setenv F77 gfortran
   or
      % export FC=gfortran                # sh
      % export F77=gfortran

  before running "configure".

  - Ubuntu (>= 11.04 "Natty Narwhal) / Debian

  As of version 11.04 of Ubuntu the default handling of shared library
  linking has changed. In the past indirect linking was enabled, such
  that a program could link library "A", which in turn uses library
  "B", and without explicitly linking the latter, routines from "B"
  would be available (a situation that occurs in Starlink). Now that
  this capability has been disabled, you will likely see strange
  linker errors if you follow verbatim the build instructions as
  described earlier in this document.

  To remedy this situation you need to re-activate indirect linking
  with LDFLAGS when configuring the build:

      % ./configure -C LDFLAGS=-Wl,--no-as-needed

  Ubuntu explain the issue here:

  https://wiki.ubuntu.com/NattyNarwhal/ToolchainTransition

  According to the following web page, this problem will also occur with
  Debian (as of the Wheezy release), although it has not been tested:

  http://wiki.debian.org/ToolChain/DSOLinking

  - OS X

  The build situation under OS X follows much like that of GNU/Linux,
  but you'll need to install your own Fortran compiler. In 10.3
  the "g77" compiler from "Fink" or "MacPorts" has been used successfully,
  in 10.4 you'll need a copy of "g95". For 10.5 or later you can use
  g95, or gfortran. The latter is available from hpc.sourceforge.net
  as well as MacPorts.

  Note you'll also need a development installation of the Apple X11
  environment, and a functioning TeX and Ghostscript if you want to build the
  documents.

  - Solaris

  The collection is known to build under Solaris 8 (sparc) and 10 (intel),
  using the SUN compilers (Workshop 6 and studio 11 respectively). To make
  sure the correct compilers are picked up, you should define:

      % setenv FC f77                     # csh
      % setenv F77 f77
      % setenv CC cc
      % setenv CXX CC
   or
      % export FC=f77                     # sh
      % export F77=f77
      % export CC=cc
      % export CXX=CC

Further information
-------------------

The Starlink document SUN/248 gives further advice about building Starlink
classic applications, including some old, out-of-date, platform-specific
notes.  A version is currently (May 2006) available at
<http://www.astro.gla.ac.uk/users/norman/star/sun248/>.
The source is in the repository at docs/sun/248.

You should consult the project web pages at <http://www.starlink.ac.uk>,
<http://starlink.jach.hawaii.edu> and consider subscribing to the Starlink
development and user mailing lists: see
<http://www.jiscmail.ac.uk/archives/starlink.html> and
<http://www.jiscmail.ac.uk/archives/stardev.html>.

Starlink document SSN/78 gives much more detailed information on the
process of building Starlink classic applications, but this document
is primarily concerned with documenting the build system itself, and
describing how to add new components to the build-system repository.
The source for this document is in the repository at docs/ssn/078, and
a built version should be available on the Starlink web pages.  A
version is also currently (May 2006) available at
<http://www.astro.gla.ac.uk/users/norman/star/ssn78/>.

This document contains some FAQs: a few of these will likely be of
interest to thise building the system from a checkout, though most
address quite specific details of how to configure software to work
within the Starlink source tree.


git repository
--------------

In February 2009 the Starlink source code was moved to a git repository
at the JAC Hawaii. This is described by a wiki at:

   http://starlink.jach.hawaii.edu/

The build procedures described above are still correct, but much of the
associated documentation, SSN/78 etc. are becoming rapidly out-of-date.
Consult the wiki for download instructions and how to access things like
specific releases.


Prerequisites
-------------

This section lists some of the software development tools and headers
that are required to build Starlink. The list is not exhastive, but is
just a suggestion of some packages to check that may not not be provided
by default by your operating system.

Ubuntu:
   git
   gfortran (or g95)
   g++
   libxext-dev
   libxau-dev
   libx11-dev
   libxt-dev
   libncurses5-dev
   flex
   byacc
   latex
   texlive-latex-extra

Fedora:
   As for Ubuntu, but note that package names are usually changed from
   "libxyz-dev" to "libXyz-devel".

Arch Linux:
   base-devel
   ed
   gcc-fortran
   ghostscript
   git
   libx11
   libxt
   netpbm
   tcsh
   texlive-most

CentOS 7:
   libXext-devel
   libXau-devel
   libX11-devel
   libXt-devel
   libxml2-devel
   ncurses-devel
   texlive-multirow

SGML tools:
   A few documents within the Starlink tree were prepared using a
   workflow based on SGML tools -- this set includes SC/13, SSN/78,
   SUN/248, SSN/71 and SSN/70.  The ./configure scripts for the
   associated components look for the Open-SP and OpenJade tools, and
   skip the documentation if they don't find them.  These tools are no
   longer actively maintained, and are not trivial to build, but are
   still available in packages.  As of late 2014, the Debian 'openjade'
   package includes both tools, as does the macports.org 'openjade'
   package; the (OS X) Homebrew package manager includes an 'open-sp'
   package which does not include OpenJade.