<!-- LINBOXING - install.xml Installation documentation section Paul Smith Copyright (C) 2007-2008 Paul Smith National University of Ireland Galway This file is part of the linboxing GAP package. The linboxing package is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. The linboxing package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. $Id: install.xml 103 2008-04-22 20:05:26Z pas $ --> <!-- ********************************************************** --> <Chapter> <Heading>Installation and Use</Heading> 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 <Ref Sect="InstallingLinBox"/>), and you must build the &linboxing; package's kernel module (Section <Ref Sect="InstallingPackage"/>). Finally, you will most likely want to run &GAP; with special command-line parameters (Section <Ref Sect="RunningLinBox"/>). This chapter covers all of these technical details. <Section Label="InstallingLinBox"> <Heading>Installing the LinBox library</Heading> 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. <Subsection Label="GettingLinBox"> <Heading>Downloading LinBox</Heading> LinBox can be downloaded as source code (a <F>.tar.gz</F> archive) from the LinBox website at <URL>http://www.linalg.org/download.html</URL>. The &linboxing; package supports version 1.1.5 of LinBox (released 3 April 2008), and newer versions. <P/> 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 <URL>http://www.linalg.org/linbox-html/install-dist.html</URL>. </Subsection> <Subsection Label="BeforeYouStart"> <Heading>Before building LinBox</Heading> 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 <C>g++</C>). The LinBox library itself requires that you already have installed two further libraries: <List> <Item>the GNU Multiprecision Arithmetic (GMP) Library (see <URL>http://gmplib.org/</URL>)</Item> <Item>a library providing the BLAS linear algebra routines (see <URL>http://www.netlib.org/blas/</URL>)</Item> </List> 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 <URL>http://math-atlas.sourceforge.net/</URL>). If you are unsure whether or not you have either the GMP or BLAS libraries installed, the <C>configure</C> scripts for both LinBox and &linboxing; check for them in the standard locations and will tell you if they can't find them. <P/> 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. </Subsection> <Subsection Label="BuildingLinBox"> <Heading>Building the LinBox library</Heading> After downloading the LinBox source archive, it can be extracted using <Listing> tar -xzf linbox-x.x.x.tar.gz </Listing> which will create a new directory called <F>linbox-x.x.x</F> (where <F>x.x.x</F> is the current version number). <P/> Then change to the <F>linbox-x.x.x</F> directory and type <Listing> ./configure make sudo make install </Listing> The last command runs <C>make install</C> with administrator privileges to install the LinBox library in the default location, <F>/usr/local/</F>. <P/> If the GMP and BLAS libraries (see Section <Ref Sect="BeforeYouStart"/>) are not in standard locations, or you do not wish to install LinBox in <F>/usr/local/</F> (or you cannot), then please refer to the LinBox installation instructions (<URL>http://www.linalg.org/linbox-html/install-dist.html</URL>) for the necessary <C>configure</C> options. </Subsection> </Section> <Section Label="InstallingPackage"> <Heading>Installing the &linboxing; package</Heading> To install the &linboxing; package, you should first unpack the &linboxing; archive file in a directory in the <F>pkg</F> hierarchy of your version of &GAP;. For example, for a package with the extension <F>.tar.gz</F>, type <Listing> tar -xzf linboxing-<#Include SYSTEM "../VERSION">.tar.gz </Listing> This will extract all of the files into a directory called <F>linboxing-<#Include SYSTEM "../VERSION"></F>. <P/> 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 <F>linboxing-<#Include SYSTEM "../VERSION"></F> directory and build the kernel module using the commands <Listing> cd linboxing-<#Include SYSTEM "../VERSION"> ./configure make </Listing> The <C>configure</C> 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 <C>make</C> should proceed with no errors. Note that <C>make install</C> is not required for &linboxing;: <C>make</C> does all that is needed. <P/> If the required packages are not in the standard locations, you can tell <C>configure</C> where they are using the following command-line switches: <List> <Mark><C>--with-blas=<lib></C></Mark> <Item>specify the name of the BLAS library, or the linker flags needed to use it</Item> <Mark><C>--with-gmpprefix=<prefix></C></Mark> <Item>specify the prefix to which GMP library is installed</Item> <Mark><C>--with-linboxprefix=<prefix></C></Mark> <Item>specify the prefix to which the LinBox library is installed</Item> <Mark><C>--with-gaproot=<path></C></Mark> <Item>specify the path to GAP's root directory</Item> </List> 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 <F>/home/pas/software/</F>. To do this, you will have configured the LinBox build process using <C>--prefix=/home/pas/software</C> and when you did <C>make install</C>, it would have copied the LinBox library and header files into <F>/home/pas/software/include</F> and <F>/home/pas/software/lib</F> respectively. You now wish to build this &linboxing; package. To tell it where to find the LinBox library, you run <C>configure</C> with the same prefix that you gave to LinBox, i.e. <C>--with-linboxprefix=/home/pas/software</C>. </Section> <Section Label="RunningLinBox"> <Heading>Starting &GAP; with LinBox-friendly memory management</Heading> &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 <C>malloc</C>, 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 <Index>cannot extend the workspace any more</Index> <C>cannot extend the workspace any more</C>. <P/> There are two current solutions to this problem, both of which require &GAP; to be run with a command-line switch: <List> <Mark>Pre-allocate some <C>malloc</C> memory for LinBox to use</Mark> <Item> The <C>-a</C> command-line option <Ref Sect="Advanced Features of GAP" BookName="Ref"/> 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 <Listing> gap -a 50M </Listing> </Item> <Mark>Allocate &GAP; a big enough workspace that it will not need extending</Mark> <Item> The <C>-m</C> command-line option <Ref Sect="Command Line Options" BookName="Ref"/> 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 <Listing> gap -m 256M </Listing> If you are unsure as to how much memory you might need, refer to <Ref Sect="Global Memory Information" BookName="Ref"/> for various &GAP; commands to let you see how much memory your &GAP; workspace is using. Running &GAP; with the <C>-g</C> (or <C>-g -g</C>) command-line switch <Ref Sect="Command Line Options" BookName="Ref"/> can also help you keep track of memory usage. </Item> </List> 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 <F>gap.sh</F> 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 <C>malloc</C>, which would mean that these switches may eventually not be needed. </Section> <Section> <Heading>Loading and testing the &linboxing; package</Heading> 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"); </Example> 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 <F>.gaprc</F> file. <P/> You can test the installation of the &linboxing; package by running the &GAP; command <Ref Func="TestLinboxing"/>: <Example> gap> TestLinboxing(); </Example> </Section> <Section> <Heading>Recompiling this documentation</Heading> 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 <Ref Func="MakeLinboxingDoc"/>. </Section> </Chapter>