Setup a workspace, adjust READMEs

Author: nagisa

Cargo.toml

@@ -1,36 +1,2 @@
-[package]
-name = "stacker"
-version = "0.1.15"
-authors = ["Alex Crichton <alex@alexcrichton.com>", "Simonas Kazlauskas <stacker@kazlauskas.me>"]
-build = "build.rs"
-license = "MIT OR Apache-2.0"
-readme = "README.md"
-repository = "https://github.com/rust-lang/stacker"
-homepage = "https://github.com/rust-lang/stacker"
-documentation = "https://docs.rs/stacker/0.1.15"
-description = """
-A stack growth library useful when implementing deeply recursive algorithms that
-may accidentally blow the stack.
-"""
-
-[lib]
-name = "stacker"
-doctest = false
-test = false
-
-[dependencies]
-cfg-if = "1.0.0"
-libc = "0.2.45"
-psm = { path = "psm", version = "0.1.7" }
-
-[target.'cfg(windows)'.dependencies.windows-sys]
-version = ">=0.34.0, <0.42.0"
-features = [
-    "Win32_System_Memory",
-    "Win32_System_Threading",
-    "Win32_Foundation",
-]
-
-
-[build-dependencies]
-cc = "1.0.2"
+[workspace]
+members = ["stacker", "psm"]

README.md

