
			INSTALL for ivtools-0.6

Instructions for building ivtools-0.6.12 from source:

0. Compilation Environment

Tools you will need before you can build:

0.a. a Unix machine.  We know it has been built on Linux, SunOS,
Solaris, and Irix.  We've incorporated diffs to build on HPUX 9.05.
It should build on most any Unix machine with similar config changes.

0.b. The gcc compiler.  Recently we've been building and testing with
gcc-2.7.2.1.  gcc-2.7.2, and gcc-2.6.3 will probably still work.  You
will also need an equivalent copy of libg++.  The libg++ version
numbers stay roughly in synch with the compiler version numbers.  If
you have if you have gcc-2.6.3 you'd want libg++-2.6.3, etc..

0.c. An installed copy of X11R4, X11R5, or X11R6 as distributed by
MIT, or equivalent (i.e., XFree86 for Linux, etc.)  If you use a
vendor's X11 product, the product should be based on R4 or later and
the product should include imake and the config files.

If imake is not in the same place as the other X11 binaries are or
anywhere else on your system, you can get the sources for imake from
the X11R5 or X11R6 distribution at several public ftp archives (such
as ftp.x.org).  

0.d. You also might want to acquire and build clippoly, a LGPLed library for
polygon clipping from:

http://www.ph.tn.tudelft.nl/People/klamer/clippoly_entry.html

Be sure to compile with -fPIC, then make a libclippoly.so in the
clippoly directory with: "gcc -shared -o libclippoly.so *.o". 

0.e. You also might want to acquire and build ACE, a C++ middleware
toolkit available from:

http://www.cs.wustl.edu/%7Eschmidt/ACE.html

Follow the instructions to build a shared library.  We currently use
ACE-4.2, with a patch applied to alleviate warnings:

http://www.vectaport.com/pub/src/ace4.2warnpatch

ACE-4.5 has worked as well with recent versions of gcc and egcs.

0.f some version of lesstif or Motif (libXm), if you want to build the
ivxt example program, which demonstrates the embedding of a ivtools
drawing editor inside Motif widgets.  Without these libraries and
include files the build of ivxt will fail, which can be safely
ignored.  To enable the ivxt build change line 7 of src/Imakefile from
"#if 0" to "#if 1".

1. Creating and/or editing config/site.def.$CPU:

*************************************************************************
** note:  A configure script now exists that has been tested on Linux, **
**        and might work for HPUX, SunOS, Solaris, Irix, and Alpha.    **
**        It still relies on imake, but eliminates the need to         **
**        manually edit the config/site.def.$CPU file.  If you want to **
**        try it, use the instructions in Appendix A instead of Step 1 **
**        and 2 below.                                                 **
**								       **
**        To revert to old-style config'ing for any of these OS'es,    **
**        change the "#if 0" near the end of the site.def.$CPU file to **
**        a "#if 1" and everything should be the same as before.       **
*************************************************************************

1.a. Set your CPU environment variable to one of the supported types
(grep config/arch.def for ArchitectureName to get a complete list or
try "make CPU" from the top directory of ivtools).  Use "setenv
CPU arch" for csh or "export CPU=arch" for sh/bash.  LINUX, SUN4, and
SGI are known to work.

1.b. Either edit the site.def.$CPU file if it exists, or determine
which existing site.def.* is closest to your needs and copy it into
site.def.$CPU.  ***Edit the parameters in this file as needed for your
facility.*** Especially verify that any pathname definitions are
correct for your environment.  

First redefine ProjectDir (at the top of each site.def.$CPU file) to
be the directory where links to all relevant software packages can be
found (i.e. where the ivtools-0.6 src tree, where clippoly, ACE,
and/or lesstif sources can be found if using any of those).

Set InstallRelative to YES if you want installation done within the
ivtools-0.6 directory, or NO if you want them installed in the BinDir,
LibDir, and LibDataDir as described in the installation section below.

If you're building on Solaris you can use the SUN4 config file instead
of a SUN5 one (config/site.def.SUN4).

If you have built the clippoly library uncomment and adjust the definition
of ClipPolyDir.  This will cause commands that exercise clippoly to be
built into ivtools.

If you have built the ACE library uncomment and adjust the definition
of AceDir.  This will cause classes and commands that exercise ACE to
be built into ivtools.

