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