
A Note On Licensing
===================

The GMP files used in this distribution have been derived from 
the GMP 4.2.4 distribution and are all licensed under the GNU 
Lesser General Public License v3 terms.  The licenses under
which these files are distributed here are set out in the files 
in the directory <build.vc9\gnu.license>.

Other files in this distribution that have been created by 
me for use in building GMP, MPIR and/or MPFR using Microsoft 
Visual Studio are provided under the same license terms.

1. What you will need to build GMP
==================================

1. You need to download GMP 4.2.4 from an appropriate location

2. You may need Python

3. If you wish to use the assembler code you will need a recent
   version of YASM from: http://www.tortall.net/projects/yasm/

2. Creating the Project Directories
===================================

First obtain the GMP distribution, named gmp-4.2.4. Unzip the 
files in the archive into a  directory tree with the gmp-4.2.4 
directory as its root.  

Unzip the files in this distribution so that they are merged
into the above directory tree with the directories

  build.vc9    -- build files for gmp and mpfr
  mpn/x86i     -- the YASM x86 assembler files (Pentium family)
  mpn/x86_64i  -- the YASM x64 assembler files (AMD64)

within the gmp root directory gmp-4.2.4.

3. Using the Assembler Based Build Projects
===========================================

If you wish to use the assembler files you will need the YASM 
x86/x64 assembler (r1438 or later) for Windows which can be 
obtained from:

  http://www.tortall.net/projects/yasm/

This assembler should be names (or renamed) yasm.exe and placed 
in the bin directory used by VC++, which, for Visual Stduio 
2008, is typically:

 C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin
 
You will also need to move the yasm.rules file from this 
distribution into the directory where Visual Studio 2008 
expects to find it, which is typically:

C:\Program Files (x86)\Microsoft Visual Studio 9.0
			  \VC\VCProjectDefaults
 
Alternatively you can configure the path for rules files in 
the VC++ configuration dialogue.

The NASM assembler is no longer supported as it has problems
with include file directory handling that the NASM team are
not willing to fix.

You will need to install Python if you wish to use the scripts
that automate the GMP and MPFR tests. Otherwise these have to 
be compiled and run manually.

4a. Compiling GMP with the Visual Studio C/C++ 2008
===================================================

These VC++ build projects are based on GMP 4.2.4 and are 
designed for use with Visual Studio 2008 Professional (or 
higher).  Some files in the GMP 4.2.4 distribution need to 
be modified in order to compile with VC++. This VC++ build 
dsitribution makes these changes so you need to back up your 
GMP files if you want to retain their original form.  This 
also means that the files that change may need to be updated 
if the original GMP files from which they are derived are 
modified by the GMP team.

4b. Building with Visual Studio 2005
====================================

The Python program vc98_swap.py will convert VC9 build projects 
into those needed for Visual Studio 2005 (VC8).  It will also
convert files that have been converted in this way back 
into their original form.  It does this conversion by looking 
for *.vcproj and *.sln files in the current working directory 
and its sub-directories and changing any found in the following
ways.

The line 

  Version="9.00"

in *.vcproj files is changed to:

  Version="8.00"

or vice versa.

The lines

  Microsoft Visual Studio Solution File, Format Version 10.00
  # Visual Studio 2008
 
in *.sln files are changed to:

  Microsoft Visual Studio Solution File, Format Version 9.00
  # Visual Studio 2005

or vice versa.

Because it acts recursively on all sub-directories of this 
directory it is important not to run it at a directory level 
in which not all projects are to be converted.

4c. Building with Visual Studio Express
=======================================

If you wish to convert these files for use with VC++ Express, 
you will need to install Python and then run vc9_to_express.py. 
This will create a new directory 'build.vc9x' that will contain 
the project files for VC++ 2008 Express. There will be two errors
when the solution is loaded because Express cannot handle two
64-bit projects.  But these should not prevent other projects 
in the solution loading. The two unavailable 64-bit projects
should then be deleted to prevent future loading errors.

5. Building GMP
===============

The GMP build is started by opening the Visual Studion C/C++ 
solution file 'gmp.sln' in build.vc9. 

If you are using VC++ Express use the 'gmp.sln' in the directory 
build.vc9x instead.  In this case you must build the projects 
manually in the following order:

1. Build gen_gmp first.
2. Build the other gen_* projects.
3. Then build the remainder as needed. 

The 64-bit build projects won't be available with VC++ Express.

