Skip to content

Referenceify conditional compilation #444

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 18, 2018
Merged

Referenceify conditional compilation #444

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bbab43f
Referenceify conditional compilation
Havvy Oct 8, 2018
d3e2edf
Grammar for all() and any() cfg preds plus remove stray commas
Havvy Oct 9, 2018
1a5197a
Conditional compilation - Fix typos
Havvy Oct 13, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
333 changes: 269 additions & 64 deletions src/conditional-compilation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,213 @@
## Conditional compilation
# Conditional compilation

Sometimes one wants to have different compiler outputs from the same code,
depending on build target, such as targeted operating system, or to enable
release builds.
> **<sup>Syntax</sup>**\
> _ConfigurationPredicate_ :\
> &nbsp;&nbsp; &nbsp;&nbsp; _ConfigurationOption_\
> &nbsp;&nbsp; | _ConfigurationAll_\
> &nbsp;&nbsp; | _ConfigurationAny_\
> &nbsp;&nbsp; | _ConfigurationNot_
>
> _ConfigurationOption_ :\
> &nbsp;&nbsp; [IDENTIFIER]&nbsp;(`=` ([STRING_LITERAL] | [RAW_STRING_LITERAL]))<sup>?</sup>
>
> _ConfigurationAll_\
> &nbsp;&nbsp; `all` `(` _ConfigurationPredicate_ (`,` _ConfigurationPredicate_)<sup>\*</sup> `,`<sup>?</sup> `)`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These don't seem to capture that they can be an empty list. Not sure if that is important, since that is an odd usage.

>
> _ConfigurationAny_\
> &nbsp;&nbsp; `any` `(` _ConfigurationPredicate_ (`,` _ConfigurationPredicate_)<sup>\*</sup> `,`<sup>?</sup> `)`
>
> _ConfigurationNot_\
> &nbsp;&nbsp; `not` `(` _ConfigurationPredicate_ `)`

