  
  [1X2 Installation and Use[0X
  
  Before  you  can  use the [5Xlinboxing[0m package in [5XGAP[0m, there are several things
  that  you  must  do.  You  must  install  a compatible version of the LinBox
  library  (Section  [14X2.1[0m),  and  you must build the [5Xlinboxing[0m package's kernel
  module  (Section  [14X2.2[0m).  Finally,  you will most likely want to run [5XGAP[0m with
  special  command-line  parameters  (Section [14X2.3[0m). This chapter covers all of
  these technical details.
  
  
  [1X2.1 Installing the LinBox library[0X
  
  Before  you  can  install  the [5Xlinboxing[0m 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 [5Xlinboxing[0m package.
  
  
  [1X2.1-1 Downloading LinBox[0X
  
  LinBox  can be downloaded as source code (a [11X.tar.gz[0m archive) from the LinBox
  website   at   [7Xhttp://www.linalg.org/download.html[0m.  The  [5Xlinboxing[0m  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
  [7Xhttp://www.linalg.org/linbox-html/install-dist.html[0m.
  
  
  [1X2.1-2 Before building LinBox[0X
  
  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 [10Xg++[0m).
  The  LinBox  library  itself  requires  that  you already have installed two
  further libraries:
  
  --    the    GNU    Multiprecision    Arithmetic    (GMP)    Library    (see
        [7Xhttp://gmplib.org/[0m)
  
  --    a   library   providing   the   BLAS   linear  algebra  routines  (see
        [7Xhttp://www.netlib.org/blas/[0m)
  
  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
  [7Xhttp://math-atlas.sourceforge.net/[0m).  If  you  are unsure whether or not you
  have  either  the GMP or BLAS libraries installed, the [10Xconfigure[0m scripts for
  both  LinBox and [5Xlinboxing[0m 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 [5Xlinboxing[0m
  package.
  
  
  [1X2.1-3 Building the LinBox library[0X
  
  After downloading the LinBox source archive, it can be extracted using
  
  [4X------------------------------------------------------------------[0X
    [4X        tar -xzf linbox-x.x.x.tar.gz[0X
    [4X      [0X
  [4X------------------------------------------------------------------[0X
  
  which  will  create  a new directory called [11Xlinbox-x.x.x[0m (where [11Xx.x.x[0m is the
  current version number).
  
  Then change to the [11Xlinbox-x.x.x[0m directory and type
  
  [4X------------------------------------------------------------------[0X
    [4X        ./configure[0X
    [4X        make[0X
    [4X        sudo make install[0X
    [4X      [0X
  [4X------------------------------------------------------------------[0X
  
  The  last command runs [10Xmake install[0m with administrator privileges to install
  the LinBox library in the default location, [11X/usr/local/[0m.
  
  If  the  GMP  and  BLAS  libraries  (see  Section [14X2.1-2[0m) are not in standard
  locations,  or  you  do  not  wish  to install LinBox in [11X/usr/local/[0m (or you
  cannot),   then   please  refer  to  the  LinBox  installation  instructions
  ([7Xhttp://www.linalg.org/linbox-html/install-dist.html[0m)   for   the  necessary
  [10Xconfigure[0m options.
  
  
  [1X2.2 Installing the [5Xlinboxing[1X package[0X
  
  To  install  the  [5Xlinboxing[0m  package,  you should first unpack the [5Xlinboxing[0m
  archive file in a directory in the [11Xpkg[0m hierarchy of your version of [5XGAP[0m. For
  example, for a package with the extension [11X.tar.gz[0m, type
  
  [4X------------------------------------------------------------------[0X
    [4X      tar -xzf linboxing-0.5.1.tar.gz[0X
    [4X    [0X
  [4X------------------------------------------------------------------[0X
  
  This will extract all of the files into a directory called [11Xlinboxing-0.5.1[0m.
  
  All of the useful functionality of the [5Xlinboxing[0m package is provided through
  a  compiled  [5XGAP[0m kernel module that uses the LinBox library directly. Change
  to  the  [11Xlinboxing-0.5.1[0m  directory  and  build  the kernel module using the
  commands
  
  [4X------------------------------------------------------------------[0X
    [4X      cd linboxing-0.5.1[0X
    [4X      ./configure[0X
    [4X      make[0X
    [4X    [0X
  [4X------------------------------------------------------------------[0X
  
  The  [10Xconfigure[0m  script runs lots of checks and will search for the locations
  of  all  of  the  required other packages, such as GMP, BLAS, LinBox and [5XGAP[0m
  itself.  If  there  are any problems, it should report them, and if not then
  [10Xmake[0m  should  proceed with no errors. Note that [10Xmake install[0m is not required
  for [5Xlinboxing[0m: [10Xmake[0m does all that is needed.
  
  If  the  required  packages  are not in the standard locations, you can tell
  [10Xconfigure[0m where they are using the following command-line switches:
  
  [8X[10X--with-blas=<lib>[0m[8X[0m
        specify  the  name  of the BLAS library, or the linker flags needed to
        use it
  
  [8X[10X--with-gmpprefix=<prefix>[0m[8X[0m
        specify the prefix to which GMP library is installed
  
  [8X[10X--with-linboxprefix=<prefix>[0m[8X[0m
        specify the prefix to which the LinBox library is installed
  
  [8X[10X--with-gaproot=<path>[0m[8X[0m
        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 [11X/home/pas/software/[0m. To do this, you will
  have  configured  the LinBox build process using [10X--prefix=/home/pas/software[0m
  and  when  you did [10Xmake install[0m, it would have copied the LinBox library and
  header  files  into  [11X/home/pas/software/include[0m  and  [11X/home/pas/software/lib[0m
  respectively. You now wish to build this [5Xlinboxing[0m package. To tell it where
  to  find the LinBox library, you run [10Xconfigure[0m with the same prefix that you
  gave to LinBox, i.e. [10X--with-linboxprefix=/home/pas/software[0m.
  
  
  [1X2.3 Starting [5XGAP[1X with LinBox-friendly memory management[0X
  
  [5XGAP[0m  and the LinBox library use different methods for allocating memory, and
  these  do  not  work  well  together.  [5XGAP[0m  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 [10Xmalloc[0m, and allocates memory wherever it feels
  like it. Because of this, if you run [5XGAP[0m and use the [5Xlinboxing[0m package, then
  there  is  a  good  chance that when [5XGAP[0m needs more memory it will find that
  some  LinBox-allocated memory gets in the way of it expanding the workspace.
  In  this case, [5XGAP[0m will simply exit (without warning!) with the error [10Xcannot
  extend the workspace any more[0m.
  
  There  are  two current solutions to this problem, both of which require [5XGAP[0m
  to be run with a command-line switch:
  
  [8XPre-allocate some [10Xmalloc[0m[8X memory for LinBox to use[0m
        The [10X-a[0m command-line option [14X'Reference: Advanced Features of GAP'[0m tells
        [5XGAP[0m  to  pre-allocate some memory that LinBox should, on most systems,
        use  in  preference to getting in the way of the [5XGAP[0m 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 [5XGAP[0m
        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
  
        [4X------------------------------------------------------------[0X
          [4X          gap -a 50M[0X
          [4X        [0X
        [4X------------------------------------------------------------[0X
  
  [8XAllocate [5XGAP[0m[8X a big enough workspace that it will not need extending[0m
        The [10X-m[0m command-line option [14X'Reference: Command Line Options'[0m tells [5XGAP[0m
        to allocate a set number of bytes for the [5XGAP[0m workspace when it starts
        up.  If  you  set  this sufficiently large then [5XGAP[0m 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 [5XGAP[0m, use
  
        [4X------------------------------------------------------------[0X
          [4X        gap -m 256M[0X
          [4X      [0X
        [4X------------------------------------------------------------[0X
  
        If  you  are  unsure  as  to  how much memory you might need, refer to
        [14X'Reference: Global Memory Information'[0m for various [5XGAP[0m commands to let
        you  see how much memory your [5XGAP[0m workspace is using. Running [5XGAP[0m with
        the  [10X-g[0m  (or  [10X-g  -g[0m)  command-line  switch  [14X'Reference:  Command Line
        Options'[0m 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 [5Xlinboxing[0m
  package,  you  can  add these options to the [11Xgap.sh[0m shell script, if you are
  using  it. Future versions of [5XGAP[0m may modify GASMAN storage manager to allow
  the  happy  co-existance  of  [5XGAP[0m  memory with [10Xmalloc[0m, which would mean that
  these switches may eventually not be needed.
  
  
  [1X2.4 Loading and testing the [5Xlinboxing[1X package[0X
  
  The  [5Xlinboxing[0m package is not loaded by default when [5XGAP[0m is started. To load
  the package, type the following at the [5XGAP[0m prompt:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X      gap> LoadPackage( "linboxing");[0X
    [4X    [0X
  [4X------------------------------------------------------------------[0X
  
  If  [5Xlinboxing[0m  isn't  already  in  memory  then  it is loaded and the author
  information  is  displayed.  If  you  are  a  frequent user of the [5Xlinboxing[0m
  package, you might consider putting this line in your [11X.gaprc[0m file.
  
  You  can  test  the installation of the [5Xlinboxing[0m package by running the [5XGAP[0m
  command [2XTestLinboxing[0m ([14X3.2-3[0m):
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X      gap> TestLinboxing();[0X
    [4X    [0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X2.5 Recompiling this documentation[0X
  
  This  documentation  is  written  using  the  [5XGAPDoc[0m  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 [5XGAP[0m when running on a standard
  UNIX installation by using the [5XGAP[0m command [2XMakeLinboxingDoc[0m ([14X3.2-2[0m).
  
