Update README and CONTRIBUTING for the new repository layout

6 files changed, 213 insertions, 158 deletions

diff --git a/library/compiler-builtins/CONTRIBUTING.md b/library/compiler-builtins/CONTRIBUTING.md
index dc40060357c..9f67cfc3157 100644
--- a/library/compiler-builtins/CONTRIBUTING.md
+++ b/library/compiler-builtins/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/library/compiler-builtins/README.md b/library/compiler-builtins/README.md
new file mode 100644
index 00000000000..3130ff7b77d
--- /dev/null
+++ b/library/compiler-builtins/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/library/compiler-builtins/compiler-builtins/Cargo.toml b/library/compiler-builtins/compiler-builtins/Cargo.toml
index e2a6c0a74bd..9e23c75a826 100644
--- a/library/compiler-builtins/compiler-builtins/Cargo.toml
+++ b/library/compiler-builtins/compiler-builtins/Cargo.toml
@@ -3,24 +3,21 @@ authors = ["Jorge Aparicio <japaricious@gmail.com>"]
 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/library/compiler-builtins/compiler-builtins/README.md b/library/compiler-builtins/compiler-builtins/README.md
index e5350d58c3e..387b70c0499 100644
--- a/library/compiler-builtins/compiler-builtins/README.md
+++ b/library/compiler-builtins/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/library/compiler-builtins/libm/Cargo.toml b/library/compiler-builtins/libm/Cargo.toml
index 44154c1a8f5..4e3850bbff0 100644
--- a/library/compiler-builtins/libm/Cargo.toml
+++ b/library/compiler-builtins/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/library/compiler-builtins/libm/README.md b/library/compiler-builtins/libm/README.md
index 52d760a4f15..349e892dfcf 100644
--- a/library/compiler-builtins/libm/README.md
+++ b/library/compiler-builtins/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
+<https://opensource.org/license/mit>.
 
 ### 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 <htps://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.
 
-See `LICENSE.txt` for full details.
+See [LICENSE.txt](LICENSE.txt) for full details.