1/* doc/configuration (in Emacs -*-outline-*- format). */ 2 3Copyright 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. 4 5This file is part of the GNU MP Library. 6 7The GNU MP Library is free software; you can redistribute it and/or modify 8it under the terms of the GNU Lesser General Public License as published by 9the Free Software Foundation; either version 3 of the License, or (at your 10option) any later version. 11 12The GNU MP Library is distributed in the hope that it will be useful, but 13WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 14or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 15License for more details. 16 17You should have received a copy of the GNU Lesser General Public License 18along 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 33For 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 43The same applies to mpf, mpq, scanf and printf. 44 45** Adding an mpn file 46 47The way we build libmpn (in the `mpn' subdirectory) is quite special. 48 49Currently only mpn/mp_bases.c is truely generic and included in every 50configuration. All other files are linked at build time into the mpn 51build directory from one of the CPU specific sub-directories, or from 52the mpn/generic directory. 53 54There 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 61There 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 69To 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 83To add a new implementation using a multi-function file, in addition 84do 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 93To add a new style of multi-function file, in addition do the 94following, 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 100To 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 154In all cases the name of the program should be added to check_PROGRAMS 155in the Makefile.am. TESTS is equal to check_PROGRAMS, so all those 156programs get run. 157 158"tests/devel" has a number of programs which are only for development 159purposes and are not for use in "make check". These should be listed 160in EXTRA_PROGRAMS to get Makefile rules created, but they're never 161built or run unless an explicit "make someprog" is used. 162 163 164* Adding a new CPU 165 166In general it's policy to use proper names for each CPU type 167supported. If two CPUs are quite similar and perhaps don't have any 168actual differences in GMP then they're still given separate names, for 169example alphaev67 and alphaev68. 170 171Canonical 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 180Aliases (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 192Configure: 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 208Fat 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 225The current versions of automake, autoconf and libtool in use can be 226checked in the ChangeLog. Look for "Update to ...". Patches may have 227been applied, look for "Regenerate ...". 228 229The GMP build system is in places somewhat dependent on the internals 230of the build tools. Obviously that's avoided as much as possible, but 231where it can't it creates a problem when upgrading or attempting to 232use different tools versions. 233 234** Updating gmp 235 236The following files need to be updated when going to a new version of 237the build tools. Unfortunately the tools generally don't identify 238when an out-of-date version is present. 239 240aclocal.m4 is updated by running "aclocal". (Only needed for a new 241automake or libtool.) 242 243INSTALL.autoconf can be copied from INSTALL in autoconf. 244 245ltmain.sh comes from libtool. Remove it and run "libtoolize --copy", 246or just copy the file by hand. 247 248ansi2knr.c, ansi2knr.1, install-sh and doc/mdate-sh come from automake 249and can be updated by copying or by removing and running "automake 250--add-missing --copy". 251 252texinfo.tex can be updated from ftp.gnu.org. Check it still works 253with "make gmp.dvi", "make gmp.ps" and "make gmp.pdf". 254 255configfsf.guess and configfsf.sub can be updated from ftp.gnu.org (or 256from the "config" cvs module at subversions.gnu.org). The gmp 257config.guess and config.sub wrappers are supposed to make such an 258update fairly painless. 259 260depcomp from automake is not needed because configure.in specifies 261automake with "no-dependencies". 262 263** How it works 264 265During 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 285At 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 297When configured with --enable-maintainer-mode the Makefiles include 298rules to re-run the necessary tools if the input files are changed. 299This can end up running a lot more things than are really necessary. 300 301If a build tree is in too much of a mess for those rules to work 302properly then a bootstrap can be done from the source directory with 303 304 aclocal 305 autoconf 306 automake 307 autoheader 308 309The autom4te.cache directory is created by autoconf to save some work 310in subsequent automake or autoheader runs. It's recreated 311automatically if removed, it doesn't get distributed. 312 313** C++ configuration 314 315It's intended that the contents of libgmp.la won't vary according to 316whether --enable-cxx is selected. This means that if C++ shared 317libraries don't work properly then a shared+static with --disable-cxx 318can be done for the C parts, then a static-only with --enable-cxx to 319get libgmpxx. 320 321libgmpxx.la uses some internals from libgmp.la, in order to share code 322between C and C++. It's intended that libgmpxx can only be expected 323to work with libgmp from the same version of GMP. If some of the 324shared internals change their interface, then it's proposed to rename 325them, for instance __gmp_doprint2 or the like, so as to provoke link 326errors 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 333shared or shared+static should be tested too. 334 335--enable-mpbsd grabs various bits of mpz, which might need to be 336adjusted if things in those routines are changed. Building mpbsd all 337the time doesn't cost much. 338 339--prefix to a dummy directory followed by "make install" will show 340what'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 344things to ensure it hits the just-built library. 345 346** Long long limb testing 347 348On systems where gcc supports long long, but a limb is normally just a 349long, the following can be used to force long long for testing 350purposes. It will probably run quite slowly. 351 352 ./configure --host=none ABI=longlong 353 354** Function argument conversions 355 356When using gcc, configuring with something like 357 358 ./configure CFLAGS="-g -Wall -Wconversion -Wno-sign-compare" 359 360can show where function parameters are being converted due to having 361function prototypes available, which won't happen in a K&R compiler. 362Doing this in combination with the long long limb setups above is 363good. 364 365Conversions between int and long aren't warned about by gcc when 366they're the same size, which is unfortunate because casts should be 367used in such cases, for the benefit of K&R compilers with int!=long 368and where the difference matters in function calls. 369 370** K&R support 371 372Function definitions must be in the GNU stylized form to work. See 373the ansi2knr.1 man page (included in the GMP sources). 374 375__GMP_PROTO is used for function prototypes, other ANSI / K&R 376differences are conditionalized in various places. 377 378Proper testing of the K&R support requires a compiler which gives an 379error for ANSI-isms. Configuring with --host=none is a good idea, to 380test all the generic C code. 381 382When using an ANSI compiler, the ansi2knr setups can be partially 383tested with 384 385 ./configure am_cv_prog_cc_stdc=no ac_cv_prog_cc_stdc=no 386 387This will test the use of $U and the like in the makefiles, but not 388much else. 389 390Forcing the cache variables can be used with a compiler like HP C 391which is K&R by default but to which configure normally adds ANSI mode 392flags. This then should be a good full K&R test. 393 394* Other Notes 395 396** Compatibility 397 398compat.c is the home of functions retained for binary compatibility, 399 but now done by other means (like a macro). 400 401struct __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 418Local variables: 419mode: outline 420fill-column: 70 421End: 422/* eof doc/configuration */ 423