Skip to content

Using Third Party Code

ILLIXR is an open-source project that uses third-party code and libraries. This document outlines the process and licensing constraints for using these inside ILLIXR.

Precompiled Libraries

Provided by OS Package Managers

If the third party library being used is provided by a package manager (yum, dnf, apt, etc.) then there are no licensing issues, as it is not being provided by ILLIXR. Any library that is used this way needs to be added to the docs/docs/modules.json file. See the documentation for more information on how to do this.

To include the library in the build, add the library to the appropriate CMakeLists.txt file. If the package (or CMake itself) provides a Find<package>.cmake or <package>Config.cmake file, then use

find_package(<package> REQUIRED)

to ensure the library exists on the build system. If the *.cmake file is in a non-standard location you may need to update the CMAKE_PREFIX_PATH variable to include the directory containing the *.cmake file.

set(CMAKE_PREFIX_PATH "/path/to/file ${CMAKE_PREFIX_PATH}")

If the package does not have a Find<package>.cmake file, but provides a pkg-config (.pc) file, then use

find_package(PkgConfig REQUIRED)
pkg_check_modules(<package> REQUIRED <package>)

to ensure the library exists on the build system. If the *.pc file is in a non-standard location you may need to update the PKG_CONFIG_PATH environment variable to include the directory containing the *.pc file.

set(ENV{PKG_CONFIG_PATH} "/path/to/file:$ENV{PKG_CONFIG_PATH}")

If neither of these are provided you may need to use the find_library command to locate the library on the build system.

Provided by Third Party

If the precompiled library is provided as a download or via a third-party installer, then the library must be licensed under a compatible license. See the license documentation for more information. To use a third-party installer in ILLIXR, you will need to add directives in the appropriate CMakeLists.txt file to download and install the library. Commands such as file(DOWNLOAD ...), execute_process(COMMAND ...), and add_custom_command can be used to accomplish this. You will need to be aware that CMake will not automatically associate the installation of the library with its use in your code. You will likely need to add targets to the DEPENDS list of your code's CMake target.

Built From Source

Any third-party code that is built from source must be licensed under a compatible license. See the license documentation for more information. To use this code in ILLIXR it is recommended to create a cmake/Get<package>.cmake file that will download and build the library. See files in the cmake directory for examples. Then, in the appropriate CMakeLists.txt file for the code that depends on the library, use either the get_external_for_plugin (if your code is a plugin) or get_external macros to include the library in the build. Also, be sure to add the library to the DEPENDS list of your code's CMake target.

Linking to the Library

Once the library has been made available to the build system (see the above sections), you will need to ensure that the system can find any relevant headers and link to and locate the library at build and runtime. This is accomplished with the target_include_directories and target_link_libraries commands in the appropriate CMakeLists.txt file. See any of the existing CMakeLists.txt files in plugins/* for examples.