From 85b1bdbf650cf9b29d956af007558bce79a03734 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Mon, 21 Apr 2025 07:15:48 +0000 Subject: [PATCH 1/4] Update licensing information after repository refactoring In order to disambiguate things now that libm is part of the compiler-builtins repository, do the following: * Mention libm in LICENSE.txt * Clarify the default license for crates other than libm and compiler-builtins * Add an explicit license field to Cargo.toml for all other crates --- LICENSE.txt | 17 +++++++++++------ builtins-test-intrinsics/Cargo.toml | 1 + builtins-test/Cargo.toml | 1 + crates/libm-macros/Cargo.toml | 1 + crates/musl-math-sys/Cargo.toml | 1 + crates/util/Cargo.toml | 1 + libm-test/Cargo.toml | 1 + 7 files changed, 17 insertions(+), 6 deletions(-) diff --git a/LICENSE.txt b/LICENSE.txt index 367e3538d..00ae6140b 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,10 +1,14 @@ -compiler-builtins as a whole is available for use under both the MIT license +The compiler-builtins crate is available for use under both the MIT license and the Apache-2.0 license with the LLVM exception (MIT AND Apache-2.0 WITH LLVM-exception). -As a contributor, you agree that your code can be used under either the MIT -license, or the Apache-2.0 license, or the Apache-2.0 license with the LLVM -exception. +The libm crate is available for use under the MIT license. + +As a contributor, you agree that your code may be used under any of the +following: the MIT license, the Apache-2.0 license, or the Apache-2.0 license +with the LLVM exception. In other words, original (non-derivative) work is +licensed under MIT OR Apache-2.0 OR Apache-2.0 WITH LLVM-exception. This is +the default license for all other source in this repository. Text of the relevant licenses is provided below: @@ -263,8 +267,9 @@ license: * Work derived from compiler-rt after 2019-01-19 is usable under the Apache-2.0 license with the LLVM exception. -* The bundled `math` module is from rust-lang/libm, usable under the MIT - license. See https://github.com/rust-lang/libm for details. +* The bundled `math` module is from the libm crate, usable under the MIT + license. For further details and copyrights, see see libm/LICENSE.txt at + https://github.com/rust-lang/compiler-builtins. Additionally, some source files may contain comments with specific copyrights or licenses. diff --git a/builtins-test-intrinsics/Cargo.toml b/builtins-test-intrinsics/Cargo.toml index 6d88cbec9..6e10628a4 100644 --- a/builtins-test-intrinsics/Cargo.toml +++ b/builtins-test-intrinsics/Cargo.toml @@ -3,6 +3,7 @@ name = "builtins-test-intrinsics" version = "0.1.0" edition = "2021" publish = false +license = "MIT OR Apache-2.0" [dependencies] compiler_builtins = { path = "../compiler-builtins", features = ["compiler-builtins"]} diff --git a/builtins-test/Cargo.toml b/builtins-test/Cargo.toml index 18185d8fe..f7bcb52b4 100644 --- a/builtins-test/Cargo.toml +++ b/builtins-test/Cargo.toml @@ -4,6 +4,7 @@ version = "0.1.0" authors = ["Alex Crichton "] edition = "2024" publish = false +license = "MIT AND Apache-2.0 WITH LLVM-exception AND (MIT OR Apache-2.0)" [dependencies] # For fuzzing tests we want a deterministic seedable RNG. We also eliminate potential diff --git a/crates/libm-macros/Cargo.toml b/crates/libm-macros/Cargo.toml index 50c869db7..3929854f0 100644 --- a/crates/libm-macros/Cargo.toml +++ b/crates/libm-macros/Cargo.toml @@ -3,6 +3,7 @@ name = "libm-macros" version = "0.1.0" edition = "2024" publish = false +license = "MIT OR Apache-2.0" [lib] proc-macro = true diff --git a/crates/musl-math-sys/Cargo.toml b/crates/musl-math-sys/Cargo.toml index 9e866a970..d3fb147e5 100644 --- a/crates/musl-math-sys/Cargo.toml +++ b/crates/musl-math-sys/Cargo.toml @@ -3,6 +3,7 @@ name = "musl-math-sys" version = "0.1.0" edition = "2024" publish = false +license = "MIT OR Apache-2.0" [dependencies] diff --git a/crates/util/Cargo.toml b/crates/util/Cargo.toml index ae37a7238..614c54bd8 100644 --- a/crates/util/Cargo.toml +++ b/crates/util/Cargo.toml @@ -3,6 +3,7 @@ name = "util" version = "0.1.0" edition = "2024" publish = false +license = "MIT OR Apache-2.0" [features] default = ["build-musl", "build-mpfr", "unstable-float"] diff --git a/libm-test/Cargo.toml b/libm-test/Cargo.toml index 6fd49774e..7a306e735 100644 --- a/libm-test/Cargo.toml +++ b/libm-test/Cargo.toml @@ -3,6 +3,7 @@ name = "libm-test" version = "0.1.0" edition = "2024" publish = false +license = "MIT OR Apache-2.0" [features] default = ["build-mpfr", "build-musl", "unstable-float"] From d3abeafba37f5b08716b57d27012841be48ef03c Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Mon, 21 Apr 2025 07:22:24 +0000 Subject: [PATCH 2/4] Move README.md to compiler-builtins, CONTRIBUTING.md to root Do this in a commit so git tracks the move; a new README will be introduced in the root, and CONTRIBUTING will be updated to apply to both crates. --- libm/CONTRIBUTING.md => CONTRIBUTING.md | 0 compiler-builtins/Cargo.toml | 2 +- README.md => compiler-builtins/README.md | 0 3 files changed, 1 insertion(+), 1 deletion(-) rename libm/CONTRIBUTING.md => CONTRIBUTING.md (100%) rename README.md => compiler-builtins/README.md (100%) diff --git a/libm/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 100% rename from libm/CONTRIBUTING.md rename to CONTRIBUTING.md diff --git a/compiler-builtins/Cargo.toml b/compiler-builtins/Cargo.toml index a014baf04..e2a6c0a74 100644 --- a/compiler-builtins/Cargo.toml +++ b/compiler-builtins/Cargo.toml @@ -18,8 +18,8 @@ include = [ '/configure.rs', '/src/*', '../LICENSE.txt', - '../README.md', '../compiler-rt/*', + 'README.md', 'libm/src/math/*', ] links = 'compiler-rt' diff --git a/README.md b/compiler-builtins/README.md similarity index 100% rename from README.md rename to compiler-builtins/README.md From c2d680f514024424327b026e1b8c933094ce47ad Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Mon, 21 Apr 2025 08:46:19 +0000 Subject: [PATCH 3/4] Update README and CONTRIBUTING for the new repository layout --- CONTRIBUTING.md | 189 +++++++++++++++++++++++++---------- README.md | 27 +++++ compiler-builtins/Cargo.toml | 23 ++--- compiler-builtins/README.md | 76 ++++---------- libm/Cargo.toml | 2 +- libm/README.md | 54 ++++------ 6 files changed, 213 insertions(+), 158 deletions(-) create mode 100644 README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dc4006035..9f67cfc31 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,68 +1,115 @@ # 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][src]. -- 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](#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. -- :tada: - -[issue tracker]: https://github.com/rust-lang/libm/issues -[src]: https://git.musl-libc.org/cgit/musl/tree/src/math -[`src/math/truncf.rs`]: https://github.com/rust-lang/libm/blob/master/src/math/truncf.rs - -Check [PR #65] for an example. - -[PR #65]: https://github.com/rust-lang/libm/pull/65 +## compiler-builtins + +1. From the [pending list](compiler-builtins/README.md#progress), pick one or + more intrinsics. +2. Port the version from [`compiler-rt`] and, if applicable, their + [tests][rt-tests]. Note that this crate has generic implementations for a lot + of routines, which may be usable without porting the entire implementation. +3. Add a test to `builtins-test`, comparing the behavior of the ported + intrinsic(s) with their implementation on the testing host. +4. Add the intrinsic to `builtins-test-intrinsics/src/main.rs` to verify it can + be linked on all targets. +5. Send a Pull Request (PR) :tada:. + +[`compiler-rt`]: https://github.com/llvm/llvm-project/tree/b6820c35c59a4da3e59c11f657093ffbd79ae1db/compiler-rt/lib/builtins +[rt-tests]: https://github.com/llvm/llvm-project/tree/b6820c35c59a4da3e59c11f657093ffbd79ae1db/compiler-rt/test/builtins + +## Porting Reminders + +1. [Rust][prec-rust] and [C][prec-c] have slightly different operator + precedence. C evaluates comparisons (`== !=`) before bitwise operations + (`& | ^`), while Rust evaluates the other way. +2. C assumes wrapping operations everywhere. Rust panics on overflow when in + debug mode. Consider using the [Wrapping][wrap-ty] type or the explicit + [wrapping_*][wrap-fn] functions where applicable. +3. Note [C implicit casts][casts], especially integer promotion. Rust is much + more explicit about casting, so be sure that any cast which affects the + output is ported to the Rust implementation. +4. Rust has [many functions][i32] for integer or floating point manipulation in + the standard library. Consider using one of these functions rather than + porting a new one. + +[prec-rust]: https://doc.rust-lang.org/reference/expressions.html#expression-precedence +[prec-c]: http://en.cppreference.com/w/c/language/operator_precedence +[wrap-ty]: https://doc.rust-lang.org/core/num/struct.Wrapping.html +[wrap-fn]: https://doc.rust-lang.org/std/primitive.i32.html#method.wrapping_add +[casts]: http://en.cppreference.com/w/cpp/language/implicit_conversion +[i32]: https://doc.rust-lang.org/std/primitive.i32.html ## 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. - +- _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 a subset of + `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. +- Rust does not have hex float literals. This crate provides two `hf16!`, + `hf32!`, `hf64!`, and `hf128!` which convert string literals to floats at + compile time. ```rust 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`]. +- 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`]. [`Wrapping`]: https://doc.rust-lang.org/std/num/struct.Wrapping.html [`wrapping_add`]: https://doc.rust-lang.org/std/primitive.u32.html#method.wrapping_add ## Testing -Normal tests can be executed with: +Testing for these crates can be somewhat complex, so feel free to rely on CI. + +The easiest way replicate CI testing is using Docker. This can be done by +running `./ci/run-docker.sh [target]`. If no target is specified, all targets +will be run. + +Tests can also be run without Docker: ```sh -# Tests against musl require that the submodule is up to date. +# Run basic tests +# +# --no-default-features always needs to be passed, an unfortunate limitation +# since the `#![compiler_builtins]` feature is enabled by default. +cargo test --workspace --no-default-features + +# Test with all interesting features +cargo test --workspace --no-default-features \ + --features arch,unstable-float,unstable-intrinsics,mem + +# Run with more detailed tests for libm +cargo test --workspace --no-default-features \ + --features arch,unstable-float,unstable-intrinsics,mem \ + --features build-mpfr,build-musl \ + --profile release-checked +``` + +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. + +[`rug`]: https://docs.rs/rug/latest/rug/ +[`gmp_mpfr_sys`]: https://docs.rs/gmp-mpfr-sys/1.6.4/gmp_mpfr_sys/ + +In order to run all tests, some dependencies may be required: + +```sh +# Allow testing compiler-builtins +./ci/download-compiler-rt.sh + +# Optional, initialize musl for `--features build-musl` git submodule init git submodule update @@ -70,13 +117,51 @@ git submodule update cargo test --release ``` -If you are on a system that cannot build musl or MPFR, passing -`--no-default-features` will run some limited tests. +### Extensive 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. +Libm also has tests that are exhaustive (for single-argument `f32` and 1- or 2- +argument `f16`) or extensive (for all other float and argument combinations). +These take quite a long time to run, but are launched in CI when relevant files +are changed. -`build-musl` does not build with MSVC, Wasm, or Thumb. +Exhaustive tests can be selected by passing an environment variable: -[`rug`]: https://docs.rs/rug/latest/rug/ -[`gmp_mpfr_sys`]: https://docs.rs/gmp-mpfr-sys/1.6.4/gmp_mpfr_sys/ +```sh +LIBM_EXTENSIVE_TESTS=sqrt,sqrtf cargo test --features build-mpfr \ + --test z_extensive \ + --profile release-checked + +# Run all tests for one type +LIBM_EXTENSIVE_TESTS=all_f16 cargo test ... + +# Ensure `f64` tests can run exhaustively. Estimated completion test for a +# single test is 57306 years on my machine so this may be worth skipping. +LIBM_EXTENSIVE_TESTS=all LIBM_EXTENSIVE_ITERATIONS=18446744073709551615 cargo test ... +``` + +## Benchmarking + +Regular walltime benchmarks can be run with `cargo bench`: + +```sh +cargo bench --no-default-features \ + --features arch,unstable-float,unstable-intrinsics,mem \ + --features benchmarking-reports +``` + +There are also benchmarks that check instruction count behind the `icount` +feature. These require [`iai-callgrind-runner`] (via Cargo) and [Valgrind] +to be installed, which means these only run on limited platforms. + +Instruction count benchmarks are run as part of CI to flag performance +regresions. + +```sh +cargo bench --no-default-features \ + --features arch,unstable-float,unstable-intrinsics,mem \ + --features icount \ + --bench icount --bench mem_icount +``` + +[`iai-callgrind-runner`]: https://crates.io/crates/iai-callgrind-runner +[Valgrind]: https://valgrind.org/ diff --git a/README.md b/README.md new file mode 100644 index 000000000..3130ff7b7 --- /dev/null +++ b/README.md @@ -0,0 +1,27 @@ +# `compiler-builtins` and `libm` + +This repository contains two main crates: + +* `compiler-builtins`: symbols that the compiler expects to be available at + link time +* `libm`: a Rust implementation of C math libraries, used to provide + implementations in `ocre`. + +More details are at [compiler-builtins/README.md](compiler-builtins/README.md) +and [libm/README.md](libm/README.md). + +For instructions on contributing, see [CONTRIBUTING.md](CONTRIBUTING.md). + +## License + +* `libm` may be used under the [MIT License] +* `compiler-builtins` may be used under the [MIT License] and the + [Apache License, Version 2.0] with the LLVM exception. +* All original contributions must be under all of: the MIT license, the + Apache-2.0 license, and the Apache-2.0 license with the LLVM exception. + +More details are in [LICENSE.txt](LICENSE.txt) and +[libm/LICENSE.txt](libm/LICENSE.txt). + +[MIT License]: https://opensource.org/license/mit +[Apache License, Version 2.0]: htps://www.apache.org/licenses/LICENSE-2.0 diff --git a/compiler-builtins/Cargo.toml b/compiler-builtins/Cargo.toml index e2a6c0a74..9e23c75a8 100644 --- a/compiler-builtins/Cargo.toml +++ b/compiler-builtins/Cargo.toml @@ -3,24 +3,21 @@ authors = ["Jorge Aparicio "] name = "compiler_builtins" version = "0.1.155" license = "MIT AND Apache-2.0 WITH LLVM-exception AND (MIT OR Apache-2.0)" -readme = "../README.md" +readme = "README.md" repository = "https://github.com/rust-lang/compiler-builtins" homepage = "https://github.com/rust-lang/compiler-builtins" documentation = "https://docs.rs/compiler_builtins" edition = "2021" -description = """ -Compiler intrinsics used by the Rust compiler. Also available for other targets -if necessary! -""" +description = "Compiler intrinsics used by the Rust compiler." include = [ - '/Cargo.toml', - '/build.rs', - '/configure.rs', - '/src/*', - '../LICENSE.txt', - '../compiler-rt/*', - 'README.md', - 'libm/src/math/*', + "../LICENSE.txt", + "../compiler-rt/*", + "/Cargo.toml", + "/build.rs", + "/configure.rs", + "/src/*", + "README.md", + "libm/src/math/*", ] links = 'compiler-rt' diff --git a/compiler-builtins/README.md b/compiler-builtins/README.md index e5350d58c..387b70c04 100644 --- a/compiler-builtins/README.md +++ b/compiler-builtins/README.md @@ -1,64 +1,18 @@ # `compiler-builtins` -This crate provides external symbols that the compiler expects to be available when -building Rust projects, typically software routines for basic operations that do not -have hardware support. It is largely a port of LLVM's [`compiler-rt`]. +This crate provides external symbols that the compiler expects to be available +when building Rust projects, typically software routines for basic operations +that do not have hardware support. It is largely a port of LLVM's +[`compiler-rt`]. -It is distributed as part of Rust's sysroot. +It is distributed as part of Rust's sysroot. `compiler-builtins` does not need +to be added as an explicit dependency in `Cargo.toml`. [`compiler-rt`]: https://github.com/llvm/llvm-project/tree/1b1dc505057322f4fa1110ef4f53c44347f52986/compiler-rt ## Contributing -1. Pick one or more intrinsics from the [pending list](#progress). -2. Fork this repository. -3. Port the intrinsic(s) and their corresponding [unit tests][1] from their - [C implementation][2] to Rust. -4. Add a test to compare the behavior of the ported intrinsic(s) with their - implementation on the testing host. -5. Add the intrinsic to `builtins-test-intrinsics/src/main.rs` to verify it - can be linked on all targets. -6. Send a Pull Request (PR). -7. Once the PR passes our extensive testing infrastructure, we'll merge it! -8. Celebrate :tada: - -[1]: https://github.com/rust-lang/llvm-project/tree/9e3de9490ff580cd484fbfa2908292b4838d56e7/compiler-rt/test/builtins/Unit -[2]: https://github.com/rust-lang/llvm-project/tree/9e3de9490ff580cd484fbfa2908292b4838d56e7/compiler-rt/lib/builtins -[3]: https://github.com/rust-lang/compiler-builtins/actions - -### Porting Reminders - -1. [Rust][5a] and [C][5b] have slightly different operator precedence. C evaluates comparisons (`== !=`) before bitwise operations (`& | ^`), while Rust evaluates the other way. -2. C assumes wrapping operations everywhere. Rust panics on overflow when in debug mode. Consider using the [Wrapping][6] type or the explicit [wrapping_*][7] functions where applicable. -3. Note [C implicit casts][8], especially integer promotion. Rust is much more explicit about casting, so be sure that any cast which affects the output is ported to the Rust implementation. -4. Rust has [many functions][9] for integer or floating point manipulation in the standard library. Consider using one of these functions rather than porting a new one. - -[5a]: https://doc.rust-lang.org/reference/expressions.html#expression-precedence -[5b]: http://en.cppreference.com/w/c/language/operator_precedence -[6]: https://doc.rust-lang.org/core/num/struct.Wrapping.html -[7]: https://doc.rust-lang.org/std/primitive.i32.html#method.wrapping_add -[8]: http://en.cppreference.com/w/cpp/language/implicit_conversion -[9]: https://doc.rust-lang.org/std/primitive.i32.html - -## Testing - -The easiest way to test locally is using Docker. This can be done by running -`./ci/run-docker.sh [target]`. If no target is specified, all targets will be -run. - -In order to run the full test suite, you will also need the C compiler runtime -to test against, located in a directory called `compiler-rt`. This can be -obtained with the following: - -```sh -curl -L -o rustc-llvm-20.1.tar.gz https://github.com/rust-lang/llvm-project/archive/rustc/20.1-2025-02-13.tar.gz -tar xzf rustc-llvm-20.1.tar.gz --strip-components 1 llvm-project-rustc-20.1-2025-02-13/compiler-rt -``` - -Local targets may also be tested with `./ci/run.sh [target]`. - -Note that testing may not work on all hosts, in which cases it is acceptable to -rely on CI. +See [CONTRIBUTING.md](CONTRIBUTING.md). ## Progress @@ -468,9 +422,15 @@ Unsupported in any current target: used on old versions of 32-bit iOS with ARMv5 ## License -The compiler-builtins crate is dual licensed under both the University of -Illinois "BSD-Like" license and the MIT license. As a user of this code you may -choose to use it under either license. As a contributor, you agree to allow -your code to be used under both. +Usage is allowed under the [MIT License] and the [Apache License, Version 2.0] +with the LLVM exception. + +[MIT License]: https://opensource.org/license/mit +[Apache License, Version 2.0]: htps://www.apache.org/licenses/LICENSE-2.0 + +### Contribution + +Contributions are licensed under the MIT License, the Apache License, +Version 2.0, and the Apache-2.0 license with the LLVM exception. -Full text of the relevant licenses is in LICENSE.TXT. +See [LICENSE.txt](../LICENSE.txt) for full details. diff --git a/libm/Cargo.toml b/libm/Cargo.toml index 44154c1a8..4e3850bbf 100644 --- a/libm/Cargo.toml +++ b/libm/Cargo.toml @@ -7,7 +7,7 @@ keywords = ["libm", "math"] license = "MIT" name = "libm" readme = "README.md" -repository = "https://github.com/rust-lang/libm" +repository = "https://github.com/rust-lang/compiler-builtins" version = "0.2.11" edition = "2021" rust-version = "1.63" diff --git a/libm/README.md b/libm/README.md index 52d760a4f..349e892df 100644 --- a/libm/README.md +++ b/libm/README.md @@ -1,38 +1,26 @@ # `libm` -A port of [MUSL]'s libm to Rust. +A Rust implementations of the C math library. -[MUSL]: https://musl.libc.org/ +## Usage -## Goals +`libm` provides fallback implementations for Rust's [float math functions] in +`core`, and the [`core_float_math`] feature. If what is available suits your +needs, there is no need to add `libm` as a dependency. -The short term goal of this library is to [enable math support (e.g. `sin`, `atan2`) for the -`wasm32-unknown-unknown` target][wasm] (cf. [rust-lang/compiler-builtins][pr]). The longer -term goal is to enable [math support in the `core` crate][core]. +If more functionality is needed, this crate can also be used directly: -[wasm]: https://github.com/rust-lang/libm/milestone/1 -[pr]: https://github.com/rust-lang/compiler-builtins/pull/248 -[core]: https://github.com/rust-lang/libm/milestone/2 +```toml +[dependencies] +libm = "0.2.11" +``` -## Already usable - -This crate is [on crates.io] and can be used today in stable `#![no_std]` programs. - -The API documentation can be found [here](https://docs.rs/libm). - -[on crates.io]: https://crates.io/crates/libm - -## Benchmark -[benchmark]: #benchmark - -The benchmarks are located in `crates/libm-bench` and require a nightly Rust toolchain. -To run all benchmarks: - -> cargo +nightly bench --all +[float math functions]: https://doc.rust-lang.org/std/primitive.f32.html +[`core_float_math`]: https://github.com/rust-lang/rust/issues/137578 ## Contributing -Please check [CONTRIBUTING.md](CONTRIBUTING.md) +Please check [CONTRIBUTING.md](../CONTRIBUTING.md) ## Minimum Rust version policy @@ -40,17 +28,15 @@ This crate supports rustc 1.63 and newer. ## License -Usage is licensed under the MIT license ([LICENSE-MIT](LICENSE-MIT) or -https://opensource.org/licenses/MIT). - +Usage is under the MIT license, available at +. ### Contribution Contributions are licensed under both the MIT license and the Apache License, -Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or -https://www.apache.org/licenses/LICENSE-2.0). Unless you explicitly state -otherwise, any contribution intentionally submitted for inclusion in the work -by you, as defined in the Apache-2.0 license, shall be dual licensed as -mentioned, without any additional terms or conditions. +Version 2.0, available at . Unless +you explicitly state otherwise, any contribution intentionally submitted for +inclusion in the work by you, as defined in the Apache-2.0 license, shall be +dual licensed as mentioned, without any additional terms or conditions. -See `LICENSE.txt` for full details. +See [LICENSE.txt](LICENSE.txt) for full details. From 30787beb1ccd1d7dfee19e38903555da6c7f8ad7 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Mon, 21 Apr 2025 09:20:37 +0000 Subject: [PATCH 4/4] Fix compiler-builtins publish compiler-builtins currently wouldn't publish correctly because of a relative path to `libm` that doesn't get included in the package. Fix this by simlinking `libm` to within the `compiler-builtins` directory. Also symlink LICENSE.txt which lets us drop the `include` array in Cargo.toml. LICENSE.txt and compiler-rt were not being included anyway, since Cargo silently drops items that are not within the crate directory. --- compiler-builtins/Cargo.toml | 10 ---------- compiler-builtins/LICENSE.txt | 1 + compiler-builtins/src/lib.rs | 2 +- compiler-builtins/src/math/libm_math | 1 + compiler-builtins/src/{math.rs => math/mod.rs} | 9 ++++----- 5 files changed, 7 insertions(+), 16 deletions(-) create mode 120000 compiler-builtins/LICENSE.txt create mode 120000 compiler-builtins/src/math/libm_math rename compiler-builtins/src/{math.rs => math/mod.rs} (96%) diff --git a/compiler-builtins/Cargo.toml b/compiler-builtins/Cargo.toml index 9e23c75a8..1de37bd86 100644 --- a/compiler-builtins/Cargo.toml +++ b/compiler-builtins/Cargo.toml @@ -9,16 +9,6 @@ homepage = "https://github.com/rust-lang/compiler-builtins" documentation = "https://docs.rs/compiler_builtins" edition = "2021" description = "Compiler intrinsics used by the Rust compiler." -include = [ - "../LICENSE.txt", - "../compiler-rt/*", - "/Cargo.toml", - "/build.rs", - "/configure.rs", - "/src/*", - "README.md", - "libm/src/math/*", -] links = 'compiler-rt' [lib] diff --git a/compiler-builtins/LICENSE.txt b/compiler-builtins/LICENSE.txt new file mode 120000 index 000000000..4ab43736a --- /dev/null +++ b/compiler-builtins/LICENSE.txt @@ -0,0 +1 @@ +../LICENSE.txt \ No newline at end of file diff --git a/compiler-builtins/src/lib.rs b/compiler-builtins/src/lib.rs index 067855603..7523a00cf 100644 --- a/compiler-builtins/src/lib.rs +++ b/compiler-builtins/src/lib.rs @@ -45,7 +45,7 @@ pub mod math; pub mod mem; // `libm` expects its `support` module to be available in the crate root. -use math::libm::support; +use math::libm_math::support; #[cfg(target_arch = "arm")] pub mod arm; diff --git a/compiler-builtins/src/math/libm_math b/compiler-builtins/src/math/libm_math new file mode 120000 index 000000000..4d65313c2 --- /dev/null +++ b/compiler-builtins/src/math/libm_math @@ -0,0 +1 @@ +../../../libm/src/math \ No newline at end of file diff --git a/compiler-builtins/src/math.rs b/compiler-builtins/src/math/mod.rs similarity index 96% rename from compiler-builtins/src/math.rs rename to compiler-builtins/src/math/mod.rs index 722374f8e..078feb9ff 100644 --- a/compiler-builtins/src/math.rs +++ b/compiler-builtins/src/math/mod.rs @@ -2,15 +2,14 @@ #[allow(dead_code)] #[allow(unused_imports)] #[allow(clippy::all)] -#[path = "../../libm/src/math/mod.rs"] -pub(crate) mod libm; +pub(crate) mod libm_math; macro_rules! libm_intrinsics { ($(fn $fun:ident($($iid:ident : $ity:ty),+) -> $oty:ty;)+) => { intrinsics! { $( pub extern "C" fn $fun($($iid: $ity),+) -> $oty { - $crate::math::libm::$fun($($iid),+) + $crate::math::libm_math::$fun($($iid),+) } )+ } @@ -185,13 +184,13 @@ pub mod partial_availability { // allow for windows (and other targets) intrinsics! { pub extern "C" fn lgamma_r(x: f64, s: &mut i32) -> f64 { - let r = super::libm::lgamma_r(x); + let r = super::libm_math::lgamma_r(x); *s = r.1; r.0 } pub extern "C" fn lgammaf_r(x: f32, s: &mut i32) -> f32 { - let r = super::libm::lgammaf_r(x); + let r = super::libm_math::lgammaf_r(x); *s = r.1; r.0 }