--- a/tools/corrosion/doc/src/usage.md Wed Sep 18 14:10:51 2024 +0200
+++ b/tools/corrosion/doc/src/usage.md Wed Nov 20 21:37:47 2024 +0100
@@ -32,6 +32,93 @@
[`INTERFACE`]: https://cmake.org/cmake/help/latest/command/add_library.html#interface-libraries
[target_link_libraries]: https://cmake.org/cmake/help/latest/command/target_link_libraries.html
+### Experimental: Install crate and headers with `corrosion_install`
+
+The default CMake [install commands] do not work correctly with the targets exported from `corrosion_import_crate()`.
+Corrosion provides `corrosion_install` to automatically install relevant files:
+
+{{#include ../../cmake/Corrosion.cmake:corrosion-install}}
+
+The example below shows how to import a rust library and make it available for install through CMake.
+
+```cmake
+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)
+
+# Import targets defined in a package or workspace manifest `Cargo.toml` file
+corrosion_import_crate(MANIFEST_PATH rust-lib/Cargo.toml)
+
+# Add a manually written header file which will be exported
+# Requires CMake >=3.23
+target_sources(rust-lib INTERFACE
+ FILE_SET HEADERS
+ BASE_DIRS include
+ FILES
+ include/rust-lib/rust-lib.h
+)
+
+# OR for CMake <= 3.23
+target_include_directories(is_odd INTERFACE
+ $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+ $<INSTALL_INTERFACE:include>
+)
+target_sources(is_odd
+ INTERFACE
+ $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/rust-lib/rust-lib.h>
+ $<INSTALL_INTERFACE:include/rust-lib/rust-lib.h>
+)
+
+# Rust libraries must be installed using `corrosion_install`.
+corrosion_install(TARGETS rust-lib EXPORT RustLibTargets)
+
+# Installs the main target
+install(
+ EXPORT RustLibTargets
+ NAMESPACE RustLib::
+ DESTINATION lib/cmake/RustLib
+)
+
+# Necessary for packaging helper commands
+include(CMakePackageConfigHelpers)
+# Create a file for checking version compatibility
+# Optional
+write_basic_package_version_file(
+ "${CMAKE_CURRENT_BINARY_DIR}/RustLibConfigVersion.cmake"
+ VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}"
+ COMPATIBILITY AnyNewerVersion
+)
+
+# Configures the main config file that cmake loads
+configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
+ "${CMAKE_CURRENT_BINARY_DIR}/RustLibConfig.cmake"
+ INSTALL_DESTINATION lib/cmake/RustLib
+ NO_SET_AND_CHECK_MACRO
+ NO_CHECK_REQUIRED_COMPONENTS_MACRO
+)
+# Config.cmake.in contains
+# @PACKAGE_INIT@
+#
+# include(${CMAKE_CURRENT_LIST_DIR}/RustLibTargetsCorrosion.cmake)
+# include(${CMAKE_CURRENT_LIST_DIR}/RustLibTargets.cmake)
+
+# Install all generated files
+install(FILES
+ ${CMAKE_CURRENT_BINARY_DIR}/RustLibConfigVersion.cmake
+ ${CMAKE_CURRENT_BINARY_DIR}/RustLibConfig.cmake
+ ${CMAKE_CURRENT_BINARY_DIR}/corrosion/RustLibTargetsCorrosion.cmake
+ DESTINATION lib/cmake/RustLib
+)
+```
+
+[install commands]: https://cmake.org/cmake/help/latest/command/install.html
+
### Per Target options
Some configuration options can be specified individually for each target. You can set them via the
@@ -68,7 +155,10 @@
### Global Corrosion Options
-All of the following variables are evaluated automatically in most cases. In typical cases you
+
+#### Selecting the Rust toolchain and target triple
+
+The following variables are evaluated automatically in most cases. In typical cases you
shouldn't need to alter any of these. If you do want to specify them manually, make sure to set
them **before** `find_package(Corrosion REQUIRED)`.
@@ -90,25 +180,20 @@
- `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_NATIVE_TOOLING:BOOL` - Use a native tool (written in Rust) as part of Corrosion. This
- option increases the configure-time significantly unless Corrosion is installed.
- Default: `OFF` if CMake >= 3.19.0. Forced `ON` for CMake < 3.19.
+
+#### Enable Convenience Options
+
+The following options are off by default, but may increase convenience:
+
+- `Rust_RUSTUP_INSTALL_MISSING_TARGET:BOOL`: Automatically install a missing target via `rustup` instead of failing.
#### Developer/Maintainer Options
These options are not used in the course of normal Corrosion usage, but are used to configure how
Corrosion is built and installed. Only applies to Corrosion builds and subdirectory uses.
-- `CORROSION_DEV_MODE:BOOL` - Indicates that Corrosion is being actively developed. Default: `OFF`
- if Corrosion is a subdirectory, `ON` if it is the top-level project
- `CORROSION_BUILD_TESTS:BOOL` - Build the Corrosion tests. Default: `Off` if Corrosion is a
subdirectory, `ON` if it is the top-level project
-- `CORROSION_GENERATOR_EXECUTABLE:STRING` - Specify a path to the corrosion-generator executable.
- This is to support scenarios where it's easier to build corrosion-generator outside of the normal
- bootstrap path, such as in the case of package managers that make it very easy to import Rust
- crates for fully reproducible, offline builds.
-- `CORROSION_INSTALL_EXECUTABLE:BOOL` - Controls whether corrosion-generator is installed with the
- package. Default: `ON` with `CORROSION_GENERATOR_EXECUTABLE` unset, otherwise `OFF`
### Information provided by Corrosion
@@ -295,14 +380,14 @@
**Important note:** The Android SDK ships with CMake 3.10 at newest, which Android Studio will
prefer over any CMake you've installed locally. CMake 3.10 is insufficient for using Corrosion,
-which requires a minimum of CMake 3.15. If you're using Android Studio to build your project,
+which requires a minimum of CMake 3.22. If you're using Android Studio to build your project,
follow the instructions in the Android Studio documentation for
[using a specific version of CMake](https://developer.android.com/studio/projects/install-ndk#vanilla_cmake).
### CMake `OUTPUT_DIRECTORY` target properties and `IMPORTED_LOCATION`
-Corrosion respects the following `OUTPUT_DIRECTORY` target properties on CMake >= 3.19:
+Corrosion respects the following `OUTPUT_DIRECTORY` target properties:
- [ARCHIVE_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.html)
- [LIBRARY_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.html)
- [RUNTIME_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.html)