Updated docs with MSVC nd Cygwin64 info.

2014-04-05 00:59:20 +01:00 · 2014-04-05 00:59:20 +01:00 · 0aceae0318
commit 0aceae0318
parent fedb3560cc
4 changed files with 540 additions and 330 deletions
--- a/doc/mpir.info
+++ b/doc/mpir.info
@ -25,7 +25,7 @@ END-INFO-DIR-ENTRY

 Indirect:
 mpir.info-1: 1044
-mpir.info-2: 300935
+mpir.info-2: 300109

 Tag Table:
 (Indirect)
@ -33,145 +33,146 @@ Node: Top1044
 Node: Copying3281
 Node: Introduction to MPIR5001
 Node: Installing MPIR7171
-Node: Build Options8609
-Node: ABI and ISA25147
-Node: Notes for Package Builds31916
-Node: Notes for Particular Systems35354
-Node: Known Build Problems42786
-Node: Performance optimization44474
-Node: MPIR Basics45610
-Node: Headers and Libraries46261
-Node: Nomenclature and Types47716
-Node: MPIR on Windows x6449637
-Node: Function Classes51564
-Node: Variable Conventions53099
-Node: Parameter Conventions54628
-Node: Memory Management56680
-Node: Reentrancy57812
-Node: Useful Macros and Constants59249
-Node: Compatibility with older versions60579
-Node: Efficiency61710
-Node: Debugging69389
-Node: Profiling75789
-Node: Autoconf79823
-Node: Emacs81697
-Node: Reporting Bugs82306
-Node: Integer Functions84873
-Node: Initializing Integers85652
-Node: Assigning Integers87586
-Node: Simultaneous Integer Init & Assign89365
-Node: Converting Integers91193
-Node: Integer Arithmetic94809
-Node: Integer Division96275
-Node: Integer Exponentiation102180
-Node: Integer Roots103003
-Node: Number Theoretic Functions104790
-Node: Integer Comparisons113615
-Node: Integer Logic and Bit Fiddling114966
-Node: I/O of Integers117526
-Node: Integer Random Numbers120413
-Node: Integer Import and Export122177
-Node: Miscellaneous Integer Functions126164
-Node: Integer Special Functions128010
-Node: Rational Number Functions131181
-Node: Initializing Rationals132376
-Node: Rational Conversions134832
-Node: Rational Arithmetic136564
-Node: Comparing Rationals137869
-Node: Applying Integer Functions139186
-Node: I/O of Rationals140670
-Node: Floating-point Functions142533
-Node: Initializing Floats145424
-Node: Assigning Floats149512
-Node: Simultaneous Float Init & Assign152062
-Node: Converting Floats153574
-Node: Float Arithmetic156797
-Node: Float Comparison158661
-Node: I/O of Floats159989
-Node: Miscellaneous Float Functions162560
-Node: Low-level Functions165193
-Node: Random Number Functions190584
-Node: Random State Initialization191654
-Node: Random State Seeding193707
-Node: Random State Miscellaneous195077
-Node: Formatted Output195669
-Node: Formatted Output Strings195915
-Node: Formatted Output Functions201155
-Node: C++ Formatted Output205232
-Node: Formatted Input207919
-Node: Formatted Input Strings208156
-Node: Formatted Input Functions212818
-Node: C++ Formatted Input215791
-Node: C++ Class Interface217699
-Node: C++ Interface General218697
-Node: C++ Interface Integers221777
-Node: C++ Interface Rationals225459
-Node: C++ Interface Floats229486
-Node: C++ Interface Random Numbers235015
-Node: C++ Interface Limitations237123
-Node: Custom Allocation239969
-Node: Language Bindings244615
-Node: Algorithms248645
-Node: Multiplication Algorithms249350
-Node: Basecase Multiplication250562
-Node: Karatsuba Multiplication252474
-Node: Toom 3-Way Multiplication256104
-Node: Toom 4-Way Multiplication262520
-Node: FFT Multiplication263894
-Node: Other Multiplication269320
-Node: Unbalanced Multiplication272002
-Node: Division Algorithms272898
-Node: Single Limb Division273246
-Node: Basecase Division276166
-Node: Divide and Conquer Division277369
-Node: Exact Division279639
-Node: Exact Remainder282839
-Node: Small Quotient Division285132
-Node: Greatest Common Divisor Algorithms286731
-Node: Binary GCD287023
-Node: Lehmer's GCD289699
-Node: Subquadratic GCD291903
-Node: Extended GCD294357
-Node: Jacobi Symbol294916
-Node: Powering Algorithms295833
-Node: Normal Powering Algorithm296097
-Node: Modular Powering Algorithm296626
-Node: Root Extraction Algorithms297690
-Node: Square Root Algorithm298006
-Node: Nth Root Algorithm300149
-Node: Perfect Square Algorithm300935
-Node: Perfect Power Algorithm303022
-Node: Radix Conversion Algorithms303644
-Node: Binary to Radix304021
-Node: Radix to Binary307952
-Node: Other Algorithms309917
-Node: Prime Testing Algorithm310271
-Node: Factorial Algorithm311498
-Node: Binomial Coefficients Algorithm312935
-Node: Fibonacci Numbers Algorithm313830
-Node: Lucas Numbers Algorithm316306
-Node: Random Number Algorithms317028
-Node: Assembler Coding319152
-Node: Assembler Code Organisation320129
-Node: Assembler Basics321102
-Node: Assembler Carry Propagation322261
-Node: Assembler Cache Handling324099
-Node: Assembler Functional Units326267
-Node: Assembler Floating Point327888
-Node: Assembler SIMD Instructions331671
-Node: Assembler Software Pipelining332660
-Node: Assembler Loop Unrolling333728
-Node: Assembler Writing Guide335948
-Node: Internals338718
-Node: Integer Internals339232
-Node: Rational Internals341489
-Node: Float Internals342729
-Node: Raw Output Internals350057
-Node: C++ Interface Internals351252
-Node: Contributors354539
-Node: References363534
-Node: GNU Free Documentation License371281
-Node: Concept Index396451
-Node: Function Index439190
+Node: Build Options8651
+Node: ABI and ISA25189
+Node: Notes for Package Builds31958
+Node: Building with Microsoft Visual Studio35405
+Node: Notes for Particular Systems40530
+Node: Known Build Problems46269
+Node: Performance optimization47957
+Node: MPIR Basics49093
+Node: Headers and Libraries49744
+Node: Nomenclature and Types51199
+Node: MPIR on Windows x6453120
+Node: Function Classes55047
+Node: Variable Conventions56582
+Node: Parameter Conventions58111
+Node: Memory Management60163
+Node: Reentrancy61295
+Node: Useful Macros and Constants62732
+Node: Compatibility with older versions64062
+Node: Efficiency65193
+Node: Debugging72872
+Node: Profiling79272
+Node: Autoconf83306
+Node: Emacs85180
+Node: Reporting Bugs85789
+Node: Integer Functions88356
+Node: Initializing Integers89135
+Node: Assigning Integers91069
+Node: Simultaneous Integer Init & Assign92848
+Node: Converting Integers94676
+Node: Integer Arithmetic98292
+Node: Integer Division99758
+Node: Integer Exponentiation105663
+Node: Integer Roots106486
+Node: Number Theoretic Functions108273
+Node: Integer Comparisons117098
+Node: Integer Logic and Bit Fiddling118449
+Node: I/O of Integers121009
+Node: Integer Random Numbers123896
+Node: Integer Import and Export125660
+Node: Miscellaneous Integer Functions129647
+Node: Integer Special Functions131493
+Node: Rational Number Functions134664
+Node: Initializing Rationals135859
+Node: Rational Conversions138315
+Node: Rational Arithmetic140047
+Node: Comparing Rationals141352
+Node: Applying Integer Functions142669
+Node: I/O of Rationals144153
+Node: Floating-point Functions146016
+Node: Initializing Floats148907
+Node: Assigning Floats152995
+Node: Simultaneous Float Init & Assign155545
+Node: Converting Floats157057
+Node: Float Arithmetic160280
+Node: Float Comparison162144
+Node: I/O of Floats163472
+Node: Miscellaneous Float Functions166043
+Node: Low-level Functions168676
+Node: Random Number Functions194067
+Node: Random State Initialization195137
+Node: Random State Seeding197190
+Node: Random State Miscellaneous198560
+Node: Formatted Output199152
+Node: Formatted Output Strings199398
+Node: Formatted Output Functions204638
+Node: C++ Formatted Output208715
+Node: Formatted Input211402
+Node: Formatted Input Strings211639
+Node: Formatted Input Functions216301
+Node: C++ Formatted Input219274
+Node: C++ Class Interface221182
+Node: C++ Interface General222180
+Node: C++ Interface Integers225260
+Node: C++ Interface Rationals228942
+Node: C++ Interface Floats232969
+Node: C++ Interface Random Numbers238498
+Node: C++ Interface Limitations240606
+Node: Custom Allocation243452
+Node: Language Bindings248098
+Node: Algorithms252128
+Node: Multiplication Algorithms252833
+Node: Basecase Multiplication254045
+Node: Karatsuba Multiplication255957
+Node: Toom 3-Way Multiplication259587
+Node: Toom 4-Way Multiplication266003
+Node: FFT Multiplication267377
+Node: Other Multiplication272803
+Node: Unbalanced Multiplication275485
+Node: Division Algorithms276381
+Node: Single Limb Division276729
+Node: Basecase Division279649
+Node: Divide and Conquer Division280852
+Node: Exact Division283122
+Node: Exact Remainder286322
+Node: Small Quotient Division288615
+Node: Greatest Common Divisor Algorithms290214
+Node: Binary GCD290506
+Node: Lehmer's GCD293182
+Node: Subquadratic GCD295386
+Node: Extended GCD297840
+Node: Jacobi Symbol298399
+Node: Powering Algorithms299316
+Node: Normal Powering Algorithm299580
+Node: Modular Powering Algorithm300109
+Node: Root Extraction Algorithms301173
+Node: Square Root Algorithm301489
+Node: Nth Root Algorithm303632
+Node: Perfect Square Algorithm304418
+Node: Perfect Power Algorithm306505
+Node: Radix Conversion Algorithms307127
+Node: Binary to Radix307504
+Node: Radix to Binary311435
+Node: Other Algorithms313400
+Node: Prime Testing Algorithm313754
+Node: Factorial Algorithm314981
+Node: Binomial Coefficients Algorithm316418
+Node: Fibonacci Numbers Algorithm317313
+Node: Lucas Numbers Algorithm319789
+Node: Random Number Algorithms320511
+Node: Assembler Coding322635
+Node: Assembler Code Organisation323612
+Node: Assembler Basics324585
+Node: Assembler Carry Propagation325744
+Node: Assembler Cache Handling327582
+Node: Assembler Functional Units329750
+Node: Assembler Floating Point331371
+Node: Assembler SIMD Instructions335154
+Node: Assembler Software Pipelining336143
+Node: Assembler Loop Unrolling337211
+Node: Assembler Writing Guide339431
+Node: Internals342201
+Node: Integer Internals342715
+Node: Rational Internals344972
+Node: Float Internals346212
+Node: Raw Output Internals353540
+Node: C++ Interface Internals354735
+Node: Contributors358022
+Node: References367017
+Node: GNU Free Documentation License374764
+Node: Concept Index399934
+Node: Function Index443132

 End Tag Table
