Update the Visual Studio 2010 readme.txt to outline the revised build process
This commit is contained in:
gladman
parent
eff43d4ee1
commit
ab19b8236c
@ -5,52 +5,52 @@ Building MPIR with Microsoft Visual Studio 2010
|
||||
A Note On Licensing
|
||||
===================
|
||||
|
||||
Files in this distribution that have been created by me for
|
||||
use in building MPIR with Microsoft Visual Studio 2010 are
|
||||
provided under the LGPL v2.1+ license terms.
|
||||
Files in this distribution that have been created by me for use in
|
||||
building MPIR with Microsoft Visual Studio 2010 are provided under
|
||||
the LGPL v2.1+ license terms.
|
||||
|
||||
The MPIR library uses numerous files which are LGPL v3+ and
|
||||
so the overall license of the library distribution is LGPL
|
||||
v3+. Some of the demos are GPL.
|
||||
The MPIR library uses numerous files which are LGPL v3+ and so the
|
||||
overall license of the library distribution is LGPL v3+. Some of
|
||||
the demos are GPL.
|
||||
|
||||
Using the Assembler Based Build Projects
|
||||
========================================
|
||||
|
||||
If you wish to use the assembler files you will need VSYASM,
|
||||
a version of YASM x86/x64 assembler tailored specifically for
|
||||
use with Microsoft Visual Studio 2010. You will need a
|
||||
If you wish to use the assembler files you will need VSYASM, a
|
||||
version of YASM x86/x64 assembler tailored specifically for use with
|
||||
Microsoft Visual Studio 2010. You will need a
|
||||
recent revision of YASM from:
|
||||
|
||||
http://www.tortall.net/projects/yasm/
|
||||
|
||||
This assembler should be placed in the bin directory used by
|
||||
VC++, which, for Visual Stduio 2010, is typically:
|
||||
This assembler should be placed in the bin directory used by VC++,
|
||||
which, for Visual Stduio 2010, is typically:
|
||||
|
||||
C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin
|
||||
|
||||
You will need to install Python if you wish to use the scripts
|
||||
that automate the MPIR and MPFR tests. Otherwise these have to
|
||||
be compiled and run manually.
|
||||
You will need to install Python if you wish to use the scripts that
|
||||
automate the MPIR and MPFR tests. Otherwise these have to be compiled
|
||||
and run manually.
|
||||
|
||||
Compiling MPIR with the Visual Studio C/C++
|
||||
===========================================
|
||||
|
||||
These VC++ build projects are primarily designed to work with
|
||||
Microsoft Visual Studio 2010 Professional. The win32 build
|
||||
projects also work with Microsoft Visual C++ 2010 Express.
|
||||
These VC++ build projects are primarily designed to work with Microsoft
|
||||
Visual Studio 2010 Professional. The win32 build projects also work with
|
||||
Microsoft Visual C++ 2010 Express.
|
||||
|
||||
To build the x64 libraries with VC++ Express you will need to
|
||||
install the Windows 7.1 SDK and Python (2.6 or later). To do
|
||||
this, run the Python program 'add.express.py' before starting
|
||||
the build process as described below. This converts the build
|
||||
projects for use with Express. If necessary, these changes can
|
||||
be removed by running the Python program 'remove.express.py'.
|
||||
To build the x64 libraries with VC++ Express you will need to install
|
||||
the Windows 7.1 SDK and Python (2.6 or later). To do this, run the Python
|
||||
program 'add.express.py' before starting the build process as described
|
||||
below. This converts the build projects for use with Express. If
|
||||
necessary, these changes can be removed by running the Python program
|
||||
'remove.express.py'.
|
||||
|
||||
Building MPIR
|
||||
=============
|
||||
|
||||
The MPIR build is started by opening the Visual Studio C/C++
|
||||
solution file 'mpir.sln' in the build.vc10 directory.
|
||||
The MPIR build is started by opening the Visual Studio C/C++ solution
|
||||
file 'mpir.sln' in the build.vc10 directory.
|
||||
|
||||
MPIR is built by using the appropriate build projects and, where
|
||||
appropriate, setting the build configuration and platform:
|
||||
@ -58,8 +58,8 @@ appropriate, setting the build configuration and platform:
|
||||
win32 or x64
|
||||
release or debug
|
||||
|
||||
All projects have release and debug configurations but not all
|
||||
projects provide for 32 and 64 bit Windows platforms.
|
||||
All projects have release and debug configurations but not all projects
|
||||
provide for 32 and 64 bit Windows platforms.
|
||||
|
||||
The supported platforms and library formats are as follows:
|
||||
|
||||
@ -89,35 +89,34 @@ The supported platforms and library formats are as follows:
|
||||
dll_mpir_core2 - MPIR DLL using Intel Core2 assembler (x64)
|
||||
dll_mpir_nehalem - MPIR DLL using Intel Core2 assembler (x64)
|
||||
|
||||
Before any of these libraries is built the appropriate MPIR
|
||||
configuration file is generated and 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.vc10).
|
||||
Simlarly when a DLL is built, the resulting DLL, its export libraries
|
||||
and its debug symbol file are copied to the files mpir.dll, mpir.exp,
|
||||
mpir.lib and mpir.pdb within the 'dll' sub-directory.
|
||||
Before any of these libraries is built the appropriate MPIR configuration
|
||||
file is generated and 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.vc10). Simlarly when a DLL is
|
||||
built, the resulting DLL, its export libraries and its debug symbol file
|
||||
are copied to the files mpir.dll, mpir.exp, mpir.lib and mpir.pdb within
|
||||
the 'dll' sub-directory.
|
||||
|
||||
This means that the 'dll' and 'lib' sub-directories respectively
|
||||
contain the last MPIR DLLs and static libraries built. These are
|
||||
then the libraries used to build software that requires MPIR or GMP.
|
||||
If you use the mpir-tests, the speed, the tune or the try programs
|
||||
it is very important to do so immediately after the MPIR library
|
||||
in question is built because these projects link to the last
|
||||
library built.
|
||||
This means that the 'dll' and 'lib' sub-directories respectively contain
|
||||
the last MPIR DLLs and static libraries built. These are then the
|
||||
libraries used to build software that requires MPIR or GMP. If you use
|
||||
the mpir-tests, the speed, the tune or the try programs it is important
|
||||
to do so immediately after the MPIR library in question is built because
|
||||
these projects link to the last library built.
|
||||
|
||||
The MPIR DLL projects include the C++ files. If you want the relevent
|
||||
files 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
|
||||
run time static libraries).
|
||||
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 run time static
|
||||
libraries).
|
||||
|
||||
Within the 'dll' and 'lib' sub-directories used for output the
|
||||
structure is:
|
||||
Within the 'dll' and 'lib' sub-directories used for output the structure
|
||||
is:
|
||||
|
||||
DLL or LIB
|
||||
Win32
|
||||
@ -129,9 +128,9 @@ structure is:
|
||||
|
||||
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).
|
||||
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).
|
||||
|
||||
C++ Interface
|
||||
=============
|
||||
@ -148,54 +147,46 @@ is not needed when they are used.
|
||||
The Tests
|
||||
=========
|
||||
|
||||
The tests use the static library versions of MPIR by default but if
|
||||
the DLL version is to be tested the file:
|
||||
There is a separate solution for the MPIR tests: mpir-tests.sln. In
|
||||
Visual Studio 2010 this is in build.vc10 folder.
|
||||
|
||||
mpir\build.vc10\mpir-tests\dll-test-config.props
|
||||
The tests are configured to always test the last version of MPIR that is
|
||||
built. But this is controlled by the file lastbuild.txt in the mpir-tests
|
||||
directory whose contents are typically:
|
||||
|
||||
should be copied into:
|
||||
dll Win32 Release "..\dll\Win32\Release"
|
||||
|
||||
mpir\build.vc10\mpir-tests\test-config.props
|
||||
|
||||
before the tests are built. Copying the file:
|
||||
giving the 'library type', the 'platform', the 'configuration' and the
|
||||
'MPIR binary directory' relative to the mpir-tests' directory.
|
||||
|
||||
This file can be edited to test a different version of MPIR but it is also
|
||||
necessary to copy either:
|
||||
|
||||
mpir\build.vc10\mpir-tests\lib-test-config.props
|
||||
|
||||
or:
|
||||
|
||||
mpir\build.vc10\mpir-tests\dll-test-config.props#
|
||||
|
||||
into:
|
||||
|
||||
mpir\build.vc10\mpir-tests\test-config.props
|
||||
|
||||
resets the tests to use the MPIR static libraries.
|
||||
depending on whether a static or DLL build of MPIR is to be tested
|
||||
respectively.
|
||||
|
||||
The tests also use the C++ library functions so for testing MPIR static
|
||||
libraries both the desired version of MPIR and the C++ library must be
|
||||
built before the tests are built and run. This is not necessary for
|
||||
MPIR DLLs as they contain the C++ routines.
|
||||
|
||||
There is a separate solution for the MPIR tests: mpir-tests.sln. In
|
||||
Visual Studio 2010 these are in build.vc10 folder. These tests must
|
||||
be run immediately after the DLL or the static C and C++ libraries
|
||||
have been built because they test the most recently built versions.
|
||||
Before running the tests it is necessary to build the add-test-lib
|
||||
project. Note also that the Win32/x64 and Debug/Release choices
|
||||
for the tests must match that of the libraries under test.
|
||||
|
||||
The MPIR tests are all configured using the property file:
|
||||
|
||||
test-config.vsprops
|
||||
|
||||
located in the mpir-tests sub-directory. These cover the C and the
|
||||
C++ tests for win32 and 64 builds in both release and debug
|
||||
configurations.
|
||||
|
||||
Test Automation
|
||||
===============
|
||||
|
||||
After they have been built the tests cn be run using the Python
|
||||
script run-tests.py in the build.vc10\mpir-tests directory. To
|
||||
see the test output the python script should be run in a command
|
||||
window from within these sub-directories:
|
||||
After they have been built the tests cn be run using the Python script
|
||||
run-tests.py in the build.vc10\mpir-tests directory. To see the test
|
||||
output the python script should be run in a command window from within
|
||||
these sub-directories:
|
||||
|
||||
cmd>run-tests.py
|
||||
|
||||
@ -203,72 +194,66 @@ and the output can be directed to a file:
|
||||
|
||||
cmd>run-tests.py >out.txt
|
||||
|
||||
When an MPIR library is built the file 'last_build.txt' is
|
||||
written to the buid.vc10 subdirectory giving details of the
|
||||
build configuration. These details are then used to run the
|
||||
MPIR 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.vc10\Win32 and build.vc10\x64 directories should be
|
||||
deleted.
|
||||
When an MPIR library is built the file 'last_build.txt' is written to
|
||||
the buid.vc10 subdirectory giving details of the build configuration.
|
||||
These details are then used to run the MPIR 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
|
||||
'lastbuild.txt' but this will only work if the files in the MPIR output
|
||||
directory 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.vc10\Win32 and build.vc10\x64
|
||||
directories should be deleted.
|
||||
|
||||
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 MPIR numeric operations.
|
||||
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 MPIR numeric operations. Some tests are skipped
|
||||
for the DLL verssion as they are not relevant in this case.
|
||||
|
||||
Using MPIR
|
||||
==========
|
||||
|
||||
Applications that use MPIR include the mpir.h header file to provide
|
||||
the prototypes for the functions that MPIR provides. Hence when a
|
||||
MPIR distribution is being used it is important to ensure that any
|
||||
MPIR header file used matches that for the version of MPIR in use.
|
||||
Applications that use MPIR include the mpir.h header file to provide the
|
||||
prototypes for the functions that MPIR provides. Hence when avMPIR
|
||||
distribution is being used it is important to ensure that anyvMPIR header
|
||||
file used matches that for the version of MPIR in use.
|
||||
|
||||
1. Using the Static Libraries
|
||||
=============================
|
||||
|
||||
To build a MPIR C or C++ based application using the the static
|
||||
libraries all that needs to be done is to add the MPIR and/or the
|
||||
MPIR C++ static libraries to the application build process.
|
||||
To build a MPIR C or C++ based application using the the static libraries
|
||||
all that needs to be done is to add the MPIR and/or the MPIR C++ 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.
|
||||
It is, of course, important to ensure that any libraries that are used
|
||||
have been built for the target platform.
|
||||
|
||||
2. 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 MPIR DLLs provided here.
|
||||
The alternative of attempting to build MPIR 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.
|
||||
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 MPIR DLLs provided here. The alternative
|
||||
of attempting to build MPIR 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).
|
||||
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).
|
||||
|
||||
3. Using the DLL Export Library
|
||||
===============================
|
||||
|
||||
If you intend to use the DLL export libraries in an application
|
||||
you need to:
|
||||
If you intend to use the DLL export libraries in an application you need to:
|
||||
|
||||
a. ensure that the application can locate the MPIR DLLs in
|
||||
question when it is run. This involves putting the
|
||||
@ -286,42 +271,102 @@ you need to:
|
||||
4. 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.
|
||||
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.
|
||||
|
||||
5. Using MPIR 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.
|
||||
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 MPIR 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.
|
||||
It is hence important to build a MPIR application using the same run time
|
||||
library as that used to build any DLL that is used - in this case the
|
||||
appropriate version 10 library.
|
||||
|
||||
6. MPIR 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.
|
||||
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 MPIR that provides a _stdcall interface
|
||||
to the normal _cdecl MPIR DLLs.
|
||||
To overcome this Jim White intends to make a wrapper DLL available for MPIR
|
||||
that provides a _stdcall interface to the normal _cdecl MPIR DLLs.
|
||||
|
||||
7. The MPIR Build Process in Outline
|
||||
====================================
|
||||
|
||||
Prebuild
|
||||
--------
|
||||
|
||||
It is not necessary to read this unless you wnat to change the buiild
|
||||
process. The first step in an MPIR build is managed by the batch file
|
||||
prebuilld.bat which has the following steps:
|
||||
|
||||
1. Read the connfiguation from the IDE input parameters which are the
|
||||
version (generic, core2, k8, k10, nehalem, p0, p3 or p4). For the
|
||||
generic version there is a second parameter for a win32 build.
|
||||
|
||||
2. Set the source directory for the mpn source code and the platform
|
||||
(win32 or x64).
|
||||
|
||||
3. Call the batch file gen_mpir_h.bat (described later) to generate
|
||||
mpir.h in the mpir root directory.
|
||||
|
||||
4. Call the batch file gen_config_h.bat (described later) to generate
|
||||
config.h in the mpir root directory.
|
||||
|
||||
5. use the batch file out_copy_rename to copy the appropriate version
|
||||
of gmp-mparam.h into the mpir root directory.
|
||||
|
||||
The gen_mpir_h batch file inputs gmp_h.in and searches for @symbol@,
|
||||
replacing those that matter with the appropiate values for the Windows
|
||||
build.
|
||||
|
||||
The gen_config_h batch file takes lists of symbols in the cfg.h files
|
||||
in the mpn sub-directories and generates HAVE_NATIVE defines from them.
|
||||
The result is then prepended onto cfg.h in the build.vc10 directory and
|
||||
the result is output as config.h into the mpir root directory.
|
||||
|
||||
The IDE build
|
||||
-------------
|
||||
|
||||
At this point the IDE builds the MPIR library.
|
||||
|
||||
Postbuild
|
||||
---------
|
||||
|
||||
After a successful MPIR build a postbuild step is managed by the batch
|
||||
file postbuild.bat which has the following steps:
|
||||
|
||||
1. Tne $(TargetPath) parameter (%1 for the batch file) is parsed to
|
||||
determine the library type (lib or dll), the platform (win32 or
|
||||
x64), the configuration (release or debug) and the filename.
|
||||
|
||||
2. The final output directory is then creaated (mpir\build.vc10\lib
|
||||
or mpir\build.vc10\dll) relative to the Visual Stduio solution
|
||||
directory (build,vc10).
|
||||
|
||||
3. A text file 'lastbuild.txt' is then output in the mpir-tests sub-
|
||||
directory describing the build configuration.
|
||||
|
||||
4. The header files used in the build are then copied into the output
|
||||
directory.
|
||||
|
||||
5. The built library files (mpir.dll, mpir.exp, mpir.lib and mpir.pdb
|
||||
for a DLL, mpir.lib and mpir.pdb for a static library) are then
|
||||
copied into the output directory.
|
||||
|
||||
6. In the sub-directory mpir-tests, either dll-test-config.props (for
|
||||
a DLL) or lib-test-config.props (for a static library) is copied
|
||||
into test-config.props to set up the tests for the version of MPIR
|
||||
being built.
|
||||
|
||||
ACKNOWLEDGEMENTS
|
||||
================
|
||||
|
||||
Loading…
Reference in New Issue
Block a user