Skip to content
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.

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

Document target_feature and cfg_target_feature. #545

Merged
merged 2 commits into from
Mar 19, 2019

Conversation

ehuss
Copy link
Contributor

@ehuss ehuss commented Mar 18, 2019

Closes #286

Havvy
Havvy previously requested changes Mar 18, 2019
Copy link
Contributor

@Havvy Havvy left a comment

Choose a reason for hiding this comment

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

Other than the nits, the documentation looks good. Nice work.

But, and this is a big but, I think that platform features should be discussed outside of the target_feature attribute as its own section and then the attribute can point to that. But if you don't want to rewrite the entire PR, we can just open that as an issue and merge this as is.

src/attributes/codegen.md Outdated Show resolved Hide resolved
src/attributes/codegen.md Show resolved Hide resolved
src/behavior-considered-undefined.md Show resolved Hide resolved
src/conditional-compilation.md Outdated Show resolved Hide resolved
@ehuss
Copy link
Contributor Author

ehuss commented Mar 18, 2019

I think that platform features should be discussed outside

I wouldn't mind rearranging things, though I don't quite see what it would look like. I am concerned that the tables will get quite large as more features are stabilized. I'm not sure what else can be said about platform features, though.

@ehuss
Copy link
Contributor Author

ehuss commented Mar 18, 2019

Oh, I was also wondering about pinging some of the people for review who know this stuff well (like alex or gnzlbg). The "Implicitly Enables" was particularly difficult to figure out. I think it is correct, but they should know more.

Copy link
Contributor

@Centril Centril left a comment

Choose a reason for hiding this comment

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

Textually, this is great; cc @gnzlbg for contents.


### Available features

The following is a list of the available feature names.
Copy link
Contributor

Choose a reason for hiding this comment

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

Is the table below only intended to document the stable target features?