--- a/doc/mpir.info-1
+++ b/doc/mpir.info-1
@ -212,6 +212,7 @@ useful bug reports.
 * Build Options::
 * ABI and ISA::
 * Notes for Package Builds::
+* Building with Microsoft Visual Studio::
 * Notes for Particular Systems::
 * Known Build Problems::
 * Performance optimization::
@ -757,7 +758,7 @@ Sparc V9 (`sparc64', `sparcv9', `ultrasparc*')
          ./configure --build=none --host=sparcv9-sun-solaris2.7 ABI=64


-File: mpir.info,  Node: Notes for Package Builds,  Next: Notes for Particular Systems,  Prev: ABI and ISA,  Up: Installing MPIR
+File: mpir.info,  Node: Notes for Package Builds,  Next: Building with Microsoft Visual Studio,  Prev: ABI and ISA,  Up: Installing MPIR

 2.3 Notes for Package Builds
 ============================
@ -825,9 +826,128 @@ which tests preprocessor symbols and chooses the correct actual
 `mpir.h'.


-File: mpir.info,  Node: Notes for Particular Systems,  Next: Known Build Problems,  Prev: Notes for Package Builds,  Up: Installing MPIR
+File: mpir.info,  Node: Building with Microsoft Visual Studio,  Next: Notes for Particular Systems,  Prev: Notes for Package Builds,  Up: Installing MPIR

-2.4 Notes for Particular Systems
+2.4 Building with Microsoft Visual Studio
+=========================================
+
+MPIR can be built with the professional and higher versions of Microsoft
+Visual Studio 2010, 2012 and 2013.  It can also be built with Visual
+Studio Express 2013 for Windows Desktop.  In addition to one of these
+versions of Visual Studio, Python 3 and the YASM assembler will need to
+be installed if the assembler optimised versions are required. if
+installed, MPIR can also be built with the Intel compiler that can be
+integrated into tne full versions of Visual Studio.
+
+   Python can be obtained from:
+
+     `https://www.python.org/'
+
+   and the YASM assembler is available here:
+
+     `http://yasm.tortall.net/Download.html'
+
+   This assembler (`vsyasm.exe', NOT `yasm.exe') should be placed in the
+binary directory used by the Visual Studio version in use, which should
+be one of:
+
+     `C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin'
+     `C:\Program Files (x86)\Microsoft Visual Studio 11.0\VC\bin'
+     `C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin'
+
+   Alternatively `vsyasm.exe' can be placed elsewhere provided that the
+environment variable `YASMPATH' gives its location.
+
+Building MPIR
+     A build of MPIR is started by double clicking on the file
+     `mpir.sln' in the appropriate sub-directory within the MPIR root
+     directory:
+
+              Visual Studio 2010:  mpir/build.vc10/mpir.sln
+              Visual Studio 2012:  mpir/build.vc11/mpir.sln
+              Visual Studio 2013:  mpir/build.vc12/mpir.sln
+
+     Visual Studio will then display a list of individual build projects
+     from which an appropriate version of MPIR can be built. For
+     example, a typical list of projects:
+
+              dll_mpir_gc     standard DLL, no assembler (win32 and x64)
+              dll_mpir_p3     assembly optimised DLL for pentium 3 (win32)
+              lib_mpir_p3     assembly optimised static library for
+                              pentium 3 (x64)
+              lib_mpir_core2  assembly optimised static library for
+                              core2 (x64)
+              dll_mpir_core2  assembly optimised DLL for core2 (x64)
+
+     allows MPIR to be built either as a static library or as a DLL. A
+     DLL will include both the C and C++ features of MPIR but a static
+     library will include only the C features so in this case the
+     project:
+
+            lib_mpir_cxx     the MPIRXX C++ static library (win32 and x64)
+
+     should also be built to provide the MPIR C++ static library
+     (`MPIRXX').
+
+     Before a project is built, Visual Studio should be set to the
+     required configuration (Release or Debug) and the required target
+     architecture (win32 or x64).  The build process puts the output
+     files into one of the two sub-directories:
+
+          `mpir/lib'
+          `mpir/dll'
+
+     depending on whether static library or DLL versions have been
+     built.
+
+Additional Assembler Optimised Versions
+     The Visual Studio builds for MPIR are initially provided with a
+     small set of assembler optimised projects but many more are
+     available and can be obtained by running the Python program
+     `mpir_config.py' that is in the appropriate build sub-directory
+     for the version of Visual Studio in use.  This program is run
+     before Visual Studio is used and provides a list of all the
+     assembler optimised versions that are available.  Any number can
+     be chosen and these builds will then be available when Visual
+     Studio is subsequently opened by double clicking on `mpir.sln'.
+
+Testing Visual Studio versions of MPIR
+     Testing a version of the library once it has been built is started
+     by double clicking on the appropriate solution file:
+
+              Visual Studio 2010:  mpir/build.vc10/mpir-tests.sln
+              Visual Studio 2012:  mpir/build.vc11/mpir-tests.sln
+              Visual Studio 2013:  mpir/build.vc12/mpir-tests.sln
+
+     The tests are always run on the last version of MPIR built and it
+     is important to set the configuration for the tests (Release or
+     Debug, win32 or x64) to be the same as that used to build MPIR.
+     After loading there will be a large list of test projects starting:
+
+            Solution `mpir-tests' (202 projects)
+                  add-test-lib
+                  bswap
+                  constants
+                  ....
+
+     The project `add-test-lib' should be selected and built first,
+     after which the solution as a whole (i.e. the first line shown
+     above) can be selected to build all the tests.  After the build
+     has completed, the tests are run by executing the Python program
+     `run-tests.py' in the appropriate Visual Studio build
+     sub-directory, for example, for Visual Studio 2013:
+
+             mpir/build.vc12/mpir-tests/run-tests.py
+
+Further Details
+     Additional details can be found in the `readme.txt' files in the
+     appropriate Visual Studio build sub-directories.
+
+
+
+File: mpir.info,  Node: Notes for Particular Systems,  Next: Known Build Problems,  Prev: Building with Microsoft Visual Studio,  Up: Installing MPIR
+
+2.5 Notes for Particular Systems
 ================================

 AIX 3 and 4
@ -858,43 +978,14 @@ Floating Point Mode
     including application code, not just MPIR.

 MS-DOS and MS Windows
-     On an MS Windows system Cygwin and MINGW can be used , they are
+     On an MS Windows system Cygwin and MINGW can be used, they are
     ports of GCC and the various GNU tools.

          `http://www.cygwin.com/'
          `http://www.mingw.org/'

-     Cygwin is a 32 bit build only but mingw is 32 or 64 bit build.
-     Depending on how the mingw tools are installed will determine the
-     best procedure for building , because of the large number of ways
-     this can be achieved it is best to search the MPIR devel mailing
-     list or the mingw mailing list.
-
-     For building with MSVC we provide a number of ways.
-
-     In addition, project files for MSVC are provided, allowing MPIR to
-     build on Microsoft's compiler. For Visual Studio 2010 see the
-     readme.txt file in the build.vc10 directory. The MSVC projects
-     provides full assembler support and for `x86_64' CPU's this will
-     produce far superior results. These project files can also be
-     accessed via the command line with the batch files `configure.bat'
-     and `make.bat' which have a `unix like' interface , however they
-     are not very well tested and are due to be replaced.
-
-     An another alternative is `configure' and `make' in the `win'
-     directory , these again have a `unix like' syntax , these are
-     tested regularly and also have the advantage of working with
-     VS2005 and up (including the free/express versions). There is some
-     auto detection of the compiler , but it's probably best to set it
-     explicity using the usual `call
-     "%VS90COMNTOOLS%\..\..\VC\vcvarsall.bat" amd64' in the command
-     window.  The program `YASM' is also required and should be in path
-     or the `%YASMPATH%' varible set.  If `configure' guesses wrong ,
-     close the window and try again changing the `ABI=...' selection
-     and or the `vcvarsall.bat' options.  `make' supports the usual
-     `clean' and `check' options .  The `only' bug is that shared
-     library builds `dll's' fail the make check in the C++ parts for
-     `istream' and `ostream' with some unresolved symbols.
+     Both 32 and 64 bit versions of MinGW and Cygwin are supported.
+     Building on these systems is very similar to building on Linux.

 MS Windows DLLs
     On systems `*-*-cygwin*' and `*-*-mingw*' by default MPIR builds
@ -987,7 +1078,7 @@ x86 MMX and SSE2 Code

 File: mpir.info,  Node: Known Build Problems,  Next: Performance optimization,  Prev: Notes for Particular Systems,  Up: Installing MPIR

-2.5 Known Build Problems
+2.6 Known Build Problems
 ========================

 You might find more up-to-date information at `http://www.mpir.org/'.
@ -1027,7 +1118,7 @@ Sparc Solaris 2.7 with gcc 2.95.2 in `ABI=32'

 File: mpir.info,  Node: Performance optimization,  Prev: Known Build Problems,  Up: Installing MPIR

-2.6 Performance optimization
+2.7 Performance optimization
 ============================

 For optimal performance, build MPIR for the exact CPU type of the target
@ -6983,112 +7074,3 @@ seen in the exponent, as per Knuth section 4.6.3.  The "left to right"
 variant described there is used rather than algorithm A, since it's
 just as easy and can be done with somewhat less temporary memory.

-
-File: mpir.info,  Node: Modular Powering Algorithm,  Prev: Normal Powering Algorithm,  Up: Powering Algorithms
-
-15.4.2 Modular Powering
-----------------------
-
-Modular powering is implemented using a 2^k-ary sliding window
-algorithm, as per "Handbook of Applied Cryptography" algorithm 14.85
-(*note References::).  k is chosen according to the size of the
-exponent.  Larger exponents use larger values of k, the choice being
-made to minimize the average number of multiplications that must
-supplement the squaring.
-
-   The modular multiplies and squares use either a simple division or
-the REDC method by Montgomery (*note References::).  REDC is a little
-faster, essentially saving N single limb divisions in a fashion similar
-to an exact remainder (*note Exact Remainder::).  The current REDC has
-some limitations.  It's only O(N^2) so above `POWM_THRESHOLD' division
-becomes faster and is used.  It doesn't attempt to detect small bases,
-but rather always uses a REDC form, which is usually a full size
-operand.  And lastly it's only applied to odd moduli.
-
-
-File: mpir.info,  Node: Root Extraction Algorithms,  Next: Radix Conversion Algorithms,  Prev: Powering Algorithms,  Up: Algorithms
-
-15.5 Root Extraction Algorithms
-===============================
-
-* Menu:
-
-* Square Root Algorithm::
-* Nth Root Algorithm::
-* Perfect Square Algorithm::
-* Perfect Power Algorithm::
-
-
-File: mpir.info,  Node: Square Root Algorithm,  Next: Nth Root Algorithm,  Prev: Root Extraction Algorithms,  Up: Root Extraction Algorithms
-
-15.5.1 Square Root
------------------
-
-Square roots are taken using the "Karatsuba Square Root" algorithm by
-Paul Zimmermann (*note References::).
-
-   An input n is split into four parts of k bits each, so with b=2^k we
-have n = a3*b^3 + a2*b^2 + a1*b + a0.  Part a3 must be "normalized" so
-that either the high or second highest bit is set.  In MPIR, k is kept
-on a limb boundary and the input is left shifted (by an even number of
-bits) to normalize.
-
-   The square root of the high two parts is taken, by recursive
-application of the algorithm (bottoming out in a one-limb Newton's
-method),
-
-     s1,r1 = sqrtrem (a3*b + a2)
-
-   This is an approximation to the desired root and is extended by a
-division to give s,r,
-
-     q,u = divrem (r1*b + a1, 2*s1)
-     s = s1*b + q
-     r = u*b + a0 - q^2
-
-   The normalization requirement on a3 means at this point s is either
-correct or 1 too big.  r is negative in the latter case, so
-
-     if r < 0 then
-       r = r + 2*s - 1
-       s = s - 1
-
-   The algorithm is expressed in a divide and conquer form, but as
-noted in the paper it can also be viewed as a discrete variant of
-Newton's method, or as a variation on the schoolboy method (no longer
-taught) for square roots two digits at a time.
-
-   If the remainder r is not required then usually only a few high limbs
-of r and u need to be calculated to determine whether an adjustment to
-s is required.  This optimization is not currently implemented.
-
-   In the Karatsuba multiplication range this algorithm is
-O(1.5*M(N/2)), where M(n) is the time to multiply two numbers of n
-limbs.  In the FFT multiplication range this grows to a bound of
-O(6*M(N/2)).  In practice a factor of about 1.5 to 1.8 is found in the
-Karatsuba and Toom-3 ranges, growing to 2 or 3 in the FFT range.
-
-   The algorithm does all its calculations in integers and the resulting
-`mpn_sqrtrem' is used for both `mpz_sqrt' and `mpf_sqrt'.  The extended
-precision given by `mpf_sqrt_ui' is obtained by padding with zero limbs.
-
-
-File: mpir.info,  Node: Nth Root Algorithm,  Next: Perfect Square Algorithm,  Prev: Square Root Algorithm,  Up: Root Extraction Algorithms
-
-15.5.2 Nth Root
---------------
-
-Integer Nth roots are taken using Newton's method with the following
-iteration, where A is the input and n is the root to be taken.
-
-              1         A
-     a[i+1] = - * ( --------- + (n-1)*a[i] )
-              n     a[i]^(n-1)
-
-   The initial approximation a[1] is generated bitwise by successively
-powering a trial root with or without new 1 bits, aiming to be just
-above the true root.  The iteration converges quadratically when
-started from a good approximation.  When n is large more initial bits
-are needed to get good convergence.  The current implementation is not
-particularly well optimized.
-
--- a/doc/mpir.info-2
+++ b/doc/mpir.info-2
@ -22,6 +22,115 @@ START-INFO-DIR-ENTRY
 * mpir: (mpir).                   MPIR Multiple Precision Integers and Rationals Library.
 END-INFO-DIR-ENTRY

+
+File: mpir.info,  Node: Modular Powering Algorithm,  Prev: Normal Powering Algorithm,  Up: Powering Algorithms
+
+15.4.2 Modular Powering
+-----------------------
+
+Modular powering is implemented using a 2^k-ary sliding window
+algorithm, as per "Handbook of Applied Cryptography" algorithm 14.85
+(*note References::).  k is chosen according to the size of the
+exponent.  Larger exponents use larger values of k, the choice being
+made to minimize the average number of multiplications that must
+supplement the squaring.
+
+   The modular multiplies and squares use either a simple division or
+the REDC method by Montgomery (*note References::).  REDC is a little
+faster, essentially saving N single limb divisions in a fashion similar
+to an exact remainder (*note Exact Remainder::).  The current REDC has
+some limitations.  It's only O(N^2) so above `POWM_THRESHOLD' division
+becomes faster and is used.  It doesn't attempt to detect small bases,
+but rather always uses a REDC form, which is usually a full size
+operand.  And lastly it's only applied to odd moduli.
+
+
+File: mpir.info,  Node: Root Extraction Algorithms,  Next: Radix Conversion Algorithms,  Prev: Powering Algorithms,  Up: Algorithms
+
+15.5 Root Extraction Algorithms
+===============================
+
+* Menu:
+
+* Square Root Algorithm::
+* Nth Root Algorithm::
+* Perfect Square Algorithm::
+* Perfect Power Algorithm::
+
+
+File: mpir.info,  Node: Square Root Algorithm,  Next: Nth Root Algorithm,  Prev: Root Extraction Algorithms,  Up: Root Extraction Algorithms
+
+15.5.1 Square Root
+------------------
+
+Square roots are taken using the "Karatsuba Square Root" algorithm by
+Paul Zimmermann (*note References::).
+
+   An input n is split into four parts of k bits each, so with b=2^k we
+have n = a3*b^3 + a2*b^2 + a1*b + a0.  Part a3 must be "normalized" so
+that either the high or second highest bit is set.  In MPIR, k is kept
+on a limb boundary and the input is left shifted (by an even number of
+bits) to normalize.
+
+   The square root of the high two parts is taken, by recursive
+application of the algorithm (bottoming out in a one-limb Newton's
+method),
+
+     s1,r1 = sqrtrem (a3*b + a2)
+
+   This is an approximation to the desired root and is extended by a
+division to give s,r,
+
+     q,u = divrem (r1*b + a1, 2*s1)
+     s = s1*b + q
+     r = u*b + a0 - q^2
+
+   The normalization requirement on a3 means at this point s is either
+correct or 1 too big.  r is negative in the latter case, so
+
+     if r < 0 then
+       r = r + 2*s - 1
+       s = s - 1
+
+   The algorithm is expressed in a divide and conquer form, but as
+noted in the paper it can also be viewed as a discrete variant of
+Newton's method, or as a variation on the schoolboy method (no longer
+taught) for square roots two digits at a time.
+
+   If the remainder r is not required then usually only a few high limbs
+of r and u need to be calculated to determine whether an adjustment to
+s is required.  This optimization is not currently implemented.
+
+   In the Karatsuba multiplication range this algorithm is
+O(1.5*M(N/2)), where M(n) is the time to multiply two numbers of n
+limbs.  In the FFT multiplication range this grows to a bound of
+O(6*M(N/2)).  In practice a factor of about 1.5 to 1.8 is found in the
+Karatsuba and Toom-3 ranges, growing to 2 or 3 in the FFT range.
+
+   The algorithm does all its calculations in integers and the resulting
+`mpn_sqrtrem' is used for both `mpz_sqrt' and `mpf_sqrt'.  The extended
+precision given by `mpf_sqrt_ui' is obtained by padding with zero limbs.
+
+
+File: mpir.info,  Node: Nth Root Algorithm,  Next: Perfect Square Algorithm,  Prev: Square Root Algorithm,  Up: Root Extraction Algorithms
+
+15.5.2 Nth Root
+---------------
+
+Integer Nth roots are taken using Newton's method with the following
+iteration, where A is the input and n is the root to be taken.
+
+              1         A
+     a[i+1] = - * ( --------- + (n-1)*a[i] )
+              n     a[i]^(n-1)
+
+   The initial approximation a[1] is generated bitwise by successively
+powering a trial root with or without new 1 bits, aiming to be just
+above the true root.  The iteration converges quadratically when
+started from a good approximation.  When n is large more initial bits
+are needed to get good convergence.  The current implementation is not
+particularly well optimized.
+

 File: mpir.info,  Node: Perfect Square Algorithm,  Next: Perfect Power Algorithm,  Prev: Nth Root Algorithm,  Up: Root Extraction Algorithms

@ -2174,7 +2283,7 @@ Concept Index
 * -finstrument-functions:                Profiling.           (line  66)
 * 2exp functions:                        Efficiency.          (line  43)
 * 80x86:                                 Notes for Particular Systems.
-                                                              (line 139)
+                                                              (line 110)
 * ABI <1>:                               ABI and ISA.         (line   6)
 * ABI:                                   Build Options.       (line 170)
 * About this manual:                     Introduction to MPIR.
@ -2238,6 +2347,8 @@ Concept Index
 * Build directory:                       Build Options.       (line  19)
 * Build notes for binary packaging:      Notes for Package Builds.
                                                              (line   6)
+* Build notes for MSVC:                  Building with Microsoft Visual Studio.
+                                                              (line   6)
 * Build notes for particular systems:    Notes for Particular Systems.
                                                              (line   6)
 * Build options:                         Build Options.       (line   6)
@ -2306,7 +2417,7 @@ Concept Index
 * Division functions <2>:                Rational Arithmetic. (line  22)
 * Division functions:                    Integer Division.    (line   6)
 * DLLs:                                  Notes for Particular Systems.
-                                                              (line  73)
+                                                              (line  44)
 * DocBook:                               Build Options.       (line 359)
 * Documentation formats:                 Build Options.       (line 352)
 * Documentation license:                 GNU Free Documentation License.
@ -2404,7 +2515,7 @@ Concept Index
 * I/O functions <2>:                     I/O of Rationals.    (line   6)
 * I/O functions:                         I/O of Integers.     (line   6)
 * i386:                                  Notes for Particular Systems.
-                                                              (line 139)
+                                                              (line 110)
 * IA-64:                                 ABI and ISA.         (line  69)
 * Import:                                Integer Import and Export.
                                                              (line  11)
@ -2537,7 +2648,7 @@ Concept Index
 * Miscellaneous integer functions:       Miscellaneous Integer Functions.
                                                              (line   6)
 * MMX:                                   Notes for Particular Systems.
-                                                              (line 145)
+                                                              (line 116)
 * Modular inverse functions:             Number Theoretic Functions.
                                                              (line 112)
 * Most significant bit:                  Miscellaneous Integer Functions.
@ -2553,6 +2664,8 @@ Concept Index
                                                              (line  34)
 * MS-DOS:                                Notes for Particular Systems.
                                                              (line  34)
+* MSVC:                                  Building with Microsoft Visual Studio.
+                                                              (line   6)
 * Multi-threading:                       Reentrancy.          (line   6)
 * Multiplication algorithms:             Multiplication Algorithms.
                                                              (line   6)
@ -2574,7 +2687,7 @@ Concept Index
 * obstack output:                        Formatted Output Functions.
                                                              (line  81)
 * OpenBSD:                               Notes for Particular Systems.
-                                                              (line  96)
+                                                              (line  67)
 * Optimizing performance:                Performance optimization.
                                                              (line   6)
 * ostream output:                        C++ Formatted Output.
@ -2689,17 +2802,17 @@ Concept Index
 * Solaris <1>:                           Known Build Problems.
                                                              (line  29)
 * Solaris <2>:                           Notes for Particular Systems.
-                                                              (line 135)
+                                                              (line 106)
 * Solaris:                               ABI and ISA.         (line 121)
 * Sparc:                                 Notes for Particular Systems.
-                                                              (line 102)
+                                                              (line  73)
 * Sparc V9:                              ABI and ISA.         (line 121)
 * Special integer functions:             Integer Special Functions.
                                                              (line   6)
 * Square root algorithm:                 Square Root Algorithm.
                                                              (line   6)
 * SSE2:                                  Notes for Particular Systems.
-                                                              (line 145)
+                                                              (line 116)
 * Stack backtrace:                       Debugging.           (line  47)
 * Stack overflow <1>:                    Debugging.           (line   7)
 * Stack overflow:                        Build Options.       (line 288)
@ -2737,13 +2850,15 @@ Concept Index
                                                              (line   6)
 * Version number:                        Useful Macros and Constants.
                                                              (line  12)
+* Visual Studio:                         Building with Microsoft Visual Studio.
+                                                              (line   6)
 * Web page:                              Introduction to MPIR.
                                                              (line  30)
 * Windows <1>:                           MPIR on Windows x64. (line   6)
 * Windows:                               Notes for Particular Systems.
                                                              (line  34)
 * x86:                                   Notes for Particular Systems.
-                                                              (line 139)
+                                                              (line 110)
 * x87:                                   Notes for Particular Systems.
                                                              (line  25)
 * XML:                                   Build Options.       (line 359)
--- a/doc/mpir.texi
+++ b/doc/mpir.texi
@ -570,6 +570,7 @@ reports.
 * Build Options::
 * ABI and ISA::
 * Notes for Package Builds::
+* Building with Microsoft Visual Studio::
 * Notes for Particular Systems::
 * Known Build Problems::
 * Performance optimization::
@ -1276,7 +1277,7 @@ cross-compile, for example


@need 2000
-@node Notes for Package Builds, Notes for Particular Systems, ABI and ISA, Installing MPIR
+@node Notes for Package Builds, Building with Microsoft Visual Studio, ABI and ISA, Installing MPIR
@section Notes for Package Builds
@cindex Build notes for binary packaging
@cindex Packaged builds
@ -1346,9 +1347,149 @@ desired ABI@.  If compiler include paths don't vary with ABI options then it
 might be necessary to create a @file{/usr/include/mpir.h} which tests
 preprocessor symbols and chooses the correct actual @file{mpir.h}.

+@need 2000
+@node Building with Microsoft Visual Studio, Notes for Particular Systems, Notes for Package Builds, Installing MPIR
+@section Building with Microsoft Visual Studio 
+@cindex Build notes for MSVC
+@cindex MSVC
+@cindex Visual Studio
+
+MPIR can be built with the professional and higher versions of Microsoft
+Visual Studio 2010, 2012 and 2013.  It can also be built with Visual 
+Studio Express 2013 for Windows Desktop.  In addition to one of these
+versions of Visual Studio, Python 3 and the YASM assembler will need
+to be installed if the assembler optimised versions are required. if
+installed, MPIR can also be built with the Intel compiler that can be
+integrated into tne full versions of Visual Studio.
+
+Python can be obtained from:
+
+@display
+@uref{https://www.python.org/}
+@end display
+
+and the YASM assembler is available here:
+
+@display
+@uref{http://yasm.tortall.net/Download.html}
+@end display
+
+This assembler (@file{vsyasm.exe}, NOT @file{yasm.exe}) should be placed in the 
+binary directory used by the Visual Studio version in use, which should be one
+of:
+
+@display
+@file{C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin}
+@file{C:\Program Files (x86)\Microsoft Visual Studio 11.0\VC\bin}
+@file{C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin}
+@end display
+
+Alternatively @file{vsyasm.exe} can be placed elsewhere provided that the
+environment variable @samp{YASMPATH} gives its location.
+
+@table @asis
+
+@item Building MPIR
+
+A build of MPIR is started by double clicking on the file @file{mpir.sln}
+in the appropriate sub-directory within the MPIR root directory:
+
+@example
+    Visual Studio 2010:  mpir/build.vc10/mpir.sln
+    Visual Studio 2012:  mpir/build.vc11/mpir.sln
+    Visual Studio 2013:  mpir/build.vc12/mpir.sln
+@end example
+    
+Visual Studio will then display a list of individual build projects
+from which an appropriate version of MPIR can be built. For example,
+a typical list of projects:
+
+@example
+    dll_mpir_gc     standard DLL, no assembler (win32 and x64)
+    dll_mpir_p3     assembly optimised DLL for pentium 3 (win32)
+    lib_mpir_p3     assembly optimised static library for 
+                    pentium 3 (x64)
+    lib_mpir_core2  assembly optimised static library for 
+                    core2 (x64)
+    dll_mpir_core2  assembly optimised DLL for core2 (x64)
+@end example
+
+allows MPIR to be built either as a static library or as a DLL. A DLL will
+include both the C and C++ features of MPIR but a static library will include
+only the C features so in this case the project:
+
+@example
+  lib_mpir_cxx     the MPIRXX C++ static library (win32 and x64)
+@end example
+
+should also be built to provide the MPIR C++ static library (@samp{MPIRXX}).
+
+Before a project is built, Visual Studio should be set to the required 
+configuration (Release or Debug) and the required target architecture 
+(win32 or x64).  The build process puts the output files into one of the
+two sub-directories:
+
+@display
+@file{mpir/lib} 
+@file{mpir/dll} 
+@end display
+    
+depending on whether static library or DLL versions have been built.
+
+@item Additional Assembler Optimised Versions
+
+The Visual Studio builds for MPIR are initially provided with a small set
+of assembler optimised projects but many more are available and can be
+obtained by running the Python program @command{mpir_config.py} that is in the
+appropriate build sub-directory for the version of Visual Studio in use. 
+This program is run before Visual Studio is used and provides a list of
+all the assembler optimised versions that are available.  Any number can
+be chosen and these builds will then be available when Visual Studio is
+subsequently opened by double clicking on @file{mpir.sln}.
+
+@item Testing Visual Studio versions of MPIR 
+
+Testing a version of the library once it has been built is started by double
+clicking on the appropriate solution file:
+
+@example
+    Visual Studio 2010:  mpir/build.vc10/mpir-tests.sln
+    Visual Studio 2012:  mpir/build.vc11/mpir-tests.sln
+    Visual Studio 2013:  mpir/build.vc12/mpir-tests.sln
+@end example
+
+The tests are always run on the last version of MPIR built and it is important
+to set the configuration for the tests (Release or Debug, win32 or x64) to be 
+the same as that used to build MPIR.  After loading there will be a large list
+of test projects starting:
+
+@example
+  Solution `mpir-tests' (202 projects)
+        add-test-lib 
+        bswap
+        constants
+        ....
+@end example
+      
+The project @samp{add-test-lib} should be selected and built first, after which 
+the solution as a whole (i.e. the first line shown above) can be selected to 
+build all the tests.  After the build has completed, the tests are run by 
+executing the Python program @command{run-tests.py} in the appropriate Visual 
+Studio build sub-directory, for example, for Visual Studio 2013:
+
+@example
+   mpir/build.vc12/mpir-tests/run-tests.py 
+@end example
+
+@item Further Details
+
+Additional details can be found in the @file{readme.txt} files in the 
+appropriate Visual Studio build sub-directories.
+
+@end table

