Compiling from Source

The following guide shows how to compile and install TinySpline from source. Once being available, guides to install the precompiled packages will be added.

Prerequirements

TinySpline uses CMake and Swig to generate, compile, and package the source files. The core has been implemented in C89 (also known as ANSI C and ISO C90) and, thus, is compatible with most compiler suites. Except of the C interface all features of TinySpline (including the C++ interface) are optional and will be disabled if CMake doesn't find the required dependencies. Consequently, the bare minimum to compile TinySpline using CMake is, apparently, CMake (version 3.4 or later) and an appropriate C/C++ compiler. The following compiler suites are officially supported: GCC, Clang, and MSVC. If the detected compiler supports C++11, CMake will add the C++ interface automatically. If, on the other hand, the detected compiler doesn't support C++11, you have to enable the CMake option TINYSPLINE_DISABLE_CXX11_FEATURES to create an interface using C++98. However, using C++11 is recommended as TinySpline makes heavy use of move semantics. In order to generate any of the bindings, a C++ (preferentially C++11) enabled compiler as well as Swig (version 3.0.1 or later) is required. Furthermore, most target languages also depend on language specific header files and libraries which, usually, are part of the installed SDK.

The following table shows all supported languages and lists their compile time requirements. The column Additional outlines languages specific dependencies:

Language C Compiler C++ Compiler Swig Additional
C x
C++ x x
C# x x x
Java x x x JNI
Lua x x x Lua libs
PHP x x x Zend
Python x x x Python libs
Ruby x x x Ruby libs

For the sake of convenience, the generated source files of a binding will be compiled and/or packaged, if suitable. That is, for instance, the generated .java files will be compiled to .class files and packaged into a single .jar archive. Thus, the following tools are required if you want to package the corresponding binding:

Language Required Tool(s) Output File
C# Any of: csc, mcs, dmcs, gmcs TinySpline.dll
Java javac and jar (available in JDK) tinyspline.jar

As always, if CMake doesn't find a tool, the relevant feature will be disabled, i.e., TinySpline.dll will not be created if neither csc nor mcs, dmcs, or gmcs is available.

Linux

Installing dependencies on systems running Linux (usually) is a breeze due to the powerful software management tools provided by most distributions. That being said, maintaining installation guides for all distributions is impractical as there hundreds of thousands of them. Hence, only the most common distributions are described below.

To be continued

Windows

To be continued

macOS

To be continued

Project Structure

The CMake project consists of three subproject. The first one is the library itself and is located in the library directory. It contains all files that are required to build TinySpline. The second subproject provides different examples and is located in the examples directory. The third subproject is the test suite containing several unit tests. It is located in the tests directory.

The core of TinySpline has been implemented in C89 and consists of the files tinyspline.h and tinyspline.c. Copy these files into your project or use CMake to create a static or shared library.

The C++ wrapper consists of the files tinysplinecpp.h and tinysplinecpp.cpp. As for the C interface, you can copy these files (along with tinyspline.h and tinyspline.c) into your project or use CMake to create a static or shared library.

All bindings work on top of the C++ wrapper and are generated with Swig. The file tinyspline.i configures all language-independent settings whereas the file tinysplineXYZ.i adds language-related features (e.g. properties for Python). Using CMake to create the bindings is recommended.

Note: The file debugging.h adds some debugging features for the C interface.

Cmake Options and Environment Variables

The following CMake options can be used to configure TinySpline:

  • TINYSPLINE_DISABLE_CXX11_FEATURES
    Disable (yes) or enable (no) C++11 features. Default: no
  • TINYSPLINE_DOUBLE_PRECISION
    Use single (no) or double (yes) precession for tinyspline::real. Default: no.
  • TINYSPLINE_PYTHON_VERSION
    Force CMake to use a specific Python version. Supported values are: '2', '3', and 'ANY'. Default: ANY.

It is, of course, possible to combine these options to adjust the build to your requirements. You can not only use CMake options to configure TinySpline, but also use equivalent environment variables which are automaticallly processed by the CMake script:

TINYSPLINE_PYTHON_VERSION=2 cmake ... # Force Python 2
TINYSPLINE_DISABLE_CXX11_FEATURES=yes TINYSPLINE_DOUBLE_PRECISION=yes cmake ... # Disable C++11 features and use double precision

Using environment variables for configuration is particularly useful when embedding the CMake build script into other build tools.

Compiling

Now let's start compiling TinySpline. First of all, download the latest release from Github or checkout the repository directly:

git clone https://github.com/msteinbeck/tinyspline.git tinyspline

Afterwards, create a build directory within your source directory and change into it:

mkdir build
cd build

Finally, run CMake and compile/package the libraries:

cmake ..
cmake --build .

You will find the resulting libraries, jars, etc. in: build/lib.

In order to cross compile the C and C++ library, use one of the provided toolchain files. Currently, toolchain files for MinGW, ARM, and AVR are available at the root directory of the source distribution (e.g. Toolchain-arm.cmake). Use the following command within your build directory to cross compile TinySpline to the desired platform:

cmake -DCMAKE_TOOLCHAIN_FILE=<path to root dir of tinypsline>/Toolchain-*.cmake ..

Install the C and C++ Libraries

The following command installs the C and C++ libraries:

cmake --build . --target install

Unfortunately, CMake is not able to install the generated bindings because most programming languages use their own approach to install files to the system. Python, for instance, uses Distutils/Setuptools to copy the resulting files to Python specific installation directories CMake is not aware of. Thus, language-related distribution tools are necessary as described in the following sections.

Install the Python Binding

The root directory of the source distribution contains the Python script setup.py which is using Setuptools to wrap the CMake build process. Additionally, it copies the resulting files to the appropriate Python installation directory. Use the following command to build and install the Python binding:

python setup.py install

Note: You may need root privileges to copy the files to the desired directory.

Install the Java Binding

There are several tools to manage the build process of software implemented in Java. TinySpline uses Maven to create and install the Java binding as Maven is used in many other projects and is well supported by various integrated development environments. You will find the pom.xml file that is used to configure Maven in the root directory of the source distribution. This file follows the usual mantra of wrapping the CMake build process to create the binding. Additionally, the shared library that is required to use the binding gets packaged into the jar archive. Use the following command to create and install the archive into your local maven repository:

mvn install

If you run this command on systems not supporting Unix makefiles, you may get the following error message: "CMake Error: Could not create named generator Unix makefiles". This error results from the cmake-maven-project plug-in that requires an actual CMake generator to properly wrap the build process. That is, if you skip the generator configuration of cmake-maven-project, it fails with: "The parameters 'generator' for goal com.googlecode.cmake-maven-project:cmake-maven-plugin:3.4.1-b1:generate are missing or invalid". Thus, Maven has been configured to use the Unix makefiles generator by default. To change the generator open the file pom.xml and replace the line:

<generator>Unix Makefiles</generator>

with one of the generators listed at: cmake.org/cmake/help/v2.8.10/cmake.html#section_Generators. Afterwards, rerun Maven:

maven clean install

Install the C#, Lua, PHP, and Ruby Bindings

Currently, TinySpline does not provide tools to install the bindings for C#, Lua, PHP, and Ruby. However, adding such tools is planned for the future. If you have experience with, for instance, Ruby gems and Rake, feel free to create a pull request :).