ExternalProject

ExternalProject is a module in CMake that provides a framework for integrating external software projects into a build. It enables downloading, configuring, building, and installing external sources as part of the overall project, often in an isolated build tree. This supports reproducible builds and helps manage dependencies that are not obtained from the system or require special build steps.

The main mechanism is the ExternalProject_Add command, which declares an external project by name and a set of properties. Key options include URL or GIT_REPOSITORY to fetch sources, SOURCE_SUBDIR, and PATCH_COMMAND for preparation. Build steps are specified with CONFIGURE_COMMAND, BUILD_COMMAND, INSTALL_COMMAND, and TEST_COMMAND, and CMAKE_ARGS or other tool-specific arguments can be passed to configure or build. External projects are built in their own build directories, typically under the main binary directory, and can be wired into the main build through DEPENDS relationships and the install prefix. The present outputs can be discovered by the main project via the installed files.

Usage scenarios include bringing in third-party libraries or tools that are not available on the host system, enforcing a controlled version, and separating their build environments from the main project. It is commonly used for long-running or platform-specific builds and allows patching or custom pre/post steps. Example integrations often download a library, configure it with the parent project’s options, build it, and install it so the main project can locate and link against the installed artifacts.

Alternatives and considerations: FetchContent provides a newer, more tightly integrated approach for bringing in dependencies at configure time, but ExternalProject remains useful for offline builds, long-running processes, or when strict separation of build trees is desired. ExternalProject can be more complex to debug and may increase overall build time due to separate build steps.