Building Sipi from Source Code

Prerequisites

To build Sipi from source code, you must have Kakadu, a JPEG 2000 development toolkit that is not provided with Sipi and must be licensed separately. The Kakadu source code archive v7_A_4-01727L.zip must be placed in the vendor subdirectory of the source tree before building Sipi.

Sipi’s build process requires CMake (minimal Version 3.0.0), a C++ compiler that supports the C++11 standard (such as GCC or clang), and several libraries that are readily available on supported platforms. The test framework requires Python 3, (version 3.5 or later), Apache ab (which is assumed to be installed by default on macOS Sierra), nginx, and a recent version of ImageMagick. Instructions for installing these prerequisites are given below.

The build process downloads and builds Sipi’s other prerequisites.

Sipi uses the Adobe ICC Color profiles, which are automatically downloaded by the build process into the file icc.zip. The user is responsible for reading and agreeing with Adobe’s license conditions, which are specified in the file Color Profile EULA.pdf.

Mac OS X & macOS

You will need Homebrew and at least OSX 10.11.5.

Prerequisites for building Sipi without its automated test framework:

xcode-select --install
brew install cmake
brew install doxygen
brew install openssl
brew install libmagic
brew install gettext

If you also want to run Sipi’s tests:

brew install nginx
sudo chown -R $USER /usr/local/var/log/nginx/
brew install imagemagick --with-openjpeg
brew install python3
pip3 install Sphinx
pip3 install pytest
pip3 install requests
pip3 install psutil
pip3 install iiif_validator

Ubuntu 16.04

Prerequisites for building Sipi without its automated test framework:

sudo apt-get install g++
sudo apt-get install cmake
sudo apt-get install libssl-dev
sudo apt-get install doxygen
sudo apt-get install libreadline-dev
sudo apt-get install gettext
sudo apt-get install libmagic-dev
sudo apt-get install unzip

If you also want to run Sipi’s tests, you will need ImageMagick, version 7.0.6 or higher. We suggest compiling it from source:

sudo apt-get install libtiff5-dev libjpeg-turbo8-dev libopenjp2-7-dev
wget https://github.com/ImageMagick/ImageMagick/archive/7.0.6-0.tar.gz
tar -xzf 7.0.6-0.tar.gz
cd ImageMagick-7.0.6-0/
./configure
make
sudo make install
sudo ldconfig /usr/local/lib

Then:

sudo apt-get install ab
sudo apt-get install nginx
sudo chown -R $USER /var/log/nginx
sudo apt-get install python3
sudo apt-get install python3-pip
sudo -H pip3 install --upgrade pip
sudo -H pip3 install Sphinx
sudo -H pip3 install pytest
sudo -H pip3 install requests
sudo -H pip3 install psutil
sudo -H pip3 install iiif_validator

Debian 8

First, follow the instructions for Ubuntu 16.04.

Then, CMake has to be patched. Unfortunaltely the version of CMake provided by the Debian packages contains a bug and cannot find the OpenSSL libraries and includes. To apply the patch, go to the Sipi dicrectory and run:

sudo ./debian-cmake-patch.sh

CentOS 7

This requires GCC version 5.3 or greater. You can install it by installing devtoolset-4, and adding this to your .bash_profile:

source scl_source enable devtoolset-4

Prerequisites for building Sipi without its automated test framework:

sudo yum -y install cmake3
sudo yum -y install readline-devel
sudo yum -y install doxygen
sudo yum -y install patch
sudo yum -y install openssl-devel
sudo yum -y install gettext
sudo yum -y install file-devel

If you also want to run Sipi’s tests, you will need ImageMagick, version 7.0.6 or higher. We suggest compiling it from source:

sudo yum install libtiff-devel libjpeg-turbo-devel openjpeg2-devel
wget https://github.com/ImageMagick/ImageMagick/archive/7.0.6-0.tar.gz
tar -xzf 7.0.6-0.tar.gz
cd ImageMagick-7.0.6-0/
./configure
make
sudo make install
sudo ldconfig /usr/local/lib

Then:

sudo yum -y install httpd-tools
sudo yum -y install nginx
sudo chown -R $USER /var/log/nginx
sudo chown -R $USER /var/lib/nginx
sudo yum -y install https://centos7.iuscommunity.org/ius-release.rpm
sudo yum -y install python35u
sudo yum -y install python35u-devel
sudo yum -y install python35u-pip
sudo pip3.5 install Sphinx
sudo pip3.5 install pytest
sudo pip3.5 install requests
sudo pip3.5 install psutil
sudo pip3.5 install iiif_validator

Docker

We provide a docker image based on Ubuntu LTS releases, containing all dependencies: https://hub.docker.com/r/dhlabbasel/sipi-base/

Compiling the Source Code

Start in the build subdirectory of the source tree:

cd build

Then compile Sipi:

cmake ..
make

By default, Sipi is built without optimization and with debug information output. To compile Sipi with optimization level 3, run:

cmake .. -DMAKE_DEBUG:BOOL=OFF
make

Running Tests

You can run the automated tests in the build directory like this:

make test // will run all tests (minimum output)
ctest --verbose // will run all tests (detailed output)
make check // will run only e2e tests (detailed output)

Making a Directory Tree for Installing Sipi

In build, type this to install Sipi in the local subdirectory of the source tree:

make install

You can then copy the contents of local to the desired location.

Generating Documentation

To generate this manual in HTML format, cd to the manual subdirectory of the source tree and type:

make html

You will then find the manual under manual/_build/html.

To generate developer documentation about Sipi’s C++ internals, cd to the build directory and type:

make doc

You will find the developer documentation in HTML format under doc/html. To generate developer documentation in PDF format, first ensure that you have LaTeX installed. Then cd to doc/html/latex and type make.

Starting Over

To delete the previous build and start over from scratch, cd to the top level of the source tree and type:

rm -rf build/* lib local extsrcs include/*_icc.h

Building inside Docker

All that was described before, can also be done by using docker. All commands need to be executed from inside the source directory (and not build the build directory). Also, Docker needs to be installed on the system.

docker image rm --force dhlabbasel/sipi-base:18.04 // deletes cached image and needs only to be used when newer image is available on dockerhub
docker run --rm -v $PWD:/sipi dhlabbasel/sipi-base:18.04 /bin/sh -c "cd /sipi/build; cmake .. && make" // building
docker run --rm -v $PWD:/sipi dhlabbasel/sipi-base:18.04 /bin/sh -c "cd /sipi/build; cmake .. && make && ctest --verbose" // building and running all tests
docker run --rm -v $PWD:/sipi dhlabbasel/sipi-base:18.04 /bin/sh -c "cd /sipi/manual; make html" // make html documentation

Since we mount the current source directory into the docker continer, all build artifacts can be accessed as if the build would have been performed without docker.