README

Build instructions on Linux/Unix systems
========================================

Requirements
------------

* Basic Unix tools: awk, grep, sed, perl
* The autotools: libtool, automake (version 1.9 or later), autoconf (version
  2.59 or later)
* A recent gcc C++ compiler, such as g++-3.3 or later
* flex and bison; on Mac OS X < 10.5 (Leopard) using fink, the flex-devel
  package must be installed.
* The readline library (libreadline5-dev or the like)
* pkg-config for library dependency tracking (that requirement may be dropped
  later on)
* for any tests, the diagnostics library is required


Building from a fresh svn checkout
----------------------------------

First, get some auto-generated files (including configure) built using

  autoreconf -i

Next, you need to run the configure script. We recommend that you perform a parallel (vtree)
build, i.e., from your build directory, you should issue something like this:

	sourcepath/configure --prefix=installprefix

Next, run

	make

and then

	make install

To use a version of diagnostics installed on your system in the standard
location of and build in audit level, add

  --with-diagnostics=,audit

If you intend to build with CXXFLAGS="-Wall -Werror -pedantic", which is
recommended, you need to add -Wno-long-long and, with recent versions of GCC,
-Wno-deprecated to work around use of non-standard hash maps.

Re-compiling later on
---------------------

Run
  make
either in the top-level directory to build all parts or in any
subdirectory to rebuild the respective subtree only (altogether with
all their dependencies in other subtrees).

If new files have been added, the Makefile.am scriptlets are updated
automatically by config/update-makefiles.pl as appropriate. Thereby any new .cpp
or .hpp file is added to the appropriate variables. If a test (named .t.cpp) has
been added, the appropriate variables are set to have the test run upon the next
make check. If necessary, also a libtool convenience library entry is created.

If a new directory has been added, its name must be added to the
SUBDIRS variable in Makefile.am of the parent directory. Then, an initial
Makefile.am will be added to the subdirectory upon the next run
update-makefiles.pl. This Makefile.am fragment will then also be populated, if
there are any .hpp or .cpp files in the new directory. Furthermore, configure.ac
is updated to contain an entry of <DIRECTORY>/Makefile. This changes causes the
(necessary) re-run of configure.

Finally, the libraries for each executable must be added manually
to the respective LDADD variable in the corresponding Makefile.am
file.


Cleaning the source tree
------------------------

Usually, you will want to do a
  make clean
in the src directory. However, make clean leaves any generated untouched. That is: Makefile,
Makefile.in, configure, and *.cc files generated by flex and bison from the
parser. To clean these as well, run
  make maintainer-clean


Building the documentation
--------------------------

The documentation may be built using
  make doxygen-doc
in the src directory and is then found in doc/dx/


Builds for debugging or testing
-------------------------------

This requires the diagnostics library to be available and detected by configure.
In that case, the following additional builds may be performed from within any
source (sub-)directory:
  make audit
  make debug
  make prod (equivalent to make)
to build at the respective diagnostics levels. Note that the results
of the audit and debug are placed in the directory build/audit,
respectively build/debug, whereas make prod builds directly in the
source directory. If make debug or make audit fails while running configure with
an error: source directory already configured, purge the build/ directory using
rm -r build/ and run the make command again.

Regression tests are run using
  make audit-check
  make debug-check
  make prod-check (equivalently, make check)
  
The audit and debug builds enable the diagnostics annotations which
are no-ops in the prod builds. Furthermore, at audit and debug level,
debug information is included (i.e., with gcc the -g option is
enabled).

The annotations generate log files which are located in the test/
subdirectory. This directory also contains test data which is required
for regression testing. The binaries attempt to access a test/
directory within their working directory---thus you should start the
binaries resulting from audit and debug builds and the regression
tests in general from the top-level source directory (naturally, make
(audit|debug|prod)-check starts in the tests from the top-level source
directory, independently from where you invoke it).


Building a distributable source .tar.gz
---------------------------------------

Performing
  make dist
in the top level source directory yields an fshell2-<version>.tar.gz package that
may be redistributed.


Other make targets
------------------

Any other target defined by automake (cf. info automake) retains its default
behavior and may be used as well.


Important configure parameters
------------------------------

The only non-standard configure parameters are:
* --enable-install-headers: This is passed on to update-makefiles.pl to enable
  (or disable) the code that sets the location headers would be installed in. By
  enabling this, headers would be installed into a similar directory structure
  upon make install, otherwise all of them are put in a single directory. This
  option should always be enabled.
* --with-dignostics=<path>,<level>: Enable diagnostics and set the path to the
  libraries and headers (without the /lib, respectively, /include/diagnostics
  part); Furthermore the default build level is set, this should be "prod".