Hints and directions for building FramerD

FramerD is written in ANSI C and has been ported to a range of
platforms.  Building a version for your platform involves four
steps:
  1. configuring the distribution
  2. compiling the distribution
  3. installing the results
  4. configuring the environment
where (3) and (4) are optional depending on how you plan on using
FramerD.

1. Configuring the distribution

FramerD uses GNU autoconf to try and figure out what is needed and/or
available for particular platforms.  The shell script "configure",
which comes with the source release, checks out various aspects of the
compilation and runtime environments and generates both the header
file include/framerd/config.h and the makefiles for FramerD and its
plugins.

	To run "configure", just go into the root source directory for
FramerD and type ./configure.  Configure takes a bunch of flags which
you can list with ./configure --help.  The most common ones to specify
are --prefix and --exec-prefix which specify the install location for
machine-independent files and machine-dependent files.  For example,
   ./configure --prefix=/usr/opt
puts executables in /usr/opt/bin, shared libraries in /usr/opt/shlib, etc.

	By default, FramerD attempts to compile for threads.  However,
support for threads is a little rough across platforms so if you run
into problems you may want to configure it to build without threading
by giving the flags:
    --without-threads
to "configure".

	FramerD tries to use the local GNU readline
library if it is available.  You can turn this off by compiling with
--without-readline.

	If you configure --with-dynamic-linking, executables
are linked with dynamic versions of the FramerD libraries, which will
make things smaller but add more run-time dependencies.  In particular,
you have to make sure that you've set up /etc/ld.so.conf or LD_LIBRARY_PATH
to include the FramerD libraries.

	Finally, if you configure with --enable-moveable, FramerD will
try to produce binaries which can be located anywhere and have configuration
information relative to the location of the binary.  This is useful if you are
building a pre-compiled binary distribution which might be unpacked anywhere
in the filesystem.

2. Compiling the distribution

To build FramerD, go to the root directory and just run "make" or
"gmake" (GNU make).  If you have problems, get GNU make and build it
that way.  It uses the file "makefile" generated by ./configure.

The following targets (arguments to make) have special meaning:
   all:     (make everything, the default)
   install: (make everything and copy files to system directories)
   clean:   (remove executables, libraries and intermediate files)
   tidy:    (remove intermediate files)
   TAGS:    (build an Emacs tags file using etags (if available)
   test:    (run the standard test suites)

You can build a specific executable or library by specifying its
pathname.  E.G.
   make bin/fdscript
just makes the FDScript interpreter.  This is a good target if you just want
to check that the individual libraries compile since it requires all of them
except the plugins.

	I usually compile FramerD with gcc and have had some success
with other compilers on other platforms.  However it has not been
extensively tested with other ANSI C compilers.  If you run into very
strange compilation problems, you might try compiling with less
optimization than the configure script normally specifies.  You can
override the C compiler flags with the variable XCFLAGS passed to
"make".  E.G.
  make XCFLAGS=-O0
uses no optimization (assuming you're using gcc) when compiling the
files it needs.  Note that up-to-date files will not be recompiled
with the new flags, so you might want to try a "make tidy" first if
you want to make sure that everything is compiled with the specified
flags.

3. Installing the distribution

You can install the compiled code by just saying "make install" in the
top level directory.  This actually runs an install script written in
FDScript, so it's also a test of whether the compile worked.  This
script puts files (binaries, scripts, etc) in the locations determined
by the `prefix' arguments you gave to "./configure", which default to
	/usr/local/bin 			[executables]
	/usr/local/lib 			[static libraries]
	/usr/local/lib 		        [dynamic libraries]
	/usr/local/include/framerd 	[include files]
You may need to have priveleges to copy and make diretories in this
tree this, so if you get permission errors, that is probably the
problem.

The installation script also creates the following directory
	/usr/local/share/framerd
in which it creates a file framerd.cfg to contain the configuration
file for your installation.  In this same directory, it creates a file
`super-pool' in this directory.  This contains a new super pool with
an ID generated at random.  You can do register-super-pool <filename>
to claim this super pool uniquely.  This is a good idea if you will be
using it to generate knowledge bases which you intend to share.

	The binaries are able to run "as is" out of any directory or
you can also simply run them in the directories where they were built.
Alternatively, you can also copy them into your personal bin
directories rather than system bin directories (say under ~/bin if
that is in your path).

	The installation script also installs a number of FDSCript
scripts in the specified bin directory.  These are FDScript program
files which start with the line:
	#!/usr/local/bin/fdscript
to indicate that fdscript should be used to interpret the files.  (If
you installed to a different location, the installed scripts will
start with a different line).

4. Setting up the environment

	 The preferred way to further customize FramerD applications
is to use the command fdconfig which modifies the FramerD
configuration file.  The command `fdconfig list' lists the current
configuration information and `fdconfig' with no arguments gives usage
information.



