install.xml

<Chapter Label="Installing-ANUPQ">
<Heading>Installing the ANUPQ Package</Heading>

The ANU <C>pq</C> 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.
<P/>

The current version of the &ANUPQ; package requires &GAP;&nbsp;4.8, and
version 1.2 of the &AutPGrp; package. However, we recommend using
at least &GAP;&nbsp;4.6 and &AutPGrp;&nbsp;1.5.
<P/>

To install the &ANUPQ; package, move the file <C>anupq-<A>XXX</A>.tar.gz</C>
for some version number <A>XXX</A> into the <C>pkg</C> directory in which you
plan to install &ANUPQ;. Usually, this will be the directory <C>pkg</C> in the
hierarchy of your version of &GAP;; it is however also possible to keep an
additional <C>pkg</C> directory in your private directories. The only
essential difference with installing &ANUPQ; in a <C>pkg</C> directory
different to the &GAP; home directory is that one must start &GAP;
with the <C>-l</C> switch (see
Section&nbsp;<Ref BookName="ref" Label="Command Line Options" Style="Text"/>),
e.g.&nbsp;if your private <C>pkg</C> directory is a subdirectory of
<C>mygap</C> in your home directory you might type:

<Listing><![CDATA[
gap -l ";myhomedir/mygap"
]]></Listing>

where <A>myhomedir</A> 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.
<P/>

Then, in your chosen <C>pkg</C> directory, unpack <C>anupq-<A>XXX</A>.tar.gz</C> by

<Listing><![CDATA[
tar xf anupq-<XXX>.tar.gz
]]></Listing>

Change to the newly created <C>anupq</C> directory. Now you need to call
<C>configure</C>. If you installed &ANUPQ; into the main <C>pkg</C> directory,
call

<Listing><![CDATA[
./configure
]]></Listing>

If you installed ANUPQ in another directory than the usual 'pkg'
subdirectory, instead call

<Listing><![CDATA[
./configure --with-gaproot=<path>
]]></Listing>

where <A>path</A> is the path to the &GAP; home directory. (You can also call

<Listing><![CDATA[
./configure --help
]]></Listing>

for further options.)
<P/>

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

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 <A>path</A> is. To do
this, start up &GAP; and find out what &GAP;'s root path is from
finding the value of the variable <C>GAPInfo.RootPaths</C>, e.g.

<Log><![CDATA[
gap> GAPInfo.RootPaths;
[ "/usr/local/lib/gap4r4/" ]
]]></Log>

would tell you to use <C>/usr/local/lib/gap4r4</C> for <A>path</A>.
<P/>

The <C>configure</C> command will fetch the architecture type for which &GAP;
has been compiled last and create a <C>Makefile</C>. You can now
simply call

<Listing><![CDATA[
make
]]></Listing>

to compile the binary and to install it in the appropriate place.
<P/>

<Index Key="ANUPQ_GAP_EXEC" Subkey="environment variable"><C>ANUPQ_GAP_EXEC</C></Index>
The path of &GAP; (see <E>Note</E> below) used by the <C>pq</C> binary (the value
<C>GAP</C> is set to in the <C>make</C> command) may be over-ridden by setting the
environment variable <C>ANUPQ_GAP_EXEC</C>. These values are only of interest
when the <C>pq</C> program is run as a standalone; however, the <C>testPq</C>
script assumes you have set one of these correctly (see Section&nbsp;<Ref Sect="Testing your ANUPQ installation" Style="Text"/>). When the <C>pq</C> program is started from &GAP;
communication occurs via an iostream, so that the <C>pq</C> binary does not
actually need to know a valid path for &GAP; is this case.
<P/>

<E>Note.</E> By <Q>path of &GAP;</Q> we mean the path of the command used to
invoke &GAP; (which should be a script, e.g. the <C>gap.sh</C> script
generated in the <C>bin</C> directory for the version of &GAP; when &GAP;
was compiled). The usual strategy is to copy the <C>gap.sh</C> script to a
standard location, e.g. <C>/usr/local/bin/gap</C>. It is a mistake to copy the
&GAP; executable <C>gap</C> (in a directory with name of form
<C>bin/<A>compile-platform</A></C>) 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).

<Section Label="Testing your ANUPQ installation">
<Heading>Testing your ANUPQ installation</Heading>

<Index Key="ANUPQ_GAP_EXEC" Subkey="environment variable"><C>ANUPQ_GAP_EXEC</C></Index>
Now it is time to test the installation. After doing <C>configure</C> and
<C>make</C> you will have a <C>testPq</C> script. The script assumes that, if the
environment variable <C>ANUPQ_GAP_EXEC</C> is set, it is a correct path for
&GAP;, or otherwise that the <C>make</C> call that compiled the <C>pq</C> program
set <C>GAP</C> to a correct path for &GAP; (see Section&nbsp;<Ref Sect="Running the pq program as a standalone" Style="Text"/> for more details). To run the tests, just type:

<Listing><![CDATA[
./testPq
]]></Listing>

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 <C>pq</C> binary interact correctly. You should see
something like the following output:

<Log><![CDATA[
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!
]]></Log>

</Section>


<Section Label="Running the pq program as a standalone">
<Heading>Running the pq program as a standalone</Heading>

<Index Key="ANUPQ_GAP_EXEC" Subkey="environment variable"><C>ANUPQ_GAP_EXEC</C></Index>
When the <C>pq</C> 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 <C>ANUPQ_GAP_EXEC</C>, and uses that, if
set, or otherwise the value of <C>GAP</C> it was compiled with, as the path
for &GAP;. If you ran <C>testPq</C> (see Section&nbsp;<Ref Sect="Testing your ANUPQ installation" Style="Text"/>) and you got both &GAP; is <C>OK</C> and the link between the
<C>pq</C> binary and &GAP; is <C>OK</C>, you should be fine. Otherwise heed the
recommendations of the error messages you get and run the <C>testPq</C> until
all tests are passed.
<P/>

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 <C>-l</C> option and set
the path used by the <C>pq</C> 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 <C>bin</C> directory; <C>you@unix></C> is your UNIX
prompt):

<Listing><![CDATA[
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
]]></Listing>

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

<Listing><![CDATA[
exec $GAP_DIR/bin/$GAP_PRG -m $GAP_MEM -o 970m -l $GAP_DIR $*
]]></Listing>

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

<Listing><![CDATA[
exec $GAP_DIR/bin/$GAP_PRG -m $GAP_MEM -o 970m -l "$GAP_DIR;~/gapstuff" $*
]]></Listing>

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

</Section>
</Chapter>