Crate cmake_package

A simple CMake package finder.

This crate is intended to be used in cargo build scripts to obtain information about and existing system CMake package and CMake targets defined in the package, such as include directories and link libraries for individual CMake targets defined in the package.

The crate runs the cmake command in the background to query the system for the package and to extract the necessary information, which means that in order for this crate to work, the cmake executable must be located the system PATH. CMake version 3.19 or newer is required for this crate to work.

The entry point for the crate is the find_package() function that returns a builder, which you can use to specify further constraints on the package (version or components). Once you call the find() method on the builder, the crate will try to find the package on the system or return an error. If the package is found, an instance of the CMakePackage struct is returned that contains information about the package. Using its target() method, you can query information about individual CMake targets defined in the package.

If you want to make your dependency on CMake optional, you can use the find_cmake() function to check that a suitable version of CMake is found on the system and then decide how to proceed yourself. It is not necessary to call the function before using find_package().

Example

use cmake_package::find_package;

let package = find_package("OpenSSL").version("1.0").find();
let target = match package {
    Err(_) => panic!("OpenSSL>=1.0 not found"),
    Ok(package) => {
        package.target("OpenSSL::SSL").unwrap()
    }
};

println!("Include directories: {:?}", target.include_directories);
target.link();

How Does it Work?

When you call FindPackageBuilder::find(), the crate will create a temporary directory with a CMakeLists.txt file that contains actual find_package() command to search for the package. The crate will then run actual cmake command in the temporary directory to let CMake find the package. The CMakeLists.txt then writes the information about the package into a JSON file that is then read by this crate to produce the CMakePackage.

When a target is queried using the CMakePackage::target() method, the crate runs the CMake command again the same directory, but this time the CMakeLists.txt attempts to locate the specified CMake target and list all its (relevant) properties and properties of all its transitive dependencies. The result is again written into a JSON file that is then processed by the crate to produce the CMakeTarget instance.

Known Limitations

The crate currently supports primarily linking against shared libraries. Linking against static libraries is not tested and may not work as expected. The crate currently does not support linking against MacOS frameworks.

CMake generator expressions are not supported in property values right now, because they are evaluated at later stage of the build, not during the “configure” phase of CMake, which is what this crate does. Some generator expressions could be supported by the crate in the future (e.g. by evaluating them ourselves).

There’s currently no way to customize the CMakeLists.txt file that is used to query the package or the target in order to extract non-standard properties or variables set by the CMake package. This may be addressed in the future.

Structs

CMakePackage

A CMake package found on the system.

CMakeProgram

A structure representing the CMake program found on the system.

CMakeTarget

Describes a CMake target found in a CMake package.

FindPackageBuilder

A builder for creating a CMakePackage instance. An instance of the builder is created by calling the find_package() function. Once the package is configured, FindPackageBuilder::find() will actually try to find the CMake package and return a CMakePackage instance (or error if the package is not found or an error occurs during the search).

Version

Enums

Error

Errors that can occur while working with CMake.

VersionError

Constants

CMAKE_MIN_VERSION

The minimum version of CMake required by this crate.

Functions

find_cmake

Find the CMake program on the system and check version compatibility.

find_package

Find a CMake package on the system.