Annotation of OpenXM_contrib/gmp/doc/configuration, Revision 1.1.1.2
1.1 maekawa 1: /* doc/configuration (in Emacs -*-outline-*- format). */
2:
1.1.1.2 ! ohara 3: Copyright 2000, 2001, 2002 Free Software Foundation, Inc.
1.1 maekawa 4:
1.1.1.2 ! ohara 5: This file is part of the GNU MP Library.
! 6:
! 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.
! 11:
! 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.
! 16:
! 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
! 20: 02111-1307, USA.
! 21:
! 22:
! 23:
! 24: * Adding a new file
! 25:
! 26: ** Adding a top-level file
! 27:
! 28: i) Add it to libgmp_la_SOURCES in Makefile.am.
! 29:
! 30: ii) If libmp.la needs it (usually doesn't), then add it to
! 31: libmp_la_SOURCES too.
! 32:
! 33: ** Adding a subdirectory file
! 34:
! 35: For instance for mpz,
! 36:
! 37: i) Add file.c to libmpz_la_SOURCES in mpz/Makefile.am.
! 38:
! 39: ii) Add mpz/file$U.lo to MPZ_OBJECTS in the top-level Makefile.am
! 40:
! 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
! 43: Makefile.am too.
! 44:
! 45: The same applies to mpf, mpq, scanf and printf.
! 46:
! 47: ** Adding an mpn file
1.1 maekawa 48:
49: The way we build libmpn (in the `mpn' subdirectory) is quite special.
50:
1.1.1.2 ! ohara 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.
1.1 maekawa 55:
56: There are four types of mpn source files.
57:
58: .asm Assembly code preprocessed with m4
1.1.1.2 ! ohara 59: .S Assembly code preprocessed with cpp
1.1 maekawa 60: .s Assembly code not preprocessed at all
61: .c C code
62:
63: There are two types of .asm files.
64:
1.1.1.2 ! ohara 65: i) ``Normal'' files containing one function, though possibly with
! 66: more than one entry point.
1.1 maekawa 67:
68: ii) Multi-function files that generate one of a set of functions
69: according to build options.
70:
1.1.1.2 ! ohara 71: To add a new implementation of an existing function,
1.1 maekawa 72:
1.1.1.2 ! ohara 73: i) Put it in the appropriate CPU-specific mpn subdirectory, it'll be
! 74: detected and used.
1.1 maekawa 75:
1.1.1.2 ! ohara 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.
! 80:
! 81: /*
! 82: PROLOGUE(func)
! 83: */
1.1 maekawa 84:
1.1.1.2 ! ohara 85: To add a new implementation using a multi-function file, in addition
! 86: do the following,
1.1 maekawa 87:
88: i) Use a MULFUNC_PROLOGUE(func1 func2 ...) in the .asm, declaring
89: all the functions implemented, including carry-in variants.
90:
91: If there's a separate PROLOGUE(func) for each possible function,
92: then MULFUNC_PROLOGUE isn't necessary (but this is usually not
93: the case).
94:
1.1.1.2 ! ohara 95: To add a new style of multi-function file, in addition do the
1.1 maekawa 96: following,
97:
98: i) Add to the "case" statement in configure.in which lists each
99: multi-function filename and what function files it can provide.
100:
1.1.1.2 ! ohara 101: To add a completely new mpn function file, do the following,
1.1 maekawa 102:
1.1.1.2 ! ohara 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).
! 106:
! 107: ii) Add it to configure.in under one of the following
! 108:
! 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)
! 111:
! 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.
! 115: (Eg. copyi)
! 116:
! 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.
! 121:
! 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.
! 125:
! 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.
1.1 maekawa 130:
1.1.1.2 ! ohara 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.
1.1 maekawa 134:
135:
1.1.1.2 ! ohara 136: ** Adding a test program
1.1 maekawa 137:
1.1.1.2 ! ohara 138: i) Tests to be run early in the testing can be added to the main
! 139: "tests" sub-directory.
1.1 maekawa 140:
1.1.1.2 ! ohara 141: ii) Tests for mpn, mpz, mpq and mpf can be added under the
! 142: corresponding tests subdirectory.
1.1 maekawa 143:
1.1.1.2 ! ohara 144: iii) Generic tests for late in the testing can be added to
! 145: "tests/misc". printf and scanf tests currently live there too.
1.1 maekawa 146:
1.1.1.2 ! ohara 147: iv) Random number function tests can be added to "tests/rand". That
! 148: directory has some development-time programs too.
1.1 maekawa 149:
1.1.1.2 ! ohara 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
! 152: for a .c file.
1.1 maekawa 153:
1.1.1.2 ! ohara 154: t_foo_SOURCES = t-foo.cc
1.1 maekawa 155:
1.1.1.2 ! ohara 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
! 158: programs get run.
1.1 maekawa 159:
1.1.1.2 ! ohara 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.
1.1 maekawa 164:
1.1.1.2 ! ohara 165: ** Macos directory
1.1 maekawa 166:
1.1.1.2 ! ohara 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.
1.1 maekawa 170:
1.1.1.2 ! ohara 171: When modifying the top-level configure.in ensure that it doesn't upset
! 172: the macos/configure script heuristics.
1.1 maekawa 173:
174:
1.1.1.2 ! ohara 175: * Adding a new CPU
1.1 maekawa 176:
1.1.1.2 ! ohara 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.
1.1 maekawa 181:
1.1.1.2 ! ohara 182: Canonical names:
1.1 maekawa 183:
1.1.1.2 ! ohara 184: i) Decide the canonical CPU names GMP will accept.
1.1 maekawa 185:
1.1.1.2 ! ohara 186: ii) Add these to the config.sub wrapper if configfsf.sub doesn't
! 187: already accept them.
1.1 maekawa 188:
1.1.1.2 ! ohara 189: iii) Document the names in gmp.texi.
1.1 maekawa 190:
1.1.1.2 ! ohara 191: Aliases (optional):
1.1 maekawa 192:
1.1.1.2 ! ohara 193: i) Any aliases can be added to the config.sub wrapper, unless
! 194: configfsf.sub already does the right thing with them.
1.1 maekawa 195:
1.1.1.2 ! ohara 196: ii) Leave configure.in and everywhere else using only the canonical
! 197: names. Aliases shouldn't appear anywhere except config.sub.
1.1 maekawa 198:
1.1.1.2 ! ohara 199: iii) Document in gmp.texi, if desired. Usually this isn't a good
! 200: idea, better encourage users to know just the canonical
! 201: names.
1.1 maekawa 202:
1.1.1.2 ! ohara 203: Configure:
1.1 maekawa 204:
1.1.1.2 ! ohara 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),
1.1 maekawa 207:
1.1.1.2 ! ohara 208: a) ABI choices (if any).
! 209: b) Compiler choices.
! 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
! 213: capabilities.
! 214:
! 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.
1.1 maekawa 218:
219:
220: * The configure system
221:
1.1.1.2 ! ohara 222: ** Installing tools
! 223:
! 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 ...".
! 227:
! 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.
! 232:
! 233: ** Updating gmp
1.1 maekawa 234:
1.1.1.2 ! ohara 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.
1.1 maekawa 238:
1.1.1.2 ! ohara 239: aclocal.m4 is updated by running "aclocal -I mpfr".
! 240:
! 241: INSTALL.autoconf can be copied from INSTALL in autoconf.
! 242:
! 243: ltmain.sh comes from libtool. Remove it and run "libtoolize --copy",
! 244: or just copy the file by hand.
! 245:
! 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".
! 249:
! 250: texinfo.tex can be updated from ftp.gnu.org. Check it still works
! 251: with "make gmp.dvi" and "texi2pdf gmp.texi".
! 252:
! 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.
! 257:
! 258: depcomp from automake is not needed because all Makefile.am files
! 259: specify "no-dependencies".
1.1 maekawa 260:
261: ** How it works
1.1.1.2 ! ohara 262:
1.1 maekawa 263: During development:
264:
265: Input files Tool Output files
266: ------------------------------------------
267: aclocal
268: acinclude.m4 --------------> aclocal.m4
1.1.1.2 ! ohara 269:
1.1 maekawa 270: autoconf
271: configure.in \ -------------> configure
272: aclocal.m4 /
1.1.1.2 ! ohara 273:
1.1 maekawa 274: automake
275: Makefile.am \ -------------> Makefile.in
1.1.1.2 ! ohara 276: configure.in /
! 277:
1.1 maekawa 278: autoheader
279: configure.in \ -------------> config.in
1.1.1.2 ! ohara 280: aclocal.m4 |
1.1 maekawa 281: acconfig.h /
282:
1.1.1.2 ! ohara 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.
1.1 maekawa 286:
287: At build time:
288:
289: Input files Tool Output files
290: ------------------------------------------
291:
1.1.1.2 ! ohara 292: Makefile.in \ configure / Makefile
! 293: config.in | -------------> | config.h
! 294: gmp-h.in | | config.m4
! 295: mp-h.in / | gmp.h
! 296: \ mp.h
! 297:
! 298: ** C++ configuration
! 299:
! 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
! 304: get libgmpxx.
! 305:
! 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.
! 312:
! 313: * Development setups
! 314:
! 315: ** General
! 316:
! 317: --disable-shared will make builds go much faster, though of course
! 318: shared or shared+static should be tested too.
! 319:
! 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.
! 323:
! 324: --prefix to a dummy directory followed by "make install" will show
! 325: what's installed.
! 326:
! 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.
! 330:
! 331: ** Debugging
! 332:
! 333: A build with maximum debugging can be made with
! 334:
! 335: ./configure --host=none --enable-assert --enable-alloca=debug
! 336:
! 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.
! 340:
! 341: ** Long long limb testing
! 342:
! 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.
! 346:
! 347: ./configure --host=none ABI=longlong
! 348:
! 349: ** Function argument conversions
! 350:
! 351: When using gcc, configuring with something like
! 352:
! 353: ./configure CFLAGS="-g -Wall -Wconversion -Wno-sign-compare"
! 354:
! 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
! 358: good.
! 359:
! 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.
! 364:
! 365: ** K&R support
! 366:
! 367: Function definitions must be in the GNU stylized form to work. See
! 368: the ansi2knr.1 man page.
! 369:
! 370: __GMP_PROTO is used for function prototypes, other ANSI / K&R
! 371: differences are conditionalized in various places.
! 372:
! 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.
! 376:
! 377: When using an ANSI compiler, the ansi2knr setups can be partially
! 378: tested with
! 379:
! 380: ./configure am_cv_prog_cc_stdc=no
! 381:
! 382: This will test the use of $U and the like in the makefiles, but not
! 383: much else.
! 384:
! 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.
! 388:
! 389:
! 390:
! 391: Local variables:
! 392: mode: outline
! 393: fill-column: 70
! 394: End:
1.1 maekawa 395: /* eof doc/configuration */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[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