Return to appa.tex CVS log

Up to [local] / OpenXM_contrib / pari-2.2 / doc

Annotation of OpenXM_contrib/pari-2.2/doc/appa.tex, Revision 1.1

1.1     ! noro        1: % $Id: appa.tex,v 1.14 2001/09/19 21:47:15 karim Exp $
        !             2: % Copyright (c) 2000  The PARI Group
        !             3: %
        !             4: % This file is part of the PARI/GP documentation
        !             5: %
        !             6: % Permission is granted to copy, distribute and/or modify this document
        !             7: % under the terms of the GNU Free Documentation License
        !             8: \appendix{Installation Guide for the UNIX Versions}
        !             9:
        !            10: \def\tocwrite#1{}
        !            11: \section{Required tools}
        !            12:
        !            13: We assume that you have either an \kbd{ANSI C} or a \kbd{C++} compiler
        !            14: available. If your machine does not have one (for example if you still use
        !            15: \kbd{/bin/cc} in \kbd{SunOS 4.1.x}), we strongly suggest that you obtain the
        !            16: \kbd{gcc/g++} compiler from the Free Software Foundation or by
        !            17: anonymous~\kbd{ftp}. As for all GNU software mentioned afterwards, you can
        !            18: find the most convenient site to fetch \kbd{gcc} at the address
        !            19:
        !            20: \kbd{http://www.gnu.ai.mit.edu/order/ftp.html}
        !            21:
        !            22: \noindent
        !            23: You can certainly compile PARI with a different compiler, but the PARI
        !            24: kernel takes advantage of some optimizations provided by \kbd{gcc} if it is
        !            25: available. This results in about 20\% speedup on most architectures%
        !            26: \footnote*{One notable exception is the native AIX C compiler on IBM
        !            27: RS/6000 workstations, which generates fast code even without any special
        !            28: help from the PARI kernel sources.}.
        !            29:
        !            30: \subsec{Optional packages:} The following programs and libraries are useful
        !            31: in conjunction with GP, but not mandatory. They're probably already installed
        !            32: somewhere on your system (with the possible exception of \kbd{readline},
        !            33: which we think is really worth a try). In any case, get them before
        !            34: proceeding if you want the functionalities they provide. All of them are free
        !            35: (though you ought to make a small donation to the FSF if you use (and like)
        !            36: GNU wares).
        !            37:
        !            38:   $\bullet$ GNU \kbd{readline} library. This provides line editing under GP,
        !            39: an automatic context-dependent completion, and an editable history of
        !            40: commands. Note that it is incompatible with SUN commandtools (yet another
        !            41: reason to dump Suntools for X Windows). A recent readline (version number at
        !            42: least 2.2) is preferred, but older versions should be usable.
        !            43:
        !            44:   $\bullet$ GNU \kbd{gzip/gunzip/gzcat} package enables GP to read
        !            45: compressed data.
        !            46:
        !            47:   $\bullet$ GNU \kbd{emacs}. GP can be run in an Emacs buffer, with all the
        !            48: obvious advantages if you are familiar with this editor. Note that
        !            49: \kbd{readline} is still useful in this case since it provides a much better
        !            50: automatic completion than is provided by Emacs GP-mode.
        !            51:
        !            52:   $\bullet$ \kbd{perl} provides extended online help (full text from this
        !            53: manual) about functions and concepts, which can be used under GP or
        !            54: independently (\kbd{http://www.perl.com} will direct you to the nearest
        !            55: \kbd{CPAN} archive site).
        !            56:
        !            57:   $\bullet$ A colour-capable \kbd{xterm}, which enables GP to use different
        !            58: (user configurable) colours for its output. All \kbd{xterm} programs which come
        !            59: with current X11R6.3 distributions will satisfy this requirement. Under X11R6,
        !            60: you can for instance use \kbd{color\_xterm} (get the latest version at
        !            61: \kbd{http://www.clark.net/pub/dickey/xterm}).
        !            62:
        !            63: \vfill\eject
        !            64: \section{Compiling the library and the GP calculator}
        !            65:
        !            66: \subsec{Basic configuration:} First, have a look at the \kbd{MACHINES} file
        !            67: to see if anything funny applies to your architecture or operating system.
        !            68: Then, type
        !            69:
        !            70: \kbd{./Configure}
        !            71:
        !            72: \noindent in the toplevel directory. This will attempt to configure GP/PARI
        !            73: without outside help. Note that if you want to install the end product in
        !            74: some nonstandard place, you can use the \kbd{--prefix} option, as in
        !            75:
        !            76: \kbd{./Configure --prefix=/an/exotic/directory}
        !            77:
        !            78: \noindent (the default prefix is \kbd{/usr/local}). This phase extracts some
        !            79: files and creates a directory \kbd{O$xxx$} where the object files and
        !            80: executables will be built. The $xxx$ part depends on your architecture and
        !            81: operating system, thus you can build GP for several different machines from
        !            82: the same source tree (the builds are completely independent, so can be done
        !            83: simultaneously).
        !            84:
        !            85: \misctitle{Technical note:} The precise default destinations are as follows:
        !            86: the \kbd{gp} binary, the scripts \kbd{gphelp} and \kbd{tex2mail} go to
        !            87: \kbd{\$prefix/bin}. The pari library goes to \kbd{\$prefix/lib} and include
        !            88: files to \kbd{\$prefix/include/pari}. As for architecture independant files,
        !            89: the man pages go into \kbd{\$prefix/man} and the rest in various
        !            90: subdirectories of \kbd{\$prefix/lib/pari}.
        !            91:
        !            92: \noindent You can also supply a \kbd{--share-prefix} argument in which case
        !            93: architecture independant files go to different directories than in the above
        !            94: scheme: \kbd{\$share/pari} (galdata package), \kbd{\$share/man} (man pages)
        !            95: and \kbd{\$share/doc/pari/} (everything else: sample GP scripts and C code,
        !            96: documentation, emacs macros). For instance, to build a package for a Linux
        !            97: distribution, you will want to use
        !            98:
        !            99: \kbd{./Configure --prefix=/usr --share-prefix=/usr/share}
        !           100:
        !           101: \noindent \kbd{Configure} will let the following environment variable
        !           102: override the defaults if set:
        !           103:
        !           104: \kbd{AS}: Assembler.
        !           105:
        !           106: \kbd{CC}: C compiler.
        !           107:
        !           108: \kbd{CFLAGS}: Flags for the C compiler.
        !           109:
        !           110: \kbd{DLLD}: Dynamic library linker.
        !           111:
        !           112: \noindent For instance, \kbd{Configure} avoids \kbd{gcc} on some
        !           113: architectures due to various problems which may have been fixed in your
        !           114: version of the compiler. You can try
        !           115:
        !           116: \kbd{env CC=gcc Configure}
        !           117:
        !           118: \noindent and compare the benches. Also, if you insist on using a \kbd{C++}
        !           119: compiler and run into trouble with a recent \kbd{g++}, try to use
        !           120: \kbd{g++ -fpermissive}.
        !           121:
        !           122: \subsec{Troubleshooting and fine tuning:} Decide whether you agree with what
        !           123: \kbd{Configure} printed on your screen (in particular the architecture,
        !           124: compiler and optimization flags). If anything should have been found and was
        !           125: not, consider that \kbd{Configure} failed and follow the instructions below.
        !           126: Look especially for the \kbd{readline} and \kbd{X11} libraries, and the
        !           127: \kbd{perl} and \kbd{gunzip} (or \kbd{zcat}) binaries.
        !           128:
        !           129: In case the default \kbd{Configure} run fails miserably, try
        !           130:
        !           131: \kbd{./Configure -a}
        !           132:
        !           133: \noindent (interactive mode) and answer all the questions (there aren't that
        !           134: many). Of course, \kbd{Configure} will still provide defaults for each answer
        !           135: but if you accept them all, it will fail just the same, so be wary. In any
        !           136: case, we would appreciate a bug report including the complete output from
        !           137: \kbd{Configure} and the file \kbd{O$xxx$/dft.Config.in} that was produced in
        !           138: the process.
        !           139:
        !           140: Note that even in interactive mode, you can't directly tell \kbd{Configure}
        !           141: where the \kbd{readline} library and include files are. If they are not in a
        !           142: standard place, it won't find them. Nonetheless, it first searches the
        !           143: distribution toplevel for a \kbd{readline} directory. Thus, if you just want
        !           144: to give \kbd{readline} a try (as you probably should), you can get the source
        !           145: and compile it there (you don't need to install it). You can also use this
        !           146: feature together with a symbolic link, named \kbd{readline}, in the PARI
        !           147: toplevel directory if you have compiled the readline library somewhere else,
        !           148: without installing it to one of its standard locations.
        !           149:
        !           150: \misctitle{Technical note:} Configure can build GP on different architectures
        !           151: simultaneously from the same toplevel sources. Instead of the \kbd{readline}
        !           152: link alluded above, you can create \kbd{readline-{\sl osname}-{\sl arch}},
        !           153: using the same naming conventions as for the \kbd{O$xxx$} directory,
        !           154: e.g \kbd{readline-linux-i686}.
        !           155:
        !           156: \subsec{Debugging/profiling}: If you also want to debug the PARI library,
        !           157:
        !           158: \kbd{Configure -g}
        !           159:
        !           160: \noindent will create a directory \kbd{O$xxx$.dbg} containing a special
        !           161: \kbd{Makefile} ensuring that the GP and PARI library built there will be
        !           162: suitable for debugging (if your compiler doesn't use standard flags,
        !           163: e.g.~\kbd{-g} you may have to tweak that \kbd{Makefile}). If you want to
        !           164: profile GP or the library (using \kbd{gprof} for instance),
        !           165:
        !           166: \kbd{Configure -pg}
        !           167:
        !           168: \noindent will create an \kbd{O$xxx$.prf} directory where a suitable version
        !           169: of PARI can be built.
        !           170:
        !           171: \subsec{Compilation and tests:} To compile the GP binary, simply type
        !           172:
        !           173: \kbd{make gp}
        !           174:
        !           175: \noindent in the distribution directory. If your \kbd{make} program supports
        !           176: parallel make, you can speed up the process by going to the \kbd{O$xxx$}
        !           177: directory that \kbd{Configure} created and doing a parallel make here (for
        !           178: instance \kbd{make -j4} with GNU make).
        !           179:
        !           180: \subsubsec{Testing}
        !           181:
        !           182: To test the binary, type \kbd{make bench}. This will build a static
        !           183: executable (the default, built by \kbd{make gp} is probably dynamic) and
        !           184: run a series of comparative tests on those two. To test only the default
        !           185: binary, use \kbd{make dobench} which starts the bench immediately.
        !           186:
        !           187: The static binary should be slightly faster. In any case, this should not
        !           188: take more than one minute (user time) on modern machines. See the file
        !           189: \kbd{MACHINES} to get an idea of how much time comparable systems need (we
        !           190: would appreciate a short note in the same format in case your system is not
        !           191: listed and you nevertheless have a working GP executable).
        !           192:
        !           193: If a \kbd{[BUG]} message shows up, something went wrong. Probably with the
        !           194: installation procedure, but it may be a bug in the Pari system, in which
        !           195: case we would appreciate a report (including the relevant \kbd{*.dif} file
        !           196: in the \kbd{O$xxx$} directory and the file \kbd{dft.Config.in}).
        !           197:
        !           198: \misctitle{Known problems:}
        !           199:
        !           200: $\bullet$ \kbd{elliptic}: the test \kbd{cmcurve=ellinit([0,-3/4,0,-2,-1])}
        !           201: may give results which differ slightly from the template (last decimal in a
        !           202: few entries). This ultimately depends on the output of
        !           203:
        !           204: \kbd{polroots(x\pow 3-3/4*x\pow 2-2*x-1)[1]}
        !           205:
        !           206: \noindent at \kbd{\b{p}38}, which may be $2.0$ or $1.999\dots$ depending on
        !           207: your hardware, libraries, compiler\dots Intel Pentiums running Linux often
        !           208: trigger this \kbd{BUG} (unrelated to the infamous \kbd{fdiv} bug), which
        !           209: can safely be ignored in any case: both results are correct given the
        !           210: requested precision.
        !           211:
        !           212: $\bullet$ \kbd{program}: the GP function \kbd{install} may not be available on
        !           213: your platform, triggering an error message (``not yet available for this
        !           214: architecture''). Have a look at the \kbd{MACHINES} files (the \kbd{dl}
        !           215: column) to check if your system is known not to support it, or has never
        !           216: been tested yet.
        !           217:
        !           218: $\bullet$ If when running \kbd{gp-dyn}, you get a message of the form
        !           219:
        !           220: \kbd{ld.so: warning: libpari.so.$xxx$ has older revision than expected $xxx$}
        !           221:
        !           222: \noindent (possibly followed by more errors), you already have a dynamic PARI
        !           223: library installed {\it and\/} a broken local configuration. Either remove the
        !           224: old library or unset the \kbd{LD\_LIBRARY\_PATH} environment variable. Try to
        !           225: disable this variable in any case if anything {\it very} wrong occurs with
        !           226: the \kbd{gp-dyn} binary (e.g Illegal Instruction on startup). It doesn't
        !           227: affect \kbd{gp-sta}.
        !           228:
        !           229: \subsubsec{Some more testing} [{\sl Optional\/}]
        !           230:
        !           231: You can test GP in compatibility mode with \kbd{make test-compat}. If you
        !           232: want to test the graphic routines, use \kbd{make test-graphic}. You will
        !           233: have to click on the mouse button after seeing each image (under X11).
        !           234: There will be eight of them, probably shown twice (under X11, try to resize
        !           235: at least one of them as a further test).
        !           236:
        !           237: The \kbd{make bench} and \kbd{make test-compat} runs produce a Postscript
        !           238: file \kbd{pari.ps} in \kbd{O$xxx$} which you can send to a Postscript
        !           239: printer. The output should bear some similarity to the screen images.
        !           240:
        !           241: \section{Installation} When everything looks fine, type
        !           242:
        !           243: \kbd{make install}
        !           244:
        !           245: \noindent (You may have to do this with superuser privileges, depending on
        !           246: the target directories.) Beware that, if you chose the same installation
        !           247: directory as before in the \kbd{Configure} process, this will wipe out any
        !           248: files from version 1.39.15 and below that might already be there. Libraries
        !           249: and executable files from newer versions (starting with version 1.900) are
        !           250: not removed since they are only links to files bearing the version number
        !           251: (beware of that as well: if you're an avid GP fan, don't forget to delete the
        !           252: old pari libraries once in a while).
        !           253:
        !           254: This installs in the directories chosen at \kbd{Configure} time the default
        !           255: GP executable (probably \kbd{gp-dyn}) under the name \kbd{gp}, the default
        !           256: PARI library (probably \kbd{libpari.so}), the necessary include files, the
        !           257: manual pages, the documentation and help scripts and emacs macros.
        !           258:
        !           259: By default, if a dynamic library \kbd{libpari.so} could be built, the static
        !           260: library \kbd{libpari.a} will not be created. If you want it as well, you can
        !           261: use the target \kbd{make install-lib-sta}. You can install a statically
        !           262: linked \kbd{gp} with the target \kbd{make install-bin-sta}. As a rule,
        !           263: programs linked statically (with \kbd{libpari.a}) may be slightly faster
        !           264: (about 5\% gain), but use much more disk space and take more time to compile.
        !           265: They are also harder to upgrade: you will have to recompile them all instead
        !           266: of just installing the new dynamic library. On the other hand, there's no
        !           267: risk of breaking them by installing a new pari library.
        !           268:
        !           269: \subsec{The Galois package:} The default \kbd{polgalois} function can only
        !           270: compute Galois groups of polynomials of degree less or equal to 7. If you
        !           271: want to handle polynomials of degree bigger than 7 (and less than 11), you
        !           272: need to fetch a separate archive: \kbd{galdata.tgz} which can probably be
        !           273: found at the same place where you got the main PARI archive, and on the
        !           274: \kbd{megrez} ftp server in any case. Untar the archive in the \kbd{datadir}
        !           275: directory which was chosen at \kbd{Configure} time (it's one of the last
        !           276: messages on the screen if you did not run \kbd{Configure -a}). You can then
        !           277: test the \kbd{polgalois} function with your favourite polynomials.
        !           278:
        !           279: \subsec{The \kbd{GPRC} file:} Copy the file \kbd{misc/gprc.dft} (or
        !           280: \kbd{gprc.dos} if you're using \kbd{GP.EXE}) to \kbd{\$HOME/.gprc}. Modify
        !           281: it to your liking. For instance, if you're not using an ANSI terminal,
        !           282: remove control characters from the \kbd{prompt} variable. You can also
        !           283: enable colors.
        !           284:
        !           285: If desired, also copy/modify \kbd{misc/gpalias} somewhere and call it from
        !           286: the \kbd{gprc} file (this provides some common shortcuts to lengthy names).
        !           287: Finally, if you have superuser privileges and want to provide system-wide
        !           288: defaults, you can copy your customized \kbd{.gprc} file to \kbd{/etc/gprc}.
        !           289:
        !           290: In older versions, \kbd{gphelp} was hidden in pari lib directory and wasn't
        !           291: meant to be used from the shell prompt, but not anymore. If gp complains it
        !           292: can't find \kbd{gphelp}, check whether your \kbd{.gprc} (or the system-wide
        !           293: \kbd{gprc}) does contain explicit paths. If so, correct them according to the
        !           294: current \kbd{misc/gprc.dft}.
        !           295:
        !           296: \section{Getting Started}
        !           297:
        !           298: \subsec{Printable Documentation:} To print the user's guide, for which you'll
        !           299: need a working (plain) \TeX\ installation; type
        !           300:
        !           301: \kbd{make doc}
        !           302:
        !           303: \noindent This will create, in two passes, a file \kbd{doc/users.dvi}
        !           304: containing the manual with a table of contents and an index. You must then
        !           305: send the \kbd{users.dvi} file to your favourite printer in the usual way,
        !           306: probably via \kbd{dvips}. Also included are a short tutorial
        !           307: (\kbd{doc/tutorial.dvi}) and a reference card (\kbd{doc/refcard.dvi}
        !           308: and \kbd{doc/refcard.ps}) for GP.
        !           309:
        !           310: \noindent If the \kbd{pdftex} package is part of your \TeX\ setup, you can
        !           311: produce these documents in PDF format, which may be more convenient for
        !           312: online browsing (the manual is complete with hyperlinks); type
        !           313:
        !           314: \kbd{make docpdf}
        !           315:
        !           316: \noindent All these documents are available online from PARI home page and on
        !           317: the \kbd{megrez} ftp server.
        !           318:
        !           319: \subsec{C programming:} Once all libraries and include files are installed,
        !           320: you can link your C programs to the PARI library. A sample makefile
        !           321: \kbd{examples/Makefile} is provided to illustrate the use of the various
        !           322: libraries. Type \kbd{make all} in the \kbd{examples} directory to see how
        !           323: they perform on the \kbd{mattrans.c} program, which is commented in the
        !           324: manual.
        !           325:
        !           326: \subsec{GP scripts:} Several complete sample GP programs are also given in
        !           327: the \kbd{examples} directory, for example Shanks's SQUFOF factoring method,
        !           328: the Pollard rho factoring method, the Lucas-Lehmer primality test for
        !           329: Mersenne numbers and a simple general class group and fundamental unit
        !           330: algorithm (much worse than the built-in \kbd{bnfinit}!). See the file
        !           331: \kbd{examples/EXPLAIN} for some explanations.
        !           332:
        !           333: \subsec{EMACS:} If you want to use \kbd{gp} under GNU Emacs, read the file
        !           334: \kbd{emacs/pariemacs.txt}. If you are familiar with Emacs, we suggest that
        !           335: you do~so.
        !           336:
        !           337: \subsec{The PARI Community:} There are three mailing lists devoted to the
        !           338: PARI/GP package (run courtesy of Dan Bernstein), and most feedback should be
        !           339: directed to those. They are:
        !           340:
        !           341: $\bullet$ \kbd{pari-announce}: to announce major version changes.
        !           342: You can't write to this one, but you should probably subscribe.
        !           343:
        !           344: $\bullet$ \kbd{pari-dev}: for everything related to the development
        !           345: of PARI, including suggestions, technical questions, bug reports or patch
        !           346: submissions.
        !           347:
        !           348:  $\bullet$ \kbd{pari-users}: for everything else.
        !           349:
        !           350: \noindent To subscribe, send empty messages respectively to
        !           351:
        !           352: \centerline{\kbd{pari-announce-subscribe@list.cr.yp.to}}
        !           353:
        !           354: \centerline{\kbd{pari-users-subscribe@list.cr.yp.to}}
        !           355:
        !           356: \centerline{\kbd{pari-dev-subscribe@list.cr.yp.to}}
        !           357:
        !           358: \noindent The PARI home page (maintained by Gerhard Niklasch) at the address
        !           359:
        !           360: \centerline{\wwwsite}
        !           361:
        !           362: \noindent maintains an archive of all discussions as well as a download area.
        !           363: If don't want to subscribe to those lists, you can write to us at the address
        !           364:
        !           365: \centerline{\kbd{pari@math.u-bordeaux.fr}}
        !           366:
        !           367: \noindent At the very least, we will forward you mail to the lists above and
        !           368: correct faulty behaviour, if necessary. But we cannot promise you will get an
        !           369: individual answer.
        !           370:
        !           371: If you have used PARI in the preparation of a paper, please cite it in the
        !           372: following form (BibTeX format):
        !           373:
        !           374: \def\@{@}
        !           375: \bprog
        !           376: @@manual{PARI2,
        !           377:     organization = "{The PARI~Group}",
        !           378:     title        = "{PARI/GP, Version @vers}",
        !           379:     year         = 2000,
        !           380:     address      = "Bordeaux",
        !           381:     note         = "available from {\tt @wwwsite}"
        !           382: }
        !           383: @eprog
        !           384: \smallskip
        !           385:
        !           386: \noindent In any case, if you like this software, we would be indebted if you
        !           387: could send us an email message giving us some information about yourself and
        !           388: what you use PARI for.
        !           389:
        !           390: \medskip
        !           391: {\bf Good luck and enjoy!}
        !           392: \vfill\eject