SLEEF Documentation

# SLEEF Documentation - Compiling and installing the library

## Table of contents

- Introduction
- Compiling and installing the library

- About CMake
- Compiling and installing library on Linux
- Compiling library with Microsoft Visual C++
- Compiling and running "Hello SLEEF"
- Importing SLEEF into your project

- Math library reference
- DFT library reference
- Other tools included in the package
- Benchmark results
- Additional notes

## About CMake

CMake is an open-source and cross-platform building tool for software packages that provides easy managing of multiple build systems at a time. It works by allowing the developer to specify build parameters and rules in a simple text file that cmake then processes to generate project files for the actual native build tools (e.g. UNIX Makefiles, Microsoft Visual Studio, Apple XCode, etc). That means you can easily maintain multiple separate builds for one project and manage cross-platform hardware and software complexity.

If you are not already familiar with cmake, please refer to the official documentation or the basic introductions in the wiki (recommended).

Before using CMake you will need to install/build the binaries on your system. Most systems have cmake already installed or provided by the standard package manager. If that is not the case for you, please download and install now. For building SLEEF, version 3.4.3 is the minimum required.

### Quick start

1. Make sure cmake is available on the command-line. The command below should display a version number greater than or equal to 3.4.3.

    $ cmake --version

2. Download the tar from the software repository or checkout out the source code from the GitHub repository.

    $ git clone https://github.com/shibatch/sleef

3. Make a separate directory to create an out-of-source build. SLEEF does not allow for in-tree builds.

    $ cd sleef
    $ mkdir build && cd build

4. Run cmake to configure your project and generate the system to build it:

    $ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    	-DCMAKE_INSTALL_PREFIX=../my-sleef-install \
    	..

This flag configures an optimised libsleef shared library build with basic debug info. By default, cmake will autodetect your system platform and configure the build using the default parameters. You can control and modify these parameters by setting variables when running cmake. See the list of options and variables for customizing your build.

NOTE: On Windows, you need to use a specific generator like this: `cmake -G"Visual Studio 15 2017 Win64" ..` specifying the Visual Studio version and targeting specifically `Win64` (to support compilation of AVX/AVX2) Check `cmake -G` to get a full list of supported Visual Studio project generators. This generator will create a proper solution `SLEEF.sln` under the build directory. You can still use `cmake --build .` to build without opening Visual Studio.

5. Now that you have the build files created by cmake, proceed from the top of the build directory:

    $ make

6. Install the library under ../my-sleef/install by running:

    $ make install

7. You can execute the tests by running:

    $ make test

### Build customization

Variables dictate how the build is generated; options are defined and undefined, respectively, on the cmake command line like this:

- cmake -DVARIABLE=<value> <cmake-build-dir>
- cmake -UVARIABLE <cmake-build-dir>

Build configurations allow a project to be built in different ways for debug, optimized, or any other special set of flags.

#### CMake Variables

- `CMAKE_BUILD_TYPE`: By default, CMake supports the following configuration:

- `Release`: Basic optimizations are turned on. This is the default setting.
- `Debug`: Basic debug flags are turned on. Optimization is disabled.
- `MinSizeRel`: Builds the smallest (but not fastest) object code
- `RelWithDebInfo`: Builds optimized code with debug information as well

- `CMAKE_INSTALL_PREFIX` : The prefix it uses when running `make install`. Defaults to /usr/local on GNU/Linux and MacOS. Defaults to C:/Program Files on Windows.
- `CMAKE_C_FLAGS_RELEASE` : The optimization options used by the compiler.
- `BUILD_TESTS` : Avoid building testing tools if set to FALSE
- `BUILD_GNUABI_LIBS` : Avoid building libraries with GNU ABI if set to FALSE
- `BUILD_DFT` : Avoid building DFT libraries if set to FALSE
- `BUILD_SHARED_LIBS` : Static libs are built if set to FALSE
- `SLEEFDFT_MAXBUTWIDTH` : This variable specifies the maximum length of combined butterfly block used in the DFT. Setting this value to 7 makes DFT faster but compilation takes more time and the library size will be larger.

## Compiling and installing library on Linux

You need to install libmpfr and OpenMP(libmpfr is only required to build the tester, and it is not linked to the library). In order to build the library, please change the directory to sleef-3.X and run the following commands.

    $ mkdir build
    $ cd build
    $ cmake -DCMAKE_INSTALL_PREFIX=/usr ..
    $ make
    $ make test
    $ sudo make install

In order to uninstall the libraries and headers, run the following command.

    $ sudo xargs rm -v < install_manifest.txt

## Compiling library with Microsoft Visual C++

You need Visual Studio 2017. Open developer command prompt for VS2017, change directory to sleef-3.X, and then run the following commands.

    D:\sleef-3.X> mkdir build
    D:\sleef-3.X> cd build
    D:\sleef-3.X\build> cmake -G"Visual Studio 15 2017 Win64" ..
    D:\sleef-3.X\build> cmake --build . --config Release -- /maxcpucount:1

Note that parallel build is not supported on MSVC.

## Compiling and running "Hello SLEEF"

Now, let's try compiling the source code shown in Fig. 2.1.

    #include <stdio.h>
    #include <x86intrin.h>
    #include <sleef.h>

    int main(int argc, char **argv) {
      double a[] = {2, 10};
      double b[] = {3, 20};

      __m128d va, vb, vc;

      va = _mm_loadu_pd(a);
      vb = _mm_loadu_pd(b);

      vc = Sleef_powd2_u10(va, vb);

      double c[2];

      _mm_storeu_pd(c, vc);

      printf("pow(%g, %g) = %g\n", a[0], b[0], c[0]);
      printf("pow(%g, %g) = %g\n", a[1], b[1], c[1]);
    }

Fig. 2.1: Source code for testing

Fig.2.2 shows typical commands for compiling and executing the hello code on Linux computers.

    $ gcc hellox86.c -o hellox86 -lsleef
    $ ./hellox86
    pow(2, 3) = 8
    pow(10, 20) = 1e+20
    $ █

Fig. 2.2: Commands for compiling and executing hellox86.c

You may need to set LD_LIBRARY_PATH environment variable appropriately. If you are trying to execute the program on Mac OSX or Windows, try copying the DLLs to the current directory.

## Importing SLEEF into your project

Below is an example CMakeLists.txt for compiling the above hellox86.c. CMake will automatically download SLEEF from GitHub repository, and thus there is no need to include SLEEF in your software package. If you prefer importing SLEEF as a submodule in git, you can use SOURCE_DIR option instead of GIT_REPOSITORY option for ExternalProject_Add.

    cmake_minimum_required(VERSION 3.4.3)
    include(ExternalProject)
    find_package(Git REQUIRED)

    ExternalProject_Add(libsleef
      GIT_REPOSITORY https://github.com/shibatch/sleef
      CMAKE_ARGS -DCMAKE_INSTALL_PREFIX=${CMAKE_BINARY_DIR}/contrib
    )

    include_directories(${CMAKE_BINARY_DIR}/contrib/include)
    link_directories(${CMAKE_BINARY_DIR}/contrib/lib)

    add_executable(hellox86 hellox86.c)
    add_dependencies(hellox86 libsleef)
    target_link_libraries(hellox86 sleef)

Fig. 2.3: Example CMakeLists.txt