/* 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 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 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.

  .asm	  Assembly code preprocessed with m4
  .S	  Assembly code preprocessed with CPP
  .s	  Assembly code not preprocessed at all
  .c	  C code

There are two types of .asm files.

  i) ``Normal'' files containing one function, possibly with more than
     one entry point.

  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 appropriate 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.

     If there's a separate PROLOGUE(func) for each possible function,
     then MULFUNC_PROLOGUE isn't necessary (but this is usually not
     the case).

When adding a new style of multi-function file, in addition do the
following,

  i) Add to the "case" statement in configure.in which lists each
     multi-function filename and what function files it can provide.

When adding a completely new mpn function file, do the following,

  i) Add it to configure.in under one of the following

     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) `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) `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

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.

Example

  $ configure CC=my-gcc

will give 

  CFLAGS = -g -O2

Specifying CC on the configure command line will make configure
believe it's a 32-bit compiler and not choose a source path with
64-bit assembly code.  Specify CC64 as well as CC to make configure
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
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 */