Building » CMake configuration

Available targets

• DIP: builds the DIPlib library
• DIPviewer: builds the DIPviewer module (plus the DIPlib library)
• DIPjavaio: builds the DIPjavaio module (plus the DIPlib library)
• PyDIP: builds the PyDIP Python module (includes the DIP, DIPviewer and DIPjavaio targets)
• dipview: builds the standalone dipview image viewer program
• dipviewjava: builds the DIPjavaio-enabled standalone dipviewjava image viewer program
• all: (default) builds all of the targets above that were configured
• install: builds all and installs everything except PyDIP
• check: builds the unit_tests program and runs it
• check_memory: builds the unit_tests program and runs it under valgrind
• apidoc: builds all the HTML documentation
• examples: builds the example programs
• package: creates a distributable package for install [note: not fully functional]
• bdist_wheel: builds a Python wheel for PyDIP
• pip_install: builds and installs a Python wheel for PyDIP
• pip_uninstall: uninstalls PyDIP

The apidoc target requires that dox++ is available, the target will not be available if it is not; this target will fail to build if additional tools are not installed. See Building the DIPlib documentation for details.

The pip_install target requires the DIPlib libraries to already be installed, so always run the install target first.

CMake variables

These variables can be set on the cmake command line with -D<variable>=<value>. Alternatively, set them in the CMake GUI.

Important CMake variables controlling the build of DIPlib:

• CMAKE_INSTALL_PREFIX: Choose an install location for all the components except PyDIP. A directory structure will be created, including the POSIX-standard lib, include and share directores.
• CMAKE_BUILD_TYPE: Set to Release (default), Debug or Sanitize (GCC or Clang only). On Windows this is ignored, choose the build type in MSVC.
• DIP_SHARED_LIBRARY: On (default) or Off. Leave On to build a shared DIPlib library, set to Off to build a static DIPlib library. Note that DIPimage and PyDIP require a shared library.
• CMAKE_C_COMPILER: Specify a C compiler for the dependencies libics, LibTIFF, libjpeg and zlib.
• CMAKE_CXX_COMPILER: Specify a C++ compiler. The system’s default C and C++ compilers are used by default.
• CMAKE_CXX_FLAGS: Specify additional C++ compiler flags. For example, with GCC or Clang you could set this to "-march=native" to optimize the build for the current machine.
• DIP_ENABLE_STACK_TRACE: On (default) or Off. In DIPlib, exceptions generate a stack trace, which you might want to disable in some circumstances.
• DIP_ENABLE_ASSERT: On or Off (default). Typically one would enable asserts in debug builds only.
• DIP_ENABLE_DOCTEST: On (default) or Off. The unit tests are embedded in DIPlib code through doctest, and will end up in the library unless disabled.
• DIP_ENABLE_MULTITHREADING: On (default) or Off. DIPlib uses OpenMP for multithreading if available on the system.
• DIP_ENABLE_ICS: On (default) or Off. Enable support for the ICS file format using the included libics library.
• DIP_ENABLE_TIFF: On (default) or Off. Enable support for the TIFF file format using the included LibTIFF library.
• DIP_ENABLE_JPEG: On (default) or Off. Enable support for the JPEG file format using the included libjpeg library.
• DIP_ENABLE_PNG: On (default) or Off. Enable support for the PNG file format using the included libspng library.
• DIP_ENABLE_ZLIB: On (default) or Off. Enable support for ZIP (deflate) compression in the ICS and TIFF file formats using the included zlib library.
• DIP_ENABLE_FFTW: On or Off (default). Enable the use of the FFTW3 library, if available.
• DIP_ENABLE_FREETYPE: On or Off (default). Enable the use of the FreeType2 library, if available.
• DIP_ENABLE_UNICODE: On (default) or Off. Enable support for UTF-8 strings within DIPlib.
• DIP_ALWAYS_128_PRNG: On or Off (default). If On, use the 128-bit PRNG code even if 128-bit integers are not natively supported.

Controlling the build of DIPviewer:

• DIP_BUILD_DIPVIEWER: On (default) or Off. Choose whether to build and install the DIPviewer module, if its dependencies are available.

Controlling the build of DIPjavaio:

• DIP_BUILD_JAVAIO: On (default) or Off. Choose whether to build and install the DIPjavaio module, if its dependencies are available.
• JAVA_HOME: Set the path to the JDK to use.
• DIP_JAVA_VERSION: Set the version of Java to target. Defaults to “1.8”.
• Note that for the MATLAB toolbox, DIPjavaio is not used; build this only if you work in C++ or Python.

Controlling the build of DIPimage:

• DIP_BUILD_DIPIMAGE: On (default) or Off. Choose whether to build and install the DIPimage toolbox, if MATLAB is available.
• Matlab_ROOT_DIR: Set the path of the MATLAB installation to compile DIPimage against.
• JAVA_HOME: Set the path to the JDK to use. Java is used by DIPimage to interface with DIPviewer.
• DIP_JAVA_VERSION: Set the version of Java to target. Defaults to “1.8”. For MATLAB versions prior to R2017b use “1.7” (and set JAVA_HOME to a release of the JDK that supports 1.7). You should not target a Java version later than the one used by your MATLAB. Check the version of Java used by MATLAB by running version -java on the MATLAB command prompt.

Controlling the build of PyDIP:

• DIP_BUILD_PYDIP: On (default) or Off. Choose whether to build the PyDIP package, if Python is available.
• Python_EXECUTABLE: Set the path to the Python binary, in case CMake doesn’t find the right one. It is also possible to instead set Python_ROOT_DIR, see FindPython.
• DIP_PYDIP_WHEEL_INCLUDE_LIBS: On or Off (default). Include the DIPlib libraries in the PyDIP wheel. Turn on for binary distribution, keep off for personal builds.

Some of these options might not be available on your system. For example, if you don’t have MATLAB installed, the DIP_BUILD_DIPIMAGE option will not be defined. In this case, setting it to Off will yield a warning message when running CMake.