@@ -0,0 +1,20 @@
+<div align="center">
+  <h1><code>stacker & psm</code></h1>
+</div>
+
+Check out the README for corresponding crates for further information on each crate.
+
+# License
+
+This project is licensed under either of
+
+ * [Apache License, Version 2.0](<https://www.apache.org/licenses/LICENSE-2.0>)
+ * [MIT license](<https://opensource.org/licenses/MIT>)
+
+at your option.
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this project by you, as defined in the Apache-2.0 license,
+shall be dual licensed as above, without any additional terms or conditions.

README.mkd

@@ -1,31 +1,39 @@
-# Portable Stack Manipulation
-
-This crate provides very portable functions to control the stack pointer and inspect the properties
-of the stack. This crate does not attempt to provide safe abstractions to any operations, the
-only goals are correctness, portability and efficiency (in that exact order). As a consequence most
-functions you’ll see in this crate are unsafe.
-
-Unless you’re writing a safe abstraction over stack manipulation, this is not the crate you
-want. Instead consider one of the safe abstractions over this crate. A good place to look at is
-the crates.io’s reverse dependency list.
+<div align="center">
+  <h1><code>psm</code></h1>
+  <p>
+    <strong>A portable library of stack introspection and manipulation operations</strong>
+  </p>
+</div>
+
+This crate provides functions to control the stack pointer and inspect the properties of the stack.
+This crate does not attempt to provide safe or Rust-idiomatic abstractions to any of the
+operations. The only goals are correctness, portability and efficiency (in this exact order). As a
+consequence most functions you’ll see in this crate are unsafe and require the caller to maintain a
+variety of invariants.
+
+Unless you are writing a safe abstraction over stack manipulation or need extremely precse control
+over your stack, this is probably not the crate you want. Instead consider one of the safe
+abstractions based on this crate. A good place to look at is the crates.io’s reverse dependency
+list.
 
 # Platform support
 
-The following table lists supported targets and architectures with notes on the level of current
-support and knowledge about the target. The three columns “Available”, “Tested” and “Callstack”
-imply an increasingly high level of support.
+The following table lists targets and architectures supported by this crate, alongside the notes on
+the current level of support and behaviour. The three columns “Available”, “Tested” and “Callstack”
+indicate different degrees of support:
 
-* “Available” basically means that the code builds and the assembly files have been written for the
-  target;
-* “Tested” means that the assembly code has been tested or otherwise verified to be correct. For
-  most targets it also means that continuous integration is set up;
-* “Callstack” means that the assembly code has been written with due care to support unwinding the
-  stack and displaying the call frames (i.e. `gdb backtrace` works as expected).
+* On platforms marked “available” this library builds and contains necessary functionality to
+  introspect or manipulate the stack (see the `psm_stack_information` and `psm_stack_manipulation`
+  macros);
+* “Tested” platforms have had their implementations tested or otherwise verified to be correct. For
+  many such targets it also means that we have a continuous integration setup;
+* “Callstack” indicates that, in addition to the library being tested, it has been verified
+  functions based on stack unwinding (e.g. `gdb backtrace`) continue to work correctly.
 
 <table>
+
 <tr>
-<th rowspan="1" colspan="2">Target</th>
-<th colspan="3">Support</th>
+<th rowspan="1" colspan="2">Target</th>  <th colspan="3">Support</th>
 </tr>
 <tr>
 <th rowspan="2">Architecture</th>
@@ -510,11 +518,9 @@ The assembly code for loongarch64 has been tested locally with a C caller.
 
 # License
 
-PSM is licensed under either of
+`psm` is licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
-   https://www.apache.org/licenses/LICENSE-2.0)
- * MIT license ([LICENSE-MIT](LICENSE-MIT) or
-   https://opensource.org/licenses/MIT)
+ * [Apache License, Version 2.0](<https://www.apache.org/licenses/LICENSE-2.0>)
+ * [MIT license](<https://opensource.org/licenses/MIT>)
 
 at your option.

psm/README.mkd

@@ -1,14 +1,4 @@
-//! # **P**ortable **S**tack **M**anipulation
-//! This crate provides portable functions to control the stack pointer and inspect the properties
-//! of the stack. This crate does not attempt to provide safe abstractions to any operations, the
-//! only goals are correctness, portability and efficiency (in that exact order).  As a consequence
-//! most functions you will find in this crate are unsafe.
-//!
-//! Note, that the stack allocation is left up to the user. Unless you’re writing a safe
-//! abstraction over stack manipulation, this is unlikely to be the crate you want. Instead
-//! consider one of the safe abstractions over this crate such as `stacker`. Another good place to
-//! look at is the crates.io’s reverse dependency list.
-
+#![doc=include_str!("../README.mkd")]
 #![allow(unused_macros)]
 #![no_std]
 

psm/src/lib.rs

@@ -0,0 +1,36 @@
+[package]
+name = "stacker"
+version = "0.1.15"
+authors = ["Alex Crichton <alex@alexcrichton.com>", "Simonas Kazlauskas <stacker@kazlauskas.me>"]
+build = "build.rs"
+license = "MIT OR Apache-2.0"
+readme = "README.md"
+repository = "https://github.com/rust-lang/stacker"
+homepage = "https://github.com/rust-lang/stacker"
+documentation = "https://docs.rs/stacker/0.1.15"
+description = """
+A stack growth library useful when implementing deeply recursive algorithms that
+may accidentally blow the stack.
+"""
+
+[lib]
+name = "stacker"
+doctest = false
+test = false
+
+[dependencies]
+cfg-if = "1.0.0"
+libc = "0.2.45"
+psm = { path = "../psm", version = "0.1.7" }
+
+[target.'cfg(windows)'.dependencies.windows-sys]
+version = ">=0.34.0, <0.42.0"
+features = [
+    "Win32_System_Memory",
+    "Win32_System_Threading",
+    "Win32_Foundation",
+]
+
+
+[build-dependencies]
+cc = "1.0.2"

stacker/Cargo.toml

@@ -0,0 +1,49 @@
+<div align="center">
+  <h1><code>stacker</code></h1>
+  <p>
+    <strong>A stack-growth library for Rust</strong>
+  </p>
+</div>
+
+
+`stacker` enables users to annotate fixed points in their programs where the stack may want to grow
+larger to accomodate for recursion or other kinds of heavy stack space usage. At each such
+annotation, the caller indicates how far away from the end of the stack it's allowed to be, plus
+the amount of stack to allocate if the remaining capacity is insufficient.
+
+Once a program has reached the end of its stack, a temporary stack on the heap is allocated and
+is switched to for the duration of a closure.
+
+A philosophy behind this crate is to expose a straightforward interface. In case the functionality
+provided by this crate aren’t flexible enough for your use-case, check out the `psm` crate upon
+which `stacker` is built.
+
+# Examples
+
+```
+// Grow the stack if we are within the "red zone" of 32K, and if we allocate
+// a new stack allocate an additional 1MB of stack space.
+//
+// If we're already within bounds, the provided closure will run on the current stack.
+stacker::maybe_grow(32 * 1024, 1024 * 1024, || {
+    // guaranteed to have at least 32K of stack available to use.
+});
+```
+
+## Platform Support
+
+This library currently uses `psm` for its cross platform capabilities, with a notable exception of
+Windows, which uses an implementation based on Fibers. See the documentation of psm for the table
+of supported platforms.
+
+On all unsupported platforms this library is a noop. It should compile and run, but it won't
+actually grow the stack and code will continue to hit the guard pages typically in place.
+
+# License
+
+`stacker` is licensed under either of
+
+ * [Apache License, Version 2.0](<https://www.apache.org/licenses/LICENSE-2.0>)
+ * [MIT license](<https://opensource.org/licenses/MIT>)
+
+at your option.