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) If the function can be provided by a multi-function file, then 125 add to the "case" statement in configure.in which lists each 126 multi-function filename and what function files it can provide. 127 128 129** Adding a test program 130 131 i) Tests to be run early in the testing can be added to the main 132 "tests" sub-directory. 133 134 ii) Tests for mpn, mpz, mpq and mpf can be added under the 135 corresponding tests subdirectory. 136 137 iii) Generic tests for late in the testing can be added to 138 "tests/misc". printf and scanf tests currently live there too. 139 140 iv) Random number function tests can be added to "tests/rand". That 141 directory has some development-time programs too. 142 143 v) C++ test programs can be added to "tests/cxx". A line like the 144 following must be added for each, since by default automake looks 145 for a .c file. 146 147 t_foo_SOURCES = t-foo.cc 148 149In all cases the name of the program should be added to check_PROGRAMS 150in the Makefile.am. TESTS is equal to check_PROGRAMS, so all those 151programs get run. 152 153"tests/devel" has a number of programs which are only for development 154purposes and are not for use in "make check". These should be listed 155in EXTRA_PROGRAMS to get Makefile rules created, but they're never 156built or run unless an explicit "make someprog" is used. 157 158 159* Adding a new CPU 160 161In general it's policy to use proper names for each CPU type 162supported. If two CPUs are quite similar and perhaps don't have any 163actual differences in GMP then they're still given separate names, for 164example alphaev67 and alphaev68. 165 166Canonical names: 167 168 i) Decide the canonical CPU names GMP will accept. 169 170 ii) Add these to the config.sub wrapper if configfsf.sub doesn't 171 already accept them. 172 173 iii) Document the names in gmp.texi. 174 175Aliases (optional): 176 177 i) Any aliases can be added to the config.sub wrapper, unless 178 configfsf.sub already does the right thing with them. 179 180 ii) Leave configure.in and everywhere else using only the canonical 181 names. Aliases shouldn't appear anywhere except config.sub. 182 183 iii) Document in gmp.texi, if desired. Usually this isn't a good 184 idea, better encourage users to know just the canonical 185 names. 186 187Configure: 188 189 i) Add patterns to configure.in for the new CPU names. Include the 190 following (see configure.in for the variables to set up), 191 192 a) ABI choices (if any). 193 b) Compiler choices. 194 c) mpn path for CPU specific code. 195 d) Good default CFLAGS for each likely compiler. 196 d) Any special tests necessary on the compiler or assembler 197 capabilities. 198 199 ii) M4 macros to be shared by asm files in a CPU family are by 200 convention in a foo-defs.m4 like mpn/x86/x86-defs.m4. They're 201 likely to use settings from config.m4 generated by configure. 202 203Fat binaries: 204 205 i) In configure.in, add CPU specific directory(s) to fat_path. 206 207 ii) In mpn/<cpu>/fat.c, identify the CPU at runtime and use suitable 208 CPUVEC_SETUP_subdir macros to select the function pointers for it. 209 210 iii) For the x86s, add to the "$tmp_prefix" setups in configure.in 211 which abbreviates subdirectory names to fit an 8.3 filesystem. 212 (No need to restrict to 8.3, just ensure uniqueness when 213 truncated.) 214 215 216* The configure system 217 218** Installing tools 219 220The current versions of automake, autoconf and libtool in use can be 221checked in the ChangeLog. Look for "Update to ...". Patches may have 222been applied, look for "Regenerate ...". 223 224The GMP build system is in places somewhat dependent on the internals 225of the build tools. Obviously that's avoided as much as possible, but 226where it can't it creates a problem when upgrading or attempting to 227use different tools versions. 228 229** Updating gmp 230 231The following files need to be updated when going to a new version of 232the build tools. Unfortunately the tools generally don't identify 233when an out-of-date version is present. 234 235aclocal.m4 is updated by running "aclocal". (Only needed for a new 236automake or libtool.) 237 238INSTALL.autoconf can be copied from INSTALL in autoconf. 239 240ltmain.sh comes from libtool. Remove it and run "libtoolize --copy", 241or just copy the file by hand. 242 243texinfo.tex can be updated from ftp.gnu.org. Check it still works 244with "make gmp.dvi", "make gmp.ps" and "make gmp.pdf". 245 246configfsf.guess and configfsf.sub can be updated from ftp.gnu.org (or 247from the "config" cvs module at subversions.gnu.org). The gmp 248config.guess and config.sub wrappers are supposed to make such an 249update fairly painless. 250 251depcomp from automake is not needed because configure.in specifies 252automake with "no-dependencies". 253 254** How it works 255 256During development: 257 258 Input files Tool Output files 259 --------------------------------------------------------- 260 261 aclocal 262 $prefix/share/aclocal*/*.m4 ----------------> aclocal.m4 263 264 265 configure.in \ autoconf 266 aclocal.m4 / -----------------------------> configure 267 268 269 */Makefile.am \ automake 270 configure.in | ----------------------------> Makefile.in 271 aclocal.m4 / 272 273 configure.in \ autoheader 274 aclocal.m4 / -----------------------------> config.in 275 276At build time: 277 278 Input files Tool Output files 279 -------------------------------------------- 280 281 */Makefile.in \ configure / */Makefile 282 config.in | -------------> | config.h 283 gmp-h.in | | config.m4 284 mp-h.in / | gmp.h 285 | mp.h 286 \ fat.h (fat binary build only) 287 288When configured with --enable-maintainer-mode the Makefiles include 289rules to re-run the necessary tools if the input files are changed. 290This can end up running a lot more things than are really necessary. 291 292If a build tree is in too much of a mess for those rules to work 293properly then a bootstrap can be done from the source directory with 294 295 aclocal 296 autoconf 297 automake 298 autoheader 299 300The autom4te.cache directory is created by autoconf to save some work 301in subsequent automake or autoheader runs. It's recreated 302automatically if removed, it doesn't get distributed. 303 304** C++ configuration 305 306It's intended that the contents of libgmp.la won't vary according to 307whether --enable-cxx is selected. This means that if C++ shared 308libraries don't work properly then a shared+static with --disable-cxx 309can be done for the C parts, then a static-only with --enable-cxx to 310get libgmpxx. 311 312libgmpxx.la uses some internals from libgmp.la, in order to share code 313between C and C++. It's intended that libgmpxx can only be expected 314to work with libgmp from the same version of GMP. If some of the 315shared internals change their interface, then it's proposed to rename 316them, for instance __gmp_doprint2 or the like, so as to provoke link 317errors rather than mysterious failures from a mismatch. 318 319* Development setups 320 321** General 322 323--disable-shared will make builds go much faster, though of course 324shared or shared+static should be tested too. 325 326--prefix to a dummy directory followed by "make install" will show 327what's installed. 328 329"make check" acts on the libgmp just built, and will ignore any other 330/usr/lib/libgmp, or at least it should do. Libtool does various hairy 331things to ensure it hits the just-built library. 332 333** Long long limb testing 334 335On systems where gcc supports long long, but a limb is normally just a 336long, the following can be used to force long long for testing 337purposes. It will probably run quite slowly. 338 339 ./configure --host=none ABI=longlong 340 341** Function argument conversions 342 343When using gcc, configuring with something like 344 345 ./configure CFLAGS="-g -Wall -Wconversion -Wno-sign-compare" 346 347can show where function parameters are being converted due to having 348function prototypes available, which won't happen in a K&R compiler. 349Doing this in combination with the long long limb setups above is 350good. 351 352Conversions between int and long aren't warned about by gcc when 353they're the same size, which is unfortunate because casts should be 354used in such cases, for the benefit of K&R compilers with int!=long 355and where the difference matters in function calls. 356 357* Other Notes 358 359** Compatibility 360 361compat.c is the home of functions retained for binary compatibility, 362 but now done by other means (like a macro). 363 364struct __mpz_struct etc - this must be retained for C++ compatibility. 365 C++ applications defining functions taking mpz_t etc parameters 366 will get this in the mangled name because C++ "sees though" the 367 typedef mpz_t to the underlying struct. 368 369__gmpn - note that glibc defines some __mpn symbols, old versions of 370 some mpn routines, which it uses for floating point printfs. 371 372 373 374 375Local variables: 376mode: outline 377fill-column: 70 378End: 379/* eof doc/configuration */ 380