
                              Install Instructions


Introduction
============

This document contains instructions for those who have downloaded the
pointless source code and want to build and install it on their system.  
It does not contain any information about installing binary distributions 
of pointless.

Supported Platforms
===================

The development platform for pointless is a debian Linux system, but
even in this early stage of development pointless is quite portable. 
There are some platforms where things are not quite as smooth, but we 
have sucessfully (some required tweaks in the generated files) compiled 
poinless on the follwing platforms:

    Architectures    : IA32, IA64, SPARC, PPC, alpha, mips4.
    Operating systems: Linux, Solaris, Irix, FreeBSD, NetBSD, OpenBSD,
                       Mac OS X.

Please, feel free to contact us in case you have problems compiling
pointless on your platform.


Cookbook Procedure
==================

If you are impatient and just want a standard installation, you can go
ahead and run through the following cookbook procedure.  If you get into
trouble following it, please read through the rest of this document
before contacting the pointless developers for technical support.
Remember to substitute "x.y" with the version identifier for the pointless
you are building.

  # 1. Unpack source code and make a build directory somewhere:

    cd /tmp
	gunzip pointless-x.y.tar.gz
	tar xvf pointless-x.y.tar

  # 2. Run configure from the build directory:

    cd pointless-x.y
    ./configure

  # 3. Build pointless:

    make

  # 4. Check that pointless works before you install it:

    make check

  # 5. Install pointless:

    make install

  # 6. Install extra pointless modules:

	pointless ships with a couple of extra modules that were
	constructed to demonstrate how one can integrate ones favorite
	tool into pointless. The current list of modules is:
	{ eps, tex, metapost, gnuplot, code, unicode }.

	You can install a module by typing:

    make install-[module-name]

	You can even try to install all modules by typing:	

    make install-modules

	If some of the modules fails to install due to missing programs
	on your system, you can revert to the module by module installation.

  # 7. Remove source and object files when you don't need them anymore:

    cd ..
    rm -rf pointless-x.y pointless-x.y.tar.gz 

Cookbook Procedure for building documentation too
=================================================

Substitute step '#2' to the steps above:

  # 2. Run configure from the build directory with option '--enable-html' 
       will ensure that html documentation is build as part of the building
       of pointless:

    cd pointless-x.y
    ./configure --enable-html

Morover, you can always explictly try to generate the documentation in 
various formats:

    cd doc
	make ps   (to generate documentation in postscript format)
	make pdf  (to generate documentation in pdf format)
	make html (to generate documentation in html format)

	pdf/ps documentation will appear in directory doc/paper-a4
	html documentation will appear in directory doc/html


The Build Environment
=====================

Pointless uses GNU Autoconf and Automake for the configuration,
compilation, and installation procedures.  This means you need a POSIX
shell environment and a decent "make" implementation.  You also need a
compiler for C++.

Most unixes have Bourne shells that are close enough to the POSIX
standard to be usable, and in the odd case where the vendor shell does
not cut it, you can install the GNU Bourne Again Shell (bash) as a
replacement.  Many unixes have poor make implementations wihtout
proper support for VPATH and other features that GNU Automake depend
on.  If you experience problems during the build phase, you might want
to try using 'GNU make' instead of the vendor 'make' program.  Make sure
'GNU make' is first in the PATH and that the environment variable $MAKE is 
not set to another 'make' implementation.

On Microsoft Windows platforms, you need to install the Cygwin
environment (www.cygwin.com) or something equivalent to get a POSIX
shell and the extra utilities needed to get through the build procedure.

The file INSTALL.GNU contains the standard, generic, installation
instructions for the GNU build environment.


Configuration Options
=====================

Pointless can be build using either X11 or SDL as the GUI environment. 
The default is to use X11 but this can always be changed by using the 
--enable-sdl=yes option to configure. (Please note, however, that we 
consider the SDL support to be "experimental" --  we will try to keep
it working, but the release procedures does not require testing of the
SDL configuration.) Below we confine ourselves to describe the two most
frequently used options to configure, namely

--prefix=<PATH>

  This option decides where pointless is going to be installed.
  The default is usually /usr/local but can be set to something else
  with this option.  Frequently used alternatives are /usr and /opt/pointless.

--help

  Specifying this option will cause configure to list all its command
  line options and exit.

