%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  install.tex     ACE documentation - installation     Alexander Hulpke
%W                                                      Joachim Neub"user
%W                                                            Greg Gamble
%%
%H  $Id: install.tex,v 1.13 2002/02/28 17:59:22 gap Exp $
%%
%Y  Copyright (C) 2000  Centre for Discrete Mathematics and Computing
%Y                      Department of Computer Science & Electrical Eng.
%Y                      University of Queensland, Australia.
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Installing and Loading the ACE Package}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the ACE Package}

To install, unpack the archive file, which should have a name of  form
`ace-<XXX>.zoo'  for  some  package  version  number   <XXX>,   as   a
sub-directory in the `pkg' hierarchy of your version of {\GAP}~4. This
might be the `pkg' directory of the {\GAP}~4  home  directory;  it  is
however also possible to keep an additional `pkg'  directory  in  your
private directories, see Section~"ref:Installing a GAP Package in your
home directory". (The only essential difference with installing {\ACE}
in a `pkg' directory different to the {\GAP}~4 home directory is  that
one must start {\GAP} with the `-l' switch, e.g.~if your private `pkg'
directory is a subdirectory of `mygap'  in  your  home  directory  you
might type:

%begintt
\){\kernttindent}gap -l ";<myhomedir>/mygap"
%endtt

where <myhomedir> is the path to your home  directory,  which  may  be
replaced by a tilde in {\GAP}~4.3. The empty path before the semicolon
is filled in by the default path of the {\GAP}~4 home directory.)

After unpacking the archive, go to the newly created  `ace'  directory
and call `./configure <path>' where <path> is the path to  the  {\GAP}
home directory. So for example if you install the package in the  main
`pkg' directory call

\begintt
./configure ../..
\endtt

This  will fetch  the  architecture  type for  which  {\GAP} has  been
compiled last and create a `Makefile'. Now simply call

\begintt
make
\endtt

to compile the binary and to install it in the appropriate place.

Note that the  current version of the configuration  process only sets
up  directory paths.  If you  need a  different compiler  or different
compiler options, you need to edit `src/Makefile.in'  yourself,  prior
to calling `make'.

If you use this installation of {\GAP} on different hardware platforms
you will have to compile the binary for each platform separately. This
is done by calling `configure',  editing  `src/Makefile.in'  possibly,
and calling `make' for the package anew  immediately  after  compiling
{\GAP} itself for the respective  architecture.  If  your  version  of
{\GAP} is already compiled (and has last been  compiled  on  the  same
architecture)  you  do  not  need  to  compile  {\GAP}  again,  it  is
sufficient  to  call  the  `configure'  script  in  the  {\GAP}   home
directory.

The manual you are currently reading describes how to use  the  {\ACE}
Package; it can be found in the `doc' subdirectory of the package.  If
your manual does not have a table of contents or index, or  has  these
but with  invalid  page  numbers  please  re-generate  the  manual  by
executing

\begintt
./make_doc
\endtt

in the `doc' subdirectory.

The subdirectory `standalone-doc' contains the file `ace3001.ps' which
holds a version of the user manual for the {\ACE} standalone; it forms
part of~\cite{Ram99}). You should consult  it  if  you  are  going  to
switch to  the  {\ACE}  standalone,  e.g.~in  order  to  directly  use
interactive facilities.

The  `src' subdirectory  contains a  copy  of the  original source  of
{\ACE}.  (The  only modification  is  that  a  file `Makefile.in'  was
obtained from  the different `make.xyz' and  will be used  to create a
`Makefile'.)  You  can replace  the source by  a newer  version before
compiling.

If you encounter problems in installation please read the `README'.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Loading the ACE Package}

To use the {\ACE} Package you have to request it explicitly.  This  is
done by calling

\beginexample
gap> RequirePackage( "ace" );
#I      The ACE (Advanced Coset Enumerator) Package
#I    C code by George Havas <havas@itee.uq.edu.au> and
#I              Colin Ramsay <cram@itee.uq.edu.au>
#I                   ACE binary version: 3.001
#I    GAP code by Greg Gamble <gregg@itee.uq.edu.au> and
#I           Alexander Hulpke <hulpke@math.colostate.edu>
#I                   ACE package version: 3.003
#I  
#I                   For help, type: ?ACE
true
\endexample

The      `RequirePackage'      command      is      described       in
Section~"ref:RequirePackage" in the {\GAP} Reference Manual.

If {\GAP} cannot find a working binary, the call  to  `RequirePackage'
will fail.

Since {\ACE}'s banner is `Info'-ed at `InfoWarning' level 1,  it  will
not be observed if the `InfoLevel' of `InfoWarning' is 0.

\index{banner!suppression}
The banner is also suppressed if the global {\GAP} variable `QUIET' is
`true' or `BANNER' is `false' (these conditions  occur  if  {\GAP}  is
invoked with the `-q' or `-b' command line switches, respectively). If
you want to load the {\ACE}  package  by  default,  you  can  put  the
`RequirePackage' command into your `.gaprc' file (see Section~"ref:The
.gaprc file" in the {\GAP} Reference Manual).

\atindex{option pkgbanner}{@option \noexpand`pkgbanner'}
Yet one more way of suppressing  {\ACE}'s  banner  is  to  supply  the
option  `pkgbanner'  with  value  `"none"'  to  the   `RequirePackage'
command:

\beginexample
gap> RequirePackage( "ace" : pkgbanner := "none" );
true
\endexample

Finally, the full banner is replaced by  a  ``short''  1-line  loading
message (`Info'-ed at `InfoWarning' level 1) if, instead,  `pkgbanner'
has the value `"short"':

\begintt
gap> RequirePackage( "ace" : pkgbanner := "short" );
#I  Loading ACE Package Version 3.003
true
\endtt

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E
