# Scytl Math Library
Scytl Math Library provides some useful mathematical primitives for projects being developed in Scytl. It also provides native optimization for some important functions from the standard Java library.

## Development

### Java code vs native code
The codebase of Scytl Math contains both Java and native code.

The Java code provides public API to be used in other projects. It also provides pure Java implementation for all API it defines.

The native code only provides optimization for some critical operations like `BigInteger.modPow`. The native code is optional by design, it is not mandatory neither for building dependent projects nor in runtime. If the Java code cannot load the native code via standard JNI mechanism it uses pure Java implementation as a fallback.

It is very important to keep the native code optional. That is why Java and native code are developed in separate modules `scytl-math` and `scytl-math-native`. The first one is an ordinary `jar` module and the second is a `nar` module to be built with `nar-maven-plugin`.     

### How to build
#### Prerequisites
Currently Scytl Math can be build for 64bit Linux and Windows only. The following steps should be performed to prepare the build infrastructure

*   Install Oracle JDK 1.8.
*   Define `JAVA_HOME` environment property pointing to the root of JDK installation.
*   Add `$JAVA_HOME/bin` (`%JAVA_HOME%\bin` on Windows) to `PATH` if necessary.
*   Install Maven 3.2.x. 
*   Add the `bin` subfolder of the Maven installation folder to `PATH`. 
*   **Linux:** Make sure that `gcc` and `make` are fresh and properly installed.
*   **Windows:** Download 64bit MSYS2 from <https://sourceforge.net/projects/msys2/>.
*   **Windows:** Install 64bit MSYS2 into a folder without spaces, for example, `C:\msys64`.
*   **Windows:** Add `C:\msys64\usr\bin` to `PATH`.
*   **Windows:** Open command prompt and install `make` package with command

```
packman -S make
```

*   **Windows:** Download 64bit MinGW from <https://sourceforge.net/projects/mingw-w64/>.
*   **Windows:** Install 64bit MinGW into a folder without space, for example, `C:\mingw-w64`. **Warning! It is very important to choose x86_64 architecture during installation, by default the installer suggests i586.**
*   **Windows:** Add `C:\mingw-64\x86_64-x.x.x-posix-seh-rt_v4-rev0\mingw64\bin` to `PATH`.
*   **Windows:** Check your environment using the commands  
```
bash
java -v
javah -h
gcc -v
make -v
```

#### Default build
The default build is performed using Scytl's Maven repository and standard Maven commands like `mvn clean package` or `mavn clean install`. The native code will be built for the host machine only.

#### Custom build
Custom build is used when the customer wants to use a special build of GMP library. It is possible to perform the build without Scytl's Maven repository but in such a case the following artifact must be copied to local or public Maven repository

*   `com.scytl.gmp:scytl-gmp:x.x.x`
*   `com.github.maven-nar:nar-maven-plugin:3.5.1-scytl`

To perform the custom build use a command of the following from

```
mvn clean package -P custom -Dgmp.include.dir=<folder with gmp.h> -Dgmp.lins.dir==<folder with libgmp.so or libgmp.dll>
```

 The native code will be built for the host machine only.

#### Publishing to Maven repository
To publish Scytl Math in public Maven repository do the follwing

*   Build Scytl Math on a Linux machine.
*   Build Scytl Math on Windows machine.
*   Gather all the artifacts in a single place. If two artifacts have the same name choose the one from from Linux.
*   Publish the artifacts with a single Maven command using `maven-deploy` plugin.  


### Some useful tools
The following tools may be useful:

*   The `tools` folder of the project repository contains the definitions of code style and code format to be imported into IDE.
*   Java system property `-Dcom.scytl.math.jni.debug=true` allows to detect if there are problems with JNI.
*   **Linux:** `nm` and `ldd` commands help to investigate problems with JNI.  
*   **Windows:** `Dependency Walker` (<http://www.dependencywalker.com/>) utility helps to investigate problems with JNI.

## Usage
To use Scytl Math in other projects add to `pom.xml` a dependency like the following

``` xml
<dependency>
    <groupId>com.scytl.math</groupId>
    <artifactId>scytl-math</artifactId>
    <version>${scytl.math.version}</version>
</dependency>
```

## Deployment

### Standalone application
To deploy Scytl Math with a standalone application just make `scytl-math-x.x.x.jar` a part of the application's classpath. If the application requires native optimization then do the following

*   Obtain the corresponding version of GNU MP library. If the generic binary is good enough then download `nar` archive of Scytl GMP Library from Maven repository and extract the required binary. Otherwise download the source from <https://gmplib.org> and build it.
*   Obtain the corresponding native part of Scytl Math. If the generic binary is good enough then download `nar` archive of Scytl Math from Maven repository and extract the required binary. Otherwise download the source from Git repository and perform a custom build against the custom build of GMP as described above.
*   Place the GMP library where the operation system can find and load it.
*   Place the Scytl Math native library `libscytl-math.so` (`scytl-math.dll` on Windows) where Java can find and load it using standard JNI mechanism. Native library from `nar` can have a slightly different name, rename it if necessary or create a symbolic link. Use environment properties `LD_LIBRARY_PATH` or `PATH` or Java system property `-Djava.library.path` to specify where Java can find the Scytl Math native library. 

### Managed application
Normally managed applications should use a Scytl Math instance deployed as a shared library. However if native optimization is not required then it is possible to make `scytl-math-x.x.x.jar` a part of the application's archive. To deploy Scytl Math to the application server treat the application server as a standalone application and apply the procedure described above.