Building the DIPlib project

To build DIPlib you will need a C++14 compliant compiler and CMake. See Dependencies for optional dependencies that you can install to improve your DIPlib experience.

A single CMake project builds the DIPlib library, DIPviewer, DIPjavaio, the DIPimage toolbox, and the PyDIP package, as well as these documentation pages. In short,

cmake <path_to_diplib_repository>
make -j check         # will build DIPlib and PyDIP, and run their unit tests
make -j install       # will install DIPlib and DIPimage
make -j pip_install   # will install PyDIP

For a full list of targets and CMake configuration options, see CMake configuration.

It is also possible to build the PyDIP project separately, using a previously installed DIPlib library,

cmake <path_to_diplib_repository>/pydip/
make -j check         # will build PyDIP, and run its unit tests
make -j pip_install   # will install PyDIP

The following are step-by-step build instructions:

  1. Building the DIPlib project on Linux
  2. Building the DIPlib project on macOS
  3. Building the DIPlib project on Windows
  4. Building the DIPlib documentation

Linking against the DIPlib library

When writing a program that depends on DIPlib (or DIPviewer and/or DIPjavaio), the simplest solution usually is to include its repository as a subproject, and in your CMake file do add_subdirectory(diplib). You then have the DIP, DIPviewer and DIPjavaio targets available (if configured correctly).

Alternatively you can use the installed DIPlib libraries. When using CMake, simply do find_package(DIPlib), then link against the imported DIPlib::DIP, DIPlib::DIPviewer and/or DIPlib::DIPjavaio targets. See the example CMake script.

When using CMake in either of the ways above, it will automatically add the relevant include directories, set the required compilation flags, and define the required macros by just linking to the relevant targets.

If you do not use CMake, there are several macros that you should define when building any program that links against DIPlib:

  • If DIPlib was build with the DIP_SHARED_LIBRARY flag not set, then you need to define the DIP_CONFIG_DIP_IS_STATIC macro when compiling the code that links against it. Likewise, if the DIP_ALWAYS_128_PRNG flag was set, then you must define a DIP_CONFIG_ALWAYS_128_PRNG macro when compiling your program. Mismatching this flag could cause your program to not link, or worse, crash at runtime.

  • The following flags do not need to be matched, but they should be if you want the inline functions to behave the same as the pre-compiled ones:

    • If the flag DIP_ENABLE_STACK_TRACE is set, define the macro DIP_CONFIG_ENABLE_STACK_TRACE.
    • If the flag DIP_ENABLE_ASSERT is set, define the macro DIP_CONFIG_ENABLE_ASSERT.
  • If your compiler supports __PRETTY_FUNCTION__, set the macro DIP_CONFIG_HAS_PRETTY_FUNCTION to get better stack traces.

  • For DIPviewer, if DIP_SHARED_LIBRARY was not set, define the DIP_CONFIG_DIPVIEWER_IS_STATIC macro. Also define DIP_CONFIG_HAS_FREEGLUT or DIP_CONFIG_HAS_GLFW depending on which back-end is used.

  • For DIPjavaio, if DIP_SHARED_LIBRARY was not set, define the DIP_CONFIG_DIPJAVAIO_IS_STATIC macro. Also define DIP_CONFIG_HAS_DIPJAVAIO for the function dip::ImageRead to be able to make use of it.