1.c. You may also want to take a look at local.def and gcc.def, but you
should be able to successfully build ivtools by only changing
parameters in your copy of site.def.$CPU.  The top of local.def
defines macro preprocessor constants that are later used to initialize
make variables.  The bottom of local.def builds up pathnames to refer
to the libraries and important directories of this package.

2. Compiling ivtools:

2.a. cd to the ivtools-0.6/ directory.

2.b. Compile it with a "make World" command.  It needs the following
variable definitions:

	XCONFIGDIR	The location of your X11 config files.
	PWD		If you're using a shell without this pre-defined

Sample Linux command line: 
	make World XCONFIGDIR=/usr/X11R6/lib/X11/config 
Sample SunOS command line:
	make World XCONFIGDIR=/usr/local/lib/X11/config 
Sample Solaris command line:
	make World XCONFIGDIR=/usr/X/lib/X11/config PWD=`pwd`
Sample Irix command line:
	make World XCONFIGDIR=/usr/lib/X11/config


This command generates Makefiles hierarchically and builds everything.

3. Testing:

Each directory under ivtools-0.6/src that begins in lower case (except
for "include" and "scripts") contains executables that exercise some
particular functionality.  "cd" to each particular directory, type
"$CPU/a.out" and see what happens.  Most of the directories have
READMEs that go into further detail on how to use the example
programs.  ivtools-0.6/src/glyphs contains sub-directories of glyph
example programs.

4. Installation:

"make install" is supported for all the libraries and a subset of the
more utilitarian example programs: the four original InterViews
programs (idraw, iclass, idemo, and dclock), the four idraw derived
programs (drawtool, netdraw, flipbook, and comdraw) and the two
comterp programs (comterp and glyphterp).

When InstallRelative is NO the binaries are installed as stripped
executables in BinDir, the libraries are installed in LibDir, and the
run-time X resource and config files are installed in LibAllDir.

When InstallRelative is YES (the default in config/site.def.$CPU), the
binaries are installed in ivtools-0.6/bin/$CPU, the libraries are
installed in ivtools-0.6/lib/$CPU, and the run-time X resource and
config files are installed in ivtools-0.6/lib/ivtools.

note: idemo, comterp, glyphterp, and comdraw have config files
that must be installed (either relative or non-relative) for the
program to find them at runtime.

Appendix A: configure script

A configure script now exists in the top-level directory of
ivtools-0.6 that can be used to automatically do some of the
configuration that otherwise requires editing config/site.def.$CPU.
Now it has been setup to interface with each existing site.def.$CPU
file, but only tested for Linux.  It works by generating a
config/config-$os-gcc.mk (i.e. config/config-linux-gcc.mk) that is
included at the bottom of config/site.def.$CPU
(i.e. config/site.def.LINUX).  So instead of manually editing the
pathnames for X11, ACE, and clippoly, you can have the configure
script find them or supply them as arguments to the command line.
Here are the relevant command line options to the configure script:e

  --x-includes=DIR        X include files are in DIR
  --x-libraries=DIR       X library files are in DIR


  --enable-install-relative[=ARG]  install relative to source tree
  --prefix=DIR			   to use when install-relative false
				   (default is /usr/local)

  --enable-use-rpath=[=ARG]        use -rpath when linking

--enable and --with options recognized:
  --with-ace=<path>    Path to ACE source
  --with-ace-libs=<path>    Path to ACE libraries
  --with-clippoly=<path>    Path to clippoly source
  --with-clippoly-libs=<path>    Path to clippoly libraries


Here is an example of using the configure script with ACE and clippoly
libraries:

./configure --with-ace=/proj/ACE_wrappers --with-ace-libs=/proj/ACE_wrappers/ace --with-clippoly=/proj/clippoly --with-clippoly-libs=/proj/clippoly

After successfully running the configure script in the top-level
directory, do a "make World" as described in Step 2 above.  You won't
need the XCONFIGDIR argument, but you'll still need the PWD argument
if your shell does not supply this environment variable.

To revert to the old-style config'ing, simply change the "#if 0" near
the end of any config/site.def.$CPU file to "#if 1", and use the
instructions in Step 1 and 2 above as before.

Special note for Solaris users of the configure script: you may have
to manually set the PWD environment variable prior to running the
configure script as well.  Any suggestions on how to avoid this PWD
environment variable dependency with autoconf and configure are
welcome.  Send e-mail to ivtools-info@vectaport.com.



