
This is INSTALL for shapeTools-1.4pl6.

It describes how to build and install the shape toolkit on your
computer. Please read the file "LICENSE" before installing and using
the shape toolkit on your machine.


The build/installation procedure
=================================

The first time you call "make" in this directory (the root directory
of the ShapeTools source tree), make invokes a configuration script
asking you a few questions about the environment where ShapeTools is
to be built and installed. You will be asked for:

- the operation system of your machine.
	See the following section for a list of supported operating
	system platforms.
- the compiler and compile flags to be used.
- whether the emacs lisp code shall be compiled and installed.
	This is *very* recommendable if you are an emacs user.
- whether the internal C-libraries and header files shall be installed.
	You will need these, when applying the patches for 'gdb' and
	'GNU-grep'.
- the locations, where executables, libraries and manuals shall be
	installed. Below in this file, you will also find some words
	about installation locations.

Subsequent calls of "make" will not run the configuration script
again automatically. Type

	make config	to run the script again and change the
			configuration of the build/install procedure

	make		to build ShapeTools
	make install	to install the commands, libraries and manuals
	make clean	to clean up


Important Hints
===============

file locking
	If you are sure, that the system file locking mechanism
	(fcntl,lockd) is installed correctly and works fine in your
	network, you should eliminate the -DATFS_OWN_LOCKING from the
	CFLAGS definition when running the configuring script.

	System 	file locking used to be default when installing
	ShapeTools, but it seems that this is a notorious
	trouble-maker on most machines (including ours). So we
	switched back to AtFS's own locking mechanism as default.
	This, however, is not 100% safe in NFS based environments. In
	some cases, conflicting updates may cause the loss of a change.

AIX	If you use AIX 3.2, you should set the environment variable
	"MALLOCTYPE=3.1". The shape program might run in an infinite
	loop otherwise.

NeXT	machines running Mach 3.0 have problems with file locking
	(fcntl). For this reason, you should not delete the 
	-DATFS_OWN_LOCKING switch from the CFLAGS.

BSD 	On pure BSD systems, /bin/sh is not capable to execute scripts
	containing shell functions. To use these scripts you have to
	install another shell (e.g. BASH). Then change the first line
	of the script from "#!/bin/sh" so that the appropriate shell
	is called. Currently this applies only to src/vc/vdiff/vdiff.

When modifying the Makefile manually, make sure to keep at least one
whitespace between equal sign and value in macro definitions. The
configuration script expects this.


Supported Operating System Platforms
=====================================

Our current development platform is Sun4/SunOS 4.1.2. We ported to and
tested the toolkit to a certain number of other machines. This is the
complete list of supported operating system platforms:

	AIX (tested on IBM RS6000 with AIX 3.2.0)
	HP/UX (tested on HP 9000 with HP/UX 9.0)
	IRIX (tested on Silicon Graphics with IRIX 4.0.5)
	mach (tested on NextStation with Mach 3.0)
	SunOS 4 (tested on SUN 4 with SunOS 4.1.3)
	Solaris 2 (tested on SUN 10 with SunOS 5.1) [*],[**]
	System V Release 4 (tested on a '386 system with ESIX) [**]
	Ultrix (tested on DECstation 5000 with Ultrix 4.2)

[*] The Solaris port was done with gcc. The Sun C-language package
    was not yet available.
[**] The Solaris 2 and System V Release 4 ports are identical.

For installing the toolkit on machines with other operating systems
see the section about porting to other system platforms below.


Installation Locations
=======================

ShapeTools is a pretty big package, consisting if executable commands,
manual pages and a bunch of different libraries. We recommend the
following installation tree:

	.../bin			commands
	.../man/man{1,3,5,7}	manuals
	.../include		include files (optional)
	.../lib			C-libraries (optional)
	.../lib/shape		shape libraries
	.../lib/emacs/lisp	emacs lisp code (optional)

If you agree with this setup, you just have to set the installation
base path (...) during the ShapeTools configuration phase. If not, you
may set the path for each group individually.


Needed Disk Space
==================

The following table shows, how much disk space you will approximately
need when compiling and installing ShapeTools. The values are
determined on a SparcStation 2 and may be different on your machine.

Distribution	  1.0 Mb (compressed)
		  2.4 Mb (unpacked)

Compilation 	  5.9 Mb (stripped) 	12.4 Mb (with debug info)
		
Installation
 - base system	  2.2 Mb (stripped) 	 5.5 Mb (with debug info)
 - libraries	  0.6 Mb (   "    )	 1.9 Mb (       "       )
 - emacs stuff	  0.1 Mb (   "    )	 0.1 Mb (       "       )


Porting ShapeTools to other Operating System Platforms
=======================================================

When implementing the toolkit, we tried to isolate operating
system specific code in two files named "config.c" and "config.h".
You find them in 'src/atfs/config.[ch]'. Porting the toolkit to
another (UNIX/POSIX) platform should begin with the examination of
these files. Try to avoid changes to any source file other than
config.[ch] as far as possible.

For compiling, configure the top Makefile using 'make config' and
choose the default system (sunos_4). After that, edit the Makefile and
change the '-DSUN_4' switch in the 'CFLAGS' definition to
'-D<your_system_name>'.

The Makefiles provided with the distribution of ShapeTools are not
really suitable for development, since they don't contain include file
dependencies. Dependencies  are held in separate files, named
'DEPENDENCIES'. Our development environment is based on
ShapeTools, where the dependencies files are included in the
Shapefiles. For Recompiling ShapeTools (or parts of it) after having
changed config.h, you must first perform "make clean" from the root of
the source tree or the appropriate subsystem.

If you have successfully ported the Shape Toolkit to another system,
please let us know. We would like to receive a diff-file documenting
your changes. This should help us to enlarge the set of ShapeTools
standard system platforms.

If you have any problems, drop a mail to: shape@cs.tu-berlin.de
