* doc/configuration: Updates.

(For the reworked mpn multi-function and optional file handling.)

1 files changed, 118 insertions, 35 deletions

diff --git a/doc/configuration b/doc/configuration
index 61f05d629..3fa20388f 100644
--- a/doc/configuration
+++ b/doc/configuration
@@ -1,18 +1,20 @@
 /* doc/configuration (in Emacs -*-outline-*- format). */
 
 * How to add a new file
+
 ** A file in the `mpn' subdirectory
+
 The way we build libmpn (in the `mpn' subdirectory) is quite special.
 
 There is (currently) only one ``generic'' file, one that is truly
-target indepentant.  That is `mp_bases.c'.  All other files are kept
-in subdirectories of `mpn' with the subdirectory names indicating
+target independent.  That is `mp_bases.c'.  All other files are kept
+in subdirectories of `mpn' with the subdirectory names indicating the
 target processor.  For example, in the `alpha' subdirectory, code
 specific to the Alpha processor is found.
 
-When running `configure', a bunch of symbolic links (if the build host
-supports that, otherwise there will be hard links) is made in the
-`mpn' subdirectory.
+When running `configure', a bunch of symbolic links are made in the
+`mpn' subdirectory.  If the the build host doesn't support symlinks
+then either hard links or copying is used.
 
 There are four types of mpn source files.
 
@@ -26,38 +28,96 @@ There are two types of .asm files.
   i) ``Normal'' files containg one function, possibly with more than
      one entry point.
 
-  ii) Multi-function files containing more than one function.
+  ii) Multi-function files that generate one of a set of functions
+      according to build options.
+
+
+When adding a new implementation of an existing function,
+
+  i) Put it in the approriate mpn subdirectory.  It'll be detected and
+     used.
+
+  ii) If it's a .asm or .S, be sure to have a PROLOGUE(func) entry
+      point since configure greps for that to set up the
+      HAVE_NATIVE_func defines in config.h.
+
+When adding a new implementation using a multi-function file, in
+addition do the following,
+
+  i) Use a MULFUNC_PROLOGUE(func1 func2 ...) in the .asm, declaring
+     all the functions implemented, including carry-in variants.
 
-When adding a new mpn function, you'll have to 
+     If there's a separate PROLOGUE(func) for each possible function,
+     then MULFUNC_PROLOGUE isn't necessary (but this is usually not
+     the case).
 
-  i) Implement it in an .asm file with one PROLOGUE(func) per *entry
-      point*.
+When adding a new style of multi-function file, in addition do the
+following,
 
-  ii) Add the function name to the `gmp_mpn_functions' variable in
-      configure.in.  If its existant is depending on target, add it to
-      `extra_functions'.
+  i) Add to the "case" statement in configure.in which lists each
+     multi-function filename and what function files it can provide.
 
-  iii) If you want `HAVE_NATIVE_func' defined in config.h, add 
-       `#undef <func>' to acconfig.h.
+When adding a completely new mpn function file, do the following,
 
-  iv) If you have created a multi-function .asm file:
+  i) Add it to configure.in under one of the following
 
-    a) Make sure that your .asm file has one MULFUNC_PROLOGUE(func)
-       per *entry point*.  This is needed because the PROLOGUE()
-       macros in a multi-function file are normally supposed to be
-       expanded by m4, and configure grep's the source file without
-       invoking m4.
+     a) `gmp_mpn_functions' if it exists for every target.  This means
+        there must be a C version in mpn/generic.  (Eg. add_n)
 
-    b) Add the file name without the .asm extension to the
-       `gmp_mulfunc_files' variable in configure.in.
+     b) `gmp_mpn_functions_optional' if it's a standard function, but
+        doesn't need to exist for every target.  Code wanting to use
+        this will test HAVE_NATIVE_func to see if it's available.
+        (Eg. copyi)
 
-    c) List all functions that the file implements in the
-       `gmp_mf_<file>' variable.
+     c) `extra_functions' for some targets, if it's a special function
+        that only ever needs to exist for certain targets.  Code
+        wanting to use it will generally look for the target, but
+        HAVE_NATIVE_func can be used if desired.
+
+  ii) If you want `HAVE_NATIVE_func' defined in config.h, add 
+      `#undef HAVE_NATIVE_func' to acconfig.h.
+
+  iii) If the function can be provided by a multi-function file,
+       then follow the directions above for them too.
 
 ** Add a file in any other directory
-FIXME
+
+When adding a top-level file,
+
+  i) Add it to libgmp_la_SOURCES in Makefile.am.
+
+  ii) If libmp.la needs it, then add it to libmp_la_SOURCES too.
+
+When adding an mpz file,
+
+  i) Add file.c to libmpz_la_SOURCES in mpz/Makefile.am.
+
+  ii) Add mpz/file.lo to MPZ_OBJECTS in the top-level Makefile.am.
+
+If a multi-function mpz file is being added,
+
+  i) In mpz/Makefile.am,
+
+     a) Add the file to EXTRA_DIST.
+
+     b) Add rules copying the file at build time to duplicates with
+        appropriate names.
+
+     c) Add each such func.c to nodist_libmpz_la_SOURCES.
+
+  ii) Add each c) above also as mpz/func.lo in MPZ_OBJECTS in the
+      top-level Makefile.am.
+
+  iii) In the multi-function file, expect a preprocessor symbol
+       OPERATION_func to indicate what form is being compiled.
+
+The same applies to mpf and mpq (except that multi-function support
+doesn't exist in mpq/Makefile.am at the moment).
+
+See mpz/mul_siui.c or mpf/integer.c for example multi-function files.
 
 * Selecting compiler and its flags by hand
+
 Specifying CC on the configure command line, will result in a default
 set of compiler flags, CFLAGS; `-g' for all compilers plus `-O2' for
 gcc.  Specify CFLAGS to set better flags.
@@ -78,27 +138,50 @@ pick 64-bit assembly code.
   $ configure CC=my64bit-cc CC64=my64bit-cc CFLAGS="-my -flags"
 
 * The configure system
+
 ** What we use
 We use the tools in <ftp://ftp.swox.com/pub/gmp/infrastructure/>.
+
 ** How to install new versions of Autoconf / Automake / Libtool
+
 *** Build Libtool
 With a fresh CVS checkout, run the bootstrap script with released
 versions (not CVS versions) of Autoconf and Automake in PATH.
+
 *** Update gmp directory
 gmp$ rm ltconfig ltmain.sh
 gmp$ libtoolize --copy
 gmp$ automake --add-missing --copy
 
 ** How it works
-Input file	Extra input	Tool		Output
-----------------------------------------------------------
-acinclude.m4			aclocal		aclocal.m4
-configure.in	aclocal.m4	autoconf	configure
-Makefile.am+configure.in	automake	Makefile.in
-configure.in+acconfig.h		autoheader	config.in
-
-		Makefile.in	configure	Makefile
-		config.in	configure	config.h
-				configure	config.m4
+During development:
+
+    Input files        Tool       Output files
+    ------------------------------------------
+                     aclocal
+    acinclude.m4  --------------> aclocal.m4
+    
+                     autoconf
+    configure.in \ -------------> configure
+    aclocal.m4   /
+    
+                     automake
+    Makefile.am  \ -------------> Makefile.in
+    configure.in / 
+    
+                     autoheader
+    configure.in \ -------------> config.in
+    acconfig.h   /
+
+
+At build time:
+
+    Input files        Tool       Output files
+    ------------------------------------------
+    
+                     configure
+    Makefile.in  \ -------------> / Makefile
+    config.in    /                | config.h
+                                  \ config.m4
 
 /* eof doc/configuration */