src/stdsimd/CONTRIBUTING.md

   1 # Contributing to stdsimd
   2
   3 The `stdsimd` crate is more than willing to accept contributions! First you'll
   4 probably want to check out the repository and make sure that tests pass for you:
   5
   6 ```
   7 $ git clone https://github.com/rust-lang-nursery/stdsimd
   8 $ cd stdsimd
   9 $ cargo +nightly test
  10 ```
  11
  12 To run codegen tests, run in release mode:
  13
  14 ```
  15 $ cargo +nightly test --release -p coresimd
  16 ```
  17
  18 Remember that this repository requires the nightly channel of Rust! If any of
  19 the above steps don't work, [please let us know][new]!
  20
  21 Next up you can [find an issue][issues] to help out on, we've selected a few
  22 with the [`help wanted`][help] and [`impl-period`][impl] tags which could
  23 particularly use some help. You may be most interested in [#40][vendor],
  24 implementing all vendor intrinsics on x86. That issue's got some good pointers
  25 about where to get started!
  26
  27 If you've got general questions feel free to [join us on gitter][gitter] and ask
  28 around! Feel free to ping either @BurntSushi or @alexcrichton with questions.
  29
  30 [gitter]: https://gitter.im/rust-impl-period/WG-libs-simd
  31
  32 # How to write examples for stdsimd intrinsics
  33
  34 There are a few features that must be enabled for the given intrinsic to work
  35 properly and the example must only be run by `cargo test --doc` when the feature
  36 is supported by the CPU. As a result, the default `fn main` that is generated by
  37 `rustdoc` will not work (in most cases). Consider using the following as a guide
  38 to ensure your example works as expected.
  39
  40 ```rust
  41 /// # // We need cfg_target_feature to ensure the example is only
  42 /// # // run by `cargo test --doc` when the CPU supports the feature
  43 /// # #![feature(cfg_target_feature)]
  44 /// # // We need target_feature for the intrinsic to work
  45 /// # #![feature(target_feature)]
  46 /// #
  47 /// # // rustdoc by default uses `extern crate stdsimd`, but we need the
  48 /// # // `#[macro_use]`
  49 /// # #[macro_use] extern crate stdsimd;
  50 /// #
  51 /// # // The real main function
  52 /// # fn main() {
  53 /// #     // Only run this if `<target feature>` is supported
  54 /// #     if cfg_feature_enabled!("<target feature>") {
  55 /// #         // Create a `worker` function that will only be run if the target feature
  56 /// #         // is supported and ensure that `target_feature` is enabled for your worker
  57 /// #         // function
  58 /// #         #[target_feature(enable = "<target feature>")]
  59 /// #         unsafe fn worker() {
  60 ///
  61 /// // Write your example here. Feature specific intrinsics will work here! Go wild!
  62 ///
  63 /// #         }
  64 /// #         unsafe { worker(); }
  65 /// #     }
  66 /// # }
  67 ```
  68
  69 If some of the above syntax does not look familiar, the [Documentation as tests] section
  70 of the [Rust Book] describes the `rustdoc` syntax quite well. As always, feel free
  71 to [join us on gitter][gitter] and ask us if you hit any snags, and thank you for helping
  72 to improve the documentation of `stdsimd`!
  73
  74 [new]: https://github.com/rust-lang-nursery/stdsimd/issues/new
  75 [issues]: https://github.com/rust-lang-nursery/stdsimd/issues
  76 [help]: https://github.com/rust-lang-nursery/stdsimd/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22
  77 [impl]: https://github.com/rust-lang-nursery/stdsimd/issues?q=is%3Aissue+is%3Aopen+label%3Aimpl-period
  78 [vendor]: https://github.com/rust-lang-nursery/stdsimd/issues/40
  79 [Documentation as tests]: https://doc.rust-lang.org/book/first-edition/documentation.html#documentation-as-tests
  80 [Rust Book]: https://doc.rust-lang.org/book/first-edition