doc/configuration

   1 /* doc/configuration (in Emacs -*-outline-*- format). */
   2
   3 Copyright 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
   4
   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 3 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.  If not, see http://www.gnu.org/licenses/.
  19
  20
  21
  22 * Adding a new file
  23
  24 ** Adding a top-level file
  25
  26   i) Add it to libgmp_la_SOURCES in Makefile.am.
  27
  28   ii) If libmp.la needs it (usually doesn't), then add it to
  29       libmp_la_SOURCES too.
  30
  31 ** Adding a subdirectory file
  32
  33 For instance for mpz,
  34
  35   i) Add file.c to libmpz_la_SOURCES in mpz/Makefile.am.
  36
  37   ii) Add mpz/file$U.lo to MPZ_OBJECTS in the top-level Makefile.am
  38
  39   iii) If for some reason libmp.la needs it (usually doesn't) then add
  40        mpz/file$U.lo to libmp_la_DEPENDENCIES in the top-level
  41        Makefile.am too.
  42
  43 The same applies to mpf, mpq, scanf and printf.
  44
  45 ** Adding an mpn file
  46
  47 The way we build libmpn (in the `mpn' subdirectory) is quite special.
  48
  49 Currently only mpn/mp_bases.c is truely generic and included in every
  50 configuration.  All other files are linked at build time into the mpn
  51 build directory from one of the CPU specific sub-directories, or from
  52 the mpn/generic directory.
  53
  54 There are four types of mpn source files.
  55
  56   .asm    Assembly code preprocessed with m4
  57   .S      Assembly code preprocessed with cpp
  58   .s      Assembly code not preprocessed at all
  59   .c      C code
  60
  61 There are two types of .asm files.
  62
  63   i) ``Normal'' files containing one function, though possibly with
  64      more than one entry point.
  65
  66   ii) Multi-function files that generate one of a set of functions
  67       according to build options.
  68
  69 To add a new implementation of an existing function,
  70
  71   i) Put it in the appropriate CPU-specific mpn subdirectory, it'll be
  72      detected and used.
  73
  74   ii) Any entrypoints tested by HAVE_NATIVE_func in other code must
  75       have PROLOGUE(func) for configure to grep.  This is normal for
  76       .asm or .S files, but for .c files a dummy comment like the
  77       following will be needed.
  78
  79               /*
  80               PROLOGUE(func)
  81               */
  82
  83 To add a new implementation using a multi-function file, in addition
  84 do the following,
  85
  86   i) Use a MULFUNC_PROLOGUE(func1 func2 ...) in the .asm, declaring
  87      all the functions implemented, including carry-in variants.
  88
  89      If there's a separate PROLOGUE(func) for each possible function
  90      (but this is usually not the case), then MULFUNC_PROLOGUE isn't
  91      necessary.
  92
  93 To add a new style of multi-function file, in addition do the
  94 following,
  95
  96   i) Add to the GMP_MULFUNC_CHOICES "case" statement in configure.in
  97      which lists each multi-function filename and what function files
  98      it can provide.
  99
 100 To add a completely new mpn function file, do the following,
 101
 102   i) Ensure the filename is a valid C identifier, due to the
 103      -DOPERATION_$* used to support multi-function files.  This means
 104      "-" can't be used (but "_" can).
 105
 106   ii) Add it to configure.in under one of the following
 107
 108       a) `gmp_mpn_functions' if it exists for every target.  This
 109          means there must be a C version in mpn/generic.  (Eg. mul_1)
 110
 111       b) `gmp_mpn_functions_optional' if it's a standard function, but
 112          doesn't need to exist for every target.  Code wanting to use
 113          this will test HAVE_NATIVE_func to see if it's available.
 114          (Eg. copyi)
 115
 116       c) `extra_functions' for some targets, if it's a special
 117          function that only ever needs to exist for certain targets.
 118          Code wanting to use it can test either HAVE_NATIVE_func or
 119          HAVE_HOST_CPU_foo, as desired.
 120
 121   iii) If HAVE_NATIVE_func is going to be used, then add a #undef to
 122        the AH_VERBATIM([HAVE_NATIVE] block in configure.in.
 123
 124   iv) Add file.c to nodist_libdummy_la_SOURCES in mpn/Makefile.am (in
 125       order to get an ansi2knr rule).  If the file is only in
 126       assembler then this step is unnecessary, but do it anyway so as
 127       not to forget if later a .c version is added.
 128
 129   v) If the function can be provided by a multi-function file, then
 130      add to the "case" statement in configure.in which lists each
 131      multi-function filename and what function files it can provide.
 132
 133
 134 ** Adding a test program
 135
 136   i) Tests to be run early in the testing can be added to the main
 137      "tests" sub-directory.
 138
 139   ii) Tests for mpn, mpz, mpq and mpf can be added under the
 140       corresponding tests subdirectory.
 141
 142   iii) Generic tests for late in the testing can be added to
 143        "tests/misc".  printf and scanf tests currently live there too.
 144
 145   iv) Random number function tests can be added to "tests/rand".  That
 146       directory has some development-time programs too.
 147
 148   v) C++ test programs can be added to "tests/cxx".  A line like the
 149      following must be added for each, since by default automake looks
 150      for a .c file.
 151
 152              t_foo_SOURCES = t-foo.cc
 153
 154 In all cases the name of the program should be added to check_PROGRAMS
 155 in the Makefile.am.  TESTS is equal to check_PROGRAMS, so all those
 156 programs get run.
 157
 158 "tests/devel" has a number of programs which are only for development
 159 purposes and are not for use in "make check".  These should be listed
 160 in EXTRA_PROGRAMS to get Makefile rules created, but they're never
 161 built or run unless an explicit "make someprog" is used.
 162
 163
 164 * Adding a new CPU
 165
 166 In general it's policy to use proper names for each CPU type
 167 supported.  If two CPUs are quite similar and perhaps don't have any
 168 actual differences in GMP then they're still given separate names, for
 169 example alphaev67 and alphaev68.
 170
 171 Canonical names:
 172
 173   i) Decide the canonical CPU names GMP will accept.
 174
 175   ii) Add these to the config.sub wrapper if configfsf.sub doesn't
 176       already accept them.
 177
 178   iii) Document the names in gmp.texi.
 179
 180 Aliases (optional):
 181
 182   i) Any aliases can be added to the config.sub wrapper, unless
 183      configfsf.sub already does the right thing with them.
 184
 185   ii) Leave configure.in and everywhere else using only the canonical
 186       names.  Aliases shouldn't appear anywhere except config.sub.
 187
 188   iii) Document in gmp.texi, if desired.  Usually this isn't a good
 189        idea, better encourage users to know just the canonical
 190        names.
 191
 192 Configure:
 193
 194   i) Add patterns to configure.in for the new CPU names.  Include the
 195      following (see configure.in for the variables to set up),
 196
 197      a) ABI choices (if any).
 198      b) Compiler choices.
 199      c) mpn path for CPU specific code.
 200      d) Good default CFLAGS for each likely compiler.
 201      d) Any special tests necessary on the compiler or assembler
 202         capabilities.
 203
 204   ii) M4 macros to be shared by asm files in a CPU family are by
 205       convention in a foo-defs.m4 like mpn/x86/x86-defs.m4.  They're
 206       likely to use settings from config.m4 generated by configure.
 207
 208 Fat binaries:
 209
 210   i) In configure.in, add CPU specific directory(s) to fat_path.
 211
 212   ii) In mpn/<cpu>/fat.c, identify the CPU at runtime and use suitable
 213       CPUVEC_SETUP_subdir macros to select the function pointers for it.
 214
 215   iii) For the x86s, add to the "$tmp_prefix" setups in configure.in
 216        which abbreviates subdirectory names to fit an 8.3 filesystem.
 217        (No need to restrict to 8.3, just ensure uniqueness when
 218        truncated.)
 219
 220
 221 * The configure system
 222
 223 ** Installing tools
 224
 225 The current versions of automake, autoconf and libtool in use can be
 226 checked in the ChangeLog.  Look for "Update to ...".  Patches may have
 227 been applied, look for "Regenerate ...".
 228
 229 The GMP build system is in places somewhat dependent on the internals
 230 of the build tools.  Obviously that's avoided as much as possible, but
 231 where it can't it creates a problem when upgrading or attempting to
 232 use different tools versions.
 233
 234 ** Updating gmp
 235
 236 The following files need to be updated when going to a new version of
 237 the build tools.  Unfortunately the tools generally don't identify
 238 when an out-of-date version is present.
 239
 240 aclocal.m4 is updated by running "aclocal".  (Only needed for a new
 241 automake or libtool.)
 242
 243 INSTALL.autoconf can be copied from INSTALL in autoconf.
 244
 245 ltmain.sh comes from libtool.  Remove it and run "libtoolize --copy",
 246 or just copy the file by hand.
 247
 248 ansi2knr.c, ansi2knr.1, install-sh and doc/mdate-sh come from automake
 249 and can be updated by copying or by removing and running "automake
 250 --add-missing --copy".
 251
 252 texinfo.tex can be updated from ftp.gnu.org.  Check it still works
 253 with "make gmp.dvi", "make gmp.ps" and "make gmp.pdf".
 254
 255 configfsf.guess and configfsf.sub can be updated from ftp.gnu.org (or
 256 from the "config" cvs module at subversions.gnu.org).  The gmp
 257 config.guess and config.sub wrappers are supposed to make such an
 258 update fairly painless.
 259
 260 depcomp from automake is not needed because configure.in specifies
 261 automake with "no-dependencies".
 262
 263 ** How it works
 264
 265 During development:
 266
 267     Input files                       Tool       Output files
 268     ---------------------------------------------------------
 269
 270                                      aclocal
 271     $prefix/share/aclocal*/*.m4 ----------------> aclocal.m4
 272
 273
 274     configure.in \                   autoconf
 275     aclocal.m4   / -----------------------------> configure
 276
 277
 278     */Makefile.am \                  automake
 279     configure.in  | ----------------------------> Makefile.in
 280     aclocal.m4    /
 281
 282     configure.in \                  autoheader
 283     aclocal.m4   / -----------------------------> config.in
 284
 285 At build time:
 286
 287     Input files          Tool       Output files
 288     --------------------------------------------
 289
 290     */Makefile.in  \   configure    / */Makefile
 291     config.in      | -------------> | config.h
 292     gmp-h.in       |                | config.m4
 293     mp-h.in        /                | gmp.h
 294                                     | mp.h
 295                                     \ fat.h  (fat binary build only)
 296
 297 When configured with --enable-maintainer-mode the Makefiles include
 298 rules to re-run the necessary tools if the input files are changed.
 299 This can end up running a lot more things than are really necessary.
 300
 301 If a build tree is in too much of a mess for those rules to work
 302 properly then a bootstrap can be done from the source directory with
 303
 304         aclocal
 305         autoconf
 306         automake
 307         autoheader
 308
 309 The autom4te.cache directory is created by autoconf to save some work
 310 in subsequent automake or autoheader runs.  It's recreated
 311 automatically if removed, it doesn't get distributed.
 312
 313 ** C++ configuration
 314
 315 It's intended that the contents of libgmp.la won't vary according to
 316 whether --enable-cxx is selected.  This means that if C++ shared
 317 libraries don't work properly then a shared+static with --disable-cxx
 318 can be done for the C parts, then a static-only with --enable-cxx to
 319 get libgmpxx.
 320
 321 libgmpxx.la uses some internals from libgmp.la, in order to share code
 322 between C and C++.  It's intended that libgmpxx can only be expected
 323 to work with libgmp from the same version of GMP.  If some of the
 324 shared internals change their interface, then it's proposed to rename
 325 them, for instance __gmp_doprint2 or the like, so as to provoke link
 326 errors rather than mysterious failures from a mismatch.
 327
 328 * Development setups
 329
 330 ** General
 331
 332 --disable-shared will make builds go much faster, though of course
 333 shared or shared+static should be tested too.
 334
 335 --enable-mpbsd grabs various bits of mpz, which might need to be
 336 adjusted if things in those routines are changed.  Building mpbsd all
 337 the time doesn't cost much.
 338
 339 --prefix to a dummy directory followed by "make install" will show
 340 what's installed.
 341
 342 "make check" acts on the libgmp just built, and will ignore any other
 343 /usr/lib/libgmp, or at least it should do.  Libtool does various hairy
 344 things to ensure it hits the just-built library.
 345
 346 ** Long long limb testing
 347
 348 On systems where gcc supports long long, but a limb is normally just a
 349 long, the following can be used to force long long for testing
 350 purposes.  It will probably run quite slowly.
 351
 352         ./configure --host=none ABI=longlong
 353
 354 ** Function argument conversions
 355
 356 When using gcc, configuring with something like
 357
 358         ./configure CFLAGS="-g -Wall -Wconversion -Wno-sign-compare"
 359
 360 can show where function parameters are being converted due to having
 361 function prototypes available, which won't happen in a K&R compiler.
 362 Doing this in combination with the long long limb setups above is
 363 good.
 364
 365 Conversions between int and long aren't warned about by gcc when
 366 they're the same size, which is unfortunate because casts should be
 367 used in such cases, for the benefit of K&R compilers with int!=long
 368 and where the difference matters in function calls.
 369
 370 ** K&R support
 371
 372 Function definitions must be in the GNU stylized form to work.  See
 373 the ansi2knr.1 man page (included in the GMP sources).
 374
 375 __GMP_PROTO is used for function prototypes, other ANSI / K&R
 376 differences are conditionalized in various places.
 377
 378 Proper testing of the K&R support requires a compiler which gives an
 379 error for ANSI-isms.  Configuring with --host=none is a good idea, to
 380 test all the generic C code.
 381
 382 When using an ANSI compiler, the ansi2knr setups can be partially
 383 tested with
 384
 385         ./configure am_cv_prog_cc_stdc=no ac_cv_prog_cc_stdc=no
 386
 387 This will test the use of $U and the like in the makefiles, but not
 388 much else.
 389
 390 Forcing the cache variables can be used with a compiler like HP C
 391 which is K&R by default but to which configure normally adds ANSI mode
 392 flags.  This then should be a good full K&R test.
 393
 394 * Other Notes
 395
 396 ** Compatibility
 397
 398 compat.c is the home of functions retained for binary compatibility,
 399     but now done by other means (like a macro).
 400
 401 struct __mpz_struct etc - this must be retained for C++ compatibility.
 402     C++ applications defining functions taking mpz_t etc parameters
 403     will get this in the mangled name because C++ "sees though" the
 404     typedef mpz_t to the underlying struct.
 405
 406     Incidentally, this probably means for C++ that our mp.h is not
 407     compatible with an original BSD mp.h, since we use struct
 408     __mpz_struct for MINT in ours.  Maybe we could change to whatever
 409     the original did, but it seems unlikely anyone would be using C++
 410     with mp.h.
 411
 412 __gmpn - note that glibc defines some __mpn symbols, old versions of
 413     some mpn routines, which it uses for floating point printfs.
 414
 415
 416
 417
 418 Local variables:
 419 mode: outline
 420 fill-column: 70
 421 End:
 422 /* eof doc/configuration */