source: trunk/third/gmp/INSTALL @ 18191

Copyright 1996, 1997, 1999, 2000, 2001 Free Software Foundation, Inc.

This file is part of the GNU MP Library.

The GNU MP Library is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or (at your
option) any later version.

The GNU MP Library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
License for more details.

You should have received a copy of the GNU Lesser General Public License
along with the GNU MP Library; see the file COPYING.LIB.  If not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.





                          INSTALLING GNU MP
                          =================


These instructions are only for the impatient.  Others should read the install
instructions in gmp.info.  Use

        info -f ./gmp.info

or in emacs

        C-u C-h i gmp.info


Here are some brief instructions on how to install GMP, and some examples to
help you get started using it.  First you need to compile.  Since you're
impatient, try this

        ./configure
        make

If that fails, or you care about the performance of GMP, you need to read the
full instructions in the chapter "Installing GMP" in the manual.

Optionally, you can install with the following.  This will be to /usr/local by
default, and you'll probably need to be "root" to be able to write there.

        make install

Next, try some small test programs, for example the ones below.

In GMP programs, all variables need to be initialized before they are
assigned, and cleared out before program flow leaves the scope in which they
were declared.  Here is an example program that reads two numbers from the
command line, multiplies them, and prints the result to stdout.


    #include <stdio.h>
    #include <gmp.h>         /* All GMP programs need to include gmp.h */

    main (int argc, char **argv)
    {
      mpz_t a, b, p;

      if (argc != 3)
        {
          printf ("Usage: %s <number> <number>\n", argv[0]);
          exit (1);
        }

      /* Initialize variables */
      mpz_init (a);
      mpz_init (b);
      mpz_init (p);

      /* Assign a and b from base 10 strings in argv */
      mpz_set_str (a, argv[1], 10);
      mpz_set_str (b, argv[2], 10);

      /* Multiply a and b and put the result in p */
      mpz_mul (p, a, b);

      /* Print p in decimal */
      gmp_printf ("%Zd\n", p);

      /* Clear out variables */
      mpz_clear (a);
      mpz_clear (b);
      mpz_clear (p);
      exit (0);
    }


This might look tedious, with all the initializing and clearing.  Fortunately
some of these operations can be combined, and other operations can often be
avoided.  An experienced GMP user might write:


    #include <stdio.h>
    #include <gmp.h>

    main (int argc, char **argv)
    {
      mpz_t a, b, p;

      if (argc != 3)
        {
          printf ("Usage: %s <number> <number>\n", argv[0]);
          exit (1);
        }

      /* Initialize and assign a and b from base 10 strings in argv */
      mpz_init_set_str (a, argv[1], 10);
      mpz_init_set_str (b, argv[2], 10);
      /* Initialize p */
      mpz_init (p);

      /* Multiply a and b and put the result in p */
      mpz_mul (p, a, b);

      /* Print p in decimal */
      gmp_printf ("%Zd\n", p);

      /* Since we're about to exit, no need to clear out variables */
      exit (0);
    }


Now you have to compile your test program, and link it with the GMP library.
Assuming your working directory is still the gmp build directory, and your
source file is called example.c, enter:

        gcc -g -I. example.c .libs/libgmp.a

After installing, the command becomes: "gcc -g example.c -lgmp".  Also, GMP is
libtool based so you can use that to link if you want.

Now try to run the example:

        ./a.out 98365871231256752134 319378318340103345227
        31415926535897932384618573336104570964418

The functions used here all operate on signed integers, and have names
starting with "mpz_".  There are many more such functions than used in these
examples.  See the chapter "Integer Functions" in the manual for a complete
list.

There are two other main classes of functions in GMP.  They operate on
rational numbers and floating-point numbers, respectively.  The chapters
"Rational Number Functions", and "Floating-point Functions" document these
classes.

To run a set of tests, do "make check".  This will take a while.

To create the printable documentation from the texinfo source, type "make
gmp.dvi" or "make gmp.ps".  This requires various "tex" commands.

If you decide to use GMP, it is a good idea you at least read the chapter "GMP
Basics" in the manual.

Some known build problems are noted in the "Installing GMP" chapter of
the manual.  Please report other problems to bug-gmp@gnu.org.



----------------
Local variables:
mode: text
fill-column: 78
End: