itsscb/rust
1
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2025-10-24 22:17:08 +00:00
Code Issues Packages Projects Releases Wiki Activity
rust/library/compiler-builtins/libm/CONTRIBUTING.md
Trevor Gross 3de783c40f Enable build-mpfr and build-musl by default 
Most users who are developing this crate are likely running on a Unix
system, since there isn't much to test against otherwise. For
convenience, enable the features required to run these tests by default.
2025-01-13 03:53:46 +00:00

3.3 KiB
Raw Blame History

How to contribute

  • Pick your favorite math function from the issue tracker.
  • Look for the C implementation of the function in the MUSL source code.
  • Copy paste the C code into a Rust file in the src/math directory and adjust src/math/mod.rs accordingly. Also, uncomment the corresponding trait method in src/lib.rs.
  • Write some simple tests in your module (using #[test])
  • Run cargo test to make sure it works. Full tests are only run when enabling features, see Testing below.
  • Send us a pull request! Make sure to run cargo fmt on your code before sending the PR. Also include "closes #42" in the PR description to close the corresponding issue.
  • 🎉

Check PR #65 for an example.

Tips and tricks

  • IMPORTANT The code in this crate will end up being used in the core crate so it can not have any external dependencies (other than core itself).

  • Only use relative imports within the math directory / module, e.g. use self::fabs::fabs or use super::k_cos. Absolute imports from core are OK, e.g. use core::u64.

  • To reinterpret a float as an integer use the to_bits method. The MUSL code uses the GET_FLOAT_WORD macro, or a union, to do this operation.

  • To reinterpret an integer as a float use the f32::from_bits constructor. The MUSL code uses the SET_FLOAT_WORD macro, or a union, to do this operation.

  • You may use other methods from core like f64::is_nan, etc. as appropriate.

  • If you're implementing one of the private double-underscore functions, take a look at the "source" name in the comment at the top for an idea for alternate naming. For example, __sin was renamed to k_sin after the FreeBSD source code naming. Do use these private functions in mod.rs.

  • You may encounter weird literals like 0x1p127f in the MUSL code. These are hexadecimal floating point literals. Rust (the language) doesn't support these kind of literals. This crate provides two macros, hf32! and hf64!, which convert string literals to floats at compile time.

    assert_eq!(hf32!("0x1.ffep+8").to_bits(), 0x43fff000);
assert_eq!(hf64!("0x1.ffep+8").to_bits(), 0x407ffe0000000000);

  • Rust code panics on arithmetic overflows when not optimized. You may need to use the Wrapping newtype to avoid this problem, or individual methods like wrapping_add.

Testing

Normal tests can be executed with:

# `--release` ables more test cases
cargo test --release

If you are on a system that cannot build musl or MPFR, passing --no-default-features will run some limited tests.

The multiprecision tests use the rug crate for bindings to MPFR. MPFR can be difficult to build on non-Unix systems, refer to gmp_mpfr_sys for help.

build-musl does not build with MSVC, Wasm, or Thumb.