Skip to content
Permalink
Browse files

Target-feature documented as unsafe. rustc book and rustc -C help hav…

…e been modified.
  • Loading branch information...
togiberlin committed Sep 4, 2019
1 parent d956e87 commit 536e6508230c7a073ce52eac1dd8858dbad5aa95
@@ -13,6 +13,7 @@
- [Targets](targets/index.md)
- [Built-in Targets](targets/built-in.md)
- [Custom Targets](targets/custom.md)
- [Known Issues](targets/known-issues.md)
- [Profile-guided Optimization](profile-guided-optimization.md)
- [Linker-plugin based LTO](linker-plugin-lto.md)
- [Contributing to `rustc`](contributing.md)
@@ -61,6 +61,8 @@ enabling or disabling a feature.
To see the valid options and an example of use, run `rustc --print
target-features`.

Using this flag is unsafe and might result in [undefined runtime behavior](https://doc.rust-lang.org/rustc/targets/known-issues.html).

## passes

This flag can be used to add extra LLVM passes to the compilation.
@@ -144,7 +144,7 @@ of print values are:
target CPU may be selected with the `-C target-cpu=val` flag.
- `target-features` — List of available target features for the current
target. Target features may be enabled with the `-C target-feature=val`
flag.
flag. This flag is unsafe. See [known issues](https://doc.rust-lang.org/rustc/targets/known-issues.html) for more details.
- `relocation-models` — List of relocation models. Relocation models may be
selected with the `-C relocation-model=val` flag.
- `code-models` — List of code models. Code models may be selected with the
@@ -11,3 +11,9 @@ To compile to a particular target, use the `--target` flag:
```bash
$ rustc src/main.rs --target=wasm32-unknown-unknown
```
## Target Features
`x86`, and `ARMv8` are two popular CPU architectures. Their instruction sets form a common baseline across most CPUs. However, some CPUs extend these with custom instruction sets, e.g. vector (`AVX`), bitwise manipulation (`BMI`) or cryptographic (`AES`).

Developers, who know on which CPUs their compiled code is going to run can choose to add (or remove) CPU specific instruction sets via the `-C target-feature=val` flag.

Please note, that this flag is generally considered as unsafe. More details can be found in [this section](https://doc.rust-lang.org/rustc/targets/known-issues.html).
@@ -0,0 +1,13 @@
# Known Issues
This section informs you about known "gotchas". Keep in mind, that this section is (and always will be) incomplete. For suggestions and amendments, feel free to [contribute](https://doc.rust-lang.org/rustc/contributing.html) to this guide.

## Target Features
Most target-feature problems arise, when mixing code that have the target-feature _enabled_ with code that have it _disabled_. If you want to avoid undefined behavior, it is recommended to build _all code_ (including the standard library and imported crates) with a common set of target-features.

By default, compiling your code with the `-C target-feature` flag will not recompile the entire standard library and/or imported crates with matching target features. Therefore, target features are generally considered as unsafe. Using `#[target_feature]` on individual functions makes the function unsafe.

Examples:

| Target-Feature | Issue | Seen on | Description | Details |
| -------------- | ----- | ------- | ----------- | ------- |
| `+soft-float` <br> and <br> `-sse` | Segfaults and ABI mismatches | `x86` and `x86-64` | The `x86` and `x86_64` architecture uses SSE registers (aka `xmm`) for floating point operations. Using software emulated floats ("soft-floats") disables usage of `xmm` registers, but parts of Rust's core libraries (e.g. `std::f32` or `std::f64`) are compiled without soft-floats and expect parameters to be passed in `xmm` registers. This leads to ABI mismatches. <br><br> Attempting to compile with disabled SSE causes the same error, too. | [#63466](https://github.com/rust-lang/rust/issues/63466) |
@@ -1151,7 +1151,8 @@ options! {CodegenOptions, CodegenSetter, basic_codegen_options,
target_cpu: Option<String> = (None, parse_opt_string, [TRACKED],
"select target processor (`rustc --print target-cpus` for details)"),
target_feature: String = (String::new(), parse_string, [TRACKED],
"target specific attributes (`rustc --print target-features` for details)"),
"target specific attributes. (`rustc --print target-features` for details). \
This feature is unsafe."),
passes: Vec<String> = (Vec::new(), parse_list, [TRACKED],
"a list of extra LLVM passes to run (space separated)"),
llvm_args: Vec<String> = (Vec::new(), parse_list, [TRACKED],

0 comments on commit 536e650

Please sign in to comment.
You can’t perform that action at this time.