@need 2000
-@node Notes for Particular Systems, Known Build Problems, Notes for Package Builds, Installing MPIR
+@node Notes for Particular Systems, Known Build Problems, Building with Microsoft Visual Studio, Installing MPIR
@section Notes for Particular Systems
@cindex Build notes for particular systems
@cindex Particular systems
@ -1400,7 +1541,7 @@ affects all code, including application code, not just MPIR.
@cindex Windows
@cindex Cygwin
@cindex MINGW
-On an MS Windows system Cygwin and MINGW can be used , they 
+On an MS Windows system Cygwin and MINGW can be used, they 
 are ports of GCC and the various GNU tools.

@display
@ -1408,37 +1549,8 @@ are ports of GCC and the various GNU tools.
@uref{http://www.mingw.org/}
@end display

-Cygwin is a 32 bit build only but mingw is 32 or 64 bit build. Depending on how
-the mingw tools are installed will determine the best procedure for building ,
-because of the large number of ways this can be achieved it is best to search
-the MPIR devel mailing list or the mingw mailing list.
-
-For building with MSVC we provide a number of ways.
-
-In addition, project files for MSVC are provided, allowing MPIR to 
-build on Microsoft's compiler. For Visual Studio 2010 see the readme.txt 
-file in the build.vc10
-directory. The MSVC projects provides full assembler support and for
-@samp{x86_64} CPU's this will produce far superior results. These project
-files can also be accessed via the command line with the batch files 
-@samp{configure.bat} and @samp{make.bat} which have a @samp{unix like}
-interface , however they are not very well tested and are due to be replaced.
-
-An another alternative is @samp{configure} and @samp{make} in the @samp{win} 
-directory , these again have a @samp{unix like} syntax , these are tested 
-regularly and also have the advantage of working with VS2005 and up (including
-the free/express versions). There is some auto detection of the compiler , but it's
-probably best to set it explicity using the usual 
-@samp{call "%VS90COMNTOOLS%\..\..\VC\vcvarsall.bat" amd64} in the command window.
-The program @samp{YASM} is also required and should be in path or the @samp{%YASMPATH%}
-varible set.
-If @samp{configure} guesses wrong , close the window and try again changing the @samp{ABI=...}
-selection and or the @samp{vcvarsall.bat} options.
-@samp{make} supports the usual @samp{clean} and @samp{check} options .
-The @samp{only} bug is that shared library builds @samp{dll's} fail the make check
-in the C++ parts for @samp{istream} and @samp{ostream} with some unresolved
-symbols.
-
+Both 32 and 64 bit versions of MinGW and Cygwin are supported. Building on these
+systems is very similar to building on Linux. 

@item MS Windows DLLs
@cindex DLLs