Configuration¶

The first step is to create a separate build directory within the piranha source tree. This directory will contain all the temporary files created during the compilation of the source code. If you want to restart the compilation process from scratch, it will be enough to erase the build directory, and repeat the process described here. This is technically called an out-of-source build, as the files generated during the build process are separated from the original source files.

From within the build directory, run the command

$ cmake ../

CMake will look for Piranha’s dependencies in standard paths, and it will produce an error message if it cannot detect them. It is possible to tell explicitly CMake where to find a specific library by passing the information on the command line. For instance,

$ cmake ../ -DGMP_LIBRARIES=/custom/location/for/libgmp.so

will instruct CMake to use the GMP library at the location /custom/location/for/libgmp.so. CMake’s GUIs are handy to discover, set and, if necessary, override the internal variables set by CMake during the configuration phase. This is particularily useful on platforms such as OSX and Windows.

Piranha can be built either in Debug or in Release mode. In Debug mode, the code will perform extensive self-checking and performance will be greatly reduced with respect to the Release mode. The build mode can be set with the CMAKE_BUILD_TYPE CMake variable, e.g.,

$ cmake ../ -DCMAKE_BUILD_TYPE=Debug

In order to compile Pyranha, the PIRANHA_BUILD_PYRANHA option must be enabled:

$ cmake ../ -DBUILD_PYRANHA=ON

Another useful CMake option is BUILD_TESTS: if selected, a suite of tests will be built. In Debug mode, unit tests will be built, in Release mode performance tests will be built.

The compiler selected by CMake is chosen according to platform-specific heuristics. If you have only one compiler installed on your system, there will be no ambiguity. If, however, you have multiple toolchains installed and want to force CMake to pick a specific one, you can set the CXX environment variable before running CMake. In bash, a possible way of doing this is

$ CXX=/path/to/other/compiler/clang++ cmake ../

This will force CMake to use the Clang C++ compiler clang++ at the location /path/to/other/compiler/.

Building¶

After the configuration step, Piranha is ready to be built. Piranha is a header-only C++ library, so, technically, you do not need to actually compile anything to use the library from C++ (but the configuration step above is still necessary to setup platform-specific functionality in the headers). The building stage is however needed when building the Python bindings Pyranha and/or when testing is enabled.

In Unix-like environments, you can build the tests and/or the Python bindings by running the standard make tool from the build directory:

$ make

On a multicore machine, it is possible to launch make in parallel to speed up the compilation. An example with 8 parallel jobs:

$ make -j8

After a successful build in Debug mode, it is good practice to run the test suite:

$ make test
Running tests...
Test project /home/yardbird/repos/piranha/build
      Start  1: array_key
 1/45 Test  #1: array_key ...............................   Passed    0.11 sec
      Start  2: base_term
 2/45 Test  #2: base_term ...............................   Passed    0.03 sec
      Start  3: cache_aligning_allocator
 3/45 Test  #3: cache_aligning_allocator ................   Passed    0.01 sec
      Start  4: convert_to
 4/45 Test  #4: convert_to ..............................   Passed    0.01 sec
      Start  5: dynamic_aligning_allocator
 5/45 Test  #5: dynamic_aligning_allocator ..............   Passed    0.01 sec
      Start  6: echelon_size
 6/45 Test  #6: echelon_size ............................   Passed    0.01 sec
      Start  7: environment
 7/45 Test  #7: environment .............................   Passed    0.01 sec
      Start  8: exceptions
 8/45 Test  #8: exceptions ..............................   Passed    0.01 sec
      Start  9: hash_set
 9/45 Test  #9: hash_set ................................   Passed    8.35 sec
[...]
42/45 Test #42: tracing .................................   Passed    0.00 sec
      Start 43: trigonometric_series
43/45 Test #43: trigonometric_series ....................   Passed    0.03 sec
      Start 44: tuning
44/45 Test #44: tuning ..................................   Passed    0.00 sec
      Start 45: type_traits
45/45 Test #45: type_traits .............................   Passed    0.00 sec

100% tests passed, 0 tests failed out of 45

Total Test time (real) = 675.26 sec

A full run of the test suite should take a few minutes on a modern desktop machine. Any failure in the unit tests should be reported as a bug.

Installation¶

The final step is the installation of Piranha on the system. In Unix-like environments, the default installation path (also known as the PREFIX) is /usr/local. The standard

$ make install

command will copy the Piranha C++ headers into PREFIX/include/piranha, and the Pyranha module (if built) in an auto-detected subdirectory of PREFIX where Python modules can be found by the Python interpreter (e.g., something like PREFIX/lib/python2.7/site-packages in a typical Python 2.7 installation on GNU/Linux).

If you do not have write permissions in /usr/local, it is possible to change the PREFIX in the configuration phase. It is advisable to set the PREFIX to a subdirectory in the user’s home directory (e.g., /home/username/.local). The PREFIX can be set via the CMAKE_INSTALL_PREFIX CMake variable during the configuration process.

On the Python side, in order to check that the installation of the Pyranha module was successful it will be enough to attempt importing it from a Python session:

>>> import pyranha

If this command produces no error messages, then the installation of Pyranha was successful. You can run the Pyranha test suite with the following commands:

>>> import pyranha.test
>>> pyranha.test.run_test_suite()
runTest (pyranha.test.basic_test_case) ... ok
runTest (pyranha.test.mpmath_test_case) ... ok
runTest (pyranha.test.math_test_case) ... ok
runTest (pyranha.test.polynomial_test_case) ... ok
runTest (pyranha.test.poisson_series_test_case) ... ok
runTest (pyranha.test.converters_test_case) ... ok
runTest (pyranha.test.serialization_test_case) ... ok

----------------------------------------------------------------------
Ran 7 tests in 2.905s

OK

Note that if you specified a non-standard PREFIX during the configuration phase, you might need to set the PYTHONPATH environment variable in order for the Python interpreter to locate Pyranha. More information is available here .