\title{Appendix A: Installation Guide for the UNIX Versions}
\begingroup
\def\num#1{\noindent{\bf#1)}}

{\bf Important Note:} Starting with release 1.38, we assume that you have
either an {\tt ANSI C} or a {\tt C++} compiler available. If your machine
does not have one (for example if you still use {\tt /bin/cc} in {\tt SunOS
4.1.x}), we strongly suggest that you obtain the {\tt gcc/g++} compiler from
the Free Software Foundation or by anonymous {\tt ftp}.

As for all GNU software mentioned afterwards, you can find the most
convenient site to obtain {\tt gcc} from at the address

{\tt http://www.gnu.ai.mit.edu/order/ftp.html}

{\bf Important Note 2:} The graphic routines in the present version have only
been tested under {\tt X11}, and may not work at all if you try to compile GP
with an old {\tt Suntools} library (even though this is supposedly supported,
nobody tested it yet !!!).

{\bf Not so important note:} The following programs and libraries are useful
in conjunction with GP, but not mandatory. Get them before proceeding if you
want the functionalities they provide. All of them are free (though you ought
to make a small donation to the FSF if you use (and like) GNU wares).

  $\bullet$ GNU {\tt readline} library. This provides line editing under GP,
an automatic context-dependant completion, and an (editable) history of
commands. However note that it is incompatible with SUN commandtools (not
with shelltools).

  $\bullet$ GNU {\tt gzip/gunzip/gzcat} package enables GP to read
compressed data.

  $\bullet$ GNU {\tt emacs}. GP can be run in an Emacs buffer, with all the
obvious advantages if you are familiar with this editor. Note that 
{\tt readline} is still useful in that case since it provides a much better
automatic completion than is provided by Emacs GP--mode.

  $\bullet$ {\tt perl} provides extended online help (full text from Chapter
3), about functions and concepts, which can be used under GP or independently
({\tt http://www.perl.com} will direct you to the nearest archive {\tt CPAN}
site)

  $\bullet$ {\tt color-xterm} enables GP to use different (user configurable)
colours for its output (you can get the latest version at {\tt
http://www.clark.net/pub/dickey/xterm})

\smallskip
\num{1} To compile the library and the gp calculator.
\smallskip
   a) First, type {\tt Configure} in the toplevel directory. This strives to
configure GP/PARI without outside help. Note that if you want to install the
end product in some exotic place, you can use the {\tt -prefix} option, such
as {\tt Configure -prefix /my/dir} (default is {\tt /usr/local}). This
should extract some files and create a directory {\tt o.$xxx$} where the
object files and executables will be built. The $xxx$ part depends on your
architecture and operating system, thus you can build GP for several
different machines from the same source tree.

  Note that if you want to debug the PARI library (welcome to the gang!),
you'll have to add the option {\tt -g} to {\tt Configure}. This will create a
special {\tt o.$xxx$.dbg} directory where a non-optimized GP and PARI library
will be created.

  In case this fails miserably, try {\tt Configure -a} and answer all the
questions (there aren't that many). {\tt Configure} will provide defaults for
each answer but if you accept them all, it will fail just the same, so be
wary. In any case, we would appreciate a bug report including the complete
output from {\tt Configure} and the file {\tt dft.Config.in} that was
produced in the process.

  Note that even with the {\tt -a} flag, you can't directly tell 
{\tt Configure} where the {\tt readline} library and include files are. If
they are not in a standard place, it won't find them. Nonetheless, it first
searches the distribution toplevel for a {\tt readline} directory. Thus, if
you just want to give {\tt readline} a try (as you probably should), you can
get the source and compile it there (you don't need to install it).
You can also use this feature and symbolic links if you compiled it somewhere
else, without installing it.\medskip

   b) Decide whether you agree with what {\tt Configure} printed on your
screen (in particular, the compiler and optimization flags). If anything
should have been found and was not, consider that {\tt Configure} failed and
follow the last part of point a) above (don't necessarily make a bug report
if you local installation is exotic). Essentially, this means the {\tt
readline} and {\tt X11} libraries, and the {\tt perl} and {\tt gunzip} (or
zcat) executable files. 
\medskip

   c) Then simply type {\tt make gp} in the distribution directory. If your
{\tt make} program supports parallel make (GNU {\tt make} does) and you have
a multi-processor machine, you can speed up the process by going to the {\tt
o.$xxx$} directory that {\tt Configure} created and doing a parallel make
here (option {\tt -j} of GNU make). \medskip

   d) {\tt [Optional]} To test the executables, type {\tt make bench} (or
{\tt make test} which is slightly less severe and takes roughly half the
time). This will build a static executable (the default, built by {\tt make
gp} is probably dynamic) and run a series of comparative tests on those two.
The static one should be slightly faster. In any case, this should not take
more than one minute (user time) on most modern machines.

  If a {\tt [BUG]} message shows up, it probably means that something is very
wrong. Most probably with the installation procedure, but it may be a bug in
the Pari system, in which case we would appreciate a report (including the
relevant {\tt *.diff} file in the {\tt o.$xxx$} directory and the file {\tt
dft.Config.in}). The {\tt program} test on {\tt gp-sta} is a special case: it
tries to use a non--portable feature of the {\tt dlopen()} routine, and this
may result in a segmentation fault in the {\tt addii(1,2)} test if your
system does not allow it (don't make a bug report if this is the case, unless
you know how to solve this !). On the other hand if GP passes this test you
will be able to use {\tt install} without problems (see reference manual).

{\bf Note:} If when running {\tt gp-dyn}, you get a message of the form

{\tt ld.so: warning: libpari.so.$xxx$ has older revision than expected $xxx$}

\noindent (possibly followed by more errors), you already have a dynamic PARI
library installed {\it and} a broken local configuration. Either remove the
old library or unset the {\tt LD\_LIBRARY\_PATH} environment variable.

   e) {\tt [Optional]} You can test GP in compatibility mode with {\tt make
test-compat} (it should take about the same time as {\tt make test}). If you
want to test the graphic routines, use {\tt make test-graphic}. You will have
to click on the mouse button after seeing each image (under X11; under
suntools you must kill the images). There will be eight of them, probably
shown twice (under X11, try to resize at least one of them as a further
test).

