chap7.txt

  
  7 Installing the ANUPQ Package
  
  The  ANU  pq  program is written in C and the package can be installed under
  UNIX  and in environments similar to UNIX. In particular it is known to work
  on Linux and Mac OS X, and also on Windows equipped with cygwin.
  
  The  current  version of the ANUPQ package requires GAP 4.8, and version 1.2
  of  the  AutPGrp  package.  However, we recommend using at least GAP 4.6 and
  AutPGrp 1.5.
  
  To  install  the  ANUPQ  package,  move  the  file anupq-XXX.tar.gz 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;  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 home directory is
  that  one  must start GAP with the -l switch (see Section Reference: 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 may be replaced by
  a  tilde.  The  empty  path before the semicolon is filled in by the default
  path of the GAP home directory.
  
  Then, in your chosen pkg directory, unpack anupq-XXX.tar.gz by
  
  
    tar xf anupq-<XXX>.tar.gz
  
  
  Change to the newly created anupq directory. Now you need to call configure.
  If you installed ANUPQ into the main pkg directory, call
  
  
    ./configure
  
  
  If   you   installed  ANUPQ  in  another  directory  than  the  usual  'pkg'
  subdirectory, instead call
  
  
    ./configure --with-gaproot=<path>
  
  
  where path is the path to the GAP home directory. (You can also call
  
  
    ./configure --help
  
  
  for further options.)
  
  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 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, e.g.
  
    Example  
    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 and create a Makefile. You can now simply call
  
  
    make
  
  
  to compile the binary and to install it in the appropriate place.
  
  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:
  
    Example  
    Made dir: /tmp/testPq
    Testing installation of ANUPQ Package (version 3.1)
     
    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 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.6.5) ... OK.
      GAP found ANUPQ package (version 3.1) ... good.
      GAP found pq binary (version 1.9) ... good.
      GAP found AutPGrp package (version 1.5) ... 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).