Tutorial 1: Getting Started

Previous: Building a 2D Poisson Solver; Next: Implement: Matrices

Objectives

In this tutorial, we will guide you through the installation process of Ginkgo. We will explain what software you need to install Ginkgo, how to build Ginkgo, run its unit tests, install it in a system folder, and finally run the examples shipped with it.

Prerequisites

The detailed prerequisites are available in your Ginkgo version of choice's README.md and INSTALL.md. In this tutorial, we assume that the develop version is used and we explain some common use cases of the Ginkgo library.

Building ginkgo

As a first step, clone the Ginkgo repository on your local machine.

git clone https://github.com/ginkgo-project/ginkgo.git

Next, enter the cloned repository, create a build directory and enter it.

cd ginkgo
mkdir build
cd build

In the next step, you have to configure the Ginkgo installation process.

If your system supports it, the easiest way to configure your installation is to use the CMake curses interface

ccmake ..

and then configure (the default key is 'C' to do so) the options as desired. If you are unsure which options you want, don't specify anything and use the defaults we provide by running the configure option. After the configuration is done, you need to generate (the default key is 'G') the CMake configuration. If the generation was successful, you can exit (the default key is 'E') and initiate the build process via

cmake --build ./ -j4

where 4 defines the number of cores you want to use in the parallel compilation.

The alternative way for configuring the installation process is to follow the standard cmake build procedure as

cmake -G "Unix Makefiles" [OPTIONS] .. && make

where you can replace [OPTIONS] with the desired cmake options. To build the reference version of all of the kernels in Ginkgo, use -DGINKGO_BUILD_REFERENCE={ON,OFF} (default is ON). The reference kernels are not optimized for performance, they serve as a correctness-check for the algorithms and are guaranteed to compute the correct result. If your platform supports OpenMP and you want to use optimized OpenMP kernels, use -DGINKGO_BUILD_OMP={ON,OFF} (default is OFF). Similarly, if your platform supports CUDA (i.e., has a CUDA-capable accelerator) and you want to use CUDA kernels, use -DGINKGO_BUILD_CUDA={ON,OFF} (default is OFF).

If you want to build Ginkgo's unit tests use -DGINKGO_BUILD_TESTS={ON,OFF} (default is ON). The unit tests are based on googletest, and if there is no googletest installation available on your system, the cmake build process will automatically download and install googletest.

To build further examples of the functionality of Ginkgo, use -DGINKGO_BUILD_EXAMPLES={ON,OFF} (default is ON).

The option -DGINKGO_DEVEL_TOOLS={ON,OFF} (default is ON) sets up the build system for development. In case you want to implement new algorithms inside Ginkgo, you need to set it to ON. If you only plan to use Ginkgo as a library inside a larger application, you can turn it off.

To build Ginkgo in Debug mode with these options, the cmake build procedure would be

cmake -G "Unix Makefiles" -BDebug -DCMAKE_BUILD_TYPE=Debug -DGINKGO_DEVEL_TOOLS=ON \
         -DGINKGO_BUILD_TESTS=ON -DGINKGO_BUILD_EXAMPLES=ON -DGINKGO_BUILD_REFERENCE=ON \
	    -DGINKGO_BUILD_OMP=ON -DGINKGO_BUILD_CUDA=ON ..
cmake --build Debug -j [JOBS]

where you replace [JOBS] with the number of jobs you want to use.

In case you want to install Ginkgo in a specific location, you can use the option -DCMAKE_INSTALL_PREFIX=path. The default location is usually /usr/local/.

For a detailed description of all the available build options, please see the Installation page.

Running unit tests [optional]

Assuming you have built Ginkgo with -DGINKGO_BUILD_TESTS=ON, you can now run Ginkgo's unit tests by calling

cd build/ # Change the directory to your build folder
make test

You will see tests for the Reference, OpenMP, and CUDA implementations of all the routines in Ginkgo, depending on which build options you have chosen.

Installation

After all tests are passed you are ready to install Ginkgo into the specified path. This can simply be done with

make install

If you didn't set an installation prefix with -DCMAKE_INSTALL_PREFIX or if the installation prefix is not writable for your user, you might have to call