From 6fa446c06efecce5b74f1cf61269ad96249f39de Mon Sep 17 00:00:00 2001 From: Kevin Lu <59781940+klu235@users.noreply.github.com> Date: Mon, 18 Sep 2023 00:24:03 -0400 Subject: [PATCH 1/2] Update conditional-compilation.md * Clarify * Reduce redundancy --- src/conditional-compilation.md | 48 +++++++++++----------------------- 1 file changed, 15 insertions(+), 33 deletions(-) diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index f52c90df5..143982444 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -22,43 +22,31 @@ > _ConfigurationPredicateList_\ >    _ConfigurationPredicate_ (`,` _ConfigurationPredicate_)\* `,`? -*Conditionally compiled source code* is source code that may or may not be -considered a part of the source code depending on certain conditions. Source code can be conditionally compiled -using the [attributes] [`cfg`] and [`cfg_attr`] and the built-in [`cfg` macro]. -These conditions are based on the target architecture of the compiled crate, -arbitrary values passed to the compiler, and a few other miscellaneous things -further described below in detail. +*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. Each form of conditional compilation takes a _configuration predicate_ that evaluates to true or false. The predicate is one of the following: -* A configuration option. It is true if the option is set and false if it is +* A configuration option. The predicate is true if the option is set, and false if it is unset. -* `all()` with a comma separated list of configuration predicates. It is false - if at least one predicate is false. If there are no predicates, it is true. -* `any()` with a comma separated list of configuration predicates. It is true - if at least one predicate is true. If there are no predicates, it is false. -* `not()` with a configuration predicate. It is true if its predicate is false - and false if its predicate is true. +* `all()` with a comma-separated list of configuration predicates. It is true precisely if all of the given predicates are true. +* `any()` with a comma-separated list of configuration predicates. It is true precisely if at least one of the given predicates is true. +* `not()` with a configuration predicate. It is true precisely if the given predicate is false. -_Configuration options_ are names and key-value pairs that are either set or -unset. Names are written as a single identifier such as, for example, `unix`. -Key-value pairs are written as an identifier, `=`, and then a string. For -example, `target_arch = "x86_64"` is a configuration option. +_Configuration options_ are either names or key-value pairs, and are either set or +unset. Configuration options that are names, such as `unix`, are specified by simply writing them. +Configuration options that are key-value pairs are written in the form `key = "value"`, such as `target_arch = "x86_64"`. -> **Note**: Whitespace around the `=` is ignored. `foo="bar"` and `foo = "bar"` -> are equivalent configuration options. +> **Note**: Whitespace around the `=` is ignored, so `foo="bar"` and `foo = "bar"` are equivalent. -Keys are not unique in the set of key-value configuration options. For example, -both `feature = "std"` and `feature = "serde"` can be set at the same time. +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 Which configuration options are set is determined statically during the -compilation of the crate. Certain options are _compiler-set_ based on data -about the compilation. Other options are _arbitrarily-set_, set based on input -passed to the compiler outside of the code. It is not possible to set a +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 impossible 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 @@ -70,11 +58,7 @@ configuration option from within the source code of the crate being compiled.
-Warning: It is possible for arbitrarily-set configuration options to have the -same value as compiler-set configuration options. For example, it is possible -to do `rustc --cfg "unix" program.rs` while compiling to a Windows target, and -have both `unix` and `windows` configuration options set at the same time. It -is unwise to actually do this. +Warning: Arbitrarily-set configuration options can clash with compiler-set configuration options. For example, it is possible to do `rustc --cfg "unix" program.rs` while compiling to a Windows target, and have both `unix` and `windows` configuration options set at the same time. Doing this would be unwise.
@@ -266,9 +250,7 @@ Example values: The `cfg` [attribute] conditionally includes the thing it is attached to based -on a configuration predicate. - -It is written as `cfg`, `(`, a configuration predicate, and finally `)`. +on the given configuration predicate (_ConfigurationPredicate_ in the syntax above). 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. From 166c05e375531a12497b6e228c64f8b3713e25b2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 17 Jul 2024 11:10:27 -0700 Subject: [PATCH 2/2] Apply review suggestions. This reverts some of the changes since they were done intentionally, and tries to improve the clarity in other areas. --- src/conditional-compilation.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index 143982444..f98b3230e 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -27,15 +27,14 @@ Each form of conditional compilation takes a _configuration predicate_ that evaluates to true or false. The predicate is one of the following: -* A configuration option. The predicate is true if the option is set, and false if it is - unset. -* `all()` with a comma-separated list of configuration predicates. It is true precisely if all of the given predicates are true. -* `any()` with a comma-separated list of configuration predicates. It is true precisely if at least one of the given predicates is true. -* `not()` with a configuration predicate. It is true precisely if the given predicate is false. +* A configuration option. The predicate is true if the option is set, and false if it is unset. +* `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. +* `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. +* `not()` with a configuration predicate. It is true if its predicate is false and false if its predicate is true. -_Configuration options_ are either names or key-value pairs, and are either set or -unset. Configuration options that are names, such as `unix`, are specified by simply writing them. -Configuration options that are key-value pairs are written in the form `key = "value"`, such as `target_arch = "x86_64"`. +_Configuration options_ are either names or key-value pairs, and are either set or unset. +Names are written as a single identifier, such as `unix`. +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. @@ -46,7 +45,7 @@ Keys do not need to be unique. For example, both `feature = "std"` and `feature 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 impossible to set a +passed to the compiler outside of the code. 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 @@ -250,7 +249,9 @@ Example values: The `cfg` [attribute] conditionally includes the thing it is attached to based -on the given configuration predicate (_ConfigurationPredicate_ in the syntax above). +on a configuration predicate. + +It is written as `cfg`, `(`, a configuration predicate, and finally `)`. 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.