1# Contributing to stdarch 2 3The `stdarch` crate is more than willing to accept contributions! First you'll 4probably want to check out the repository and make sure that tests pass for you: 5 6``` 7$ git clone https://github.com/rust-lang/stdarch 8$ cd stdarch 9$ TARGET="<your-target-arch>" ci/run.sh 10``` 11 12Where `<your-target-arch>` is the target triple as used by `rustup`, e.g. `x86_64-unknown-linux-gnu` (without any preceding `nightly-` or similar). 13Also remember that this repository requires the nightly channel of Rust! 14The above tests do in fact require nightly rust to be the default on your system, to set that use `rustup default nightly` (and `rustup default stable` to revert). 15 16If any of the above steps don't work, [please let us know][new]! 17 18Next up you can [find an issue][issues] to help out on, we've selected a few 19with the [`help wanted`][help] and [`impl-period`][impl] tags which could 20particularly use some help. You may be most interested in [#40][vendor], 21implementing all vendor intrinsics on x86. That issue's got some good pointers 22about where to get started! 23 24If you've got general questions feel free to [join us on gitter][gitter] and ask 25around! Feel free to ping either @BurntSushi or @alexcrichton with questions. 26 27[gitter]: https://gitter.im/rust-impl-period/WG-libs-simd 28 29# How to write examples for stdarch intrinsics 30 31There are a few features that must be enabled for the given intrinsic to work 32properly and the example must only be run by `cargo test --doc` when the feature 33is supported by the CPU. As a result, the default `fn main` that is generated by 34`rustdoc` will not work (in most cases). Consider using the following as a guide 35to ensure your example works as expected. 36 37```rust 38/// # // We need cfg_target_feature to ensure the example is only 39/// # // run by `cargo test --doc` when the CPU supports the feature 40/// # #![feature(cfg_target_feature)] 41/// # // We need target_feature for the intrinsic to work 42/// # #![feature(target_feature)] 43/// # 44/// # // rustdoc by default uses `extern crate stdarch`, but we need the 45/// # // `#[macro_use]` 46/// # #[macro_use] extern crate stdarch; 47/// # 48/// # // The real main function 49/// # fn main() { 50/// # // Only run this if `<target feature>` is supported 51/// # if cfg_feature_enabled!("<target feature>") { 52/// # // Create a `worker` function that will only be run if the target feature 53/// # // is supported and ensure that `target_feature` is enabled for your worker 54/// # // function 55/// # #[target_feature(enable = "<target feature>")] 56/// # unsafe fn worker() { 57/// 58/// // Write your example here. Feature specific intrinsics will work here! Go wild! 59/// 60/// # } 61/// # unsafe { worker(); } 62/// # } 63/// # } 64``` 65 66If some of the above syntax does not look familiar, the [Documentation as tests] section 67of the [Rust Book] describes the `rustdoc` syntax quite well. As always, feel free 68to [join us on gitter][gitter] and ask us if you hit any snags, and thank you for helping 69to improve the documentation of `stdarch`! 70 71# Alternative Testing Instructions 72 73It is generally recommended that you use `ci/run.sh` to run the tests. 74However this might not work for you, e.g. if you are on Windows. 75 76In that case you can fall back to running `cargo +nightly test` and `cargo +nightly test --release -p core_arch` for testing the code generation. 77Note that these require the nightly toolchain to be installed and for `rustc` to know about your target triple and its CPU. 78In particular you need to set the `TARGET` environment variable as you would for `ci/run.sh`. 79In addition you need to set `RUSTCFLAGS` (need the `C`) to indicate target features, e.g. `RUSTCFLAGS="-C -target-features=+avx2"`. 80You can also set `-C -target-cpu=native` if you're "just" developing against your current CPU. 81 82Be warned that when you use these alternative instructions, [things may go less smoothly than they would with `ci/run.sh`][ci-run-good], e.g. instruction generation tests may fail because the disassembler named them differently, e.g. it may generate `vaesenc` instead of `aesenc` instructions despite them behaving the same. 83Also these instructions execute less tests than would normally be done, so don't be surprised that when you eventually pull-request some errors may show up for tests not covered here. 84 85 86[new]: https://github.com/rust-lang/stdarch/issues/new 87[issues]: https://github.com/rust-lang/stdarch/issues 88[help]: https://github.com/rust-lang/stdarch/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22 89[impl]: https://github.com/rust-lang/stdarch/issues?q=is%3Aissue+is%3Aopen+label%3Aimpl-period 90[vendor]: https://github.com/rust-lang/stdarch/issues/40 91[Documentation as tests]: https://doc.rust-lang.org/book/first-edition/documentation.html#documentation-as-tests 92[Rust Book]: https://doc.rust-lang.org/book/first-edition 93[ci-run-good]: https://github.com/rust-lang/stdarch/issues/931#issuecomment-711412126 94