From e7db03cd3bc4ea39a5b27cd9057c4d959ae56653 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 7 Aug 2024 22:28:31 -0400 Subject: [PATCH 1/5] Add identifier syntax to conditional-compilation.md --- src/conditional-compilation.md | 141 ++++++++++++++++++++++++++++++--- 1 file changed, 131 insertions(+), 10 deletions(-) diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index f73f8354a..e6e26b21c 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -1,5 +1,9 @@ # Conditional compilation +r[cfg] + + +r[cfg.syntax] > **Syntax**\ > _ConfigurationPredicate_ :\ >       _ConfigurationOption_\ @@ -22,30 +26,62 @@ > _ConfigurationPredicateList_\ >    _ConfigurationPredicate_ (`,` _ConfigurationPredicate_)\* `,`? -*Conditionally compiled source code* is source code that is compiled only under certain conditions. Source code can be made conditionally compiled using the [`cfg`] and [`cfg_attr`] [attributes] and the built-in [`cfg` macro]. Whether to compile can depend on the target architecture of the compiled crate, arbitrary values passed to the compiler, and other things further described below. +r[cfg.general] +*Conditionally compiled source code* is source code that is compiled only under certain conditions. + +r[cfg.attributes-macro] +Source code can be made conditionally compiled using the [`cfg`] and [`cfg_attr`] [attributes] and the built-in [`cfg` macro]. +r[cfg.conditional] +Whether to compile can depend on the target architecture of the compiled crate, arbitrary values passed to the compiler, and other things further described below. + +r[cfg.predicate] Each form of conditional compilation takes a _configuration predicate_ that evaluates to true or false. The predicate is one of the following: +r[cfg.predicate.option] * A configuration option. The predicate is true if the option is set, and false if it is unset. + +r[cfg.predicate.all] * `all()` with a comma-separated list of configuration predicates. It is true if all of the given predicates are true, or if the list is empty. + +r[cfg.predicate.any] * `any()` with a comma-separated list of configuration predicates. It is true if at least one of the given predicates is true. If there are no predicates, it is false. + +r[cfg.predicate.not] * `not()` with a configuration predicate. It is true if its predicate is false and false if its predicate is true. +r[cfg.option-spec] _Configuration options_ are either names or key-value pairs, and are either set or unset. + +r[cfg.option-name] Names are written as a single identifier, such as `unix`. + +r[cfg.option-key-value] Key-value pairs are written as an identifier, `=`, and then a string, such as `target_arch = "x86_64"`. > **Note**: Whitespace around the `=` is ignored, so `foo="bar"` and `foo = "bar"` are equivalent. +r[cfg.option-key-uniqueness] Keys do not need to be unique. For example, both `feature = "std"` and `feature = "serde"` can be set at the same time. ## Set Configuration Options +r[cfg.options.set] + + +r[cfg.options.general] Which configuration options are set is determined statically during the -compilation of the crate. Some options are _compiler-set_ based on data -about the compilation. Other options are _arbitrarily-set_ based on input -passed to the compiler outside of the code. It is not possible to set a +compilation of the crate. + +r[cfg.options.target] +Some options are _compiler-set_ based on data about the compilation. + +r[cfg.options.other] +Other options are _arbitrarily-set_ based on input passed to the compiler outside of the code. + +r[cfg.options.crate] +It is not possible to set a configuration option from within the source code of the crate being compiled. > **Note**: For `rustc`, arbitrary-set configuration options are set using the @@ -60,10 +96,15 @@ configuration option from within the source code of the crate being compiled. ### `target_arch` +r[cfg.target_arch] + + +r[cfg.target_arch.gen] Key-value option set once with the target's CPU architecture. The value is similar to the first element of the platform's target triple, but not identical. +r[cfg.target_arch.values] Example values: * `"x86"` @@ -76,9 +117,14 @@ Example values: ### `target_feature` +r[cfg.target_feature] + + +r[cfg.target_feature.general] Key-value option set for each platform feature available for the current compilation target. +r[cfg.target_feature.values] Example values: * `"avx"` @@ -90,14 +136,22 @@ Example values: * `"sse4.1"` See the [`target_feature` attribute] for more details on the available -features. An additional feature of `crt-static` is available to the +features. + +r[cfg.target_feature.crt_static] +An additional feature of `crt-static` is available to the `target_feature` option to indicate that a [static C runtime] is available. ### `target_os` +r[cfg.target_os] + + +r[cfg.target_os.general] Key-value option set once with the target's operating system. This value is similar to the second and third element of the platform's target triple. +r[cfg.target_os.values] Example values: * `"windows"` @@ -113,10 +167,15 @@ Example values: ### `target_family` +r[cfg.target_family] + + +r[cfg.target_family.general] Key-value option providing a more generic description of a target, such as the family of the operating systems or architectures that the target generally falls into. Any number of `target_family` key-value pairs can be set. +r[cfg.target_family.values] Example values: * `"unix"` @@ -126,11 +185,17 @@ Example values: ### `unix` and `windows` -`unix` is set if `target_family = "unix"` is set and `windows` is set if -`target_family = "windows"` is set. +r[cfg.target_family.unix] +`unix` is set if `target_family = "unix"` is set. + +r[cfg.target_family.windows] +`windows` is set if `target_family = "windows"` is set. ### `target_env` +r[cfg.target_env] + +r[cfg.target_env.values] Key-value option set with further disambiguating information about the target platform with information about the ABI or `libc` used. For historical reasons, this value is only defined as not the empty-string when actually needed for @@ -139,6 +204,7 @@ empty. This value is similar to the fourth element of the platform's target triple. One difference is that embedded ABIs such as `gnueabihf` will simply define `target_env` as `"gnu"`. +r[cfg.target_env.values] Example values: * `""` @@ -149,12 +215,19 @@ Example values: ### `target_abi` +r[cfg.target_abi] + + +r[cfg.target_env.general] Key-value option set to further disambiguate the `target_env` with information -about the target ABI. For historical reasons, -this value is only defined as not the empty-string when actually needed for -disambiguation. Thus, for example, on many GNU platforms, this value will be +about the target ABI. + +r[cfg.target_env.disambiguation] +For historical reasons, this value is only defined as not the empty-string when actually + needed for disambiguation. Thus, for example, on many GNU platforms, this value will be empty. +r[cfg.target_env.values] Example values: * `""` @@ -166,13 +239,19 @@ Example values: ### `target_endian` +r[cfg.target_endian] Key-value option set once with either a value of "little" or "big" depending on the endianness of the target's CPU. ### `target_pointer_width` +r[cfg.target_poitner_width] + + +r[cfg.target_pointer_width.general] Key-value option set once with the target's pointer width in bits. +r[cfg.target_pointer_width.values] Example values: * `"16"` @@ -181,8 +260,13 @@ Example values: ### `target_vendor` +r[cfg.target_vendor] + + +r[cfg.target_vendor.general] Key-value option set once with the vendor of the target. +r[cfg.target_vendor.values] Example values: * `"apple"` @@ -192,12 +276,19 @@ Example values: ### `target_has_atomic` +r[cfg.target_has_atomic] + + +r[cfg.target_has_atomic.general] Key-value option set for each bit width that the target supports atomic loads, stores, and compare-and-swap operations. +r[cfg.target_has_atomic.stdlib] When this cfg is present, all of the stable [`core::sync::atomic`] APIs are available for the relevant atomic width. + +r[cfg.target_has_atomic.values] Possible values: * `"8"` @@ -209,11 +300,15 @@ Possible values: ### `test` +r[cfg.test] + Enabled when compiling the test harness. Done with `rustc` by using the [`--test`] flag. See [Testing] for more on testing support. ### `debug_assertions` +r[cfg.debug_assertions] + Enabled by default when compiling without optimizations. This can be used to enable extra debugging code in development but not in production. For example, it controls the behavior of the standard library's @@ -221,13 +316,20 @@ production. For example, it controls the behavior of the standard library's ### `proc_macro` +r[cfg.proc_macro] + Set when the crate being compiled is being compiled with the `proc_macro` [crate type]. ### `panic` +r[cfg.panic] + + +r[cfg.panic.general] Key-value option set depending on the panic strategy. Note that more values may be added in the future. +r[cfg.panic.values] Example values: * `"abort"` @@ -237,20 +339,28 @@ Example values: ### The `cfg` attribute +r[cfg.attr] + + +r[cfg.attr.syntax] > **Syntax**\ > _CfgAttrAttribute_ :\ >    `cfg` `(` _ConfigurationPredicate_ `)` +r[cfg.attr.general] The `cfg` [attribute] conditionally includes the thing it is attached to based on a configuration predicate. +r[cfg.attr.syntax-explanation] It is written as `cfg`, `(`, a configuration predicate, and finally `)`. +r[cfg.attr.effect] If the predicate is true, the thing is rewritten to not have the `cfg` attribute on it. If the predicate is false, the thing is removed from the source code. +r[cfg.attr.crate-level-attrs] When a crate-level `cfg` has a false predicate, the behavior is slightly different: any crate attributes preceding the `cfg` are kept, and any crate attributes following the `cfg` are removed. This allows `#![no_std]` and @@ -293,10 +403,15 @@ fn when_unwinding() { ``` +r[cfg.attr.restriction] The `cfg` attribute is allowed anywhere attributes are allowed. ### The `cfg_attr` attribute +r[cfg.cfg_attr] + + +r[cfg.cfg_attr.syntax] > **Syntax**\ > _CfgAttrAttribute_ :\ >    `cfg_attr` `(` _ConfigurationPredicate_ `,` _CfgAttrs_? `)` @@ -304,9 +419,12 @@ The `cfg` attribute is allowed anywhere attributes are allowed. > _CfgAttrs_ :\ >    [_Attr_] (`,` [_Attr_])\* `,`? + +r[cfg.cfg_attr.syntax] The `cfg_attr` [attribute] conditionally includes [attributes] based on a configuration predicate. +r[cfg.cfg_attr.behaviour] When the configuration predicate is true, this attribute expands out to the attributes listed after the predicate. For example, the following module will either be found at `linux.rs` or `windows.rs` based on the target. @@ -318,6 +436,7 @@ either be found at `linux.rs` or `windows.rs` based on the target. mod os; ``` +r[cfg.cfg_attr.attribute-list] Zero, one, or more attributes may be listed. Multiple attributes will each be expanded into separate attributes. For example: @@ -337,10 +456,12 @@ fn bewitched() {} > is valid. This example would be equivalent to > `#[cfg_attr(all(target_os = "linux", feature ="multithreaded"), some_other_attribute)]`. +r[cfg.cfg_attr.restriction] The `cfg_attr` attribute is allowed anywhere attributes are allowed. ### The `cfg` macro +r[cfg.macro] The built-in `cfg` macro takes in a single configuration predicate and evaluates to the `true` literal when the predicate is true and the `false` literal when it is false. From 8ce6f604a25553fdcf8d4c1c9788500d1084e632 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 7 Aug 2024 22:33:31 -0400 Subject: [PATCH 2/5] Fix duplicate key cfg.target_env.general --- src/conditional-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index e6e26b21c..fdedb431e 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -195,7 +195,7 @@ r[cfg.target_family.windows] r[cfg.target_env] -r[cfg.target_env.values] +r[cfg.target_env.general] Key-value option set with further disambiguating information about the target platform with information about the ABI or `libc` used. For historical reasons, this value is only defined as not the empty-string when actually needed for From fe425df49099310afdeeb7da8febd326dcf435d2 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 7 Aug 2024 22:36:54 -0400 Subject: [PATCH 3/5] Use proper keys in cfg.target_abi --- src/conditional-compilation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index fdedb431e..bff5483a5 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -218,16 +218,16 @@ Example values: r[cfg.target_abi] -r[cfg.target_env.general] +r[cfg.target_abi.general] Key-value option set to further disambiguate the `target_env` with information about the target ABI. -r[cfg.target_env.disambiguation] +r[cfg.target_abi.disambiguation] For historical reasons, this value is only defined as not the empty-string when actually needed for disambiguation. Thus, for example, on many GNU platforms, this value will be empty. -r[cfg.target_env.values] +r[cfg.target_abi.values] Example values: * `""` From f833730b8891caaf881f4cce1e4317c6070253f4 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 7 Aug 2024 22:38:35 -0400 Subject: [PATCH 4/5] I'm 0/3 on duplicate attributes, 4th times the charm? --- src/conditional-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index bff5483a5..ea28d4812 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -420,7 +420,7 @@ r[cfg.cfg_attr.syntax] >    [_Attr_] (`,` [_Attr_])\* `,`? -r[cfg.cfg_attr.syntax] +r[cfg.cfg_attr.general] The `cfg_attr` [attribute] conditionally includes [attributes] based on a configuration predicate. From 17499898b02cd920175eaed55a71e850e18aae09 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 21 Aug 2024 19:50:39 -0400 Subject: [PATCH 5/5] Remove double linebreaks from conditional-compilation.md --- src/conditional-compilation.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index ea28d4812..2a4db8d5a 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -2,7 +2,6 @@ r[cfg] - r[cfg.syntax] > **Syntax**\ > _ConfigurationPredicate_ :\ @@ -69,7 +68,6 @@ Keys do not need to be unique. For example, both `feature = "std"` and `feature r[cfg.options.set] - r[cfg.options.general] Which configuration options are set is determined statically during the compilation of the crate. @@ -98,7 +96,6 @@ configuration option from within the source code of the crate being compiled. r[cfg.target_arch] - r[cfg.target_arch.gen] Key-value option set once with the target's CPU architecture. The value is similar to the first element of the platform's target triple, but not @@ -119,7 +116,6 @@ Example values: r[cfg.target_feature] - r[cfg.target_feature.general] Key-value option set for each platform feature available for the current compilation target. @@ -146,7 +142,6 @@ An additional feature of `crt-static` is available to the r[cfg.target_os] - r[cfg.target_os.general] Key-value option set once with the target's operating system. This value is similar to the second and third element of the platform's target triple. @@ -169,7 +164,6 @@ Example values: r[cfg.target_family] - r[cfg.target_family.general] Key-value option providing a more generic description of a target, such as the family of the operating systems or architectures that the target generally falls into. Any number of @@ -217,7 +211,6 @@ Example values: r[cfg.target_abi] - r[cfg.target_abi.general] Key-value option set to further disambiguate the `target_env` with information about the target ABI. @@ -247,7 +240,6 @@ on the endianness of the target's CPU. r[cfg.target_poitner_width] - r[cfg.target_pointer_width.general] Key-value option set once with the target's pointer width in bits. @@ -262,7 +254,6 @@ Example values: r[cfg.target_vendor] - r[cfg.target_vendor.general] Key-value option set once with the vendor of the target. @@ -278,7 +269,6 @@ Example values: r[cfg.target_has_atomic] - r[cfg.target_has_atomic.general] Key-value option set for each bit width that the target supports atomic loads, stores, and compare-and-swap operations. @@ -325,7 +315,6 @@ Set when the crate being compiled is being compiled with the `proc_macro` r[cfg.panic] - r[cfg.panic.general] Key-value option set depending on the panic strategy. Note that more values may be added in the future. @@ -341,7 +330,6 @@ Example values: r[cfg.attr] - r[cfg.attr.syntax] > **Syntax**\ > _CfgAttrAttribute_ :\ @@ -410,7 +398,6 @@ The `cfg` attribute is allowed anywhere attributes are allowed. r[cfg.cfg_attr] - r[cfg.cfg_attr.syntax] > **Syntax**\ > _CfgAttrAttribute_ :\ @@ -419,7 +406,6 @@ r[cfg.cfg_attr.syntax] > _CfgAttrs_ :\ >    [_Attr_] (`,` [_Attr_])\* `,`? - r[cfg.cfg_attr.general] The `cfg_attr` [attribute] conditionally includes [attributes] based on a configuration predicate.