29 [package]: https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html |
29 [package]: https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html |
30 [workspace]: https://doc.rust-lang.org/cargo/reference/workspaces.html |
30 [workspace]: https://doc.rust-lang.org/cargo/reference/workspaces.html |
31 [`IMPORTED`]: https://cmake.org/cmake/help/latest/prop_tgt/IMPORTED.html |
31 [`IMPORTED`]: https://cmake.org/cmake/help/latest/prop_tgt/IMPORTED.html |
32 [`INTERFACE`]: https://cmake.org/cmake/help/latest/command/add_library.html#interface-libraries |
32 [`INTERFACE`]: https://cmake.org/cmake/help/latest/command/add_library.html#interface-libraries |
33 [target_link_libraries]: https://cmake.org/cmake/help/latest/command/target_link_libraries.html |
33 [target_link_libraries]: https://cmake.org/cmake/help/latest/command/target_link_libraries.html |
|
34 |
|
35 ### Experimental: Install crate and headers with `corrosion_install` |
|
36 |
|
37 The default CMake [install commands] do not work correctly with the targets exported from `corrosion_import_crate()`. |
|
38 Corrosion provides `corrosion_install` to automatically install relevant files: |
|
39 |
|
40 {{#include ../../cmake/Corrosion.cmake:corrosion-install}} |
|
41 |
|
42 The example below shows how to import a rust library and make it available for install through CMake. |
|
43 |
|
44 ```cmake |
|
45 include(FetchContent) |
|
46 |
|
47 FetchContent_Declare( |
|
48 Corrosion |
|
49 GIT_REPOSITORY https://github.com/corrosion-rs/corrosion.git |
|
50 GIT_TAG v0.5 # Optionally specify a commit hash, version tag or branch here |
|
51 ) |
|
52 # Set any global configuration variables such as `Rust_TOOLCHAIN` before this line! |
|
53 FetchContent_MakeAvailable(Corrosion) |
|
54 |
|
55 # Import targets defined in a package or workspace manifest `Cargo.toml` file |
|
56 corrosion_import_crate(MANIFEST_PATH rust-lib/Cargo.toml) |
|
57 |
|
58 # Add a manually written header file which will be exported |
|
59 # Requires CMake >=3.23 |
|
60 target_sources(rust-lib INTERFACE |
|
61 FILE_SET HEADERS |
|
62 BASE_DIRS include |
|
63 FILES |
|
64 include/rust-lib/rust-lib.h |
|
65 ) |
|
66 |
|
67 # OR for CMake <= 3.23 |
|
68 target_include_directories(is_odd INTERFACE |
|
69 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include> |
|
70 $<INSTALL_INTERFACE:include> |
|
71 ) |
|
72 target_sources(is_odd |
|
73 INTERFACE |
|
74 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/rust-lib/rust-lib.h> |
|
75 $<INSTALL_INTERFACE:include/rust-lib/rust-lib.h> |
|
76 ) |
|
77 |
|
78 # Rust libraries must be installed using `corrosion_install`. |
|
79 corrosion_install(TARGETS rust-lib EXPORT RustLibTargets) |
|
80 |
|
81 # Installs the main target |
|
82 install( |
|
83 EXPORT RustLibTargets |
|
84 NAMESPACE RustLib:: |
|
85 DESTINATION lib/cmake/RustLib |
|
86 ) |
|
87 |
|
88 # Necessary for packaging helper commands |
|
89 include(CMakePackageConfigHelpers) |
|
90 # Create a file for checking version compatibility |
|
91 # Optional |
|
92 write_basic_package_version_file( |
|
93 "${CMAKE_CURRENT_BINARY_DIR}/RustLibConfigVersion.cmake" |
|
94 VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}" |
|
95 COMPATIBILITY AnyNewerVersion |
|
96 ) |
|
97 |
|
98 # Configures the main config file that cmake loads |
|
99 configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in |
|
100 "${CMAKE_CURRENT_BINARY_DIR}/RustLibConfig.cmake" |
|
101 INSTALL_DESTINATION lib/cmake/RustLib |
|
102 NO_SET_AND_CHECK_MACRO |
|
103 NO_CHECK_REQUIRED_COMPONENTS_MACRO |
|
104 ) |
|
105 # Config.cmake.in contains |
|
106 # @PACKAGE_INIT@ |
|
107 # |
|
108 # include(${CMAKE_CURRENT_LIST_DIR}/RustLibTargetsCorrosion.cmake) |
|
109 # include(${CMAKE_CURRENT_LIST_DIR}/RustLibTargets.cmake) |
|
110 |
|
111 # Install all generated files |
|
112 install(FILES |
|
113 ${CMAKE_CURRENT_BINARY_DIR}/RustLibConfigVersion.cmake |
|
114 ${CMAKE_CURRENT_BINARY_DIR}/RustLibConfig.cmake |
|
115 ${CMAKE_CURRENT_BINARY_DIR}/corrosion/RustLibTargetsCorrosion.cmake |
|
116 DESTINATION lib/cmake/RustLib |
|
117 ) |
|
118 ``` |
|
119 |
|
120 [install commands]: https://cmake.org/cmake/help/latest/command/install.html |
34 |
121 |
35 ### Per Target options |
122 ### Per Target options |
36 |
123 |
37 Some configuration options can be specified individually for each target. You can set them via the |
124 Some configuration options can be specified individually for each target. You can set them via the |
38 `corrosion_set_xxx()` functions specified below: |
125 `corrosion_set_xxx()` functions specified below: |
66 responsible for also adding a rustflag which adds the necessary `--target=` argument for the |
153 responsible for also adding a rustflag which adds the necessary `--target=` argument for the |
67 linker. |
154 linker. |
68 |
155 |
69 |
156 |
70 ### Global Corrosion Options |
157 ### Global Corrosion Options |
71 All of the following variables are evaluated automatically in most cases. In typical cases you |
158 |
|
159 #### Selecting the Rust toolchain and target triple |
|
160 |
|
161 The following variables are evaluated automatically in most cases. In typical cases you |
72 shouldn't need to alter any of these. If you do want to specify them manually, make sure to set |
162 shouldn't need to alter any of these. If you do want to specify them manually, make sure to set |
73 them **before** `find_package(Corrosion REQUIRED)`. |
163 them **before** `find_package(Corrosion REQUIRED)`. |
74 |
164 |
75 - `Rust_TOOLCHAIN:STRING` - Specify a named rustup toolchain to use. Changes to this variable |
165 - `Rust_TOOLCHAIN:STRING` - Specify a named rustup toolchain to use. Changes to this variable |
76 resets all other options. Default: If the first-found `rustc` is a `rustup` proxy, then the default |
166 resets all other options. Default: If the first-found `rustc` is a `rustup` proxy, then the default |
88 requested, `OFF` otherwise. Forced `OFF` if `rustup` was not found. |
178 requested, `OFF` otherwise. Forced `OFF` if `rustup` was not found. |
89 - `Rust_CARGO:STRING` - Path to `cargo`. Default: the `cargo` installed next to `${Rust_COMPILER}`. |
179 - `Rust_CARGO:STRING` - Path to `cargo`. Default: the `cargo` installed next to `${Rust_COMPILER}`. |
90 - `Rust_CARGO_TARGET:STRING` - The default target triple to build for. Alter for cross-compiling. |
180 - `Rust_CARGO_TARGET:STRING` - The default target triple to build for. Alter for cross-compiling. |
91 Default: On Visual Studio Generator, the matching triple for `CMAKE_VS_PLATFORM_NAME`. Otherwise, |
181 Default: On Visual Studio Generator, the matching triple for `CMAKE_VS_PLATFORM_NAME`. Otherwise, |
92 the default target triple reported by `${Rust_COMPILER} --version --verbose`. |
182 the default target triple reported by `${Rust_COMPILER} --version --verbose`. |
93 - `CORROSION_NATIVE_TOOLING:BOOL` - Use a native tool (written in Rust) as part of Corrosion. This |
183 |
94 option increases the configure-time significantly unless Corrosion is installed. |
184 #### Enable Convenience Options |
95 Default: `OFF` if CMake >= 3.19.0. Forced `ON` for CMake < 3.19. |
185 |
|
186 The following options are off by default, but may increase convenience: |
|
187 |
|
188 - `Rust_RUSTUP_INSTALL_MISSING_TARGET:BOOL`: Automatically install a missing target via `rustup` instead of failing. |
96 |
189 |
97 |
190 |
98 #### Developer/Maintainer Options |
191 #### Developer/Maintainer Options |
99 These options are not used in the course of normal Corrosion usage, but are used to configure how |
192 These options are not used in the course of normal Corrosion usage, but are used to configure how |
100 Corrosion is built and installed. Only applies to Corrosion builds and subdirectory uses. |
193 Corrosion is built and installed. Only applies to Corrosion builds and subdirectory uses. |
101 |
194 |
102 - `CORROSION_DEV_MODE:BOOL` - Indicates that Corrosion is being actively developed. Default: `OFF` |
|
103 if Corrosion is a subdirectory, `ON` if it is the top-level project |
|
104 - `CORROSION_BUILD_TESTS:BOOL` - Build the Corrosion tests. Default: `Off` if Corrosion is a |
195 - `CORROSION_BUILD_TESTS:BOOL` - Build the Corrosion tests. Default: `Off` if Corrosion is a |
105 subdirectory, `ON` if it is the top-level project |
196 subdirectory, `ON` if it is the top-level project |
106 - `CORROSION_GENERATOR_EXECUTABLE:STRING` - Specify a path to the corrosion-generator executable. |
|
107 This is to support scenarios where it's easier to build corrosion-generator outside of the normal |
|
108 bootstrap path, such as in the case of package managers that make it very easy to import Rust |
|
109 crates for fully reproducible, offline builds. |
|
110 - `CORROSION_INSTALL_EXECUTABLE:BOOL` - Controls whether corrosion-generator is installed with the |
|
111 package. Default: `ON` with `CORROSION_GENERATOR_EXECUTABLE` unset, otherwise `OFF` |
|
112 |
197 |
113 |
198 |
114 ### Information provided by Corrosion |
199 ### Information provided by Corrosion |
115 |
200 |
116 For your convenience, Corrosion sets a number of variables which contain information about the version of the rust |
201 For your convenience, Corrosion sets a number of variables which contain information about the version of the rust |
293 -DCMAKE_ANDROID_NDK=/path/to/android-ndk-rxxd -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a |
378 -DCMAKE_ANDROID_NDK=/path/to/android-ndk-rxxd -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a |
294 ``` |
379 ``` |
295 |
380 |
296 **Important note:** The Android SDK ships with CMake 3.10 at newest, which Android Studio will |
381 **Important note:** The Android SDK ships with CMake 3.10 at newest, which Android Studio will |
297 prefer over any CMake you've installed locally. CMake 3.10 is insufficient for using Corrosion, |
382 prefer over any CMake you've installed locally. CMake 3.10 is insufficient for using Corrosion, |
298 which requires a minimum of CMake 3.15. If you're using Android Studio to build your project, |
383 which requires a minimum of CMake 3.22. If you're using Android Studio to build your project, |
299 follow the instructions in the Android Studio documentation for |
384 follow the instructions in the Android Studio documentation for |
300 [using a specific version of CMake](https://developer.android.com/studio/projects/install-ndk#vanilla_cmake). |
385 [using a specific version of CMake](https://developer.android.com/studio/projects/install-ndk#vanilla_cmake). |
301 |
386 |
302 |
387 |
303 ### CMake `OUTPUT_DIRECTORY` target properties and `IMPORTED_LOCATION` |
388 ### CMake `OUTPUT_DIRECTORY` target properties and `IMPORTED_LOCATION` |
304 |
389 |
305 Corrosion respects the following `OUTPUT_DIRECTORY` target properties on CMake >= 3.19: |
390 Corrosion respects the following `OUTPUT_DIRECTORY` target properties: |
306 - [ARCHIVE_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.html) |
391 - [ARCHIVE_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.html) |
307 - [LIBRARY_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.html) |
392 - [LIBRARY_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.html) |
308 - [RUNTIME_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.html) |
393 - [RUNTIME_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.html) |
309 - [PDB_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/PDB_OUTPUT_DIRECTORY.html) |
394 - [PDB_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/prop_tgt/PDB_OUTPUT_DIRECTORY.html) |
310 |
395 |