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