Adding Corrosion to your project

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. For CMake versions below 3.19 Corrosion strongly recommends installing the package, either via a package manager or manually using CMake's installation facilities. If you have CMake 3.19 or newer, we recommend to use either the FetchContent or the Subdirectory method to integrate Corrosion.

FetchContent

If you are using CMake >= 3.19 or 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/corrosion-rs/corrosion.git
    GIT_TAG v0.5 # Optionally specify a commit hash, version tag or branch here
)
# Set any global configuration variables such as `Rust_TOOLCHAIN` before this line!
FetchContent_MakeAvailable(Corrosion)

Subdirectory

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/corrosion-rs/corrosion.git

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

add_subdirectory(path/to/corrosion)

Installation

Installation will pre-build all of Corrosion's native tooling (required only for CMake versions below 3.19) and install it together with Corrosions CMake files into a standard location. On CMake >= 3.19 installing Corrosion does not offer any speed advantages, unless the native tooling option is explicitly enabled.

Install from source

First, download and install Corrosion:

git clone https://github.com/corrosion-rs/corrosion.git
# Optionally, specify -DCMAKE_INSTALL_PREFIX=<target-install-path> to specify a 
# custom installation directory
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 available in your PATH, you can use it from your own project like any other package from your CMakeLists.txt:

find_package(Corrosion REQUIRED)

Package Manager

Homebrew (unofficial)

Corrosion is available via Homebrew and can be installed via

brew install corrosion

Please note that this package is community maintained. Please also keep in mind that Corrosion follows semantic versioning and minor version bumps (i.e. 0.3 -> 0.4) may contain breaking changes, while Corrosion is still pre 1.0. Please read the release notes when upgrading Corrosion.