From 9eb29319c51cb75fb0779611413be9e5141ee3f3 Mon Sep 17 00:00:00 2001 From: Yuval Deutscher Date: Sun, 9 Jul 2023 14:38:16 +0300 Subject: [PATCH] Add documentation to global corrosion options --- doc/src/usage.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/src/usage.md b/doc/src/usage.md index 948f6e6f..19bf950d 100644 --- a/doc/src/usage.md +++ b/doc/src/usage.md @@ -77,11 +77,16 @@ them **before** `find_package(Corrosion REQUIRED)`. 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 +- `Rust_COMPILER:STRING` - Path to `rustc`, which should be used for compiling or for toolchain + detection (if it is a `rustup` proxy). 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_RESOLVE_RUSTUP_TOOLCHAINS:BOOL` - If the found `rustc` is a `rustup` proxy, resolve a + concrete path to a specific toolchain managed by `rustup`, according to the `rustup` toolchain + selection rules and other options detailed here. If this option is turned off, the found `rustc` + will be used as-is to compile, even if it is a `rustup` proxy, which might increase compilation + time. Default: `ON` if the found `rustc` is a rustup proxy or a `rustup` managed toolchain was + requested, `OFF` otherwise. Forced `OFF` if `rustup` was not found. +- `Rust_CARGO:STRING` - Path to `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`. @@ -118,7 +123,7 @@ versions individually. - `Rust_LLVM_VERSION<_MAJOR|_MINOR|_PATCH>` - The LLVM version used by rustc. - `Rust_IS_NIGHTLY` - 1 if a nightly toolchain is used, otherwise 0. Useful for selecting an unstable feature for a crate, that is only available on nightly toolchains. -- Cache variables containing information based on the target triple for the selected target +- Cache variables containing information based on the target triple for the selected target as well as the default host target: - `Rust_CARGO_TARGET_ARCH`, `Rust_CARGO_HOST_ARCH`: e.g. `x86_64` or `aarch64` - `Rust_CARGO_TARGET_VENDOR`, `Rust_CARGO_HOST_VENDOR`: e.g. `apple`, `pc`, `unknown` etc. @@ -303,7 +308,7 @@ Corrosion respects the following `OUTPUT_DIRECTORY` target properties on CMake > - [RUNTIME_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.html) - [PDB_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/PDB_OUTPUT_DIRECTORY.html) -If the target property is set (e.g. by defining the `CMAKE_XYZ_OUTPUT_DIRECTORY` variable before calling +If the target property is set (e.g. by defining the `CMAKE_XYZ_OUTPUT_DIRECTORY` variable before calling `corrosion_import_crate()`), corrosion will copy the built rust artifacts to the location defined in the target property. Due to limitations in CMake these target properties are evaluated in a deferred manner, to