architect/input/raw.rs
1//! <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts>
2//!
3//! Cargo sets several environment variables when build scripts are run.
4
5use std::env;
6use std::ffi::OsString;
7
8macro_rules! decl_var_os {
9 ($($(#[$meta:meta])* $env:ident)*) => {
10 $(paste::paste! {
11 $(#[$meta])*
12 pub fn [<$env:lower _os>]() -> Option<OsString> {
13 env::var_os(stringify!($env))
14 }
15 })*
16 };
17}
18
19decl_var_os! {
20 /// Path to the `cargo` binary performing the build.
21 CARGO
22 /// The directory containing the manifest for the package being built (the package containing the build script). Also note that this is the value of the current working directory of the build script when it starts.
23 CARGO_MANIFEST_DIR
24 /// The path to the manifest of your package.
25 CARGO_MANIFEST_PATH
26 /// The manifest `links` value.
27 CARGO_MANIFEST_LINKS
28 /// Contains parameters needed for Cargo’s [jobserver] implementation to parallelize subprocesses. Rustc or cargo invocations from build.rs can already read `CARGO_MAKEFLAGS`, but GNU Make requires the flags to be specified either directly as arguments, or through the `MAKEFLAGS` environment variable. Currently Cargo doesn’t set the `MAKEFLAGS` variable, but it’s free for build scripts invoking GNU Make to set it to the contents of `CARGO_MAKEFLAGS`.
29 ///
30 /// [jobserver]: https://www.gnu.org/software/make/manual/html_node/Job-Slots.html
31 CARGO_MAKEFLAGS
32
33 /// The folder in which all output and intermediate artifacts should be placed. This folder is inside the build directory for the package being built, and it is unique for the package in question.
34 OUT_DIR
35 /// The target triple that is being compiled for. Native code should be compiled for this triple. See the [Target Triple] description for more information.
36 ///
37 /// [Target Triple]: https://doc.rust-lang.org/cargo/appendix/glossary.html#target
38 TARGET
39 /// The host triple of the Rust compiler.
40 HOST
41 /// The parallelism specified as the top-level parallelism. This can be useful to pass a `-j` parameter to a system like `make`. Note that care should be taken when interpreting this environment variable. For historical purposes this is still provided but recent versions of Cargo, for example, do not need to run `make -j`, and instead can set the `MAKEFLAGS` env var to the content of `CARGO_MAKEFLAGS` to activate the use of Cargo’s GNU Make compatible [jobserver] for sub-make invocations.
42 ///
43 /// [jobserver]: https://www.gnu.org/software/make/manual/html_node/Job-Slots.html
44 NUM_JOBS
45 /// Values of the corresponding variables for the profile currently being built.
46 OPT_LEVEL
47 /// Values of the corresponding variables for the profile currently being built.
48 DEBUG
49 /// `release` for release builds, `debug` for other builds. This is determined based on if the [profile] inherits from the [dev] or [release] profile. Using this environment variable is not recommended. Using other environment variables like `OPT_LEVEL` provide a more correct view of the actual settings being used.
50 ///
51 /// [profile]: https://doc.rust-lang.org/cargo/reference/profiles.html
52 /// [dev]: https://doc.rust-lang.org/cargo/reference/profiles.html#dev
53 /// [release]: https://doc.rust-lang.org/cargo/reference/profiles.html#release
54 PROFILE
55
56 /// The compiler and documentation generator that Cargo has resolved to use, passed to the build script so it might use it as well.
57 RUSTC
58 /// The compiler and documentation generator that Cargo has resolved to use, passed to the build script so it might use it as well.
59 RUSTDOC
60 /// The `rustc` wrapper, if any, that Cargo is using. See [build.rustc-wrapper].
61 ///
62 /// [build.rustc-wrapper]: https://doc.rust-lang.org/cargo/reference/config.html#buildrustc-wrapper
63 RUSTC_WRAPPER
64 /// The `rustc` wrapper, if any, that Cargo is using for workspace members. See [build.rustc-workspace-wrapper].
65 ///
66 /// [build.rustc-workspace-wrapper]: https://doc.rust-lang.org/cargo/reference/config.html#buildrustc-workspace-wrapper
67 RUSTC_WORKSPACE_WRAPPER
68 /// The path to the linker binary that Cargo has resolved to use for the current target, if specified. The linker can be changed by editing `.cargo/config.toml`; see the documentation about [cargo configuration] for more information.
69 ///
70 /// [cargo configuration]: https://doc.rust-lang.org/cargo/reference/config.html
71 RUSTC_LINKER
72 /// Extra flags that Cargo invokes `rustc` with, separated by a `0x1f` character (ASCII Unit Separator). See [build.rustflags]. Note that since Rust 1.55, `RUSTFLAGS` is removed from the environment; scripts should use `CARGO_ENCODED_RUSTFLAGS` instead.
73 ///
74 /// [build.rustflags]: https://doc.rust-lang.org/cargo/reference/config.html#buildrustflags
75 CARGO_ENCODED_RUSTFLAGS
76
77 /// Each activated feature of the package being built.
78 CARGO_CFG_FEATURE
79 /// Set on [unix-like platforms].
80 ///
81 /// [unix-like platforms]: https://doc.rust-lang.org/reference/conditional-compilation.html#unix-and-windows
82 CARGO_CFG_UNIX
83 /// Set on [windows-like platforms].
84 ///
85 /// [windows-like platforms]: https://doc.rust-lang.org/reference/conditional-compilation.html#unix-and-windows
86 CARGO_CFG_WINDOWS
87 /// The [target family].
88 ///
89 /// [target family]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_family
90 CARGO_CFG_TARGET_FAMILY
91 /// The [target operating system].
92 ///
93 /// [target operating system]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_os
94 CARGO_CFG_TARGET_OS
95 /// The CPU [target architecture].
96 ///
97 /// [target architecture]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_arch
98 CARGO_CFG_TARGET_ARCH
99 /// The [target vendor].
100 ///
101 /// [target vendor]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_vendor
102 CARGO_CFG_TARGET_VENDOR
103 /// The [target environment] ABI.
104 ///
105 /// [target environment]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_env
106 CARGO_CFG_TARGET_ENV
107 /// The [target ABI].
108 ///
109 /// [target ABI]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_abi
110 CARGO_CFG_TARGET_ABI
111 /// The CPU [pointer width].
112 ///
113 /// [pointer width]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_pointer_width
114 CARGO_CFG_TARGET_POINTER_WIDTH
115 /// The CPU [target endianness].
116 ///
117 /// [target endianness]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_endian
118 CARGO_CFG_TARGET_ENDIAN
119 /// List of CPU [target features] enabled.
120 ///
121 /// [target features]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_feature
122 CARGO_CFG_TARGET_FEATURE
123
124 /// The full version of your package.
125 CARGO_PKG_VERSION
126 /// The major version of your package.
127 CARGO_PKG_VERSION_MAJOR
128 /// The minor version of your package.
129 CARGO_PKG_VERSION_MINOR
130 /// The patch version of your package.
131 CARGO_PKG_VERSION_PATCH
132 /// The pre-release version of your package.
133 CARGO_PKG_VERSION_PRE
134 /// Colon separated list of authors from the manifest of your package.
135 CARGO_PKG_AUTHORS
136 /// The name of your package.
137 CARGO_PKG_NAME
138 /// The description from the manifest of your package.
139 CARGO_PKG_DESCRIPTION
140 /// The home page from the manifest of your package.
141 CARGO_PKG_HOMEPAGE
142 /// The repository from the manifest of your package.
143 CARGO_PKG_REPOSITORY
144 /// The license from the manifest of your package.
145 CARGO_PKG_LICENSE
146 /// The license file from the manifest of your package.
147 CARGO_PKG_LICENSE_FILE
148 /// The Rust version from the manifest of your package. Note that this is the minimum Rust version supported by the package, not the current Rust version.
149 CARGO_PKG_RUST_VERSION
150 /// Path to the README file of your package.
151 CARGO_PKG_README
152}
153
154/// For each activated feature of the package being built, this environment
155/// variable will be present where `<name>` is the name of the feature
156/// uppercased and having `-` translated to `_`.
157pub fn cargo_feature(name: &str) -> bool {
158 env::var_os(format!(
159 "CARGO_FEATURE_{}",
160 name.to_uppercase().replace('-', "_")
161 ))
162 .is_some()
163}
164
165/// For each activated feature of the package being built, this environment
166/// variable will be present where `<name>` is the name of the feature
167/// uppercased and having `-` translated to `_`.
168pub fn cargo_features() -> Vec<String> {
169 env::vars_os()
170 .filter_map(|(var, _)| {
171 var.into_string()
172 .ok()?
173 .strip_prefix("CARGO_FEATURE_")
174 .map(ToOwned::to_owned)
175 })
176 .collect()
177}
178
179/// For each [configuration option] of the package being built, this environment
180/// variable will contain the value of the configuration, where `<cfg>` is the
181/// name of the configuration uppercased and having `-` translated to `_`.
182/// Boolean configurations are present if they are set, and not present
183/// otherwise. Configurations with multiple values are joined to a single
184/// variable with the values delimited by `,`. This includes values built-in to
185/// the compiler (which can be seen with `rustc --print=cfg`) and values set by
186/// build scripts and extra flags passed to `rustc` (such as those defined in
187/// `RUSTFLAGS`). Some examples of what these variables are:
188///
189/// [configuration option]: https://doc.rust-lang.org/reference/conditional-compilation.html
190pub fn cargo_cfg_os(cfg: &str) -> Option<OsString> {
191 env::var_os(format!(
192 "CARGO_CFG_{}",
193 cfg.to_uppercase().replace('-', "_")
194 ))
195}
196
197/// For each [configuration option] of the package being built, this environment
198/// variable will contain the value of the configuration, where `<cfg>` is the
199/// name of the configuration uppercased and having `-` translated to `_`.
200/// Boolean configurations are present if they are set, and not present
201/// otherwise. Configurations with multiple values are joined to a single
202/// variable with the values delimited by `,`. This includes values built-in to
203/// the compiler (which can be seen with `rustc --print=cfg`) and values set by
204/// build scripts and extra flags passed to `rustc` (such as those defined in
205/// `RUSTFLAGS`). Some examples of what these variables are:
206///
207/// [configuration option]: https://doc.rust-lang.org/reference/conditional-compilation.html
208pub fn cargo_cfgs_os() -> Vec<(String, OsString)> {
209 env::vars_os()
210 .filter_map(|(var, value)| {
211 var.into_string()
212 .ok()?
213 .strip_prefix("CARGO_CFG_")
214 .map(|k| (k.to_owned(), value))
215 })
216 .collect()
217}
218
219/// For more information about this set of environment variables, see build
220/// script documentation about [links].
221///
222/// [links]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#the-links-manifest-key
223pub fn cargo_dep_os(name: &str, key: &str) -> Option<OsString> {
224 env::var_os(format!(
225 "DEP_{}_{}",
226 name.to_uppercase().replace('-', "_"),
227 key.to_uppercase().replace('-', "_")
228 ))
229}
230
231/// For more information about this set of environment variables, see build
232/// script documentation about [links].
233///
234/// [links]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#the-links-manifest-key
235pub fn cargo_deps_os() -> Vec<(String, String, OsString)> {
236 env::vars_os()
237 .filter_map(|(var, value)| {
238 var.into_string()
239 .ok()?
240 .strip_prefix("DEP_")
241 .and_then(|s| s.split_once('_'))
242 .map(|(d, k)| (d.to_owned(), k.to_owned(), value))
243 })
244 .collect()
245}