Skip to content

Building and Installing

Karen Sawrey edited this page May 20, 2019 · 14 revisions

Building Themis

The easiest way to install Themis is to use package repositories. Themis Core library can be installed into your system from Cossack Labs repositories. High-level language wrappers can be installed from language-specific repositories.

Most language wrappers (except those for mobile) require Themis Core library to be installed in the system. Make sure to install the core library and its dependencies before installing the language wrappers.

Package repositories contain stable versions of Themis, prebuilt and packaged for the most widely-used systems. If you need the latest development version of Themis, you can build and install Themis from GitHub source code.

If your system or package manager is not supported yet, please let us know via dev@cossacklabs.com.

Building Themis on your own machine

To build Themis on your own machine, you will need some common UNIX build tools:

  • C compiler: GCC or Clang,
  • GNU make.

Themis also requires either OpenSSL, LibreSSL, or BoringSSL package to be installed for you to be able to use one of them as a cryptographic backend.

Attention! You need to install the developer version of the package (usually suffixed with -dev or -devel) as it contains the necessary header files.

In either case, we strongly recommend that you use the most recent version of these packages.

Themis with Docker

Building Themis on your own machine is the typical way of building Themis. If you're building Themis to use it with Android, you may consider an alternative variant and build Themis with Docker. If you have Docker and you just want to build Themis quickly (and especially if you want to build Themis for Android), you can use our prebuilt android-build image. Use:

docker run --rm -it -v $(pwd):/projects cossacklabs/android-build bash -c 'git clone https://github.com/cossacklabs/themis.git && cd themis'

This command will download and run ubuntu:16.04 image with pre-installed compilers, OpenSSL, and BoringSSL libraries – comes very handy when you don't want to build on your real machine.

Building Themis Core

No matter what you have selected on the previous step – your own machine or Docker – you need to start with getting the latest version of Themis from GitHub:

git clone https://github.com/cossacklabs/themis.git

From the source directory, type:

make install

(Depending on your rights, sudo might be necessary for installation.)

This should work for the most common case: building Themis with the default configuration and installing it to the system-default location.

Makefile targets

Themis comes with a Makefile that should serve you well for all the typical use cases and goals.

Here are some of the targets supported by the Makefile:

  • make install — build and install Themis Core headers and libraries in the system,
  • make all — build Themis libraries, but do not install them,
  • make themis_shared — only build the shared Themis library,
  • make themis_static — only build the static Themis library,
  • make test — build and run Themis Core test suite,
  • make clean — remove the build directory with intermediate files.

Makefile configuration

Most of Themis configuration is guessed automatically from your system environment. There is no separate ./configure step, everything comes prepared in advance!

However, if you wish to customise some build and installation aspects, Themis Makefile supports a number of configuration variables.

Installation prefix

By default, Themis is installed to the /usr hierarchy (/usr/local on macOS).
To change the installation destination, set the PREFIX variable:

make install PREFIX=/opt/themis

This is what a typical directory structure would look like after a successful installation:

/usr              - installation prefix
├── include
│   ├── themis            - header files
│   │   ├── themis.h
│   │   └── ...
│   └── soter
│       └── ...
│
└── lib
    ├── pkgconfig         - pkg-config support files
    │   ├── libthemis.pc
    │   └── libsoter.pc
    │
    ├── libthemis.a       — compiled libraries
    ├── libsoter.a
    ├── libthemis.so
    └── libsoter.so

Debug builds

By default, Themis libraries are built in release mode. To build Themis in debug mode with debug symbols, set the DEBUG variable:

make DEBUG=yes

Cryptographic backends

Currently, Themis supports OpenSSL-like cryptographic engines (libcrypto):

In the future, we plan to broaden the support of different crypto implementation libraries (and, in some rare cases, provide our own).

You need to install both the engine and its development header files. The packages are usually called libssl and libssl-dev (or -devel).

By default, Themis will build with system default cryptographic engine. If you need to use a custom libcrypto, set these parameters:

  • ENGINE: name of the engine to use (openssl, libressl, boringssl)
  • ENGINE_INCLUDE_PATH: path to the directory with openssl header files
  • ENGINE_LIB_PATH: path to the directory with libcrypto library

For example:

make install \
    ENGINE=libressl \
    ENGINE_INCLUDE_PATH=/opt/libressl-2.8.3/include \
    ENGINE_LIB_PATH=/opt/libressl-2.8.3/lib
BoringSSL

You can opt for BoringSSL by setting ENGINE=boringssl. This will build and use the BoringSSL version embedded into Themis, you don't need to do anything else.
For Android wrapper, Themis currently uses BoringSSL engine by default.

