install.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  install.tex     ACE documentation - installation     Alexander Hulpke
%W                                                      Joachim Neub"user
%W                                                            Greg Gamble
%%
%H  $Id$
%%
%Y  Copyright (C) 2000  Centre for Discrete Mathematics and Computing
%Y                      Department of Information Tech. & 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. 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   (see
Section~"ref:Command  Line  Options"),  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  (since
{\GAP}~4.3) may be replaced by a tilde.  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 above commented out because we don't ordinarily ship `make_doc'
%% and in any case they would need `tools.tar.gz' and various other
%% things to run it.

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{Ram99ace}). 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. Since
{\GAP} 4.4, this is done by calling

\beginexample
gap> LoadPackage("ace");
---------------------------------------------------------------------------
Loading    ACE (Advanced Coset Enumerator) 5.2
GAP code by Greg Gamble <[e-mail]> (address for correspondence)
       Alexander Hulpke (http://www.math.colostate.edu/~hulpke)
           [uses ACE binary (C code program) version: 3.001]
C code by  George Havas (http://staff.itee.uq.edu.au/havas)
           Colin Ramsay <[e-mail]>
Co-maintainer: Max Horn <[e-mail]>

                 For help, type: ?ACE
---------------------------------------------------------------------------
true

\endexample

\atindex{option pkgbanner}{@option \noexpand`pkgbanner'}
In version 4.1 of the {\ACE} package there was an  option  `pkgbanner'
that allowed the user  some  control  on  how  the  banner  above  was
displayed. This only worked with {\GAP}~4.3. Since, the {\ACE} package
now requires at least {\GAP}~4.4, this option has been removed. If you
still have {\GAP}~4.3, you will need to use {\ACE}~4.1.

\index{banner!suppression}
The banner may be suppressed by providing the version string (`"5.2"')
as second argument and `false' as third argument to the  `LoadPackage'
command.    The    `LoadPackage'    command    is     described     in
Section~"ref:LoadPackage" in the {\GAP} Reference Manual.

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

If you want to load  the  {\ACE}  package  by   default,  you  can  put
the  `LoadPackage' command into your `gaprc' (or  `.gaprc'  file)  (see
Section~"ref:The gap.ini and gaprc files" in the {\GAP} Reference Manual).

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