ePiX -- INSTALL

Last Change: June 02, 2006

This file contains detailed installation instructions for ePiX-1.x

Lines starting with a "%" denote commands typed at a shell prompt. 
Lines starting with a "#" denote commands run as root.
Don't type the prompt characters "%" or "#". :)

"${prefix}" stands for the complete path to the install directory,
e.g. "/usr/local" or "/home/hwang/epix".


The following software must be installed on your system in order for
you to use ePiX:

  * The GNU shell, bash
  * A C++ compiler and development libraries, preferably g++ (> 3.1)
  * GhostScript, ImageMagick, and teTeX
  * GNU binutils, textutils, and fileutils (ar, sed, grep, ln, rm...)

Please consult your system documentation for information on installing
these components. The POST-INSTALL file contains potentially helpful
information, as well.


ePiX comprises a header file (epix.h), a compiled library (libepix.a),
and four shell scripts (epix, elaps, flix, and laps) that automate
file processing by running auxiliary programs.  The shell scripts must
be in your PATH.


--- Synopsis ---

(1) Unpack
(2) Configure:

% ./configure [options]

(3) Build:

% make
% make install


--- Step-by-step Instructions ---

(1) Unpack

  Tarballs are available gzip or bzip2 compressed. To unpack, use the
  appropriate version number and tar options (z for .gz, j for .bz2, v
  to see filenames unpacked):

% tar -zxf epix-x.y.z.tar.gz

  or

% tar -jxf epix-x.y.z.tar.bz2

  If your "tar" doesn't understand decompression, do

% gunzip -c epix-x.y.z.tar.gz | tar -xf -

  or

% bzcat epix-x.y.z.tar.bz2 | tar -xf -


  Change to the source directory:

% cd epix-x.y.z


(2) Configure the package:

  As of Version 1.0.7, ePiX uses GNU autoconf. The build commands now
  match the familiar "./configure; make; make install". To customize
  the build, you needn't edit a config file, but instead will provide
  options (if needed) to the configure script. Most users can run one
  of the commands

% ./configure

  or

% ./configure --with-contrib

  (The latter configures epix to build S. D. Pedersen's enhancements
  for coordinate systems and the accompanying documentation. If you
  don't know what these are, you may safely run the first command.
  Otherwise, please read the NEWS file for important changes to the
  behavior of the contrib package.)

  To change the installation directory from the default (/usr/local)
  to your home directory, do

% ./configure --prefix=${HOME}

  To list all options, do

% ./configure --help


(3) Compile and install:

% make

  This builds the following files for installation:
  * A static library (libepix.a)
  * A header file (epix.h)
  * Four shell scripts
  * The manual and sample document

  If you configured the contrib package, a separate library and header
  will be built, and installed in parallel with the "core" library and
  header.

  Be sure you are using GNU make. If the build fails immediately with
  an error about unexpected characters in the Makefile, speak to your
  system administrator about availability of GNU make, or try running
  the command "gmake".


  If there are no build errors, you're ready to install.

  You must have write permission in the install directory you selected
  in step (2). If you have been logged on as yourself until now (a Very
  Good Idea:) and are installing in a system directory, do:

% su
Password: <your root password>

# make install

  (The root prompt on many systems is # rather than %.) If the install
  succeeds, you're done:

# exit

  If you are installing somewhere in your HOME directory, just type

% make install


(4) Post-Install:

  Documentation is installed in ${prefix}/share/doc/epix, as compiled
  files (ps, pdf) and tarred LaTeX sources.

  The directory ${prefix}/share/epix/config contains miscellaneous
  optional files, notably Jay Belanger's emacs mode for working with
  ePiX source files, and completions for users of Ian MacDonald's bash
  completions package. POST-INSTALL has instructions on installing and
  using these files.

  From the source directory, do
  
% make clean

  to clean the source tree of compiled files. This command removes the
  top-level Makefile. Run ./configure to re-create the Makefile if
  necessary.


(5) Uninstalling:

  To remove a version of ePiX from your system, go to the directory
  where the sources were unpacked, log on as root if necessary, and do:

# make uninstall

  If you ran "make clean" at some point, you need to ./configure the
  source package *the same way as it was originally built* before you
  do "make uninstall".


  To uninstall multiple versions, it suffices to remove the following
  files and directories manually:

[] Shell scripts
  ${prefix}/bin/{elaps,epix,flix,laps}

[] Static libraries
  ${prefix}/lib/libepix.a   (Symbolic link)
  ${prefix}/lib/libepix-*.a (Versions prior to 1.0.6)
  ${prefix}/lib/epix/*      (Versions after 1.0.7)

[] Header files
  ${prefix}/include/epix*.h

[] Configuration files
  ${prefix}/share/epix/*     (Versions prior to 1.0.6)
  ${prefix}/share/doc/epix/* (Versions after 1.0.7)

[] Manuals and samples
  ${prefix}/share/doc/epix/*


--- Contact Information ---

If you have questions, comments, suggestions, etc., please write to:

Andrew D. ("Andy") Hwang  <rot 13 nujnat at zngupf dot ubylpebff dot rqh>
Dept. of Mathematics and Computer Science
College of the Holy Cross
Worcester, MA, 01610-2395, USA