The {\tt make test} run produces a Postscript file {\tt pari.ps} in {\tt
o.$xxx$} which you can send to a Postscript printer. The output should bear
some similarity to the screen images. \medskip

\num{2} If everything seems to be all right, type {\tt make install}.
Beware that, if you chose the same installation directory as before in the
{\tt Configure} process, this will wipe out any files from version 1.39.15
and below that would already be there. Libraries and executable files from
newer versions (starting with version 1.900) are not removed since they are
only links to files bearing the version number (beware of that as well: if
you're an avid GP fan, delete the old libraries you don't use anymore).

  This installs in the directory chosen at {\tt Configure} time the default
GP executable (probably {\tt gp-dyn}) under the name {\tt gp}, the default
PARI library (probably {\tt libpari.so}), the necessary include files, the
manual pages, the documentation help scripts and emacs macros.

  You can install separately {\tt gp} by using the target {\tt install-bin}.
By default, if a dynamic library {\tt libpari.so} could be built, the static
library {\tt libpari.a} will not be created. If you want it as well, you can
use the target {\tt make install-lib-sta}. You can install a statically
linked {\tt gp} with the target {\tt make install-bin-sta}.

  As a rule, programs linked statically (with {\tt libpari.a}) will be
slightly faster (about 5\% gain), but use much more disk space and take more
time to compile. They also are harder to upgrade: you will have to recompile
them all instead of just installing the new dynamic library. \medskip

\num{3} If you want to get rid of your {\tt .o} files and the created
binaries in the {\tt o.$xxx$} directory, type {\tt make clean}. \medskip

\num{4} Once all libraries and include files are installed, you can link
your C programs to the PARI library. A sample makefile {\tt
examples/Makefile} is provided to illustrate the use of the various
libraries. Type {\tt make all} in the {\tt examples} directory to see how
they perform on the {\tt mattrans.c} program, which is given in
\secref{se:prog}\medskip

\num{5} To print the user's guide, type {\tt make doc}. This will create
a file {\tt doc/users.dvi} containing the manual with a table of contents and
an index in two passes. You must then send the {\tt users.dvi} file to your
favorite printer in the usual way. Also included are a short tutorial for GP
({\tt doc/tutorial.dvi}) and a reference card for GP ({\tt doc/refcard.dvi}
and {\tt doc/refcard.ps}). This won't work if {\tt Configure} did not succeed
(you can make it work by renaming {\tt Makefile.sos} to {\tt Makefile} in the
{\tt doc} directory). \medskip

\num{6} Several complete sample GP programs are also given in the {\tt
examples} directory, for example Shanks's SQUFOF factoring method, the
Pollard rho factoring method, the Lucas-Lehmer primality test for Mersenne
numbers and a simple general class group and fundamental unit algorithm (much
worse than the built-in {\tt bnfinit}!). See the file EXPLAIN for some
explanations. \medskip

\num{7} If you want to use {\tt gp} under GNU Emacs (see
\secref{se:emacs} of the user's guide) read the file {\tt
emacs/pariemacs.txt}. If you are familiar with Emacs, we suggest that you do
so. \medskip

\num{8} There are three mailing lists devoted to the PARI/GP package
(run courtesy of Dan Bernstein), and most feedback should be directed to
those. They are:

$\bullet$ {\tt pari-announce}: to announce major version changes. You can't write to
this one, but you should probably subscribe.

$\bullet$ {\tt pari-dev}: for everything related to the development of PARI,
including suggestions, technical questions, bug reports or patch submissions.

$\bullet$ {\tt pari-users}: for everything else.

To subscribe, send empty messages respectively to

\centerline{\tt    pari-announce-subscribe@list.cr.yp.to}

\centerline{\tt    pari-users-subscribe@list.cr.yp.to}

\centerline{\tt    pari-dev-subscribe@list.cr.yp.to}

If you are not a member of any of those lists and don't want to become 
one, you can write to us at the address

\centerline{\tt  pari@math.u-bordeaux.fr}

At the very least, we will forward you mail to the lists above and correct
faulty behaviour, if necessary. But we cannot promise you will get an
individual answer.

   In any case, if you like this software, we would appreciate if you could
send us an email message giving us some information about yourself. Put as
header of your message ``new user'', so we can recognize it easily.
\medskip

\num{9} Good luck and enjoy!
\vfill\eject
\endgroup
