Copyright (c) 2003 by Paul O. Lewis
Installation instructions for Linux/Unix/Mac
----------------------------------------

Assuming you have downloaded ncl-2.0.tar.gz to a machine named sherlock
and it now resides in your home directory (say, /home/plewis), the
following shows how to unpack, compile and install the libraries and
example programs composing the NCL.

1. (if building from the svn repository)
   Create the configure script

   sherlock [/home/plewis] 1% sh bootstrap.sh
   
OR

1. (if building from a posted archive)
    Unpack the archive

   sherlock [/home/plewis] 1% gunzip ncl-2.0.tar.gz
   sherlock [/home/plewis] 2% tar xf ncl-2.0.tar
   sherlock [/home/plewis] 3% cd ncl-2.0



2. Run the configure script to create the makefiles

   sherlock [/home/plewis/ncl-2.0] 4% ./configure --prefix=`pwd`

   The --prefix directive is optional: without it the example programs
   and libraries will be installed in the default locations (probably
   /usr/local/bin and /usr/local/lib, respectively). The `pwd` (note
   the use of two backquotes here) uses the output of the pwd command
   (the present working directory) as the base directory for the install
   stage. This would result in the example programs being installed in
   /home/plewis/ncl-2.0/bin and the libraries in /home/plewis/ncl-2.0/lib.
   The configure command has other options: use './configure --help' to 
   find out about them. Note that I have not anticipated the use of 
   configure options other than --prefix, so be aware that using them
   may have unexpected effects, or no effect whatsoever.

3. Invoke make to compile everything

   sherlock [/home/plewis/ncl-2.0] 5% make

4. Invoke make again to install the executables and libaries in the
   default location (or a non-default location if the --prefix option
   was used with configure)

   sherlock [/home/plewis/ncl-2.0] 6% make install

Installation instructions for Win32
-----------------------------------
If you downloaded the ncl-2.0.zip archive, you will find a directory called
VC6 in the unpacked distribution. This directory contains a Visual C++ 6 
workspace and projects for building a static NCL library and each of the
three example applications. 

Example applications
--------------------

The above procedure creates both a static link library as well as 'so'
files (shared object libraries). Both libraries are complete implementations
of the NCL, but only the shared object libraries are used by the example 
programs. To test the library, try out the example programs, which will now
be in the 'bin' subdirectory under the directory specified by --prefix:

nclsimplest is identical to the program described in the main documentation.
In the example installation described above, the main documentation would be
rooted at the file /home/plewis/ncl-2.0/html/index.html. This program 
recognizes only two blocks, TAXA and TREES, and is designed to show how little
programming is really necessary to use the NCL. As a result, this program is
not very user-friendly and you will have to take a look at the main function
of the nclsimplest.cpp file to get an indication of how to invoke the program.

ncltest is more complete, although still not very user-friendly. This program
should be able to read most existing NEXUS formatted data files, assuming
those data files follow the original description of the format. Note that
some newer programs (e.g. MrBayes and Mesquite) have added new features to
the original NEXUS blocks, and thus files created for these programs may
not be read correctly by ncltest and other programs based on the NCL library.

basiccmdline is designed to illustrate how to write a more user-friendly, 
command-based application using the NCL. When it starts, it presents the
user with a prompt (BASICCMDLINE>) and allows the user to enter several
commands, including 'help', 'quit', 'log', 'execute' and 'show'. Try using
the 'execute' command to read a NEXUS file, then the 'show' command to output
a summary of the information in the file.

Three example data files (characters.nex, distances.nex and sample.tre) are
present in the data subdirectory (e.g. /home/plewis/ncl-2.0/data in the 
example installation above). You may wish to copy these files into your bin
directory to make it easier to use them with the three example programs.

Building your own applications
------------------------------
The simplest way to incorporate the NCL into your own applications is to
just include the relevant source code files into the Makefile for your 
project and thus statically link the NCL into your program. Here is a simple
Makefile that could be used to create the nclsimplest example application:

--------------- start of example Makefile ----------------

# Start by defining some useful macros
#
SRC_DIR       = ./src
SHELL         = /bin/sh
CXX           = g++
CXX_FLAGS     = -O2
INCLUDE_FLAGS = -I$(SRC_DIR)
LINK_LIBS     = -lm -lstdc++

# Define the list of object files that are needed to build
# the nclsimplest application
#
NCL_OBJS      = nxsblock.o \
                nxsexception.o \
                nxsreader.o \
                nxsstring.o \
                nxstaxablock.o \
                nxstoken.o \
                nxstreesblock.o 

# Use .PHONY to create targets that are always rebuilt, even
# when their timestamps indicate that they are up-to-date
#
.PHONY : all clean cleanall
all : $(NCL_OBJS) nclsimplest
clean :
        rm -f *.o
cleanall : clean
        rm -f nclsimplest

# The following rule rebuilds any .o file whose corresponding
# .cpp file is not up-to-date. The $< means 'first depencency'
#
%.o : $(SRC_DIR)/%.cpp
        $(CXX) $(INCLUDE_FLAGS) $(CXX_FLAGS) -c $<

# Now comes the rule for building the main target
# The $@ means 'target file name'
# The $< means 'first depencency'
#
nclsimplest : nclsimplest.o $(NCL_OBJS)
        $(CXX) $(LINK_FLAGS) -o $@ $< $(NCL_OBJS) $(LINK_LIBS)

--------------- end of example Makefile ----------------

A more portable option is to do as I have done and use the GNU 
build system to create your distribution. I have included the files I used
with GNU Automake (Makefile.am and src/Makefile.am). These files, with
little modification, can be used in turn as the basis for your distribution.
You will need to download (from www.gnu.org) and install Automake (ver. 1.7 
or higher), Autoconf (ver. 2.57 or higher), and LibTool (ver. 1.5 or higher)
on your system to make use of this third option.

