7 Installing the ANUPQ Package

Sections

1. Testing your ANUPQ installation
2. Running the pq program as a standalone
3. Setting the Verbosity of ANUPQ via Info and InfoANUPQ
4. Utility Functions

The ANU pq program is written in C and the package can be installed under UNIX and in environments similar to 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 or Windows equipped with cygwin.

The current version of the ANUPQ package requires GAP 4.4, and version 1.2 of the AutPGrp package. If you still have GAP 4.3 (at least fix4), then you must use ANUPQ 2.2, and AutPGrp 1.1. You should not use earlier versions of the ANUPQ package since they are known to have bugs.

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; it is however also possible to keep an additional pkg directory in your private directories. The only essential difference with installing ANUPQ in a pkg directory different to the GAP 4 home directory is that one must start GAP with the -l switch (see Section Command Line Options), e.g. if your private pkg directory is a subdirectory of mygap in your home directory you might type:

gap -l ";myhomedir/mygap"

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.

Then, in your chosen pkg directory, unzoo anupq-XXX.zoo by

unzoo -x anupq-XXX

Change 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

./configure ../..

What this does is look for a file sysinfo.gap in the root directory of GAP in order to determine an architecture name for the subdirectory of bin in which to put the compiled pq binary. This only makes sense if GAP was compiled for the same architecture that pq will be. If you have a shared file system mounted across different architectures, then you should run configure and make for ANUPQ for each architecture immediately after compiling GAP on the same architecture.

If you had to install the package in your own directory but wish to use the system GAP 4 then you will need to find out what path is. To do this, start up GAP and find out what GAP's root path is from finding the value of the variable GAPInfo.RootPaths (in GAP 4.4; this was GAP_ROOT_PATHS prior to GAP 4.4), e.g.

gap> GAPInfo.RootPaths;
[ "/usr/local/lib/gap4r4/" ]

would tell you to use /usr/local/lib/gap4r4 for path.

The configure command 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

make

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

If you need a special target, e.g. you don't have gmp or are not on a Linux system, and 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:

make unknown | more

An abbreviation of the target list is as follows:

'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)
'iX86-pc-cygwin-gcc-gmp'   for IBM x86 PCs under CYGWIN with GNU cc and GNU mp
'iX86-pc-cygwin-gcc'       for IBM x86 PCs under CYGWIN with GNU cc
[... 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

Let's suppose that the linux-iX86-gcc2-gmp target does not satisfy your requirements, that your system is Solaris 2.8 (i.e. SunOS 5.8), you have gmp but its include and lib directories are somewhere else, and that gap4 is the command used to start GAP 4. Then the following might be the appropriate make call:

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

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.

The path of GAP (see Note below) 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.

Note. By ``path of GAP'' we mean the path of the command used to invoke GAP (which should be a script, e.g. the gap.sh script generated in the bin directory for the version of GAP when GAP was compiled). The usual strategy is to copy the gap.sh script to a standard location, e.g. /usr/local/bin/gap. It is a mistake to copy the GAP executable gap (in a directory with name of form bin/compile-platform) to the standard location, since direct invocation of the executable results in GAP starting without being able to find its own library (a fatal error).

7.1 Testing your ANUPQ installation

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:

testPq

Some of the tests the script runs take a while. Please be patient. The script checks that you not only have a correct GAP (at least version 4.4) installation that includes the AutPGrp package, but that the ANUPQ package and its pq binary interact correctly. You should see something like the following output:

Made dir: /tmp/testPq
Testing installation of ANUPQ Package (version 3.0)
 
The first two tests check that the pq C program compiled ok.
Testing the pq binary ... OK.
Testing the pq binary's stack size ... OK.
The pq C program compiled ok! We test it's the right one below.
 
The next tests check that you have the right version of GAP
for version 3.0 of the ANUPQ package and that GAP is finding
the right versions of the ANUPQ and AutPGrp packages.
 
Checking GAP ...
 pq binary made with GAP set to: /usr/local/bin/gap
 Starting GAP to determine version and package availability ...
  GAP version (4.4.6) ... OK.
  GAP found ANUPQ package (version 3.0) ... good.
  GAP found pq binary (version 1.8) ... good.
  GAP found AutPGrp package (version 1.2) ... 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!

7.2 Running the pq program as a standalone

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. To create the script that runs GAP it is easiest to copy the system one and edit it, e.g. start by executing the following UNIX commands (skip the second step if you already have a bin directory; you@unix> is your UNIX prompt):

you@unix> cd
you@unix> mkdir bin
you@unix> cd bin
you@unix> which gap
/usr/local/bin/gap
you@unix> cp /usr/local/bin/gap mygap
you@unix> chmod +x mygap

At the second-last step use the path of GAP returned by which gap. Now hopefully you will have a copy of the script that runs the system GAP in mygap. Now use your favourite editor to edit the -l part of the last line of mygap which should initially look something like:

exec $GAP_DIR/bin/$GAP_PRG -m $GAP_MEM -o 970m -l $GAP_DIR $*

so that it becomes (the tilde is a UNIX abbreviation for your home directory):

exec $GAP_DIR/bin/$GAP_PRG -m $GAP_MEM -o 970m -l "$GAP_DIR;~/gapstuff" $*

assuming that your personal GAP pkg directory is a subdirectory of gapstuff in your home directory. Finally, to let the pq program know where GAP is and also know where your pkg directory is that contains ANUPQ, set the environment variable ANUPQ_GAP_EXEC to the complete (i.e. absolute) path of your mygap script (do not use the tilde abbreviation), or at the make step that compiles pq do

make GAP=absolute-path-of-mygap

7.3 Setting the Verbosity of ANUPQ via Info and InfoANUPQ

gap> SetInfoLevel(InfoANUPQ, 2);

gap> SetInfoLevel(InfoANUPQ, 3);

gap> SetInfoLevel(InfoANUPQ, 4);

gap> SetInfoLevel(InfoANUPQ, 5);

gap> SetInfoLevel(InfoANUPQ, 6);