2 Installation and Use
  
  Before  you  can  use the linboxing package in GAP, there are several things
  that  you  must  do.  You  must  install  a compatible version of the LinBox
  library  (Section  2.1),  and  you must build the linboxing package's kernel
  module  (Section  2.2).  Finally,  you will most likely want to run GAP with
  special  command-line  parameters  (Section 2.3). This chapter covers all of
  these technical details.
  
  
  2.1 Installing the LinBox library
  
  Before  you  can  install  the linboxing package, you need to have built and
  installed  the  LinBox  library  on  your machine. At least version 1.1.5 of
  LinBox is required to use the linboxing package.
  
  
  2.1-1 Downloading LinBox
  
  LinBox  can be downloaded as source code (a .tar.gz archive) from the LinBox
  website   at   http://www.linalg.org/download.html.  The  linboxing  package
  supports  version  1.1.5  of  LinBox  (released  3  April  2008),  and newer
  versions.
  
  The  following sections give a brief summary of how to build and install the
  LinBox  library.  Full  installation  instructions  come with the downloaded
  LinBox       source       archive,      or      are      available      from
  http://www.linalg.org/linbox-html/install-dist.html.
  
  
  2.1-2 Before building LinBox
  
  Before  you  can  build  LinBox library you will need the standard tools for
  building  a package from source code (including a C++ compiler such as g++).
  The  LinBox  library  itself  requires  that  you already have installed two
  further libraries:
  
  --    the    GNU    Multiprecision    Arithmetic    (GMP)    Library    (see
        http://gmplib.org/)
  
  --    a   library   providing   the   BLAS   linear  algebra  routines  (see
        http://www.netlib.org/blas/)
  
  These libraries may already be installed on your system or be available from
  your  standard  package  repositories, so you will not usually need to build
  these  from  source code (although if you are interested in performance, you
  should   build   your   own   BLAS   library,   for   example   using  ATLAS
  http://math-atlas.sourceforge.net/).  If  you  are unsure whether or not you
  have  either  the GMP or BLAS libraries installed, the configure scripts for
  both  LinBox and linboxing check for them in the standard locations and will
  tell you if they can't find them.
  
  Further  details  about  setting  up  these  prerequisites  is  available in
  LinBox's  own  installation instructions. None of the optional packages that
  LinBox  can  also use (such as NTL or Givaro) are required for the linboxing
  package.
  
  
  2.1-3 Building the LinBox library
  
  After downloading the LinBox source archive, it can be extracted using
  
  ------------------------------------------------------------------
            tar -xzf linbox-x.x.x.tar.gz
          
  ------------------------------------------------------------------
  
  which  will  create  a new directory called linbox-x.x.x (where x.x.x is the
  current version number).
  
  Then change to the linbox-x.x.x directory and type
  
  ------------------------------------------------------------------
            ./configure
            make
            sudo make install
          
  ------------------------------------------------------------------
  
  The  last command runs make install with administrator privileges to install
  the LinBox library in the default location, /usr/local/.
  
  If  the  GMP  and  BLAS  libraries  (see  Section 2.1-2) are not in standard
  locations,  or  you  do  not  wish  to install LinBox in /usr/local/ (or you
  cannot),   then   please  refer  to  the  LinBox  installation  instructions
  (http://www.linalg.org/linbox-html/install-dist.html)   for   the  necessary
  configure options.
  
  
  2.2 Installing the linboxing package
  
  To  install  the  linboxing  package,  you should first unpack the linboxing
  archive file in a directory in the pkg hierarchy of your version of GAP. For
  example, for a package with the extension .tar.gz, type
  
  ------------------------------------------------------------------
          tar -xzf linboxing-0.5.1.tar.gz
        
  ------------------------------------------------------------------
  
  This will extract all of the files into a directory called linboxing-0.5.1.
  
  All of the useful functionality of the linboxing package is provided through
  a  compiled  GAP kernel module that uses the LinBox library directly. Change
  to  the  linboxing-0.5.1  directory  and  build  the kernel module using the
  commands
  
  ------------------------------------------------------------------
          cd linboxing-0.5.1
          ./configure
          make
        
  ------------------------------------------------------------------
  
  The  configure  script runs lots of checks and will search for the locations
  of  all  of  the  required other packages, such as GMP, BLAS, LinBox and GAP
  itself.  If  there  are any problems, it should report them, and if not then
  make  should  proceed with no errors. Note that make install is not required
  for linboxing: make does all that is needed.
  
  If  the  required  packages  are not in the standard locations, you can tell
  configure where they are using the following command-line switches:
  
  --with-blas=<lib>
        specify  the  name  of the BLAS library, or the linker flags needed to
        use it
  
  --with-gmpprefix=<prefix>
        specify the prefix to which GMP library is installed
  
  --with-linboxprefix=<prefix>
        specify the prefix to which the LinBox library is installed
  
  --with-gaproot=<path>
        specify the path to GAP's root directory
  
  For  example,  you  may  need  to use these switches in the following common
  case.  If  you  do  not  have root access, you may have installed the LinBox
  library  in your home directory at /home/pas/software/. To do this, you will
  have  configured  the LinBox build process using --prefix=/home/pas/software
  and  when  you did make install, it would have copied the LinBox library and
  header  files  into  /home/pas/software/include  and  /home/pas/software/lib
  respectively. You now wish to build this linboxing package. To tell it where
  to  find the LinBox library, you run configure with the same prefix that you
  gave to LinBox, i.e. --with-linboxprefix=/home/pas/software.
  
  
  2.3 Starting GAP with LinBox-friendly memory management
  
  GAP  and the LinBox library use different methods for allocating memory, and
  these  do  not  work  well  together.  GAP  needs  all  of  its memory to be
  contiguous,  and  so  needs  to  have  free  space at the end of its current
  allocation  if  it  ever  wants  to expand its workspace. The LinBox library
  allocates  its  memory  using malloc, and allocates memory wherever it feels
  like it. Because of this, if you run GAP and use the linboxing package, then
  there  is  a  good  chance that when GAP needs more memory it will find that
  some  LinBox-allocated memory gets in the way of it expanding the workspace.
  In  this case, GAP will simply exit (without warning!) with the error cannot
  extend the workspace any more.
  
  There  are  two current solutions to this problem, both of which require GAP
  to be run with a command-line switch:
  
  Pre-allocate some malloc memory for LinBox to use
        The -a command-line option 'Reference: Advanced Features of GAP' tells
        GAP  to  pre-allocate some memory that LinBox should, on most systems,
        use  in  preference to getting in the way of the GAP workspace. If you
        set  this  sufficiently  large (i.1. larger than the largest amount of
        LinBox  memory  than  you  are  likely  to need at one time), then GAP
        should  be  able  to  expand  its  workspace  as much as it likes. For
        example,  to  allocate  50Mb  of  memory to LinBox (enough for 100,000
        small integer matrix elements), use
  
        ------------------------------------------------------------
                    gap -a 50M
                  
        ------------------------------------------------------------
  
  Allocate GAP a big enough workspace that it will not need extending
        The -m command-line option 'Reference: Command Line Options' tells GAP
        to allocate a set number of bytes for the GAP workspace when it starts
        up.  If  you  set  this sufficiently large then GAP will never need to
        expand  its workspace and LinBox can allocate its matrices wherever it
        likes  in  the  remaining  memory.  For  example, to allocate 256Mb of
        memory to GAP, use
  
        ------------------------------------------------------------
                  gap -m 256M
                
        ------------------------------------------------------------
  
        If  you  are  unsure  as  to  how much memory you might need, refer to
        'Reference: Global Memory Information' for various GAP commands to let
        you  see how much memory your GAP workspace is using. Running GAP with
        the  -g  (or  -g  -g)  command-line  switch  'Reference:  Command Line
        Options' can also help you keep track of memory usage.
  
  You  can  use  both of these solutions at the same time, which may be a safe
  `belt  and  braces'  approach.  If you intend to regularly use the linboxing
  package,  you  can  add these options to the gap.sh shell script, if you are
  using  it. Future versions of GAP may modify GASMAN storage manager to allow
  the  happy  co-existance  of  GAP  memory with malloc, which would mean that
  these switches may eventually not be needed.
  
  
  2.4 Loading and testing the linboxing package
  
  The  linboxing package is not loaded by default when GAP is started. To load
  the package, type the following at the GAP prompt:
  
  ---------------------------  Example  ----------------------------
          gap> LoadPackage( "linboxing");
        
  ------------------------------------------------------------------
  
  If  linboxing  isn't  already  in  memory  then  it is loaded and the author
  information  is  displayed.  If  you  are  a  frequent user of the linboxing
  package, you might consider putting this line in your .gaprc file.
  
  You  can  test  the installation of the linboxing package by running the GAP
  command TestLinboxing (3.2-3):
  
  ---------------------------  Example  ----------------------------
          gap> TestLinboxing();
        
  ------------------------------------------------------------------
  
  
  2.5 Recompiling this documentation
  
  This  documentation  is  written  using  the  GAPDoc  package, and should be
  available in PDF, HTML and text formats. It should not normally be necessary
  to rebuild the documentation (if you are reading this!). However, rebuilding
  the  documentation  can  be  done from within GAP when running on a standard
  UNIX installation by using the GAP command MakeLinboxingDoc (3.2-2).