Visual Studiio 2008 can be started for building the 32 or 64 bit 
versions of GMP by clicking on the gmp.sln file in the build.vc9 
directory. 

If you wish to use the Intel compiler, you need to convert the 
build files by right clicking on the GMP top level solution and 
then selecting the conversion option.  Before building for the 
first time with the Intel compiler after such a conversion, it 
is advisable to clean all the build projects and to delete any 
files in the build.vc9\Win32 and build.vc9\x64 sub-directories.

Select the desired DLL or static library and then set the 
desired build configuration:

    win32 or x64
    release or debug
    
To build the GMP dynamic link libraries (DLLs) select and build
those whiich you need as follows:

    dll_gmp_amd64  - GMP DLL using AMD6 Athlon assembler (x64)
    dll_gmp_core2  - GMP DLL using Intel Core2 assembler (x64)
    dll_gmp_gc     - GMP DLL using generic C (win32 & x64)
    dll_gmp_p0     - GMP DLL using Pentium assembler (win32)
    dll_gmp_p3     - GMP DLL using Pentium III assembler (win32)
    dll_gmp_p4     - GMP DLL using Pentium IV assembler (win32)

To build GMP static libraries choose from:

    lib_gmp_amd64  - GMP library using AMD6 Athlon assembler (x64)
    lib_gmp_amd64  - GMP library Intel Core2 assembler (x64)
    lib_gmp_gc     - GMP library using generic C (win32 & x64)
    lib_gmp_p0     - GMP library using Pentium assembler (win32)
    lib_gmp_p3     - GMP library using Pentium III assembler (win32
    lib_gmp_p4     - GMP library using Pentium IV assembler (win32)
     
Before any of these libraries is built the appropriate GMP 
configuration file is automatically copied into config.h.  After a 
static library is built its config.h file is copied into the output
directory; the library and its associated files are then copied to 
the 'lib' sub-directory within the VC++ solution folder (build.vc9).
Simlarly when a DLL is built, the resulting DLL, its export libraries
and its debug symbol file are copied to the files gmp.dll, gmp.exp, 
gmp.lib and gmp.pdb within the 'dll' sub-directory.
 
This means that the 'dll' and 'lib' sub-directories respectively 
contain the last GMP DLLs and static libraries built.  These are
then the libraries used in build any other libraries that are built
later.

The GMP DLL projects include the C++ files. If you do not want 
these the relevent files needed to be excluded from the DLL(s) you 
build. Go to the 'cpp' subdirectory of their build project in the 
IDE and exclude all the files in this subdirectory from the build 
process.

All the DLLs and static libraries are multi-threaded and are 
linked to the multi-threaded Microsoft run-time libraries (DLLs are 
linked to DLL run time libraries and static libraries are linked to 
static run time libraries).

Within the 'dll' and 'lib' sub-directories used for output the 
structure is:

   DLL or LIB 
      Win32
         Release
         Debug
      x64
         Release
         Debug   

in order to enable the appropriate library for the desired target 
platform to be easily located.  The individual project sub-
directories also contain the libraries once they have been built 
(the 'dll' and 'lib' directories are just used to hold the latest 
built versions for linking the tests that are described later). 

6. The C++ Interface
====================

After a GMP library has been built, other libraries can be built.
These always use the last GMP library (of the same type, static or DLL) 
that has been built.  To build the GMP C+ library wrapper use:

    lib_gmpxx  - GMP C++ wrapper static library (win32 & x64)

7. The Tests
============

There is a separate solution for the GMP tests: gmp_tests.sln. In 
Visual Studio 2008 these are in the gmp_tests project folder.  These
tests should be run immediately after the DLL or static library 
under test has been built.  Before running the tests it is necessary
to build the add_test_lib project in the 'gmp_tests' solution folder 
(note that the Win32/x64 and Debug/Release configuration built must 
match the intended test configuration). 

The GMP tests are all configured using the property file:

	test_config.vsprops

located in the gmp_tests sub-directory. These cover the C and the 
C++ tests for win32 and 64 builds in both release and debug 
configurations.  All these property files use an IDE macro named 
$(BinDir) that determines whether the tests are applied to the the 
static LIB or the DLL versions versions of the libraries. The 
default is:

	$(BinDir) = $(SolutionDir)lib

for linking the tests to the static libraries but this can be 
changed to 

	$(BinDir) = $(SolutionDir)dll
	
to link the test to the DLL libraries.  A second macro $(LIBS)
is also needed to set the libaries to be used:

	$(BinDir)$(PlatformName)\$(ConfigurationName)\gmp.lib 

for testing the DLL and 

	$(BinDir)$(PlatformName)\$(ConfigurationName)\gmp.lib 	
	$(BinDir)$(PlatformName)\$(ConfigurationName)\gmpxx.lib

for testing the static libraries (enter these with a ' ' between 
them when setting up the macro).

Note, however, tha the DLL tests are not useful at the moment 
because they use internal features of GMP that are not exported
by the DLLs. Hence they fail to link in almost all cases.

There is also another macro, $(TestDir), that specifies where 
the executable test files are placed but changing this will 
prevent the test scripts (see later) from being used.

8. Test Automation
==================

After they have been built the tests cn be run using the 
Python program run_tests.py in the build.vc9\gmp_tests
directory (build.vc9x\gmp_tests for VC++ express). To 
see the test output the python program should be run in
a command window from within these sub-directories:

	cmd>gmp_tests.py 
	
and the output can be directed to a file:

	cmd>gmp_tests.py >out.txt 
	
When a GMP library is built the file 'last_build.txt' is  
written to the buid.vc9 subdirectory giving details of the 
build configuration. These details are then used to run the 
GMP tests and this means that these tests need to be run 
immediately after the library to be tested has been built.  

It is possible to test a different library by editing 
'last_build.txt' but this will only work if the files in the 
$(BinDir) are correct.  In order to avoid errors, it is 
advisable before testing to do a clean build of the library 
under test (to do a completely clean build, the files in 
the build.vc9\Win32 and build.vc9\x64 directories should be 
deleted.  

8a. Two Tests Fail
==================

The tests for cxx/locale and misc/locale fail to link 
because the test defines a symbol - localeconv - that is 
in the Microsoft runtime libraries.  This is not significant 
for GMP numeric operations. 

9. Using GMP
============

Applications that use GMP include the gmp.h header file to provide 
the prototypes for the functions that GMP provides. Hence when a
GMP distribution is being used it is important to ensure that any
GMP header file used matches that for the version of GMP in use.

9a. Using the Static Libraries
==============================

To build a GMP C or C++ based application using the the static
libraries all that needs to be done is to add the GMP or GMPXX
static libraries to the application build process.  

It is, of course, important to ensure that any libraries that are
used have been built for the target platform.

9b. Using the DLL Export Libraries
==================================

The DLLs built by VC++ use the _cdecl calling convention in 
which exported symbols have their C names prefixed with an 
extra '_' character.  Some applications expect the _stdcall 
convention to be used in which there is an underscore prefix 
and a suffix of '@n' where n is the number of bytes used for 
the function arguments on the stack.  Such applications will 
need to be modified to work with the GMP DLLs provided here. 
The alternative of attempting to build GMP using the _stdcall 
convention is not recommended (and won't work with the 
assembler based builds anyway). This is further complicated 
if the builds for x64 are used since the conventions here are 
different again.

There are two ways of linking to a DLL. The first way is to
use one or more of the DLL export libraries built as described
earlier (note that these are not the same as static libraries
although they are used in a similar way when an application 
is built).

9c. Using the DLL Export Library
================================

If you intend to use the DLL export libraries in an application
you need to:

   a. ensure that the application can locate the GMP DLLs in 
      question when it is run.  This involves putting the 
      DLL(s) on a recognised directory path.

   b. define __GMP_LIBGMP_DLL when the application is built
      in order to ensure that GMP's DLL export symbols are 
      properly recognised as such so that they can be 
      accessed via the GMP import library
   
   c. link the application to the gmp.lib library that is
      provided with the DLL you intend to use (this is
      produced when the DLL is built)

9d. Using DLL Dynamic loading
=============================

The second way of linking to a DLL is to use dynamic 
loading.  This is more complex and will not be discussed 
here. The VC++ documentation describes how to use DLLs in 
this way.

9e. Using GMP functions that use FILE's as Input or Output
==========================================================

In Windows the different C runtime libraries each have 
their own stream input/output tables, which means that 
FILE* pointers cannot be passed from one to another. In 
consequence, if an application that is built with one 
library attempts to pass FILE parameters to a DLL that 
is built with another, the FILE parameters will not be 
recognised and the program will fail.

It is hence important to build a GMP application using 
the same run time library as that used to build any 
DLL that is used - in this case the appropriate version 
9 library.

If this is not possible, Jim White has made a DLL 
available that will map all stream Input/Output 
functions in a way that ensures that they use the 
correct runtime library.

9f. GMP Applications that Require _stdcall Functions
====================================================

Some applications, for example Visual Basic 6, require 
that DLL based functions provide a _stdcall interface, 
whereas the VC++ default for DLLs is _cdecl.

To overcome this Jim White intends to make a wrapper 
DLL available for GMP that provides a _stdcall interface 
to the normal _cdecl GMP DLLs. 

10. KNOWN BUILD ISSUES FOR VC++ v9
==================================

A few test files require minor modifications to compile in 
this build as follows;

-----------------------------------
gmp-4.2.4\tests\mpn\t-perfsqr.c
28a29,31
> #ifdef _MSC_VER		/* BRG */
> #include "perfsqr.h"
> #else
30c33
< 
---
> #endif
-----------------------------------
gmp-4.2.4\tests\mpz\t-perfsqr.c
28a29,31
> #ifdef _MSC_VER		/* BRG */
> #include "perfsqr.h"
> #else
30c33
< 
---
> #endif
-----------------------------------
gmp-4.2.4\tests\misc.c
30c30
< #if HAVE_FLOAT_H
---
> #if HAVE_FLOAT_H || defined( _MSC_VER )	/* BRG */
479a480,485
> #if defined( _MSC_VER )
>   {		unsigned int cw;
> 		_controlfp_s(&cw, 0, 0);
> 		_controlfp_s(&cw, (cw & ~0xC00) | (rc << 10), _MCW_RC);
>   }
> #else
480a487
> #endif
491,492c499,506
<   switch ((x86_fstcw () & ~0xC00) >> 10) {
---
>   unsigned int cw;
> #if defined( _MSC_VER )
>   _controlfp_s(&cw, 0, 0);
> #else
>   cw = x86_fstcw();
> #endif
> 
>   switch ((cw & ~0xC00) >> 10) {
-----------------------------------
gmp-4.2.4\tests\refmpn.c
1674c1674
<               ASSERT (refmpn_add_n (np+i, np+i, dp, dsize) != 0);
---
>               ASSERT_CARRY (refmpn_add_n (np+i, np+i, dp, dsize) != 0);
-----------------------------------
gmp-4.2.4\longlong.h
168a169,208
> #ifdef _MSC_VER
> #  include <intrin.h>
> 
> #  if defined( _WIN64 )
> #    define count_leading_zeros(c,x)        \
>       do {                                  \
>         ASSERT ((x) != 0);                  \
>         _BitScanReverse64(&c, (x));         \
>         c = 63 - c;                         \
>       } while (0)
> #    define count_trailing_zeros(c,x)       \
>       do {                                  \
>         ASSERT ((x) != 0);                  \
>         _BitScanForward64(&c, (x));         \
>       } while (0)
> #    define umul_ppmm(xh, xl, m0, m1)       \
>       do {                                  \
>         xl = _umul128( (m0), (m1), &xh);    \
>       } while (0)
> #  else
> #    define count_leading_zeros(c,x)        \
>       do {                                  \
>         ASSERT ((x) != 0);                  \
>         _BitScanReverse(&c, (x));           \
>         c = 31 - c;                         \
>       } while (0)
> #    define count_trailing_zeros(c,x)       \
>       do {                                  \
>         ASSERT ((x) != 0);                  \
>         _BitScanForward(&c, (x));           \
>       } while (0)
> #    define umul_ppmm(xh, xl, m0, m1)       \
>       do { unsigned __int64 _t;             \
>         _t = __emulu( (m0), (m1));          \
>         xl = _t & 0xffffffff;               \
>         xh = _t >> 32;                      \
>       } while (0)
> #  endif
-----------------------------------

Also longlong.h is rearranged to assisst building with the Intel compiler.

11. ACKNOWLEDGEMENTS
====================

My thanks to:

1. The GMP team for their work on GMP and the MPFR team for their
   work on MPFR
2. Sam Krasnik and Mike Loehr for suggestions on how to improve and
   correct errors in earlier releases.
3. Patrick Pelissier, Vincent Lefèvre and Paul Zimmermann for helping
   to resolve VC++ issues in MPFR.

       Brian Gladman, December 2008