I know it wouldn't be great to link to the compiler implementation as the source of documentation, and I'll try to keep this in sync as new PRs are merged, but particularly for those who want to learn about the unstable features, the compiler source might be useful (e.g. here: https://github.com/rust-lang/rust/blob/master/src/librustc_codegen_llvm/llvm_util.rs#L96).

Copy link
Contributor

Choose a reason for hiding this comment

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

Everything in the reference documents what is stable (as of the current nightly; the reference updates on the website alongside rustc releases)

For unstable things, there's the unstable book (https://github.com/rust-lang/rust/tree/master/src/doc/unstable-book).

being compiled for.

It is [undefined behavior] to call a function that is compiled with a feature
that is not supported on the current platform the code is running on.
Copy link
Contributor

@gnzlbg gnzlbg Mar 18, 2019

Choose a reason for hiding this comment

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

I don't know whether unsafe superpowers are documented in the reference, but being able to call a target-feature function without proving that the platform the code is running on supports the feature is an unsafe super power.

EDIT: it might be worth it to add this super-power to the list, and link from them to here.

Copy link
Contributor

Choose a reason for hiding this comment

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

So forget about this, the the unsafe super-powers are documented here: https://doc.rust-lang.org/reference/unsafety.html#unsafety but they already contain "calling unsafe functions" which is what applies for these.

We'll only need to update this list if the target-feature 1.1 RFC gets merged.

Copy link
Contributor

@gnzlbg gnzlbg left a comment

Choose a reason for hiding this comment

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

LGTM. I leave it up to you whether you want to link to the compiler source or not.

Thank you for doing this.

@Havvy Havvy merged commit bc87a02 into rust-lang:master Mar 19, 2019
@Havvy
Copy link
Contributor

Havvy commented Mar 19, 2019

💟 Thanks!

Centril added a commit to Centril/rust that referenced this pull request Mar 29, 2019
Update books

Update reference, book, rust-by-example, edition-guide, embedded-book

## reference

15 commits in 41493ff..27ad493
2019-03-05 12:32:22 +0100 to 2019-03-26 02:06:15 +0100
- Document wasm_import_module for #[link]. (rust-lang/reference#554)
- Fix tidy error. (rust-lang/reference#552)
- Some minor contributing updates. (rust-lang/reference#551)
- Document `type_length_limit`. (rust-lang/reference#546)
- Add some terms to the glossary. (rust-lang/reference#547)
- Document `target_feature` and `cfg_target_feature`. (rust-lang/reference#545)
- Remove undocumented page (rust-lang/reference#539)
- Reorg and update attributes (rust-lang/reference#537)
- Fix some minor link errors. (rust-lang/reference#538)
- Add linkchecker. (rust-lang/reference#521)
- Expand docs on Macros By Example. (rust-lang/reference#511)
- document #[panic_handler] (rust-lang/reference#362)
- document #[used] (rust-lang/reference#361)
- Note that UB is program-global (rust-lang/reference#490)
- Fix copy-paste error in procedural-macros.md (rust-lang/reference#533)

## book

16 commits in 9cffbeabec3bcec42d09432bfe7705125c848889..b93ec30bbc7b1b5c2f44223249ab359bed2ed5a6
2019-03-02 08:22:41 -0500 to 2019-03-26 16:54:10 -0400
- Unignore example that now compiles
- Fix code snippet (rust-lang/book#1863)
- Fix mdbook link text in readme (rust-lang/book#1881)
- Wrap to 80 cols
- Make sentence more complete (rust-lang/book#1885)
- consistenly use increment and decrement (rust-lang/book#1884)
- Fix link to Reference's conditional-compilation. (rust-lang/book#1878)
- Fix subject/verb agreement
- Remove nostarch snapshot files that have been incorporated and checked
- haha teach the dictionary steve's name
- Add authorship info to the front page
- fix accidental <ol>'s (rust-lang/book#1866)
- Edits to Macros (rust-lang/book#1848)
- Mention `lock` returns `MutexGuard` wrapped in a `LockResult`
- Add an example that illustrates NLL (rust-lang/book#1842)
- change the parameter name from `type` to `kind` (rust-lang/book#1845)

## rust-by-example

33 commits in 2ce92beabb912d417a7314d6da83ac9b50dc2afb..f68ef3d0f4959f6a7d92a08d9994b117f0f4d32d
2018-11-20 10:10:23 -0500 to 2019-03-12 15:32:12 -0300
- Fix some broken links. (rust-lang/rust-by-example#1161)
- Update links in README (rust-lang/rust-by-example#1167)
- Add score/lifetimes/trait.md (rust-lang/rust-by-example#1168)
- Fix rust-lang/rust-by-example#1147 - No more `open_mode` method (rust-lang/rust-by-example#1164)
- Fix for loop description in list print example (rust-lang/rust-by-example#1162)
- Add link to Cargo chapter in the index page (rust-lang/rust-by-example#1159)
- Fix grammar in sentence about integer notation (rust-lang/rust-by-example#1157)
- Do not use deprecated functions from `std::error::Error` trait (rust-lang/rust-by-example#1151)
- Update new_types.md to clarify conversion to base type (rust-lang/rust-by-example#1148)
- Fix compatibility with Rust 2018 (rust-lang/rust-by-example#1150)
- Hello: Fix hint link in `fmt` chapter. (rust-lang/rust-by-example#1146)
- Clarify pub(restricted) example a bit (rust-lang/rust-by-example#1133)
- Add "literal" to list of macro designators (rust-lang/rust-by-example#1153)
- Minor fixes for the macros chapter (rust-lang/rust-by-example#1113)
- Use new book links instead of the old second-edition ones (rust-lang/rust-by-example#1143)
- Recommend implementing Display over ToString (rust-lang/rust-by-example#1145)
- Remove unused import and format with `rustfmt` (rust-lang/rust-by-example#1144)
- fix typo (rust-lang/rust-by-example#1142)
- Update syntax for 2018 Edition (rust-lang/rust-by-example#1136)
- Added two missing full stops (rust-lang/rust-by-example#1138)
- Removed unnecessary spaces before macro designators in macros/dry (rust-lang/rust-by-example#1139)
- fix install mdbook command (rust-lang/rust-by-example#1128)
- Changed word `function` to `type` in comment of fn area (rust-lang/rust-by-example#1132)
- Added two missing backticks in generics/multi_bounds (rust-lang/rust-by-example#1129)
- Fixed small logic error in error/option_unwrap/and_then (rust-lang/rust-by-example#1127)
- Fix typo (rust-lang/rust-by-example#1125)
- The code of conduct link was dead. I fixed it. (rust-lang/rust-by-example#1122)
- I added a space in the Display fmt for Complex (rust-lang/rust-by-example#1123)
- Fix Rust install link in the index (rust-lang/rust-by-example#1124)
- Update cargo conventions section (rust-lang/rust-by-example#1121)
- Fixed curly braces in the `To and from Strings` chapter to be parentheses (rust-lang/rust-by-example#1120)
- Edit a typo (rust-lang/rust-by-example#1119)
- Fixes rust-lang/rust-by-example#1115 by correcting the typo from into_iterator to into_iter (rust-lang/rust-by-example#1118)

## edition-guide

1 commits in aa0022c875907886cae8f3ef8e9ebf6e2a5e728d..b56ddb11548450a6df4edd1ed571b2bc304eb9e6
2019-02-27 22:10:39 -0800 to 2019-03-10 10:23:16 +0100
- Links fixes (rust-lang/edition-guide#133)

## embedded-book

6 commits in 9e656ead82bfe869493dec82653a52e27fa6a05c..07fd3880ea0874d82b1d9ed30ad3427ec98b4e8a
2019-03-03 16:03:26 +0000 to 2019-03-27 15:40:52 +0000
- Fix test errors.  (rust-embedded/book#180)
- Update qemu.md  (rust-embedded/book#170)
- Update no-std.md to remove obsolete FAQ link  (rust-embedded/book#177)
- We've come a long way :)  (rust-embedded/book#176)
- Correct link to team  (rust-embedded/book#175)
- Update some book links to their new homes.  (rust-embedded/book#173)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants