% Copyright (c) 2021  The PARI Group
%
% This file is part of the PARI/GP documentation
%
% Permission is granted to copy, distribute and/or modify this document
% under the terms of the GNU General Public License
\def\TITLE{Installing Pari/GP}
\input parimacro.tex
\def\tocwrite#1{}
\title{Installation Guide for the UNIX Versions}{}

\section{Required tools}

Compiling PARI requires a \kbd{C} or \kbd{C++} compiler supporting C99 or
higher. If you do
not have one, we suggest that you obtain the \kbd{gcc/g++} compiler. As for
all GNU software mentioned afterwards, you can find the most convenient site
to fetch \kbd{gcc} at the address
$$\url{https://www.gnu.org/prep/ftp.html}$$
%
(On Mac OS X, this is also provided in the \kbd{Xcode} tool
suite; or the lightweight ``Command-Line Tools (CLT) for \kbd{Xcode}''.) You can
compile PARI with a different compiler, but the PARI kernel takes advantage
of optimizations provided by \kbd{gcc}. Compiling with GCC results in at least
20\% speedup on most architectures.

\misctitle{Optional libraries and programs} The following programs and libraries
are useful in conjunction with \kbd{gp}, but not mandatory. In any case, get them
before proceeding if you want the functionality they provide. All of libraries
and programs are free. The download page on our website
$$
\url{https://pari.math.u-bordeaux.fr/download.html}
$$
contains pointers on how to get them.

  \item GNU \kbd{MP} (GMP) library. GMP provides an alternative multiprecision
kernel, which is faster than PARI's native one. When using GMP the
binaries become incompatible, so the resulting PARI library \kbd{SONAME} is libpari-gmp.

  \item GNU \kbd{readline} library. Readline provides line editing under
\kbd{gp}, an automatic context-dependent completion, and an editable history
of commands.

  \item GNU \kbd{emacs} and the \tet{PariEmacs} package. The \kbd{gp}
calculator can be run in an Emacs buffer, with all the obvious advantages if
you are familiar with this editor. Note that \kbd{readline} is still useful
in this case since it provides a better automatic completion than is provided
by Emacs's GP-mode.

  \item GNU \kbd{gzip/gunzip/gzcat} package enables \kbd{gp} to read
compressed data.

  \item \kbd{perl} provides extended online help (full text from the
manual) about functions and concepts. The script handling this online help
can be used under \kbd{gp} or independently.

\section{Compiling the library and the \kbd{gp} calculator}

\subsec{Basic configuration} Type

\kbd{./Configure}

\noindent in the toplevel directory. This attempts to configure PARI/GP
without outside help. Note that if you want to install the end product in
a nonstandard place, you can use the \kbd{--prefix} option, as in

\kbd{./Configure --prefix=}\var{/an/exotic/directory}

\noindent (the default prefix is \kbd{/usr/local}). For example, to build a
package for a Linux distribution, you may want to use

\kbd{./Configure --prefix=/usr}

The command

\kbd{./Configure --builddir=\var{DIR}}

\noindent configures the build for a particular system. It extracts some files
and creates the \var{build directory} \var{DIR}, where the object files and
executables will be built. Thus you can build PARI/GP for several different
machines from the same source tree. When building for multiple machines the
builds are independent and can be performed simultaneously.

If the \kbd{--builddir=\var{DIR}} argument is omitted, the build directory is
named \kbd{O\var{osname}-\var{arch}}, where the \var{osname} and
\var{arch} components depends on your architecture and operating system.
A debug build (\kbd{Configure -g}) or a profiling build (\kbd{Configure -pg})
bring in an extra \kbd{.dbg} (resp.~\kbd{.prf}) suffix.

Decide whether you agree with what \kbd{Configure} printed on your screen, in
particular the architecture, compiler and optimization flags. Look for
messages prepended by \kbd{\#\#\#}, which report genuine problems.
Look especially for the \kbd{gmp}, \kbd{readline} and \kbd{X11} libraries,
and the \kbd{perl} and \kbd{gunzip} (or \kbd{zcat}) binaries.
If anything should have been found and was not, consider that \kbd{Configure}
failed and follow the instructions in section~3.

The \kbd{Configure} script creates a file \kbd{config.log} in the build
directory, which contains debugging information --- in particular, all
messages from compilers ---  that may help diagnose problems. This file
is erased and recreated from scratch each time \kbd{Configure} is run.

\subsec{Advanced configuration}
\kbd{Configure} accepts many other flags, and you may use any number of them
to build quite a complicated configuration command. See \kbd{Configure
--help} for a complete list. In particular, GMP is configured using the set
of flags \kbd{--with-gmp*}, and Readline is configured using the set
of flags \kbd{--with-readline*}.

\kbd{--with-gmp}: enables a particular installation of GMP. If the GMP
library was installed in \kbd{/an/exotic/directory}, then you can use
\kbd{--with-gmp=/an/exotic/directory} to find the headers and libraries.

If you are using GMP, tune it first, then tune PARI. Make sure you tune PARI
on the machine that will actually run your computations. Do not use a heavily
loaded machine for tunings.

\kbd{--with-readline}: enables a particular installation of Readline. If
Readline was installed in \kbd{/an/exotic/directory}, then you can use
\kbd{--with-readline=/an/exotic/directory} to find the headers and libraries.

\kbd{make -jN}: You may speed up the compilation by using a parallel make.
The command below tells make to execute 4 recipes simultaneously.
\bprog
  env MAKE="make -j4" Configure
@eprog

Next, we focus on some of the nonobvious options used by \kbd{Configure}:

\kbd{--tune}: fine tunes the library for the host used for compilation.
Tuning the package adjusts thresholds by running a large number of comparative
tests and creates a file \kbd{tune.h} in the build directory, that will be
used from now on, overriding the ones in \kbd{src/kernel/none/} and
\kbd{src/kernel/gmp/}. It will take a while: about 30 minutes. Expect a small
performance boost, perhaps a 10\% speed increase compared to default settings.
Note that this is dependent on the \kbd{--mt} option, so make sure to include
the relevant value, as in \kbd{Configure --tune --mt=pthread}.

\kbd{--graphic=}\var{lib}: enables a particular graphic library.
The default is \kbd{X11} on most platforms, but PARI can use
\kbd{fltk} or \kbd{win32} (GDI), or even dump a \kbd{ps}
or \kbd{svg} file and open it using an external viewer.

\kbd{--time=}\var{function}: chooses a timing function. The default usually
works fine, however you can use a different one that better fits your needs.
PARI can use \kbd{getrusage}, \kbd{clock\_gettime}, \kbd{times} or
\kbd{ftime} as timing functions. (Not all timing functions are available on
all platforms.) The three first functions give timings in terms of CPU usage
of the current task, approximating the complexity of the algorithm. The last
one, \kbd{ftime}, gives timings in terms of absolute (wall-clock) time.
Moreover, the \kbd{clock\_gettime} function is more precise, but much slower
(at the time of this writing), than \kbd{getrusage} or \kbd{times}.

\kbd{--with-runtime-perl=}\var{perl}: absolute path to the runtime \kbd{perl}
binary to be used by the \kbd{gphelp} and \kbd{tex2mail} scripts. Defaults
to the path found by \kbd{Configure} on the build host (usually
\kbd{/usr/bin/perl}). For cross-compiling builds, when the target and build
hosts have mismatched configurations; suggested values are

\kbd{/usr/bin/env perl}: the first \kbd{perl} executable found in user's
\kbd{PATH},

\kbd{/usr/bin/perl}: \kbd{perl}'s standard location.

The remaining options are specific to parallel programming. We provide an
\emph{Introduction to parallel GP programming} in the file
\kbd{doc/parallel.dvi}, and to multi-threaded \kbd{libpari} programs
in Appendix~D. Beware that these options change the library ABI, in
particular you will need to \kbd{make clean} between successive builds
using different values of this option:

\kbd{--mt=}\var{engine}: specify the engine used for parallel computations.
Supported value are

\item single: (default) no parallellism.

\item pthread: use POSIX threads. This is well-suited for multi-core systems.
Setting this option also set \kbd{--enable-tls}, see below. This option
requires the pthread library.
For benchmarking, it is often useful to set \kbd{--time=ftime} so that GP
report wall-clock instead of the sum of the time spent by each thread.

\item mpi: use the MPI interface to parallelism.  This allows PARI to take
advantage of clusters using MPI. This option requires a MPI library.
It is usually necessary to set the environment variable \kbd{CC} to
\kbd{mpicc}.

Note that running \kbd{Configure --tune} implicitly compiles and tunes for
\kbd{--mt=single}; if you intend to install a binary compiled with
another option, say \kbd{pthread}, you should use \kbd{Configure --tune
--mt=pthread} instead.

\kbd{--enable-tls}: build the thread-safe version of the library. Implied by
\kbd{--mt=pthread}. This tends to slow down the \emph{shared} library
\kbd{libpari.so} by about $25\%$, so you probably want to use the static
library \kbd{libpari.a} instead.

\subsec{Compilation} To compile the \kbd{gp} binary and build the
documentation, type

\kbd{make all}

\noindent from the build directory. Recall the build directory is
(by default) of the form \kbd{O\var{osname}-\var{arch}} or
passed to \kbd{Configure} using the option
\kbd{--build=\var{DIR}}. To only compile the \kbd{gp} binary, type

\kbd{make gp}

\noindent in the toplevel directory (this will correctly determine
the \kbd{O\var{osname}-\var{arch}} default directory) or \kbd{make -C
\var{DIR} gp} (it is also possible to \kbd{cd \var{DIR}} first).

If your \kbd{make} program supports parallel make, you can speed up the
process by going to the build directory that \kbd{Configure} created and
doing a parallel make here, for instance \kbd{make -j4} with GNU make. It
should also work from the toplevel directory.

\subsec{Basic tests}

To test the binary, type \kbd{make bench}. This runs a quick series of
tests, for a few seconds on modern machines.

In many cases, this will also build a different binary (named \kbd{gp-sta} or
\kbd{gp-dyn}) linked in a slightly different way and run the tests with both.
(In exotic configurations, one may pass all the tests while the other fails
and we want to check for this.) To test only the default binary, use
\kbd{make dobench} which starts the bench immediately.

If a \kbd{[BUG]} message shows up, something went wrong. The testing utility
directs you to files containing the differences between the test output and
the expected results. Have a look and decide for yourself if something is
amiss. If it looks like a bug in the Pari system, we would appreciate a
report, see the last section.

\subsec{Cross-compiling}

When cross-compiling, you can set the environment variable \kbd{RUNTEST} to a
program that is able to run the target binaries, e.g. an emulator. It will be
used for both the \kbd{Configure} tests and \kbd{make bench}.

\section{Troubleshooting and fine tuning}
In case the default \kbd{Configure} run fails miserably, try

\kbd{./Configure -a}

\noindent (interactive mode) and answer all the questions: there are about 30
of them, and default answers are provided. If you accept all default answers,
\kbd{Configure} will fail just the same, so be wary. In any case, we would
appreciate a bug report (see the last section).

\subsec{Installation directories} The install location of programs and
libraries is controlled by the \kbd{--prefix} configure option. The default
location is \kbd{/usr/local}.

The precise destinations of programs and libraries are as
follows: the \kbd{gp} binary, the scripts \kbd{gphelp} and \kbd{tex2mail} go
to \kbd{\$prefix/bin}. The pari library goes to \kbd{\$prefix/lib} and
include files to \kbd{\$prefix/include/pari}. Other system-dependent data go
to \kbd{\$prefix/lib/pari}.

Architecture independent files go to various subdirectories of
\kbd{\$share\_prefix}, which defaults to \kbd{\$prefix/share}, and can be
specified via the \kbd{--share-prefix} argument. Man pages go into
\kbd{\$share\_prefix/man}, and other system-independent data
under \kbd{\$share\_prefix/pari}: documentation,
sample GP scripts and C code, extra packages like \kbd{elldata} or
\kbd{galdata}.

\noindent You can also set directly \kbd{--bindir} (executables),
\kbd{--libdir} (library), \kbd{--includedir} (include files), \kbd{--mandir}
(manual pages), \kbd{--datadir} (other architecture-independent data), and
finally \kbd{--sysdatadir} (other architecture-dependent data).

\subsec{Environment variables} \kbd{Configure} lets the following environment
variable override the defaults if set:

\kbd{CC}: C compiler.

\kbd{DLLD}: Dynamic library linker.

\kbd{LD}: Static linker.

\noindent For instance, \kbd{Configure} may avoid \kbd{/bin/cc} on some
architectures due to various problems which may have been fixed in your
version of the compiler. You can try

\kbd{env CC=cc Configure}

\noindent and compare the benches. Also, if you insist on using a \kbd{C++}
compiler and run into trouble with a fussy \kbd{g++}, try to use
\kbd{g++ -fpermissive}.

\noindent The contents of the following variables are \emph{appended} to the
values computed by \kbd{Configure}:

\kbd{CFLAGS}: Flags for \kbd{CC}.

\kbd{CPPFLAGS}: Flags for \kbd{CC} (preprocessor).

\kbd{LDFLAGS}: Flags for \kbd{LD}.

\noindent The contents of the following variables are \emph{prepended} to
the values computed by \kbd{Configure}:

\kbd{C\_INCLUDE\_PATH} is prepended to the list of directories
searched for include files. Note that adding \kbd{-I} flags to
\kbd{CFLAGS} is not enough since \kbd{Configure} sometimes
relies on finding the include files and parsing them, and it does not
parse \kbd{CFLAGS} at this time.

\kbd{LIBRARY\_PATH} is prepended to the list of directories
searched for libraries.

\noindent You may disable inlining by adding \kbd{-DDISABLE\_INLINE} to
\kbd{CFLAGS}, and prevent the use of the \kbd{volatile} keyword with
\kbd{-DDISABLE\_VOLATILE}.

\subsec{Target plateform ABI}: By design, Configure will always build PARI for
the default target ABI of the compiler. To build for a different ABI, add
the relevant compiler flag to CFLAGS. Some examples (with gcc):

\kbd{CFLAGS=-m32} build 32-bit binaries (on a 64-bit system)

\kbd{CFLAGS=-mavx2} allows uses of AVX2 instructions on x86\_64

\kbd{CFLAGS=-march=native} use the largest ABI supported by the CPU PARI
is compiled on. Binaries will be faster but not portable to older CPU.

\subsec{Debugging/profiling}: If you also want to debug the PARI library,

\kbd{Configure -g}

\noindent creates a directory \kbd{O$xxx$.dbg} containing a special
\kbd{Makefile} ensuring that the \kbd{gp} and PARI library built there is
suitable for debugging. If you want to
profile \kbd{gp} or the library, using \kbd{gprof} for instance,

\kbd{Configure -pg}

\noindent will create an \kbd{O$xxx$.prf} directory where a suitable version
of PARI can be built.

The \kbd{gp} binary built above with \kbd{make all} or \kbd{make gp} is
optimized. If you have run \kbd{Configure -g} or \kbd{-pg} and want to build
a special purpose binary, you can \kbd{cd} to the \kbd{.dbg} or \kbd{.prf}
directory and type \kbd{make gp} there. You can also invoke \kbd{make gp.dbg}
or \kbd{make gp.prf} directly from the toplevel.

\subsec{Multiprecision kernel} The kernel can be specified via the

\kbd{--kernel=\emph{fully\_qualified\_kernel\_name}}

\noindent switch. The PARI kernel consists of two levels: Level 0 (operation
on words) and Level 1 (operation on multi-precision integers and reals),
which can take the following values.

Level 0: \kbd{auto} (as detected), \kbd{none} (portable C) or
one of the assembler micro-kernels
\bprog
  alpha
  hppa hppa64
  ia64
  ix86 x86_64
  m68k
  ppc ppc64
  sparcv7 sparcv8_micro sparcv8_super
@eprog

Level 1: \kbd{auto} (as detected), \kbd{none} (native code only), or \kbd{gmp}

\noindent\item A fully qualified kernel name is of the form
\kbd{\var{Level0}-\var{Level1}}, the default value being \kbd{auto-auto}.

\noindent\item A \emph{name} not containing a dash '\kbd{-}' is an alias
for a fully qualified kernel name. An alias stands for
\kbd{\emph{name}-none}, but \kbd{gmp} stands for \kbd{auto-gmp}.

\subsec{Problems related to readline}
\kbd{Configure} does not try very hard to find the \kbd{readline} library and
include files. If they are not in a standard place, it will not find them.
You can invoke \kbd{Configure} with one of the following arguments:

   \kbd{--with-readline[=\emph{prefix to \kbd{lib/libreadline}.xx and
\kbd{include/readline.h}}]}

   \kbd{--with-readline-lib=\emph{path to \kbd{libreadline}.xx}}

   \kbd{--with-readline-include=\emph{path to \kbd{readline.h}}}

\misctitle{Known problems}

\item on Linux: Linux distributions have separate \kbd{readline} and
\kbd{readline-devel} packages. You need both of them installed to
compile gp with readline support. If only \kbd{readline} is installed,
\kbd{Configure} will complain. \kbd{Configure} may also complain about a
missing libncurses.so, in which case, you have to install the
\kbd{ncurses-devel} package (some distributions let you install
\kbd{readline-devel} without \kbd{ncurses-devel}, which is a bug in
their package dependency handling).

\item on OS X.4 or higher: these systems comes equipped with a fake
\kbd{readline}, which is not sufficient for our purpose. As a result, gp is
built without readline support. Since \kbd{readline} is not trivial to
install in this environment, a step by step solution can be found in the PARI
FAQ, see
$$
\url{https://pari.math.u-bordeaux.fr/}.
$$

\subsec{Testing}

\subsubsec{Known problems} if \kbd{BUG} shows up in \kbd{make bench}

\item If when running \kbd{gp-dyn}, you get a message of the form

\kbd{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 \emph{and} a broken local configuration. Either remove the
old library or unset the \kbd{LD\_LIBRARY\_PATH} environment variable. Try to
disable this variable in any case if anything \emph{very} wrong occurs with
the \kbd{gp-dyn} binary, like an Illegal Instruction on startup. It does not
affect \kbd{gp-sta}.

\item Some implementations of the \kbd{diff} utility (on HPUX for
instance) output \kbd{No differences encountered} or some similar
message instead of the expected empty input, thus producing a spurious
\kbd{[BUG]} message.

\subsubsec{Some more testing} [{\sl Optional\/}]

You can test \kbd{gp} in compatibility mode with \kbd{make test-compat}. If
you want to test the graphic routines, use \kbd{make test-ploth}. You will
have to click on the mouse button after seeing each image. There will be
eight of them, probably shown twice (try to resize at least one of them as a
further test).

The \kbd{make bench}, \kbd{make test-compat} and \kbd{make test-ploth} runs
all produce a Postscript file \kbd{pari.ps} in \kbd{O$xxx$} which you can
send to a Postscript printer. The output should bear some similarity to the
screen images.

\subsubsec{Heavy-duty testing} [{\sl Optional\/}]
There are a few extra tests which should be useful only for developers.

\kbd{make test-kernel} checks whether the low-level kernel seems to work,
and provides simple diagnostics if it does not. Only useful if \kbd{make
bench} fails horribly, e.g.~things like \kbd{1+1} do not work.

\kbd{make test-all} runs all available test suites. Thorough, but slow. Some
of the tests require extra packages (\kbd{elldata}, \kbd{galdata}, etc.)
to be available. If you want to test such an extra package \emph{before}
\kbd{make install} (which would install it to its final location, where
\kbd{gp} expects to find it), run
\bprog
  env GP_DATA_DIR=$PWD/data make test-all
@eprog\noindent from the PARI toplevel directory, otherwise the test will
fail.

\kbd{make test-io} tests writing to and reading from  files. It requires
a working \kbd{system()} command (fails on Windows + MingW).

\kbd{make test-time} tests absolute and relative timers. This test has a
tendency to fail when the machine is heavily loaded or if the granularity
of the chosen system timer is bigger than 2ms. Try it a few times before
reporting a problem.

\kbd{make test-install} tests the GP function \kbd{install}. This may not be
available on your platform, triggering an error message (``not yet available
for this architecture''). The implementation may be broken on your platform
triggering an error or a crash when an install'ed function is used.

\section{Installation} When everything looks fine, type

\kbd{make install}

\noindent You may have to do this with superuser privileges, depending on the
target directories. (Tip for MacOS X beginners: use \kbd{sudo make install}.)
In this case, it is advised to type \kbd{make all} first to avoid running
unnecessary commands as \kbd{root}.

\misctitle{Caveat} Install directories are created honouring your \kbd{umask}
settings: if your umask is too restrictive, e.g.~\kbd{077}, the installed
files will not be world-readable. (Beware that running \kbd{sudo} may change
your user umask.)

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

To save on disk space, you can manually \kbd{gzip} some of the documentation
files if you wish: \kbd{usersch*.tex} and all \kbd{dvi} files (assuming your
\kbd{xdvi} knows how to deal with compressed files); the online-help system
can handle it.

\subsec{Static binaries and libraries}
By default, if a dynamic library \kbd{libpari.so} can be built, the \kbd{gp}
binary we install is \kbd{gp-dyn}, pointing to \kbd{libpari.so}. On the other
hand, we can build a \kbd{gp} binary into which the \kbd{libpari} is
statically linked (the library code is copied into the binary); that binary
is not independent of the machine it was compiled on, and may still refer to
other dynamic libraries than \kbd{libpari}.

You may want to compile your own programs in the same way, using the static
\kbd{libpari.a} instead of \kbd{libpari.so}. By default this static library
\kbd{libpari.a} is not created. If you want it as well, use the target
\kbd{make install-lib-sta}. You can install a statically linked \kbd{gp} with
the target \kbd{make install-bin-sta}. As a rule, programs linked statically
(with \kbd{libpari.a}) may be slightly faster (about 5\% gain, possibly
up to 20\% when using \kbd{pthreads}), but use more disk space and take more
time to compile. They are also harder to upgrade: you will have to recompile
them all instead of just installing the new dynamic library. On the other
hand, there is no risk of breaking them by installing a new pari library.

\subsec{Extra packages} The following optional packages endow PARI with some
extra capabilities:

\item \kbd{elldata}: This package contains the elliptic curves in
John Cremona's database. It is needed by the functions \kbd{ellidentify},
\kbd{ellsearch}, \kbd{forell} and can be used by \kbd{ellinit} to initialize a curve given by its standard code.

\item \kbd{galdata}: The default \kbd{polgalois} function can only
compute Galois groups of polynomials of degree less or equal to 7. Install
this package if you want to handle polynomials of degree bigger than 7 (and
less than 11).

\item \kbd{seadata}: This package contains the database of modular
polynomials extracted from the ECHIDNA databases and computed by David R.
Kohel. It is used to speed up the functions \kbd{ellap}, \kbd{ellcard} and
\kbd{ellgroup} for primes larger than $10^{20}$.

\item \kbd{galpol}: This package contains the GALPOL database of polynomials
defining Galois extensions of the rationals, accessed by \kbd{galoisgetpol}.

\medskip

To install package \emph{pack}, you need to fetch the separate archive:
\emph{pack}\kbd{.tgz} which you can download from the \kbd{pari} server.
Copy the archive in the PARI toplevel directory, then extract its
contents; these will go to \kbd{data/\emph{pack}/}. Typing \kbd{make
install} installs all such packages.

\subsec{The \kbd{GPRC} file} Copy the file \kbd{misc/gprc.dft} (or
\kbd{gprc.dos} if you are using \kbd{GP.EXE}) to \kbd{\$HOME/.gprc}. Modify
it to your liking. For instance, if you are not using an ANSI terminal,
remove control characters from the \kbd{prompt} variable. You can also
enable colors.

If desired, read \kbd{\$datadir/misc/gpalias}  from the \kbd{gprc}
file, which provides some common shortcuts to lengthy names; fix the path in
gprc first. (Unless you tampered with this via Configure, \kbd{datadir} is
\kbd{\$prefix/share/pari}.) If you have superuser privileges and want to
provide system-wide defaults, copy your customized \kbd{.gprc} file to
\kbd{/etc/gprc}.

In older versions, \kbd{gphelp} was hidden in pari lib directory and was not
meant to be used from the shell prompt, but not anymore. If gp complains it
cannot find \kbd{gphelp}, check whether your \kbd{.gprc} (or the system-wide
\kbd{gprc}) does contain explicit paths. If so, correct them according to the
current \kbd{misc/gprc.dft}.

\section{Getting Started}

\subsec{Printable Documentation} Building gp with \kbd{make all} also builds
its documentation. You can also type directly \kbd{make doc}. In any case,
you need a working (plain) \TeX\ installation.

After that, the \kbd{doc} directory contains various \kbd{dvi} files:
\kbd{libpari.dvi} (manual for the PARI library), \kbd{users.dvi} (manual
for the \kbd{gp} calculator), \kbd{tutorial.dvi} (a tutorial), and
\kbd{refcard.dvi} (a reference card for GP). You can send these files to your
favorite printer in the usual way, probably via \kbd{dvips}. The reference
card is also provided as a \kbd{PostScript} document, which may be easier to
print than its \kbd{dvi} equivalent (it is in Landscape orientation and
assumes A4 paper size).

\noindent If \kbd{pdftex} is part of your \TeX\ setup, you can produce these
documents in PDF format, which may be more convenient for online browsing
(the manual is complete with hyperlinks); type

\kbd{make docpdf}

\noindent All these documents are available online from PARI home page
(see the last section).

\subsec{C programming} Once all libraries and include files are installed,
you can link your C programs to the PARI library. A sample makefile
\kbd{examples/Makefile} is provided to illustrate the use of the various
libraries. Type \kbd{make all} in the \kbd{examples} directory to see how
they perform on the \kbd{extgcd.c} program, which is commented in the
manual.

This should produce a statically linked binary \kbd{extgcd-sta}
(standalone), a dynamically linked binary \kbd{extgcd-dyn} (loads libpari
at runtime) and a shared library \kbd{libextgcd}, which can be used from
\kbd{gp} to \kbd{install} your new \kbd{extgcd} command.

The standalone binary should be bulletproof, but the other two may fail
for various reasons. If when running \kbd{extgcd-dyn}, you get a message
of the form ``DLL not found'', then stick to statically linked binaries
or look at your system documentation to see how to indicate at linking
time where the required DLLs may be found! (E.g.~on Windows, you will
need to move \kbd{libpari.dll} somewhere in your \kbd{PATH}.)

\subsec{GP scripts} Several complete sample GP programs are also given in
the \kbd{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. See the file \kbd{examples/EXPLAIN} for some explanations.

\subsec{The PARI Community} PARI's home page at the address
$$\url{https://pari.math.u-bordeaux.fr/}$$
%
maintains an archive of mailing lists dedicated to PARI, documentation
(including Frequently Asked Questions), a download area and our Bug Tracking
System (BTS). Bug reports should be submitted online to the BTS, which may be
accessed from the navigation bar on the home page or directly at
$$\url{https://pari.math.u-bordeaux.fr/Bugs/}$$
%
Further information can be found at that address but, to report a
configuration problem, make sure to include the relevant \kbd{*.dif} files in
the \kbd{O$xxx$} directory and the file \kbd{pari.cfg}.
\smallskip

There are a number of mailing lists devoted to PARI/GP, and most feedback
should be directed there. Instructions and archives can be consulted at
$$ \url{https://pari.math.u-bordeaux.fr/lists-index.html} $$
%
The most important are:

\item \kbd{pari-announce} (\emph{read-only}): to announce major version
changes. You cannot write to this one, but you should probably subscribe.

\item \kbd{pari-dev}: for everything related to the development of PARI,
including suggestions, technical questions or patch submissions. Bug reports
can be discussed here, but as a rule it is better to submit them directly
to the BTS.

\item \kbd{pari-users}: for everything else.

\noindent You may send an email to the last two without being subscribed.
To subscribe, send an message respectively to
\def\@{@}
\bprog
  pari-announce-request@@pari.math.u-bordeaux.fr
     pari-users-request@@pari.math.u-bordeaux.fr
       pari-dev-request@@pari.math.u-bordeaux.fr
@eprog\noindent with the word \kbd{subscribe} in the \kbd{Subject:}.
You can also write to us at the address
\bprog
  pari@@math.u-bordeaux.fr
@eprog\noindent but we cannot promise you will get an individual answer.
\smallskip

If you have used PARI in the preparation of a paper, please cite it in the
following form (BibTeX format):

\bprog
@@preamble{\usepackage{url}}
@@manual{PARI2,
    organization = "{The PARI~Group}",
    title        = "{PARI/GP version @vers}",
    year         = 2024,
    address      = "Bordeaux",
    note         = "available from \url{https://pari.math.u-bordeaux.fr/}"
}
@eprog
\smallskip

\noindent In any case, if you like this software, we would be indebted if you
could send us an email message giving us some information about yourself and
what you use PARI for.

\medskip
{\bf Good luck and enjoy!}
\vfill\eject
\end
