diff options
Diffstat (limited to 'libgrust/rustc-lib/stdarch/CONTRIBUTING.md')
| -rw-r--r-- | libgrust/rustc-lib/stdarch/CONTRIBUTING.md | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/libgrust/rustc-lib/stdarch/CONTRIBUTING.md b/libgrust/rustc-lib/stdarch/CONTRIBUTING.md new file mode 100644 index 0000000..85b7bb4 --- /dev/null +++ b/libgrust/rustc-lib/stdarch/CONTRIBUTING.md @@ -0,0 +1,80 @@ +# Contributing to stdarch + +The `stdarch` crate is more than willing to accept contributions! First you'll +probably want to check out the repository and make sure that tests pass for you: + +``` +$ git clone https://github.com/rust-lang/stdarch +$ cd stdarch +$ cargo +nightly test +``` + +To run codegen tests, run in release mode: + +``` +$ cargo +nightly test --release -p coresimd +``` + +Remember that this repository requires the nightly channel of Rust! If any of +the above steps don't work, [please let us know][new]! + +Next up you can [find an issue][issues] to help out on, we've selected a few +with the [`help wanted`][help] and [`impl-period`][impl] tags which could +particularly use some help. You may be most interested in [#40][vendor], +implementing all vendor intrinsics on x86. That issue's got some good pointers +about where to get started! + +If you've got general questions feel free to [join us on gitter][gitter] and ask +around! Feel free to ping either @BurntSushi or @alexcrichton with questions. + +[gitter]: https://gitter.im/rust-impl-period/WG-libs-simd + +# How to write examples for stdarch intrinsics + +There are a few features that must be enabled for the given intrinsic to work +properly and the example must only be run by `cargo test --doc` when the feature +is supported by the CPU. As a result, the default `fn main` that is generated by +`rustdoc` will not work (in most cases). Consider using the following as a guide +to ensure your example works as expected. + +```rust +/// # // We need cfg_target_feature to ensure the example is only +/// # // run by `cargo test --doc` when the CPU supports the feature +/// # #![feature(cfg_target_feature)] +/// # // We need target_feature for the intrinsic to work +/// # #![feature(target_feature)] +/// # +/// # // rustdoc by default uses `extern crate stdarch`, but we need the +/// # // `#[macro_use]` +/// # #[macro_use] extern crate stdarch; +/// # +/// # // The real main function +/// # fn main() { +/// # // Only run this if `<target feature>` is supported +/// # if cfg_feature_enabled!("<target feature>") { +/// # // Create a `worker` function that will only be run if the target feature +/// # // is supported and ensure that `target_feature` is enabled for your worker +/// # // function +/// # #[target_feature(enable = "<target feature>")] +/// # unsafe fn worker() { +/// +/// // Write your example here. Feature specific intrinsics will work here! Go wild! +/// +/// # } +/// # unsafe { worker(); } +/// # } +/// # } +``` + +If some of the above syntax does not look familiar, the [Documentation as tests] section +of the [Rust Book] describes the `rustdoc` syntax quite well. As always, feel free +to [join us on gitter][gitter] and ask us if you hit any snags, and thank you for helping +to improve the documentation of `stdarch`! + +[new]: https://github.com/rust-lang/stdarch/issues/new +[issues]: https://github.com/rust-lang/stdarch/issues +[help]: https://github.com/rust-lang/stdarch/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22 +[impl]: https://github.com/rust-lang/stdarch/issues?q=is%3Aissue+is%3Aopen+label%3Aimpl-period +[vendor]: https://github.com/rust-lang/stdarch/issues/40 +[Documentation as tests]: https://doc.rust-lang.org/book/first-edition/documentation.html#documentation-as-tests +[Rust Book]: https://doc.rust-lang.org/book/first-edition |