If you wish to use a custom build of BoringSSL, start with reading the instructions at boringssl.googlesource.com. In addition to the ENGINE variable, you need to set the ENGINE_INCLUDE_PATH and ENGINE_LIB_PATH variables, too.
Note that both libcrypto.a and libdecrepit.a have to be put in ENGINE_LIB_PATH.

Building Themis wrappers

Instructions for building wrappers assume that you have a working installation of the relevant language toolchains available via standard system paths.

Android

Using Docker

If you have Docker and you just need to build Themis quickly, you can use our prebuilt android-build image:

docker run --rm -it -v $(pwd):/projects cossacklabs/android-build bash -c 'git clone https://github.com/cossacklabs/themis.git && cd themis && git submodule update --init && ./gradlew assembleRelease'

It will create AAR (Android library project) in the build/outputs/aar/ folder. Link this aar file manually into your application.

Manually from sources

Themis for Android uses Gradle build system.
A Gradle wrapper is included in the root directory of the project. Like the rest of the modern Android ecosystem, Themis uses BoringSSL as its cryptographic backend. BoringSSL is included as a submodule in the Themis repository.

You should install the latest Android SDK tools or Android Studio. You don't need full Android Studio to build Themis, just the command line SDK tools.

Make sure to specify the correct path to your Android SDK:

export ANDROID_HOME=/path/to/android/sdk

Make sure your SDK has the necessary build tools and Android NDK:

$ANDROID_HOME/tools/bin/sdkmanager --update
$ANDROID_HOME/tools/bin/sdkmanager 'build-tools;27.0.3' \
                                   'platforms;android-27' \
                                   'ndk-bundle'

Since BoringSSL is included as a submodule, make sure all the Git submodules are initialised in your working copy:

git submodule update --init

Build Themis for Android:

./gradlew --info assembleRelease

It will create AAR (Android library project) in the build/outputs/aar/ folder. Link this aar file manually into your application.

To run Android tests, make sure ADB is enabled in settings, connect your device(s) and run:

./gradlew --info connectedAndroidTest

C++

After building and installing the core library, use the following line to install ThemisPP:

make themispp_install

You can then run ThemisPP test suite to verify the installation:

make themispp_test test_cpp

Java

Build jni library

Please make sure you have correctly installed JDK and configured JAVA_HOME before building Themis for Java. You can learn more about how to get and install JDK in Oracle documentation.

After building and installing the core library, use the following line to build the JNI wrapper:

make themis_jni

This will produce the libthemis_jni.so shared library in the build directory (build by default).

To build JNI code for Java, the build system needs to know the location of the jni.h header. By default, it will be looking for the file in ${JAVA_HOME}/include directory. You may specify a different location by setting the JDK_INCLUDE_PATH environment variable.

On macOS, you might need to explicitly specify path to Java headers with CFLAGS:

# Example path to JAVA_HOME
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-11.0.2.jdk/Contents/Home

export CFLAGS="-I$JAVA_HOME/include -I$JAVA_HOME/include/darwin"
make themis_jni

Link Themis to your project

Copy Themis Java files from themis/src/wrappers/themis/java. Paste them into your project src folder.

Copy libthemis_jni library to your project lib folder, link it as lib to your project.

See Themis Java examples for illustration.

JavaScript

After building and installing the core library, use the following line to install JsThemis:

make jsthemis_install

You can then run JsThemis test suite to verify the installation:

make prepare_tests_all test_js

PHP

After building and installing the core library, use the following line to install PHPThemis:

make phpthemis_install

This will build and install phpthemis.so to the standard Zend extension directory.

You will need to add the following line to your php.ini file in order to enable Themis extension:

extension=phpthemis.so

You can then verify if PHPThemis is correctly installed using

php --ri phpthemis

PHPThemis test suite can be run in the following manner:

make prepare_tests_all test_php

Python

After building and installing the core library, use the following line to install PyThemis:

make pythemis_install

You can then run PyThemis test suite to verify the installation:

make prepare_tests_all test_python

Ruby

After building and installing the core library, use the following line to install RubyThemis:

make rbthemis_install

If you want to install RubyThemis into the user folder, use GEM_INSTALL_OPTIONS:

GEM_INSTALL_OPTIONS=--user-install make rbthemis_install

You can then run RubyThemis test suite to verify the installation:

make prepare_tests_all test_ruby

Rust

Rust-Themis wrapper is available on crates.io. In order to use the wrapper, you still need to have the core library installed.

  1. Install Themis Core as a system library using your system's package manager.

    ⚠️ IMPORTANT: Rust-Themis requires core Themis headers to be installed, therefore you need to install the development package: libthemis-dev for Debian and Ubuntu, libthemis-devel for RHEL and CentOS.

  2. Add the following line to your Cargo.toml file:

    [dependencies]
    themis = "0.11"
Clone this wiki locally
You can’t perform that action at this time.