306 lines
16 KiB
XML
306 lines
16 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<topic id="846f5c8a-6cba-433e-9f18-cde2ff5695cd" revisionNumber="1">
|
|
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
|
|
<introduction>
|
|
<para>
|
|
The <legacyBold>GMP Native Interface for .NET Library</legacyBold> exposes to .NET (through P-Invoke and .NET types)
|
|
all of the functionality of the
|
|
<externalLink>
|
|
<linkText>GNU MP Library</linkText>
|
|
<linkUri>https://gmplib.org/</linkUri>
|
|
<linkTarget>_self</linkTarget>
|
|
</externalLink>
|
|
(version 6.1.2). It automatically loads at runtime the 32-bit or 64-bit GNU MP library that matches the current CPU
|
|
architecture, thus allowing building Visual Studio Projects for Any CPU, x86, or x64.
|
|
It is based on the GNU MP "fat" build which automatically detects the current CPU type, and selects any available
|
|
assembly language code optimization for that CPU, thus providing best performance.
|
|
</para>
|
|
</introduction>
|
|
|
|
<section>
|
|
<title>Source Code</title>
|
|
<content>
|
|
<para>
|
|
The source code of the library is available on
|
|
<externalLink>
|
|
<linkText>GitHub</linkText>
|
|
<linkUri>https://github.com/</linkUri>
|
|
<linkTarget>_self</linkTarget>
|
|
</externalLink>
|
|
in the project
|
|
<externalLink>
|
|
<linkText>Math.Gmp.Native</linkText>
|
|
<linkUri>https://github.com/MachineCognitis/Math.Gmp.Native</linkUri>
|
|
<linkTarget>_self</linkTarget>
|
|
</externalLink>.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
|
|
<section>
|
|
<title>NuGet Package</title>
|
|
<content>
|
|
<para>
|
|
You can use the library by loading it from the
|
|
<externalLink>
|
|
<linkText>NuGet</linkText>
|
|
<linkUri>https://www.nuget.org/</linkUri>
|
|
<linkTarget>_self</linkTarget>
|
|
</externalLink>
|
|
package
|
|
<externalLink>
|
|
<linkText>Math.Gmp.Native.NET</linkText>
|
|
<linkUri>https://www.nuget.org/packages/Math.Gmp.Native.NET/</linkUri>
|
|
<linkTarget>_self</linkTarget>
|
|
</externalLink>.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<content>
|
|
<para>
|
|
The <codeEntityReference autoUpgrade="true">T:Math.Gmp.Native.gmp_lib</codeEntityReference> class has a static
|
|
method for each one of the GNU MP functions.
|
|
Other types are defined to mimic struct's and typedef's of the GNU MP and C libraries, as well as C language
|
|
constructs such as <codeInline>char *</codeInline> and <codeInline>void *</codeInline>.
|
|
</para>
|
|
<para>
|
|
The GMP Native Interface for .NET Library relies on pre-built 32-bit and 64-bit versions of the GNU MP Library.
|
|
Instructions for building the GNU MP Library on Windows are given below.
|
|
</para>
|
|
<para>
|
|
For convenience, this help file has been created from the GNU MP manual version 6.1.2. It shows with examples
|
|
how each GNU MP function is called in .NET. For an introduction to GNU MP, refer to the
|
|
<externalLink>
|
|
<linkText>GNU MP Manual</linkText>
|
|
<linkUri>https://gmplib.org/manual/</linkUri>
|
|
<linkTarget>_self</linkTarget>
|
|
</externalLink>.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
|
|
<section>
|
|
<title>C and .NET Types Equivalence</title>
|
|
<content>
|
|
<para>
|
|
The table below shows how each C type maps to .NET.
|
|
Note that the <codeEntityReference autoUpgrade="true">T:Math.Gmp.Native.mp_limb_t</codeEntityReference>
|
|
and <codeEntityReference autoUpgrade="true">T:Math.Gmp.Native.size_t</codeEntityReference> C types map
|
|
to the CPU word, i.e., 32 or 64 bits.
|
|
In particular, because <codeEntityReference autoUpgrade="true">T:Math.Gmp.Native.mp_limb_t</codeEntityReference>
|
|
is the type of the integers that make up multi-precision numbers, matching the CPU word size ensures
|
|
maximum performance.
|
|
Unless you intend to use low-level (mpn) functions, you do not need to take into account the
|
|
CPU word size, and can build for the "Any CPU" platform.
|
|
</para>
|
|
<table>
|
|
<tableHeader>
|
|
<row>
|
|
<entry><para>C Types</para></entry>
|
|
<entry><para>.NET Types</para></entry>
|
|
</row>
|
|
</tableHeader>
|
|
<row>
|
|
<entry><para>short</para></entry>
|
|
<entry><para>Int16 / short (C#) / Short (VB.NET)</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para>int</para></entry>
|
|
<entry><para>Int32 / int (C#) / Integer (VB.NET)</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para>long</para></entry>
|
|
<entry><para>Int32 / int (C#) / Integer (VB.NET)</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para>long long</para></entry>
|
|
<entry><para>Int64 / long (C#) / Long (VB.NET)</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para><codeEntityReference autoUpgrade="true">T:Math.Gmp.Native.mp_bitcnt_t</codeEntityReference></para></entry>
|
|
<entry><para>UInt32 / uint (C#) / UInteger (VB.NET)</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para><codeEntityReference autoUpgrade="true">T:Math.Gmp.Native.mp_exp_t</codeEntityReference></para></entry>
|
|
<entry><para>Int32 / int (C#) / Integer (VB.NET)</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para><codeEntityReference autoUpgrade="true">T:Math.Gmp.Native.mp_size_t</codeEntityReference></para></entry>
|
|
<entry><para>Int32 / int (C#) / Integer (VB.NET)</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para><codeEntityReference autoUpgrade="true">T:Math.Gmp.Native.mp_limb_t</codeEntityReference></para></entry>
|
|
<entry><para>UInt32 (on 32-bit CPU) / UInt64 (on 64-bit CPU)</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para><codeEntityReference autoUpgrade="true">T:Math.Gmp.Native.size_t</codeEntityReference></para></entry>
|
|
<entry><para>UInt32 (on 32-bit CPU) / UInt64 (on 64-bit CPU)</para></entry>
|
|
</row>
|
|
</table>
|
|
</content>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Building the GNU MP Library on Windows</title>
|
|
<content>
|
|
<list class="ordered">
|
|
<listItem>
|
|
<para>
|
|
Install <externalLink><linkText>MSYS2</linkText><linkUri>https://github.com/msys2/msys2/wiki/MSYS2-introduction</linkUri><linkTarget>_self</linkTarget></externalLink>.
|
|
</para>
|
|
<para>
|
|
On a 64-bit computer, install <externalLink><linkText>msys2-x86_64-20161025.exe</linkText><linkUri>https://github.com/MachineCognitis/Math.Gmp.Native/blob/master/Math.Gmp.Native/Dependencies/</linkUri><linkTarget>_self</linkTarget></externalLink>,
|
|
and on a 32-bit computer, install <externalLink><linkText>msys2-i686-20161025.exe</linkText><linkUri>https://github.com/MachineCognitis/Math.Gmp.Native/tree/master/Math.Gmp.Native/Dependencies/</linkUri><linkTarget>_self</linkTarget></externalLink>.
|
|
You can also check for a more recent version of MSYS2 <externalLink><linkText>here</linkText><linkUri>https://github.com/msys2/msys2/wiki/MSYS2-installation</linkUri></externalLink>.
|
|
Install MSYS2 to its default location.
|
|
</para>
|
|
<para>
|
|
After installation, you need to updates MSYS2 packages. From the Windows Start Menu, start <command>MSYS2 MSYS</command>. In the shell command window,
|
|
enter the command:
|
|
</para>
|
|
<list class="nobullet">
|
|
<listItem>
|
|
<para>
|
|
<userInput>pacman -Syuu</userInput>
|
|
</para>
|
|
</listItem>
|
|
</list>
|
|
<para>
|
|
and follow instructions.
|
|
You will have to close the command window, reopen a new one, and reenter the command <userInput>pacman -Syuu</userInput>.
|
|
</para>
|
|
<para>
|
|
Finally, in order to build software, you need to install a number of packages with the command:
|
|
</para>
|
|
<list class="nobullet">
|
|
<listItem>
|
|
<para>
|
|
<userInput>pacman -S --needed base-devel mingw-w64-i686-toolchain mingw-w64-x86_64-toolchain git subversion mercurial mingw-w64-i686-cmake mingw-w64-x86_64-cmake</userInput>
|
|
</para>
|
|
</listItem>
|
|
</list>
|
|
<para>
|
|
run from the same command window as in the previous step.
|
|
</para>
|
|
<para>
|
|
To build 32-bit software, use the <command>MSYS2 MinGW 32-bit</command> command from the Windows Start Menu, and
|
|
for 64-bit software, use <command>MSYS2 MinGW 64-bit</command>.
|
|
</para>
|
|
</listItem>
|
|
<listItem>
|
|
<para>
|
|
Install <externalLink><linkText>yasm</linkText><linkUri>http://yasm.tortall.net/Download.html</linkUri><linkTarget>_self</linkTarget></externalLink>.
|
|
</para>
|
|
<para>
|
|
On a 64-bit computer, copy <externalLink><linkText>yasm-1.3.0-win64.exe</linkText><linkUri>https://github.com/MachineCognitis/Math.Gmp.Native/blob/master/Math.Gmp.Native/Dependencies/</linkUri><linkTarget>_self</linkTarget></externalLink>
|
|
to <localUri>C:\msys64\usr\bin</localUri>, and rename it to <localUri>yasm.exe</localUri>.
|
|
</para>
|
|
<para>
|
|
Similarly on a 32-bit computer, copy <externalLink><linkText>yasm-1.3.0-win32.exe</linkText><linkUri>https://github.com/MachineCognitis/Math.Gmp.Native/blob/master/Math.Gmp.Native/Dependencies/</linkUri><linkTarget>_self</linkTarget></externalLink>
|
|
to <localUri>C:\msys32\usr\bin</localUri>, and rename it to <localUri>yasm.exe</localUri>.
|
|
</para>
|
|
</listItem>
|
|
<listItem>
|
|
<para>
|
|
Build <externalLink><linkText>GNU MP</linkText><linkUri>https://gmplib.org/</linkUri><linkTarget>_self</linkTarget></externalLink>.
|
|
</para>
|
|
<para>
|
|
Create folders <localUri>C:\Temp\x86</localUri> and <localUri>C:\Temp\x64</localUri>.
|
|
These are the folder where the compiled 32-bit and 64-bit versions of GNU MP will be installed.
|
|
Unzip <externalLink><linkText>gmp-6.1.2.tar.bz2</linkText><linkUri>https://github.com/MachineCognitis/Math.Gmp.Native/blob/master/Math.Gmp.Native/Dependencies/</linkUri><linkTarget>_self</linkTarget></externalLink>
|
|
in folder <localUri>C:\Temp</localUri>.
|
|
This puts GNU MP in subfolder <localUri>gmp-6.1.2</localUri>.
|
|
</para>
|
|
<para>
|
|
In each one of the command windows openend with the commands <command>MSYS2 MinGW 32-bit</command>
|
|
and <command>MSYS2 MinGW 64-bit</command> from the Windows Start Menu, run the commands below:
|
|
</para>
|
|
<list class="nobullet">
|
|
<listItem>
|
|
<para>
|
|
<userInput>cd /c/Temp/gmp-6.1.2</userInput><markup><br/></markup>
|
|
<userInput>./configure --enable-fat --disable-static --enable-shared --prefix=/c/Temp/x86</userInput> or <userInput>x64</userInput><markup><br/></markup>
|
|
<userInput>make</userInput><markup><br/></markup>
|
|
<userInput>make check</userInput><markup><br/></markup>
|
|
<userInput>make install</userInput><markup><br/></markup>
|
|
</para>
|
|
</listItem>
|
|
</list>
|
|
<para>
|
|
The <userInput>--prefix</userInput> specifies the install folder.
|
|
Note that the Windows <localUri>C:\</localUri> drive is specified as the root <localUri>/C/</localUri> folder in the <command>MinGW</command> window.
|
|
Note also that the <userInput>configure</userInput> and <userInput>make</userInput> commands are to be run against a fresly uncompressed GNU MP source.
|
|
The <userInput>make install</userInput> command creates <localUri>libgmp-10.dll</localUri> in the <localUri>C:\Temp\x86</localUri> and <localUri>C:\Temp\x64</localUri> folders.
|
|
These two compiled versions of the GNU MP library are to be copied to the <localUri>x86</localUri> and <localUri>x64</localUri> folders of the <localUri>Math.Gmp.Native</localUri> Visual Studio projects.
|
|
They can also be copied directly into the <localUri>x86</localUri> and <localUri>x64</localUri> folders of the <localUri>bin/Debug</localUri> or <localUri>bin/Release</localUri> folders.
|
|
</para>
|
|
<para>
|
|
The 32-bit and 64-bit <userInput>make check</userInput> commands generate some warnings, but all tests passed successfully.
|
|
</para>
|
|
</listItem>
|
|
</list>
|
|
</content>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Building the GNU MP Library for a Specific CPU Type on Windows</title>
|
|
<content>
|
|
<para>
|
|
The <userInput>--enable-fat</userInput> build option above creates a library where optimized low level subroutines are chosen at runtime according to the CPU detected.
|
|
By using instead the <userInput>--host</userInput> option, you can build a library for a specific CPU type.
|
|
You will end up with a library that runs only on that CPU type, but the library will be samller.
|
|
See the <externalLink><linkText>Build Options</linkText><linkUri>https://gmplib.org/manual/Build-Options.html#Build-Options/</linkUri><linkTarget>_self</linkTarget></externalLink> from the GNU MP Manual for the supported CPU types.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Using the GNU MP Library in a Visual Studio C++ Project</title>
|
|
<content>
|
|
<para>
|
|
Although our main goal was to compile GNU MP in order to use it from .NET, the compiled 32-bit and 64-bit GNU MP libraries may be used directly in Visual Studio C++ projects.
|
|
For example, create a default Visual Studio C++ Console Application.
|
|
Set the <system>Platform</system> to <system>x64</system>.
|
|
Copy from the <localUri>C:\Temp\x64</localUri> folder the files <localUri>include\gmp.h</localUri>, <localUri>bin\libgmp-10.dll</localUri>, and <localUri>lib\libgmp.dll.a</localUri> to the Visual Studio C++ project folder.
|
|
Include <localUri>gmp.h</localUri> in your C++ source file.
|
|
In the <system>Linker</system>, <system>Input Property Page</system> of the project, add <localUri>libgmp.dll.a</localUri> to the <system>Additional Dependencies</system>.
|
|
Build your C++ project, and copy <localUri>libgmp-10.dll</localUri> to the output <localUri>bin</localUri> folder.
|
|
Run your application.
|
|
</para>
|
|
<para>
|
|
See <externalLink><linkText>ConsoleApplication12.zip</linkText><linkUri>https://github.com/MachineCognitis/Math.Gmp.Native/blob/master/Math.Gmp.Native/Dependencies/</linkUri><linkTarget>_self</linkTarget></externalLink>
|
|
for a sample Visual Studio C++ project.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
|
|
<relatedTopics>
|
|
<externalLink>
|
|
<linkText>MSYS2</linkText>
|
|
<linkUri>https://github.com/msys2/msys2/wiki/MSYS2-introduction</linkUri>
|
|
<linkTarget>_self</linkTarget>
|
|
</externalLink>
|
|
<externalLink>
|
|
<linkText>yasm</linkText>
|
|
<linkUri>http://yasm.tortall.net/Download.html</linkUri>
|
|
<linkTarget>_self</linkTarget>
|
|
</externalLink>
|
|
<externalLink>
|
|
<linkText>GNU MP</linkText>
|
|
<linkUri>https://gmplib.org/</linkUri>
|
|
<linkTarget>_self</linkTarget>
|
|
</externalLink>
|
|
<externalLink>
|
|
<linkText>Math.Gmp.Native on GitHub</linkText>
|
|
<linkUri>https://github.com/MachineCognitis/Math.Gmp.Native</linkUri>
|
|
<linkTarget>_self</linkTarget>
|
|
</externalLink>
|
|
</relatedTopics>
|
|
|
|
</developerConceptualDocument>
|
|
</topic>
|