| version 1.1, 2000/09/09 14:12:20 |
version 1.1.1.2, 2003/08/25 16:06:11 |
|
|
| /* doc/configuration (in Emacs -*-outline-*- format). */ |
/* doc/configuration (in Emacs -*-outline-*- format). */ |
| |
|
| * How to add a new file |
Copyright 2000, 2001, 2002 Free Software Foundation, Inc. |
| |
|
| ** A file in the `mpn' subdirectory |
This file is part of the GNU MP Library. |
| |
|
| The way we build libmpn (in the `mpn' subdirectory) is quite special. |
The GNU MP Library is free software; you can redistribute it and/or modify |
| |
it under the terms of the GNU Lesser General Public License as published by |
| |
the Free Software Foundation; either version 2.1 of the License, or (at your |
| |
option) any later version. |
| |
|
| There is (currently) only one ``generic'' file, one that is truly |
The GNU MP Library is distributed in the hope that it will be useful, but |
| target independent. That is `mp_bases.c'. All other files are kept |
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY |
| in subdirectories of `mpn' with the subdirectory names indicating the |
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public |
| target processor. For example, in the `alpha' subdirectory, code |
License for more details. |
| specific to the Alpha processor is found. |
|
| |
|
| When running `configure', a bunch of symbolic links are made in the |
You should have received a copy of the GNU Lesser General Public License |
| `mpn' subdirectory. If the the build host doesn't support symlinks |
along with the GNU MP Library; see the file COPYING.LIB. If not, write to |
| then either hard links or copying is used. |
the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA |
| |
02111-1307, USA. |
| |
|
| |
|
| |
|
| |
* Adding a new file |
| |
|
| |
** Adding a top-level file |
| |
|
| |
i) Add it to libgmp_la_SOURCES in Makefile.am. |
| |
|
| |
ii) If libmp.la needs it (usually doesn't), then add it to |
| |
libmp_la_SOURCES too. |
| |
|
| |
** Adding a subdirectory file |
| |
|
| |
For instance for mpz, |
| |
|
| |
i) Add file.c to libmpz_la_SOURCES in mpz/Makefile.am. |
| |
|
| |
ii) Add mpz/file$U.lo to MPZ_OBJECTS in the top-level Makefile.am |
| |
|
| |
iii) If for some reason libmp.la needs it (usually doesn't) then add |
| |
mpz/file$U.lo to libmp_la_DEPENDENCIES in the top-level |
| |
Makefile.am too. |
| |
|
| |
The same applies to mpf, mpq, scanf and printf. |
| |
|
| |
** Adding an mpn file |
| |
|
| |
The way we build libmpn (in the `mpn' subdirectory) is quite special. |
| |
|
| |
Currently only mpn/mp_bases.c is truely generic and included in every |
| |
configuration. All other files are linked at build time into the mpn |
| |
build directory from one of the CPU specific sub-directories, or from |
| |
the mpn/generic directory. |
| |
|
| There are four types of mpn source files. |
There are four types of mpn source files. |
| |
|
| .asm Assembly code preprocessed with m4 |
.asm Assembly code preprocessed with m4 |
| .S Assembly code preprocessed with CPP |
.S Assembly code preprocessed with cpp |
| .s Assembly code not preprocessed at all |
.s Assembly code not preprocessed at all |
| .c C code |
.c C code |
| |
|
| There are two types of .asm files. |
There are two types of .asm files. |
| |
|
| i) ``Normal'' files containing one function, possibly with more than |
i) ``Normal'' files containing one function, though possibly with |
| one entry point. |
more than one entry point. |
| |
|
| ii) Multi-function files that generate one of a set of functions |
ii) Multi-function files that generate one of a set of functions |
| according to build options. |
according to build options. |
| |
|
| |
To add a new implementation of an existing function, |
| |
|
| When adding a new implementation of an existing function, |
i) Put it in the appropriate CPU-specific mpn subdirectory, it'll be |
| |
detected and used. |
| |
|
| i) Put it in the appropriate mpn subdirectory. It'll be detected and |
ii) Any entrypoints tested by HAVE_NATIVE_func in other code must |
| used. |
have PROLOGUE(func) for configure to grep. This is normal for |
| |
.asm or .S files, but for .c files a dummy comment like the |
| |
following will be needed. |
| |
|
| ii) If it's a .asm or .S, be sure to have a PROLOGUE(func) entry |
/* |
| point since configure greps for that to set up the |
PROLOGUE(func) |
| HAVE_NATIVE_func defines in config.h. |
*/ |
| |
|
| When adding a new implementation using a multi-function file, in |
To add a new implementation using a multi-function file, in addition |
| addition do the following, |
do the following, |
| |
|
| i) Use a MULFUNC_PROLOGUE(func1 func2 ...) in the .asm, declaring |
i) Use a MULFUNC_PROLOGUE(func1 func2 ...) in the .asm, declaring |
| all the functions implemented, including carry-in variants. |
all the functions implemented, including carry-in variants. |
| Line 51 addition do the following, |
|
| Line 92 addition do the following, |
|
| then MULFUNC_PROLOGUE isn't necessary (but this is usually not |
then MULFUNC_PROLOGUE isn't necessary (but this is usually not |
| the case). |
the case). |
| |
|
| When adding a new style of multi-function file, in addition do the |
To add a new style of multi-function file, in addition do the |
| following, |
following, |
| |
|
| i) Add to the "case" statement in configure.in which lists each |
i) Add to the "case" statement in configure.in which lists each |
| multi-function filename and what function files it can provide. |
multi-function filename and what function files it can provide. |
| |
|
| When adding a completely new mpn function file, do the following, |
To add a completely new mpn function file, do the following, |
| |
|
| i) Add it to configure.in under one of the following |
i) Ensure the filename is a valid C identifier, due to the |
| |
-DOPERATION_$* used to support multi-function files. This means |
| |
"-" can't be used (but "_" can). |
| |
|
| a) `gmp_mpn_functions' if it exists for every target. This means |
ii) Add it to configure.in under one of the following |
| there must be a C version in mpn/generic. (Eg. add_n) |
|
| |
|
| b) `gmp_mpn_functions_optional' if it's a standard function, but |
a) `gmp_mpn_functions' if it exists for every target. This |
| doesn't need to exist for every target. Code wanting to use |
means there must be a C version in mpn/generic. (Eg. mul_1) |
| this will test HAVE_NATIVE_func to see if it's available. |
|
| (Eg. copyi) |
|
| |
|
| c) `extra_functions' for some targets, if it's a special function |
b) `gmp_mpn_functions_optional' if it's a standard function, but |
| that only ever needs to exist for certain targets. Code |
doesn't need to exist for every target. Code wanting to use |
| wanting to use it will generally look for the target, but |
this will test HAVE_NATIVE_func to see if it's available. |
| HAVE_NATIVE_func can be used if desired. |
(Eg. copyi) |
| |
|
| ii) If you want `HAVE_NATIVE_func' defined in config.h, add |
c) `extra_functions' for some targets, if it's a special |
| `#undef HAVE_NATIVE_func' to acconfig.h. |
function that only ever needs to exist for certain targets. |
| |
Code wanting to use it can test either HAVE_NATIVE_func or |
| |
HAVE_HOST_CPU_foo, as desired. |
| |
|
| iii) If the function can be provided by a multi-function file, |
iii) Add `#undef HAVE_NATIVE_func' to acconfig.h. This is only |
| then follow the directions above for them too. |
actually necessary if that define is going to be used, but for |
| |
consistency it's good to do it always. |
| |
|
| ** Add a file in any other directory |
iv) Add file.c to nodist_libdummy_la_SOURCES in mpn/Makefile.am (in |
| |
order to get an ansi2knr rule). If the file is only in |
| |
assembler then this step is unnecessary, but do it anyway so as |
| |
not to forget if later a .c version is added. |
| |
|
| When adding a top-level file, |
v) If the function can be provided by a multi-function file, then |
| |
add to the "case" statement in configure.in which lists each |
| |
multi-function filename and what function files it can provide. |
| |
|
| i) Add it to libgmp_la_SOURCES in Makefile.am. |
|
| |
|
| ii) If libmp.la needs it, then add it to libmp_la_SOURCES too. |
** Adding a test program |
| |
|
| When adding an mpz file, |
i) Tests to be run early in the testing can be added to the main |
| |
"tests" sub-directory. |
| |
|
| i) Add file.c to libmpz_la_SOURCES in mpz/Makefile.am. |
ii) Tests for mpn, mpz, mpq and mpf can be added under the |
| |
corresponding tests subdirectory. |
| |
|
| ii) Add mpz/file.lo to MPZ_OBJECTS in the top-level Makefile.am. |
iii) Generic tests for late in the testing can be added to |
| |
"tests/misc". printf and scanf tests currently live there too. |
| |
|
| If a multi-function mpz file is being added, |
iv) Random number function tests can be added to "tests/rand". That |
| |
directory has some development-time programs too. |
| |
|
| i) In mpz/Makefile.am, |
v) C++ test programs can be added to "tests/cxx". A line like the |
| |
following must be added for each, since by default automake looks |
| |
for a .c file. |
| |
|
| a) Add the file to EXTRA_DIST. |
t_foo_SOURCES = t-foo.cc |
| |
|
| b) Add rules copying the file at build time to duplicates with |
In all cases the name of the program should be added to check_PROGRAMS |
| appropriate names. |
in the Makefile.am. TESTS is equal to check_PROGRAMS, so all those |
| |
programs get run. |
| |
|
| c) Add each such func.c to nodist_libmpz_la_SOURCES. |
"tests/devel" has a number of programs which are only for development |
| |
purposes and are not for use in "make check". These should be listed |
| |
in EXTRA_PROGRAMS to get Makefile rules created, but they're never |
| |
built or run unless an explicit "make someprog" is used. |
| |
|
| ii) Add each c) above also as mpz/func.lo in MPZ_OBJECTS in the |
** Macos directory |
| top-level Makefile.am. |
|
| |
|
| iii) In the multi-function file, expect a preprocessor symbol |
The macos/configure script will automatically pick up additions to |
| OPERATION_func to indicate what form is being compiled. |
gmp_mpn_functions, MPZ_OBJECTS, etc, but currently test programs need |
| |
to be added to Makefile.in manually. |
| |
|
| The same applies to mpf and mpq (except that multi-function support |
When modifying the top-level configure.in ensure that it doesn't upset |
| doesn't exist in mpq/Makefile.am at the moment). |
the macos/configure script heuristics. |
| |
|
| See mpz/mul_siui.c or mpf/integer.c for example multi-function files. |
|
| |
|
| * Selecting compiler and its flags by hand |
* Adding a new CPU |
| |
|
| Specifying CC on the configure command line, will result in a default |
In general it's policy to use proper names for each CPU type |
| set of compiler flags, CFLAGS; `-g' for all compilers plus `-O2' for |
supported. If two CPUs are quite similar and perhaps don't have any |
| gcc. Specify CFLAGS to set better flags. |
actual differences in GMP then they're still given separate names, for |
| |
example alphaev67 and alphaev68. |
| |
|
| Example |
Canonical names: |
| |
|
| $ configure CC=my-gcc |
i) Decide the canonical CPU names GMP will accept. |
| |
|
| will give |
ii) Add these to the config.sub wrapper if configfsf.sub doesn't |
| |
already accept them. |
| |
|
| CFLAGS = -g -O2 |
iii) Document the names in gmp.texi. |
| |
|
| Specifying CC on the configure command line will make configure |
Aliases (optional): |
| believe it's a 32-bit compiler and not choose a source path with |
|
| 64-bit assembly code. Specify CC64 as well as CC to make configure |
|
| pick 64-bit assembly code. |
|
| |
|
| $ configure CC=my64bit-cc CC64=my64bit-cc CFLAGS="-my -flags" |
i) Any aliases can be added to the config.sub wrapper, unless |
| |
configfsf.sub already does the right thing with them. |
| |
|
| |
ii) Leave configure.in and everywhere else using only the canonical |
| |
names. Aliases shouldn't appear anywhere except config.sub. |
| |
|
| |
iii) Document in gmp.texi, if desired. Usually this isn't a good |
| |
idea, better encourage users to know just the canonical |
| |
names. |
| |
|
| |
Configure: |
| |
|
| |
i) Add patterns to configure.in for the new CPU names. Include the |
| |
following (see configure.in for the variables to set up), |
| |
|
| |
a) ABI choices (if any). |
| |
b) Compiler choices. |
| |
c) mpn path for CPU specific code. |
| |
d) Good default CFLAGS for each likely compiler. |
| |
d) Any special tests necessary on the compiler or assembler |
| |
capabilities. |
| |
|
| |
ii) M4 macros to be shared by asm files in a CPU family are by |
| |
convention in a foo-defs.m4 like mpn/x86/x86-defs.m4. They're |
| |
likely to use settings from config.m4 generated by configure. |
| |
|
| |
|
| * The configure system |
* The configure system |
| |
|
| ** What we use |
** Installing tools |
| We use the tools in <ftp://ftp.swox.com/pub/gmp/infrastructure/>. |
|
| |
|
| ** How to install new versions of Autoconf / Automake / Libtool |
The current versions of automake, autoconf and libtool in use can be |
| |
checked in the ChangeLog. Look for "Update to ...". Patches may have |
| |
been applied, look for "Regenerate ...". |
| |
|
| *** Build Libtool |
The GMP build system is in places somewhat dependent on the internals |
| With a fresh CVS checkout, run the bootstrap script with released |
of the build tools. Obviously that's avoided as much as possible, but |
| versions (not CVS versions) of Autoconf and Automake in PATH. |
where it can't it creates a problem when upgrading or attempting to |
| |
use different tools versions. |
| |
|
| *** Update gmp directory |
** Updating gmp |
| gmp$ rm ltconfig ltmain.sh |
|
| gmp$ libtoolize --copy |
|
| gmp$ automake --add-missing --copy |
|
| |
|
| |
The following files need to be updated when going to a new version of |
| |
the build tools. Unfortunately the tools generally don't identify |
| |
when an out-of-date version is present. |
| |
|
| |
aclocal.m4 is updated by running "aclocal -I mpfr". |
| |
|
| |
INSTALL.autoconf can be copied from INSTALL in autoconf. |
| |
|
| |
ltmain.sh comes from libtool. Remove it and run "libtoolize --copy", |
| |
or just copy the file by hand. |
| |
|
| |
ansi2knr.c, ansi2knr.1, install.sh, mdate-sh and mkinstalldirs come |
| |
from automake and can be updated by copying or by removing and running |
| |
"automake --add-missing --copy". |
| |
|
| |
texinfo.tex can be updated from ftp.gnu.org. Check it still works |
| |
with "make gmp.dvi" and "texi2pdf gmp.texi". |
| |
|
| |
configfsf.guess and configfsf.sub can be updated from ftp.gnu.org (or |
| |
from the "config" cvs module at subversions.gnu.org). The gmp |
| |
config.guess and config.sub wrappers are supposed to make such an |
| |
update fairly painless. |
| |
|
| |
depcomp from automake is not needed because all Makefile.am files |
| |
specify "no-dependencies". |
| |
|
| ** How it works |
** How it works |
| |
|
| During development: |
During development: |
| |
|
| Input files Tool Output files |
Input files Tool Output files |
| ------------------------------------------ |
------------------------------------------ |
| aclocal |
aclocal |
| acinclude.m4 --------------> aclocal.m4 |
acinclude.m4 --------------> aclocal.m4 |
| |
|
| autoconf |
autoconf |
| configure.in \ -------------> configure |
configure.in \ -------------> configure |
| aclocal.m4 / |
aclocal.m4 / |
| |
|
| automake |
automake |
| Makefile.am \ -------------> Makefile.in |
Makefile.am \ -------------> Makefile.in |
| configure.in / |
configure.in / |
| |
|
| autoheader |
autoheader |
| configure.in \ -------------> config.in |
configure.in \ -------------> config.in |
| |
aclocal.m4 | |
| acconfig.h / |
acconfig.h / |
| |
|
| |
When configured with --enable-maintainer-mode the necessary tools are |
| |
re-run on changing the input files. This can end up running a lot |
| |
more things than are really necessary, but that's too bad. |
| |
|
| At build time: |
At build time: |
| |
|
| Input files Tool Output files |
Input files Tool Output files |
| ------------------------------------------ |
------------------------------------------ |
| |
|
| configure |
|
| Makefile.in \ -------------> / Makefile |
|
| config.in / | config.h |
|
| \ config.m4 |
|
| |
|
| |
Makefile.in \ configure / Makefile |
| |
config.in | -------------> | config.h |
| |
gmp-h.in | | config.m4 |
| |
mp-h.in / | gmp.h |
| |
\ mp.h |
| |
|
| |
** C++ configuration |
| |
|
| |
It's intended that the contents of libgmp.la won't vary according to |
| |
whether --enable-cxx is selected. This means that if C++ shared |
| |
libraries don't work properly then a shared+static with --disable-cxx |
| |
can be done for the C parts, then a static-only with --enable-cxx to |
| |
get libgmpxx. |
| |
|
| |
libgmpxx.la uses some internals from libgmp.la, in order to share code |
| |
between C and C++. It's intended that libgmpxx can only be expected |
| |
to work with libgmp from the same version of GMP. If some of the |
| |
shared internals change their interface, then it's proposed to rename |
| |
them, for instance __gmp_doprint2 or the like, so as to provoke link |
| |
errors rather than mysterious failures from a mismatch. |
| |
|
| |
* Development setups |
| |
|
| |
** General |
| |
|
| |
--disable-shared will make builds go much faster, though of course |
| |
shared or shared+static should be tested too. |
| |
|
| |
--enable-mpbsd grabs various bits of mpz, which might need to be |
| |
adjusted if things in those routines are changed. Building mpbsd all |
| |
the time doesn't cost much. |
| |
|
| |
--prefix to a dummy directory followed by "make install" will show |
| |
what's installed. |
| |
|
| |
"make check" acts on the libgmp just built, and will ignore any other |
| |
/usr/lib/libgmp, or at least it should do. Libtool does various hairy |
| |
things to ensure it hits the just-built library. |
| |
|
| |
** Debugging |
| |
|
| |
A build with maximum debugging can be made with |
| |
|
| |
./configure --host=none --enable-assert --enable-alloca=debug |
| |
|
| |
Malloc memory leaks are always checked by the test programs. With |
| |
alloca=debug any TMP_ALLOC leaks will be detected too. |
| |
--enable-alloca=malloc-reentrant also has this effect. |
| |
|
| |
** Long long limb testing |
| |
|
| |
On systems where gcc supports long long, but a limb is normally just a |
| |
long, the following can be used to force long long for testing |
| |
purposes. It will probably run quite slowly. |
| |
|
| |
./configure --host=none ABI=longlong |
| |
|
| |
** Function argument conversions |
| |
|
| |
When using gcc, configuring with something like |
| |
|
| |
./configure CFLAGS="-g -Wall -Wconversion -Wno-sign-compare" |
| |
|
| |
can show where function parameters are being converted due to having |
| |
function prototypes available, which won't happen in a K&R compiler. |
| |
Doing this in combination with the long long limb setups above is |
| |
good. |
| |
|
| |
Conversions between int and long aren't warned about by gcc when |
| |
they're the same size, which is unfortunate because casts should be |
| |
used in such cases, for the benefit of K&R compilers with int!=long |
| |
and where the difference matters in function calls. |
| |
|
| |
** K&R support |
| |
|
| |
Function definitions must be in the GNU stylized form to work. See |
| |
the ansi2knr.1 man page. |
| |
|
| |
__GMP_PROTO is used for function prototypes, other ANSI / K&R |
| |
differences are conditionalized in various places. |
| |
|
| |
Proper testing of the K&R support requires a compiler which gives an |
| |
error for ANSI-isms. Configuring with --host=none is a good idea, to |
| |
test all the generic C code. |
| |
|
| |
When using an ANSI compiler, the ansi2knr setups can be partially |
| |
tested with |
| |
|
| |
./configure am_cv_prog_cc_stdc=no |
| |
|
| |
This will test the use of $U and the like in the makefiles, but not |
| |
much else. |
| |
|
| |
am_cv_prog_cc_stdc=no can be used with a compiler like HP C which is |
| |
K&R by default but to which configure normally adds ANSI mode flags. |
| |
This then should be a good full K&R test. |
| |
|
| |
|
| |
|
| |
Local variables: |
| |
mode: outline |
| |
fill-column: 70 |
| |
End: |
| /* eof doc/configuration */ |
/* eof doc/configuration */ |
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to configuration CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gmp / doc