/* doc/configuration (in Emacs -*-outline-*- format). */ Copyright 2000, 2001 Free Software Foundation, Inc. This file is part of the GNU MP Library. 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. The GNU MP Library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with the GNU MP Library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * Adding a new file ** 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. .asm Assembly code preprocessed with m4 .S Assembly code preprocessed with CPP .s Assembly code not preprocessed at all .c C code There are two types of .asm files. i) ``Normal'' files containing one function, possibly with more than one entry point. ii) Multi-function files that generate one of a set of functions according to build options. When adding a new implementation of an existing function, i) Put it in the appropriate mpn subdirectory. It'll be detected and used. 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 HAVE_NATIVE_func defines in config.h. When adding a new implementation using a multi-function file, in addition do the following, i) Use a MULFUNC_PROLOGUE(func1 func2 ...) in the .asm, declaring all the functions implemented, including carry-in variants. If there's a separate PROLOGUE(func) for each possible function, then MULFUNC_PROLOGUE isn't necessary (but this is usually not the case). When adding a new style of multi-function file, in addition do the following, i) Add to the "case" statement in configure.in which lists each multi-function filename and what function files it can provide. When adding a completely new mpn function file, do 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). ii) Add it to configure.in under one of the following a) `gmp_mpn_functions' if it exists for every target. This means there must be a C version in mpn/generic. (Eg. add_n) b) `gmp_mpn_functions_optional' if it's a standard function, but doesn't need to exist for every target. Code wanting to use 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 that only ever needs to exist for certain targets. Code wanting to use it will generally test the target, but HAVE_NATIVE_func can be used if desired. iii) If you want `HAVE_NATIVE_func' defined in config.h, add `#undef HAVE_NATIVE_func' to acconfig.h. iv) If it might be implemented in C, either sometimes or always, add it to nodist_libdummy_la_SOURCES in mpn/Makefile.am (to get an ansi2knr rule). v) If the function can be provided by a multi-function file, then follow the directions above for that too. ** Adding a non-mpn file When adding a top-level file, i) Add it to libgmp_la_SOURCES in Makefile.am. ii) If libmp.la needs it, then add it to libmp_la_SOURCES too. When adding an mpz file, 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). ii) Add file.c to libmpz_la_SOURCES in mpz/Makefile.am. If a multi-function mpz file is being added, i) In mpz/Makefile.am, a) Add the file to EXTRA_DIST. b) Add rules copying the file at build time to appropriate names. c) Add each such func.c to nodist_libmpz_la_SOURCES. ii) In the multi-function file, expect a preprocessor symbol OPERATION_func to indicate what form is being compiled. The same applies to mpq, mpf, mpbsd and mpfr. See mpz/mul_siui.c or mpf/integer.c for example multi-function files. ** Adding a test program Generic test programs, or tests for things in the top-level directory can be added in the "tests" sub-directory. A "tests/rand" exists for tests on the random number functions in the top-level directory. Tests related to mpz functions can be added to the tests/mpz directory. Similarly for mpq, mpf and mpbsd. In any case the name of the program should be added to check_PROGRAMS in the respective Makefile.am. TESTS is equal to check_PROGRAMS so each of these is run. 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 some-program" is used. ** Macos directory The macos/configure script will automatically pick up additions to gmp_mpn_functions, MPZ_OBJECTS, etc, but test programs and multi-function files need to be added to Makefile.in manually. Take care when modifying configure.in that it doesn't upset the macos/configure script. * Adding a new CPU Canonical names: i) Decide the canonical CPU names GMP will accept. ii) Add these to the config.sub wrapper if configfsf.sub doesn't already accept them. iii) Document the names in gmp.texi Aliases (optional): 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) 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 provided by configure. * The configure system ** Installing tools The current versions of automake, autoconf and libtool in use can be checked in the ChangeLog. Look for "Update to ...". Libtool 1.4.1 will want the following patch to libtool.m4, for the benefit of DLLs on old cygwin and mingw systems. --- libtool.m4.old Thu Sep 6 15:45:43 2001 +++ libtool.m4 Thu Sep 6 15:45:58 2001 @@ -1303,7 +1303,7 @@ # can override, but on older systems we have to supply one (in ltdll.c) if test "x$lt_cv_need_dllmain" = "xyes"; then ltdll_obj='$output_objdir/$soname-ltdll.'"$ac_objext " - ltdll_cmds='test -f $output_objdir/$soname-ltdll.c || sed -e "/^# \/\* ltdll\.c starts here \*\//,/^# \/\* ltdll.c ends here \*\// { s/^# //; p; }" -e d < [$]0 > $output_objdir/$soname-ltdll.c~ + ltdll_cmds='test -f $output_objdir/$soname-ltdll.c || sed -e "/^# \/\* ltdll\.c starts here \*\//,/^# \/\* ltdll.c ends here \*\// { s/^# //; p; }" -e d < $''0 > $output_objdir/$soname-ltdll.c~ test -f $output_objdir/$soname-ltdll.$ac_objext || (cd $output_objdir && $CC -c $soname-ltdll.c)~' else ltdll_obj= ** Updating gmp The GMP configure is a bit involved, but it ought to be reasonably easy to update to newer versions of the tools. aclocal.m4 is updated by running "aclocal" in the usual way. 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 During development: Input files Tool Output files ------------------------------------------ aclocal acinclude.m4 --------------> aclocal.m4 autoconf configure.in \ -------------> configure aclocal.m4 / automake Makefile.am \ -------------> Makefile.in configure.in / autoheader configure.in \ -------------> config.in aclocal.m4 | 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: Input files Tool Output files ------------------------------------------ Makefile.in \ configure / Makefile config.in | -------------> | config.h gmp-h.in | | config.m4 mp-h.in / | gmp.h \ mp.h * Development setups ** General --disable-shared will make builds go much faster, though testing shared or shared+static build should be done on occasion. Combinations of --enable-mpbsd, --enable-fft and --enable-mpfr are worth doing. The --enable-mpbsd in particular it a touch hairy and worth trying enabled and disabled (the latter being the default). gcc 2.7.2.3 for i386 has reloader bugs perhaps related to asm block handling, which are worked around in various places. Checking that no new ones have been hit is worthwhile. In all cases a "make install" is good to see that the right things are copied to the right places. The usual --prefix should be used into a clean test tree to look at this. ** 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. It will probably run very slowly. ./configure --host=none ABI=longlong ** Function argument conversions When using gcc, configuring with something like ./configure CFLAGS="-g -Wall -Wconversion" can show where function parameters are being converted due to having function prototypes available. The warnings about signed/unsigned mismatches are pointless and annoying, but attention should be paid to any size conversions due to prototypes, since these won't occur under 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 those (perhaps rare) systems where int!=long under a K&R compiler and where the difference matters in function calls. * K&R support K&R compilers are still supported, via automake ansi2knr. Function definitions must be in a stylized form for this to work (see the ansi2knr.1 man page). _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 */