%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  install.tex     ANUPQ documentation - installation      Werner Nickel
%%
%%
%H  $Id: install.tex,v 1.7 2001/10/10 15:03:29 gap Exp $
%%
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Installing the ANUPQ Package}

The ANU `pq' program is  written  in  C  and  the  package  can  only  be
installed under UNIX. It has been tested on DECstation running Ultrix,  a
HP 9000/700 and  HP  9000/800  running  HP-UX,  a  MIPS  running  RISC/os
Berkeley, a NeXTstation running NeXTSTEP 3.0, a SUN running SunOS and  an
Intel Pentium based PC running Linux.

To install the {\ANUPQ} package, move the file `anupq-<XXX>.zoo' for some
version number <XXX> into the  `pkg'  directory  in  which  you  plan  to
install {\ANUPQ}. Usually, this  will  be  the  directory  `pkg'  in  the
hierarchy of your version of GAP 4. (However, it is also possible to keep
an additional `pkg' directory in your private  directories,  see  section
"ref:Installing GAP  Packages"  of  the  {\GAP}~4  reference  manual  for
details on how to do this.)

Then unzoo `anupq-<XXX>.zoo' by

%\begintt
\){\kernttindent}unzoo -x anupq-<XXX>
%\endtt

Change directory to the newly created `anupq' directory. Now you need  to
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, create a `Makefile' and list a number of ``targets'' to call `make'
with. If you have one of  the  standard  Linux  (or  NetBSD  or  FreeBSD)
systems with `gcc', wish to compile with  `-O2'  optimisation,  and  have
`gmp' with its include and  library  files  in  `/usr/local/include'  and
`/usr/local/lib', respectively, you can now simply call

\begintt
make
\endtt

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

If you need a special target (perhaps you don't have `gmp' or you are not
on a Linux, NetBSD or FreeBSD system) then you need to call `make' with a
target argument. If  the  targets  displayed  on  the  screen  after  the
`configure' step rushed past your eyes and you can't scroll back  to  see
them, you can ``pipe'' those same targets through `less' or `more',  e.g.
with `more':

\begintt
make unknown || more
\endtt

An abbreviation of the target list is as follows:

\begintt
'linux-iX86-gcc2-gmp'      for IBM x86 PCs under linux/BSD with GNU cc 2 and mp
'linux-iX86-cc-gmp'        for IBM x86 PCs under linux/BSD with cc and GNU mp
'linux-iX86-gcc2'          for IBM x86 PCs under linux/BSD with GNU cc 2
'linux-iX86-cc'            for IBM x86 PCs under linux/BSD with cc (GNU)
[... 16 lines deleted ...]
'sunos-gcc2-gmp'           for SunOS with GNU cc 2 and gmp
'sunos-cc-gmp'             for SunOS with cc and GNU mp
'sunos-gcc2'               for SunOS with GNU cc 2
'sunos-cc'                 for SunOS with cc
'unix-gmp'                 for a generic unix system with cc and GNU mp
'unix'                     for a generic unix system with cc
'clean'                    remove all created files

   targets are listed according to preference,
   i.e., 'sunos-gcc2' is better than 'sunos-cc'
   no target is the same as choosing 'linux-iX86-gcc2-gmp'
   additional C compiler and linker flags can be passed with
   'make <target> COPTS=<compiler-opts> LOPTS=<linker-opts>',
   e.g., 'make sunos-cc COPTS=-g LOPTS=-g'.

   set GAP if GAP4 is not started with the command 'gap',
   e.g., 'make sunos-cc GAP=/usr/local/bin/gap4'.

   in order to use the GNU multiple precision (gmp) set
   'GNUINC' (default '/usr/local/include') and 
   'GNULIB' (default '/usr/local/lib')

   do 'make unknown || more' to see these targets again via more
\endtt

Let's suppose that the `linux-iX86-gcc2-gmp' target does not satisfy your
requirements; let's suppose your system is Solaris 2.8 (i.e.~SunOS  5.8),
you have `gmp' but its include  and  library  directories  are  somewhere
else, and that `gap4' is the command used to initiate {\GAP}~4. Then  the
following `make' call might be correct in this case:

\begintt
make sunos-gcc2-gmp GAP=gap4 GNUINC=/opt/local/include GNULIB=/opt/local/lib
\endtt

If you  don't  have  the  *GNU*  multiple  precision  arithmetic  (`gmp')
installed on your system, don't worry,  `gmp'  is  *not  required*;  just
select an appropriate target without `-gmp'.

\indextt{ANUPQ_GAP_EXEC!environment variable}
The path of {\GAP} used by the `pq' binary (the value `GAP' is set to  in
the `make'  command)  may  be  over-ridden  by  setting  the  environment
variable `ANUPQ_GAP_EXEC'. These values are only  of  interest  when  the
`pq' program is run as a standalone; however, the `testPq' script  assumes
you have set one of these  correctly  (see  Section~"Testing  your  ANUPQ
installation"). When the `pq' program is started from {\GAP} communication
occurs via an iostream, so that the `pq' binary does not actually need to
know a valid path for {\GAP} is this case.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Testing your ANUPQ installation}

\indextt{ANUPQ_GAP_EXEC!environment variable}
Now it is time to test the  installation.  After  doing  `configure'  and
`make' you will have a `testPq' script. The script assumes that,  if  the
environment variable `ANUPQ_GAP_EXEC' is set, it is a  correct  path  for
{\GAP}, or otherwise that the `make' call that compiled the  `pq'  program
set `GAP' to a correct path  for  {\GAP}  (see  Section~"Running  the  pq
program as a standalone" for more details). To run the tests, just type:

\begintt
testPq
\endtt

Some of the tests the script runs take a while. Please  be  patient.  The
output you see should be something like the following:

\begintt
Made dir: /tmp/testPq
Testing the pq binary ... OK.
Testing the pq binary's stack size ... OK.
Checking GAP ...
 pq binary made with GAP set to: /home/rigel/gregg/bin/gap-dev
 Starting GAP to determine version and package availability ...
  GAP version (4.dev) ... OK.
  GAP has ANUPQ package (>= v 1.1) installed ... good.
  GAP has AutPGrp package installed ... good.
 GAP is OK.
Checking the link between the pq binary and GAP ... OK.
Testing the standard presentation part of the pq binary ... OK.
Doing p-group generation (final GAP/ANUPQ) test ... OK.
Tests complete.
Removed dir: /tmp/testPq
Enjoy using your functional ANUPQ package!
\endtt

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Running the pq program as a standalone}

\indextt{ANUPQ_GAP_EXEC!environment variable}
When the `pq' program is run as a standalone it sometimes  needs  to  call
{\GAP} to compute stabilisers of subgroups; in doing so, it first  checks
the value of the environment variable `ANUPQ_GAP_EXEC', and uses that, if
set, or otherwise the value of `GAP' it was compiled with,  as  the  path
for  {\GAP}.  If  you  ran  `testPq'  (see  Section~"Testing  your  ANUPQ
installation") and you got both {\GAP} is `OK' and the link  between  the
`pq' binary and {\GAP} is `OK', you should be fine.  Otherwise  heed  the
recommendations of the error messages you get and run the `testPq'  until
all tests are passed.

It is especially important that the {\GAP}, whose path you  gave,  should
know where to find the {\ANUPQ} and {\AutPGrp} packages. To  ensure  this
the path should be to a shell script that invokes {\GAP}. If  you  needed
to install the needed packages in your own directory (because,  say,  you
are not a system administrator) then you should  create  your  own  shell
script that runs {\GAP} with a correct setting of the `-l' option and set
the path used by the  `pq'  binary  to  the  path  of  that  script  (see
Section~"ref:Installing a GAP Package in  your  home  directory"  in  the
Reference Manual, which describes explicitly  how  to  create  the  shell
script).

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