SLEEF - Compiling and installing the library

Table of contents

Preliminaries

In order to build SLEEF, you need CMake, which is an open-source and cross-platform building tool. In order to test the library, it is better to have the GNU MPFR Library, Libssl and FFTW.

CMake 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). If you are not already familiar with cmake, please refer to the official documentation or the basic introductions in the wiki.

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.5.1.

$ cmake --version

2. Checkout out the source code from our 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 ..

See the list of options and variables for customizing your build.

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

$ make

6. You can execute the tests by running:

$ make test

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

$ make install

Common CMake variables

Below is the list of common cmake variables that are used to configure a build for SLEEF.

SLEEF-specific CMake variables

Below is the list of SLEEF-specific cmake variables.

Compiling and installing the library on Linux

In order to build the library, you need to install OpenMP. In order to test the library, you need to install libmpfr, libssl and libfftw3. Availability of these libraries are checked upon execution of cmake. Please change the directory to sleef-3.X and run the following commands.

$ sudo apt-get install libmpfr-dev libssl-dev libfftw3-dev
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr ..
$ make
$ make test
$ sudo make install

Parallel build is only supported with Ninja.


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

$ sudo xargs rm -v < install_manifest.txt

Building the library with LTO support

You can build the library with link time opimization(LTO) support with the following commands. Note that you can only build static libraries with LTO support. You also have to use the same compiler with the same version to build the library and other source codes.

$ CC=gcc cmake -DBUILD_SHARED_LIBS=FALSE -DENABLE_LTO=TRUE ..

In order to build the library with thinLTO support with clang, you need to specify LLVM AR command that exactly corresponds to the clang compiler.

$ CC=clang-9 cmake -DBUILD_SHARED_LIBS=FALSE -DENABLE_LTO=TRUE -DLLVM_AR_COMMAND=llvm-ar-9 ..

Building the header files for inlining the whole SLEEF functions

Header files for inlining the whole SLEEF functions can be built with the following commands. With these header files, it may be easier to inline the whole SLEEF functions than using LTO. You have to specify "-ffp-contract=off" compiler option when compiling a source code that includes one of these header files.

$ cmake -DBUILD_INLINE_HEADERS=TRUE ..

Compiling the library with Microsoft Visual C++

You need Visual Studio 2019. Open developer command prompt for VS2019 and change directory to sleef-3.X. When configuring a build with cmake, you need to use a specific generator: `cmake -G"Visual Studio 16 2019" ..` This generator will create a proper solution `SLEEF.sln` under the build directory. You can still use `cmake --build .` to build the library without opening Visual Studio.

Below is an example of commands for building SLEEF with Visual Studio.

D:\sleef-3.X> mkdir build
D:\sleef-3.X> cd build
D:\sleef-3.X\build> cmake -G"Visual Studio 15 2017 Win64" ..    &:: If you are using VS2017
D:\sleef-3.X\build> cmake -G"Visual Studio 16 2019" ..          &:: If you are using VS2019
D:\sleef-3.X\build> cmake --build . --config Release -- /maxcpucount:1

Compiling the library with Clang on Windows

You need Visual Studio 2019. Install ninja via VS2019 installer. Download and install clang on Windows from llvm.org. Below is an example of commands for building SLEEF with Clang on Windows.

D:\sleef-3.X> "c:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
D:\sleef-3.X> mkdir build
D:\sleef-3.X> cd build
D:\sleef-3.X\build> cmake -GNinja -DCMAKE_C_COMPILER:PATH="C:\Program Files\LLVM\bin\clang.exe" ..
D:\sleef-3.X\build> ninja

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.5.1)
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

Cross compilation for iOS and Android

SLEEF has preliminary support for iOS and Android. Here, "preliminary" means that the library is only tested to be built, but not tested to work correctly on the real devices. In order to cross compile the library, you need a cmake tool chain file for the corresponding OS. The tool chain file for iOS can be downloaded from https://github.com/leetal/ios-cmake. The tool chain file for Android is included in the SDK. You first need to build the library for the host computer, then for the target OS. Below is an example sequence of commands for cross compiling the library for iOS.

$ mkdir build-native
$ cd build-native
$ cmake -GNinja ..
$ ninja
$ cd ..
$ mkdir build-cross
$ cd build-cross
$ cmake -GNinja -DCMAKE_TOOLCHAIN_FILE=../ios.toolchain.cmake -DNATIVE_BUILD_DIR=`pwd`/../build-native -DDISABLE_MPFR=TRUE -DDISABLE_SSL=TRUE ..
$ ninja

Below is an example sequence of commands for cross compiling the library for Android.

$ mkdir build-native
$ cd build-native
$ cmake -GNinja ..
$ ninja
$ cd ..
$ mkdir build-cross
$ cd build-cross
$ cmake -GNinja -DCMAKE_TOOLCHAIN_FILE=/opt/android-ndk-r21d/build/cmake/android.toolchain.cmake -DNATIVE_BUILD_DIR=`pwd`/../build-native -DANDROID_ABI=arm64-v8a ..
$ ninja