Corrosion, formerly known as cmake-cargo, is a tool for integrating Rust into an existing CMake project. Corrosion is capable of importing executables, static libraries, and dynamic libraries from a crate.

• Automatic Import of Executable, Static, and Shared Libraries from Rust Crate
• Easy Installation of Rust Executables
• Trivially Link Rust Executables to C++ Libraries in Tree
• Multi-Config Generator Support
• Simple Cross-Compilation

• Automatic Generation of Rust Bindings (via bindgen) and C/C++ Bindings (via cbindgen)
• Easy Install of Libraries

cmake_minimum_required(VERSION 3.12)
project(MyCoolProject LANGUAGES CXX)

find_package(Corrosion REQUIRED)

add_crate(rust-lib/Cargo.toml)

add_executable(cpp-exe main.cpp)
target_link_libraries(cpp-exe PUBLIC rust-lib)

There are two fundamental installation methods that are supported by Corrosion - installation as a CMake package or using it as a subdirectory in an existing CMake project. Corrosion strongly recommends installing the package, either via a package manager or manually using cmake's installation facilities.

Installation will pre-build all of Corrosion's native tooling, meaning that configuring any project which uses Corrosion is much faster. Using Corrosion as a subdirectory will result in the native tooling for Corrosion to be re-built every time you configure a new build directory, which could be a non-trivial cost for some projects. It also may result in issues with large, complex projects with many git submodules that each individually may use Corrosion. This can unnecessarily exacerbate diamond dependency problems that wouldn't otherwise occur using an externally installed Corrosion.

Coming soon...

After using a package manager, the next recommended way to use Corrosion is to install it as a package using CMake. This means you won't need to rebuild Corrosion's tooling every time you generate a new build directory. Installation also solves the diamond dependency problem that often comes with git submodules or other primitive dependency solutions.

First, download and install Corrosion:

git clone https://github.com/AndrewGaspar/corrosion.git
# Optionally, specify -DCMAKE_INSTALL_PREFIX=<target-install-path>. You can install Corrosion anyway
cmake -Scorrosion -Bbuild -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
# This next step may require sudo or admin privileges if you're installing to a system location,
# which is the default.
cmake --install build --config Release

You'll want to ensure that the install directory is available in your PATH or CMAKE_PREFIX_PATH environment variable. This is likely to already be the case by default on a Unix system, but on Windows it will install to C:\Program Files (x86)\Corrosion by default, which will not be in your PATH or CMAKE_PREFIX_PATH by default.

Once Corrosion is installed and you've ensured the package is avilable in your PATH, you can use it from your own project like any other package from your CMakeLists.txt:

find_package(Corrosion REQUIRED)

If installation is difficult or not feasible in your environment, you can use the FetchContent module to include Corrosion. This will download Corrosion and use it as if it were a subdirectory at configure time.

In your CMakeLists.txt:

include(FetchContent)

FetchContent_Declare(
    Corrosion
    GIT_REPOSITORY https://github.com/AndrewGaspar/corrosion.git
    GIT_TAG origin/master # Optionally specify a version tag or branch here
)

FetchContent_MakeAvailable(Corrosion)

Corrosion can also be used directly as a subdirectory. This solution may work well for small projects, but it's discouraged for large projects with many dependencies, especially those which may themselves use Corrosion. Either copy the Corrosion library into your source tree, being sure to preserve the LICENSE file, or add this repository as a git submodule:

git submodule add https://github.com/AndrewGaspar/corrosion.git

From there, using Corrosion is easy. In your CMakeLists.txt:

add_subdirectory(path/to/corrosion)

All of the following variables are evaluated automatically in most cases. In typical cases you shouldn't need to alter any of these.

• Rust_TOOLCHAIN:STRING - Specify a named rustup toolchain to use. Changes to this variable resets all other options. Default: If the first-found rustc is a rustup proxy, then the default rustup toolchain (see rustup show) is used. Otherwise, the variable is unset by default.
• Rust_ROOT:STRING - CMake provided. Path to a Rust toolchain to use. This is an alternative if you want to select a specific Rust toolchain, but it's not managed by rustup. Default: Nothing

• Rust_COMPILER:STRING - Path to an actual rustc. If set to a rustup proxy, it will be replaced by a path to an actual rustc. Default: The rustc in the first-found toolchain, either from rustup, or from a toolchain available in the user's PATH.
• Rust_CARGO:STRING - Path to an actual cargo. Default: the cargo installed next to ${Rust_COMPILER}.
• Rust_CARGO_TARGET:STRING - The default target triple to build for. Alter for cross-compiling. Default: On Visual Studio Generator, the matching triple for CMAKE_VS_PLATFORM_NAME. Otherwise, the default target triple reported by ${Rust_COMPILER} --version --verbose.

Corrosion makes it completely trivial to import a crate into an existing CMake project. Consider a project called rust2cpp with the following file structure:

rust2cpp/
    rust/
        src/
            lib.rs
        Cargo.lock
        Cargo.toml
    CMakeLists.txt
    main.cpp

This project defines a simple Rust lib crate, like so, in rust2cpp/rust/Cargo.toml:

[package]
name = "rust-lib"
version = "0.1.0"
authors = ["Andrew Gaspar <andrew.gaspar@outlook.com>"]
license = "MIT"
edition = "2018"

[dependencies]

[lib]
crate-type=["staticlib"]

In addition to "staticlib", you can also use "cdylib". In fact, you can define both with a single crate and switch between which is used using the standard BUILD_SHARED_LIBS variable.

This crate defines a simple crate called rust-lib. Importing this crate into your CMakeLists.txt is trivial:

# Note: you must have already included Corrosion for `add_crate` to be available. See the
# `Installation` section above.

add_crate(rust/Cargo.toml)

Now that you've imported the crate into CMake, all of the executables, static libraries, and dynamic libraries defined in the Rust can be directly referenced. So, merely define your C++ executable as normal in CMake and add your crate's library using target_link_libraries:

add_executable(cpp-exe main.cpp)
target_link_libraries(cpp-exe PUBLIC rust-lib)

That's it! You're now linking your Rust library to your C++ library.

Currently, you must manually declare bindings in your C or C++ program to the exported routines and types in your Rust project. You can see boths sides of this in the Rust code and in the C++ code.

Integration with cbindgen is planned for the future.

TODO