Configuration options are boolean (on or off) and are named either with a
single identifier (e.g. `foo`) or an identifier and a string (e.g. `foo = "bar"`;
the quotes are required and spaces around the `=` are unimportant). Note that
similarly-named options, such as `foo`, `foo="bar"` and `foo="baz"` may each be
set or unset independently.
*Conditionally compiled source code* is source code that may or may not be
considered a part of the source code depending on certain conditions. <!-- This
definition is sort of vacuous --> Source code can be conditionally compiled
using [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.

Configuration options are either provided by the compiler or passed in on the
command line using `--cfg` (e.g. `rustc main.rs --cfg foo --cfg 'bar="baz"'`).
Rust code then checks for their presence using the `#[cfg(...)]` [attribute]:
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
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.

_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.

> **Note**: Whitespace around the `=` is ignored. `foo="bar"` and `foo = "bar"`
> are equivalent configuration options.

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.

## 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
configuration option from within the source code of the crate being compiled.

> **Note**: For `rustc`, arbitrary-set configuration options are set using the
> [`--cfg`] flag.

<div class="warning">

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.

</div>

### `target_arch`

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.

Example values:

* `"x86"`,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are some random trailing commas here.

* `"x86_64"`
* `"mips"`
* `"powerpc"`
* `"powerpc64"`
* `"arm"`,
* `"aarch64"`

### `target_os`

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.

Example values:

* `"windows"`
* `"macos"`
* `"ios"`
* `"linux"`
* `"android"`
* `"freebsd"`
* `"dragonfly"`
* `"bitrig"`
* `"openbsd"`
* `"netbsd"`

### `target_family`

Key-value option set at most once with the target's operating system value.

Example values:

* `"unix"`
* `"windows"`

### `unix` and `windows`

`unix` is set if `target_family = "unix"` is set and `windows` is set if
`target_family = "windows"` is set.

### `target_env`

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
disambiguation. Thus, for example, on many GNU platforms, this value will be
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"`.

Example values:

* `""`
* `"gnu"`
* `"msvc"`
* `"musl"`

### `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`

Key-value option set once with the target's pointer width in bits. For example,
for targets with 32-bit pointers, this is set to `"32"`. Likewise, it is set
to `"64"` for targets with 64-bit pointers.

<!-- Are there targets that have a different bit number? -->
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a 16 bit platform listed in tier 3 here


### `target_has_atomic`

Key-value option set for each integer size on which the target can perform
atomic operations.

Possible values:

* `"8"`
* `"16"`
* `"32"`
* `"64"`
* `"ptr"`

### `target_vendor`

Key-value option set once with the vendor of the target.

Possible values:

* `"apple"`
* `"pc"`
* `"unknown"`

### `test`

Enabled when compiling the test harness. Done with `rustc` by using the
[`--test`] flag.

### `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
[`debug_assert!`] macro.

### `proc_macro`

Set when the crate being compiled is being compiled with the `proc_macro`
[crate type].

## Forms of conditional compilation

### The `cfg` attribute

> **<sup>Syntax</sup>**\
> _CfgAttrAttribute_ :\
> &nbsp;&nbsp; `cfg` `(` _ConfigurationPredicate_ `)`

<!-- should we say they're active attributes here? -->

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 `)`.

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.

Some examples on functions:

```rust
// The function is only included in the build when compiling for macOS
Expand Down Expand Up @@ -41,62 +236,72 @@ fn needs_not_foo() {
}
```

This illustrates some conditional compilation can be achieved using the
`#[cfg(...)]` [attribute]. `any`, `all` and `not` can be used to assemble
arbitrarily complex configurations through nesting.

The following configurations must be defined by the implementation:

* `target_arch = "..."` - Target CPU architecture, such as `"x86"`,
`"x86_64"` `"mips"`, `"powerpc"`, `"powerpc64"`, `"arm"`, or
`"aarch64"`. This value is closely related to the first element of
the platform target triple, though it is not identical.
* `target_os = "..."` - Operating system of the target, examples
include `"windows"`, `"macos"`, `"ios"`, `"linux"`, `"android"`,
`"freebsd"`, `"dragonfly"`, `"bitrig"` , `"openbsd"` or
`"netbsd"`. This value is closely related to the second and third
element of the platform target triple, though it is not identical.
* `target_family = "..."` - Operating system family of the target, e. g.
`"unix"` or `"windows"`. The value of this configuration option is defined
as a configuration itself, like `unix` or `windows`.
* `unix` - See `target_family`.
* `windows` - See `target_family`.
* `target_env = ".."` - Further disambiguates the target platform with
information about the ABI/libc. Presently this value is either
`"gnu"`, `"msvc"`, `"musl"`, or the empty string. For historical
reasons this value has only been defined as non-empty when needed
for disambiguation. Thus on many GNU platforms this value will be
empty. This value is closely related to the fourth element of the
platform target triple, though it is not identical. For example,
embedded ABIs such as `gnueabihf` will simply define `target_env` as
`"gnu"`.
* `target_endian = "..."` - Endianness of the target CPU, either `"little"` or
`"big"`.
* `target_pointer_width = "..."` - Target pointer width in bits. This is set
to `"32"` for targets with 32-bit pointers, and likewise set to `"64"` for
64-bit pointers.
* `target_has_atomic = "..."` - Set of integer sizes on which the target can perform
atomic operations. Values are `"8"`, `"16"`, `"32"`, `"64"` and `"ptr"`.
* `target_vendor = "..."` - Vendor of the target, for example `apple`, `pc`, or
simply `"unknown"`.
* `test` - Enabled when compiling the test harness (using the `--test` flag).
* `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
`debug_assert!` macro.
* `proc_macro` - Set when the crate being compiled is being compiled with the
`proc_macro` [crate type].

You can also set another [attribute] based on a `cfg` variable with `cfg_attr`:
The `cfg` attribute is allowed anywhere attributes are allowed except on
generic parameters.

### The `cfg_attr` attribute

> **<sup>Syntax</sup>**\
> _CfgAttrAttribute_ :\
> &nbsp;&nbsp; `cfg_attr` `(` _ConfigurationPredicate_ `,` [_MetaItem_] `,`<sup>?</sup> `)`

The `cfg_attr` [attribute] conditionally includes [attributes] based on a
configuration predicate.

It is written as `cfg_attr` followed by `(`, a configuration predicate, a
[metaitem], an optional `,`, and finally a `)`.

When the configuration predicate is true, this attribute expands out to be an
attribute of the attribute metaitem. For example, the following module will
either be found at `linux.rs` or `windows.rs` based on the target.

```rust,ignore
#[cfg_attr(a, b)]
#[cfg_attr(linux, path = "linux.rs")]
#[cfg_attr(windows, path = "windows.rs")]
mod os;
```

This is the same as `#[b]` if `a` is set by `cfg`, and nothing otherwise.
> **Note**: The `cfg_attr` can expand to another `cfg_attr`. For example,
> `#[cfg_attr(linux, cfg_attr(feature = "multithreaded", some_other_attribute))`
> is valid. This example would be equivalent to
> `#[cfg_attr(and(linux, feaure ="multithreaded"), some_other_attribute)]`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

feaure → feature


The `cfg_attr` attribute is allowed anywhere attributes are allowed except on
generic parameters.

### The `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.

Lastly, configuration options can be used in expressions by invoking the `cfg!`
macro: `cfg!(a)` evaluates to `true` if `a` is set, and `false` otherwise.
For example:

```rust
let machine_kind = if cfg!(unix) {
"unix"
} else if cfg!(windows) {
"windows"
} else {
"unknown"
};

println!("I'm running on a {} machine!", machine_kind);
```

[IDENTIFIER]: identifiers.html
[RAW_STRING_LITERAL]: tokens.html#raw-string-literals
[STRING_LITERAL]: tokens.html#string-literals
[_MetaItem_]: attributes.html
[`--cfg`]: ../rustc/command-line-arguments.html#a--cfg-configure-the-compilation-environment
[`--test`]: ../rustc/command-line-arguments.html#a--test-build-a-test-harness
[`cfg`]: #the-cfg-attribute
[`cfg` macro]: #the-cfg-macro
[`cfg_attr`]: #the-cfg_attr-attribute
[`debug_assert!`]: ../std/macro.debug_assert.html
[attribute]: attributes.html
[crate type]: linkage.html
[attributes]: attributes.html
[crate type]: linkage.html
[expressions]: expressions.html
[items]: items.html
[metaitem]: attributes.html