1
/* doc/configuration (in Emacs -*-outline-*- format). */
3
Copyright 2000, 2001, 2002 Free Software Foundation, Inc.
5
This file is part of the GNU MP Library.
7
The GNU MP Library is free software; you can redistribute it and/or modify
8
it under the terms of the GNU Lesser General Public License as published by
9
the Free Software Foundation; either version 2.1 of the License, or (at your
10
option) any later version.
12
The GNU MP Library is distributed in the hope that it will be useful, but
13
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
15
License for more details.
17
You should have received a copy of the GNU Lesser General Public License
18
along with the GNU MP Library; see the file COPYING.LIB. If not, write to
19
the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
26
** Adding a top-level file
28
i) Add it to libgmp_la_SOURCES in Makefile.am.
30
ii) If libmp.la needs it (usually doesn't), then add it to
33
** Adding a subdirectory file
37
i) Add file.c to libmpz_la_SOURCES in mpz/Makefile.am.
39
ii) Add mpz/file$U.lo to MPZ_OBJECTS in the top-level Makefile.am
41
iii) If for some reason libmp.la needs it (usually doesn't) then add
42
mpz/file$U.lo to libmp_la_DEPENDENCIES in the top-level
45
The same applies to mpf, mpq, scanf and printf.
49
The way we build libmpn (in the `mpn' subdirectory) is quite special.
51
Currently only mpn/mp_bases.c is truely generic and included in every
52
configuration. All other files are linked at build time into the mpn
53
build directory from one of the CPU specific sub-directories, or from
54
the mpn/generic directory.
56
There are four types of mpn source files.
58
.asm Assembly code preprocessed with m4
59
.S Assembly code preprocessed with cpp
60
.s Assembly code not preprocessed at all
63
There are two types of .asm files.
65
i) ``Normal'' files containing one function, though possibly with
66
more than one entry point.
68
ii) Multi-function files that generate one of a set of functions
69
according to build options.
71
To add a new implementation of an existing function,
73
i) Put it in the appropriate CPU-specific mpn subdirectory, it'll be
76
ii) Any entrypoints tested by HAVE_NATIVE_func in other code must
77
have PROLOGUE(func) for configure to grep. This is normal for
78
.asm or .S files, but for .c files a dummy comment like the
79
following will be needed.
85
To add a new implementation using a multi-function file, in addition
88
i) Use a MULFUNC_PROLOGUE(func1 func2 ...) in the .asm, declaring
89
all the functions implemented, including carry-in variants.
91
If there's a separate PROLOGUE(func) for each possible function,
92
then MULFUNC_PROLOGUE isn't necessary (but this is usually not
95
To add a new style of multi-function file, in addition do the
98
i) Add to the "case" statement in configure.in which lists each
99
multi-function filename and what function files it can provide.
101
To add a completely new mpn function file, do the following,
103
i) Ensure the filename is a valid C identifier, due to the
104
-DOPERATION_$* used to support multi-function files. This means
105
"-" can't be used (but "_" can).
107
ii) Add it to configure.in under one of the following
109
a) `gmp_mpn_functions' if it exists for every target. This
110
means there must be a C version in mpn/generic. (Eg. mul_1)
112
b) `gmp_mpn_functions_optional' if it's a standard function, but
113
doesn't need to exist for every target. Code wanting to use
114
this will test HAVE_NATIVE_func to see if it's available.
117
c) `extra_functions' for some targets, if it's a special
118
function that only ever needs to exist for certain targets.
119
Code wanting to use it can test either HAVE_NATIVE_func or
120
HAVE_HOST_CPU_foo, as desired.
122
iii) Add `#undef HAVE_NATIVE_func' to acconfig.h. This is only
123
actually necessary if that define is going to be used, but for
124
consistency it's good to do it always.
126
iv) Add file.c to nodist_libdummy_la_SOURCES in mpn/Makefile.am (in
127
order to get an ansi2knr rule). If the file is only in
128
assembler then this step is unnecessary, but do it anyway so as
129
not to forget if later a .c version is added.
131
v) If the function can be provided by a multi-function file, then
132
add to the "case" statement in configure.in which lists each
133
multi-function filename and what function files it can provide.
136
** Adding a test program
138
i) Tests to be run early in the testing can be added to the main
139
"tests" sub-directory.
141
ii) Tests for mpn, mpz, mpq and mpf can be added under the
142
corresponding tests subdirectory.
144
iii) Generic tests for late in the testing can be added to
145
"tests/misc". printf and scanf tests currently live there too.
147
iv) Random number function tests can be added to "tests/rand". That
148
directory has some development-time programs too.
150
v) C++ test programs can be added to "tests/cxx". A line like the
151
following must be added for each, since by default automake looks
154
t_foo_SOURCES = t-foo.cc
156
In all cases the name of the program should be added to check_PROGRAMS
157
in the Makefile.am. TESTS is equal to check_PROGRAMS, so all those
160
"tests/devel" has a number of programs which are only for development
161
purposes and are not for use in "make check". These should be listed
162
in EXTRA_PROGRAMS to get Makefile rules created, but they're never
163
built or run unless an explicit "make someprog" is used.
167
The macos/configure script will automatically pick up additions to
168
gmp_mpn_functions, MPZ_OBJECTS, etc, but currently test programs need
169
to be added to Makefile.in manually.
171
When modifying the top-level configure.in ensure that it doesn't upset
172
the macos/configure script heuristics.
177
In general it's policy to use proper names for each CPU type
178
supported. If two CPUs are quite similar and perhaps don't have any
179
actual differences in GMP then they're still given separate names, for
180
example alphaev67 and alphaev68.
184
i) Decide the canonical CPU names GMP will accept.
186
ii) Add these to the config.sub wrapper if configfsf.sub doesn't
189
iii) Document the names in gmp.texi.
193
i) Any aliases can be added to the config.sub wrapper, unless
194
configfsf.sub already does the right thing with them.
196
ii) Leave configure.in and everywhere else using only the canonical
197
names. Aliases shouldn't appear anywhere except config.sub.
199
iii) Document in gmp.texi, if desired. Usually this isn't a good
200
idea, better encourage users to know just the canonical
205
i) Add patterns to configure.in for the new CPU names. Include the
206
following (see configure.in for the variables to set up),
208
a) ABI choices (if any).
210
c) mpn path for CPU specific code.
211
d) Good default CFLAGS for each likely compiler.
212
d) Any special tests necessary on the compiler or assembler
215
ii) M4 macros to be shared by asm files in a CPU family are by
216
convention in a foo-defs.m4 like mpn/x86/x86-defs.m4. They're
217
likely to use settings from config.m4 generated by configure.
220
* The configure system
224
The current versions of automake, autoconf and libtool in use can be
225
checked in the ChangeLog. Look for "Update to ...". Patches may have
226
been applied, look for "Regenerate ...".
228
The GMP build system is in places somewhat dependent on the internals
229
of the build tools. Obviously that's avoided as much as possible, but
230
where it can't it creates a problem when upgrading or attempting to
231
use different tools versions.
235
The following files need to be updated when going to a new version of
236
the build tools. Unfortunately the tools generally don't identify
237
when an out-of-date version is present.
239
aclocal.m4 is updated by running "aclocal -I mpfr".
241
INSTALL.autoconf can be copied from INSTALL in autoconf.
243
ltmain.sh comes from libtool. Remove it and run "libtoolize --copy",
244
or just copy the file by hand.
246
ansi2knr.c, ansi2knr.1, install.sh, mdate-sh and mkinstalldirs come
247
from automake and can be updated by copying or by removing and running
248
"automake --add-missing --copy".
250
texinfo.tex can be updated from ftp.gnu.org. Check it still works
251
with "make gmp.dvi" and "texi2pdf gmp.texi".
253
configfsf.guess and configfsf.sub can be updated from ftp.gnu.org (or
254
from the "config" cvs module at subversions.gnu.org). The gmp
255
config.guess and config.sub wrappers are supposed to make such an
256
update fairly painless.
258
depcomp from automake is not needed because all Makefile.am files
259
specify "no-dependencies".
265
Input files Tool Output files
266
------------------------------------------
268
acinclude.m4 --------------> aclocal.m4
271
configure.in \ -------------> configure
275
Makefile.am \ -------------> Makefile.in
279
configure.in \ -------------> config.in
283
When configured with --enable-maintainer-mode the necessary tools are
284
re-run on changing the input files. This can end up running a lot
285
more things than are really necessary, but that's too bad.
289
Input files Tool Output files
290
------------------------------------------
292
Makefile.in \ configure / Makefile
293
config.in | -------------> | config.h
294
gmp-h.in | | config.m4
300
It's intended that the contents of libgmp.la won't vary according to
301
whether --enable-cxx is selected. This means that if C++ shared
302
libraries don't work properly then a shared+static with --disable-cxx
303
can be done for the C parts, then a static-only with --enable-cxx to
306
libgmpxx.la uses some internals from libgmp.la, in order to share code
307
between C and C++. It's intended that libgmpxx can only be expected
308
to work with libgmp from the same version of GMP. If some of the
309
shared internals change their interface, then it's proposed to rename
310
them, for instance __gmp_doprint2 or the like, so as to provoke link
311
errors rather than mysterious failures from a mismatch.
317
--disable-shared will make builds go much faster, though of course
318
shared or shared+static should be tested too.
320
--enable-mpbsd grabs various bits of mpz, which might need to be
321
adjusted if things in those routines are changed. Building mpbsd all
322
the time doesn't cost much.
324
--prefix to a dummy directory followed by "make install" will show
327
"make check" acts on the libgmp just built, and will ignore any other
328
/usr/lib/libgmp, or at least it should do. Libtool does various hairy
329
things to ensure it hits the just-built library.
333
A build with maximum debugging can be made with
335
./configure --host=none --enable-assert --enable-alloca=debug
337
Malloc memory leaks are always checked by the test programs. With
338
alloca=debug any TMP_ALLOC leaks will be detected too.
339
--enable-alloca=malloc-reentrant also has this effect.
341
** Long long limb testing
343
On systems where gcc supports long long, but a limb is normally just a
344
long, the following can be used to force long long for testing
345
purposes. It will probably run quite slowly.
347
./configure --host=none ABI=longlong
349
** Function argument conversions
351
When using gcc, configuring with something like
353
./configure CFLAGS="-g -Wall -Wconversion -Wno-sign-compare"
355
can show where function parameters are being converted due to having
356
function prototypes available, which won't happen in a K&R compiler.
357
Doing this in combination with the long long limb setups above is
360
Conversions between int and long aren't warned about by gcc when
361
they're the same size, which is unfortunate because casts should be
362
used in such cases, for the benefit of K&R compilers with int!=long
363
and where the difference matters in function calls.
367
Function definitions must be in the GNU stylized form to work. See
368
the ansi2knr.1 man page.
370
__GMP_PROTO is used for function prototypes, other ANSI / K&R
371
differences are conditionalized in various places.
373
Proper testing of the K&R support requires a compiler which gives an
374
error for ANSI-isms. Configuring with --host=none is a good idea, to
375
test all the generic C code.
377
When using an ANSI compiler, the ansi2knr setups can be partially
380
./configure am_cv_prog_cc_stdc=no
382
This will test the use of $U and the like in the makefiles, but not
385
am_cv_prog_cc_stdc=no can be used with a compiler like HP C which is
386
K&R by default but to which configure normally adds ANSI mode flags.
387
This then should be a good full K&R test.
395
/* eof doc/configuration */
added
removed
src/gmp/doc/configuration
