fixup links and style

Gankra · Jul 6, 2024 · 6b6912a · 6b6912a
1 parent c374c21
commit 6b6912a
Show file tree

Hide file tree

Showing 26 changed files with 85 additions and 72 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -5,6 +5,7 @@ version.workspace = true
 edition.workspace = true
 license.workspace = true
 repository.workspace = true
+homepage.workspace = true
 
 exclude = ["generated_impls/", "tests/"]
 
@@ -48,6 +49,7 @@ members = ["kdl-script"]
 resolver = "2"
 
 [workspace.package]
+homepage = "https://faultlore.com/abi-cafe/book"
 repository = "https://github.com/Gankra/abi-cafe"
 edition = "2021"
 license = "MIT OR Apache-2.0"

diff --git a/README.md b/README.md
@@ -14,16 +14,16 @@ ABI Cafe automates testing that two languages/compilers agree on their ABIs.
 
 **ABI Cafe is essentially an ABI fuzzer**, which:
 
-* [Creates a header file describing an interface](./kdl-script/index.md)
-* [Generates source code for a *user* and *implementation* of that interface](./harness/generate.md)
-* [Builds and runs the resulting program](./harness/run.md)
-* [Checks that both sides saw the same values](./harness/check.md)
+* [Creates a header file describing an interface](https://faultlore.com/abi-cafe/book/kdl-script/index.html)
+* [Generates source code for a *user* and *implementation* of that interface](https://faultlore.com/abi-cafe/book/harness/combos/toolchains.html)
+* [Builds and runs the resulting program](https://faultlore.com/abi-cafe/book/harness/combos.html)
+* [Checks that both sides saw the same values](https://faultlore.com/abi-cafe/book/harness/combos/values.html)
 
 If they agree, great!
 
 If they don't agree, even better, we just learned something! **We then try to diagnose why they disagreed, and generate a minimized version that a human can inspect and report!**
 
-Now do this [a bajillion times](./harness/combos.md) and suddenly we're learning a whole lot! Alternatively, you can [hand-craft any type or function signature you're interested in](./kdl-script/index.md), and explore its interoperability between different toolchains.
+Now do this [a bajillion times](https://faultlore.com/abi-cafe/book/harness/combos.html) and suddenly we're learning a whole lot! Alternatively, you can [hand-craft any type or function signature you're interested in](https://faultlore.com/abi-cafe/book/kdl-script/index.html), and explore its interoperability between different toolchains.
 
 ABI Cafe is purely *descriptive*. It has no preconceived notion of what *should* work, and it doesn't trust any damn thing anyone says about it. We don't analyze assembly or metadata, and we'll gleefully create programs riddled with Undefined Behaviour. We're here to *learn* not *lecture*.
 
@@ -33,7 +33,7 @@ This design is based on a fundamental belief that **ABIs exist only through shee
 
 ## Choose Your Own Adventure
 
-* [I want to use ABI Cafe in my compiler's testsuite](./harness/combos.md)
-* [I want to add support for my compiler/language to ABI Cafe](./harness/combos/toolchains.md)
-* [I want to add a test to ABI Cafe](./harness/combos/tests.md)
-* [I want to add a new kind of type to ABI Cafe](./kdl-script/types/index.md)
+* [I want to use ABI Cafe in my compiler's testsuite](https://faultlore.com/abi-cafe/book/harness/combos.html)
+* [I want to add support for my compiler/language to ABI Cafe](https://faultlore.com/abi-cafe/book/harness/combos/toolchains.html)
+* [I want to add a test to ABI Cafe](https://faultlore.com/abi-cafe/book/harness/combos/tests.html)
+* [I want to add a new kind of type to ABI Cafe](https://faultlore.com/abi-cafe/book/kdl-script/types/index.html)
diff --git a/docs/book.toml b/docs/book.toml
@@ -3,4 +3,12 @@ authors = []
 language = "en"
 multilingual = false
 src = "src"
-title = "abi-cafe"
+title = "ABI Cafe"
+
+[output.html]
+git-repository-url = "https://github.com/Gankra/abi-cafe"
+edit-url-template = "https://github.com/Gankra/abi-cafe/edit/main/docs/{path}"
+search.use-boolean-and = true
+
+# [output.linkcheck]
+# warning-policy = "error"
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -9,9 +9,9 @@
     - [type reprs](./harness/combos/reprs.md)
     - [toolchain pairings](./harness/combos/toolchains.md)
     - [value generators](./harness/combos/values.md)
-    - [value selectors)](./harness/combos/selectors.md)
+    - [value selectors](./harness/combos/selectors.md)
     - [value writers](./harness/combos/writers.md)
-- [trophycase](./trophies.md)
+- [trophy case](./trophies.md)
 
 # KDLScript
 

diff --git a/docs/src/harness/combos.md b/docs/src/harness/combos.md
@@ -1,18 +1,18 @@
-# Usage
+# usage
 
 To run ABI Cafe, just [checkout the repository](https://github.com/Gankra/abi-cafe) and `cargo run`!
 
 (Working on a prebuilt solution, a few last blockers to resolve before shipping that.)
 
 While ABI Cafe isn't a For Reals Fuzzer (yet?), it accomplishes a similar goal through the magic of procedural generation and combinatorics. These docs serve to describe the N layers of combinatorics we use to turn a grain of sand into a mountain of broken compilers.
 
-- [test files: `--tests`](./harness/combos/tests.md)
-- [calling conventions: `--conventions`](./harness/combos/conventions.md)
-- [type reprs: `--reprs`](./harness/combos/reprs.md)
-- [toolchain pairings: `--pairs`](./harness/combos/toolchains.md)
-- [value generators: `--gen-vals`](./harness/combos/values.md)
-- [value selectors: `--select-vals`](./harness/combos/selectors.md)
-- [value writers: `--write-vals`](./harness/combos/writers.md)
+- [test files: `--tests`](./combos/tests.md)
+- [calling conventions: `--conventions`](./combos/conventions.md)
+- [type reprs: `--reprs`](./combos/reprs.md)
+- [toolchain pairings: `--pairs`](./combos/toolchains.md)
+- [value generators: `--gen-vals`](./combos/values.md)
+- [value selectors: `--select-vals`](./combos/selectors.md)
+- [value writers: `--write-vals`](./combos/writers.md)
 
 When you run `abi-cafe` we will end up running the cross-product of all of these settings, typically resulting in thousands of function calls. See the subsections for details!
 

diff --git a/docs/src/harness/combos/selectors.md b/docs/src/harness/combos/selectors.md
@@ -1,4 +1,4 @@
-# value selection
+# value selectors
 
 When generating the source for a program to test, we want a way to identify which of the [values of the function arguments](./values.md) we actually care about [writing somewhere](./writers.md). This is specifically relevant when generating a minimized test case.
 

diff --git a/docs/src/harness/combos/tests.md b/docs/src/harness/combos/tests.md
@@ -19,7 +19,7 @@ Suggested Examples:
 
 * [simple.kdl](https://github.com/Gankra/abi-cafe/blob/main/include/tests/normal/simple.kdl) - a little example of a "normal" test with explicitly defined functions to test
 * [SimpleStruct.procgen.kdl](https://github.com/Gankra/abi-cafe/blob/main/include/tests/procgen/struct/SimpleStruct.procgen.kdl) - similar to simple.kdl, but procgen
-* [MetersU32.procgen.kdl](https://github.com/Gankra/abi-cafe/blob/main/include/tests/procgen/pun/MetersU32.procgen.kdl) - an example of a ["pun type"](../kdl-script/types/pun.md), where different languages use different definitions
+* [MetersU32.procgen.kdl](https://github.com/Gankra/abi-cafe/blob/main/include/tests/procgen/pun/MetersU32.procgen.kdl) - an example of a ["pun type"](../../kdl-script/types/pun.md), where different languages use different definitions
 * [IntrusiveList.procgen.kdl](https://github.com/Gankra/abi-cafe/blob/main/include/tests/procgen/fancy/IntrusiveList.procgen.kdl) - an example of how we can procgen tests for self-referential types and tagged unions
 * [i8.procgen.kdl](https://github.com/Gankra/abi-cafe/blob/main/include/tests/procgen/primitive/i8.procgen.kdl) - ok this one isn't instructive it's just funny that it can be a blank file because i8 is builtin so all the info needed is in the filename
 

diff --git a/docs/src/harness/combos/toolchains.md b/docs/src/harness/combos/toolchains.md
@@ -2,7 +2,7 @@
 
 Toolchains refer to a specific compiler (or configuration of a compiler). The entire purpose of ABI Cafe is to take two compilers and pair them up, checking that code built with one can properly call into code built by the other.
 
-Within ABI Cafe, each Toolchain also comes with a [code generation backend](../generate.md), which can take [a header file describing some types and functions](../../kdl-script/index.md) and generate either an implementation of those functions, or a caller of those functions.
+Within ABI Cafe, each Toolchain also comes with a [code generation backend](../combos/toolchains.md), which can take [a header file describing some types and functions](../../kdl-script/index.md) and generate either an implementation of those functions, or a caller of those functions.
 
 
 ## `--toolchains`

diff --git a/docs/src/harness/combos/values.md b/docs/src/harness/combos/values.md
@@ -1,4 +1,4 @@
-# value generation (randomizing!)
+# value generators
 
 When generating the source for a program to test, we need to pick values which will be passed to all the functions. These values are baked into the program, with both sides statically knowing which values they *should* have, and the test harness also having that information available for checking and diagnostics.
 

diff --git a/docs/src/intro.md b/docs/src/intro.md
@@ -18,9 +18,9 @@ ABI Cafe automates testing that two languages/compilers agree on their ABIs.
 **ABI Cafe is essentially an ABI fuzzer**, which:
 
 * [Creates a header file describing an interface](./kdl-script/index.md)
-* [Generates source code for a *user* and *implementation* of that interface](./harness/generate.md)
-* [Builds and runs the resulting program](./harness/run.md)
-* [Checks that both sides saw the same values](./harness/check.md)
+* [Generates source code for a *user* and *implementation* of that interface](./harness/combos/toolchains.md)
+* [Builds and runs the resulting program](./harness/combos.md)
+* [Checks that both sides saw the same values](./harness/combos/values.md)
 
 If they agree, great!
 

diff --git a/docs/src/kdl-script/attributes.md b/docs/src/kdl-script/attributes.md
@@ -1,6 +1,6 @@
-# KDLScript attributes
+# attributes
 
-Attributes start with `@` and apply to the next item (function or type) that follows them. There are currently 3 major classes of attributes:
+KDLScript Attributes start with `@` and apply to the next item (function or type) that follows them. There are currently 3 major classes of attributes:
 
 * repr attrs
     * lang reprs
@@ -16,7 +16,7 @@ Attributes start with `@` and apply to the next item (function or type) that fol
     * `@align 16` - align to N
     * `@packed` - pack fields to eliminate padding
 * passthrough attrs
-    * `@ "literally anything here"
+    * `@ "literally anything here"`
 
 The significance of repr attributes is that providing *any* explicit `repr` attribute is considered an opt-out from the default automatic repr all user-defined types receive.
 

diff --git a/docs/src/kdl-script/functions/index.md b/docs/src/kdl-script/functions/index.md
@@ -1 +1,8 @@
 # functions
+
+Functions are where the Actually Useful *library* version of KDLScript and the Just A Meme *application* version of KDLScript diverge. This difference is configured by the `eval` feature.
+
+As a library, KDLScript only has [function *signature declarations*](./signatures.md), and it's the responsibility of the ABI Cafe backend using KDLScript to figure out what the body should be.
+
+As a CLI binary, KDLScript [actually lets you fill in the body with some hot garbage I hacked up](./bodies.md).
+
diff --git a/docs/src/kdl-script/functions/signatures.md b/docs/src/kdl-script/functions/signatures.md
@@ -1,13 +1,6 @@
-# KDLScript function signatures
+# function signatures
 
-
-Functions are where the Actually Useful *library* version of KDLScript and the Just A Meme *application* version of KDLScript diverge. This difference is configured by the `eval` feature.
-
-In library form KDLScript only has function *signature declarations*, and it's the responsibility of the [abi-cafe][] backend using KDLScript to figure out what the body should be. In binary form you can actually fill in the body with some hot garbage I hacked up.
-
-For now we'll only document declaration.
-
-Here is a fairly complicated/contrived example function:
+Here is a fairly complicated/contrived example function signature:
 
 ```kdl
 fn "my_func" {
@@ -17,13 +10,21 @@ fn "my_func" {
         _ "&bool"
     }
     outputs {
-        _ "bool"
-        _ "&ErrorCode"
+        _ "ErrorCode"
     }
 }
 ```
 
-Functions can have arbitrarily many inputs and outputs with either named or "positional" names (which will get autonaming like `arg0`, `arg1` and `out0`, `out1`, etc.).
+Functions can have arbitrarily many inputs and outputs with either named or "positional" (`_`) names which will get autonaming like `arg0` and `out0`.
+
+Currently there is no meaning ascribed to multiple outputs, every backend refuses to implement them. Note that "returning a tuple" or any other composite is still one output. We would need to like, support Go or something to make this a meaningful expression.
+
+Named args [*could* be the equivalent of Swift named args](https://github.com/Gankra/abi-cafe/issues/32), where the inner and outer name can vary, but the outer name is like, part of the function name itself (and/or ABI)?
+
+[Varargs support is also TBD but has a sketch](https://github.com/Gankra/abi-cafe/issues/1#issuecomment-2200345710).
+
+
+# Outparams
 
 <details>
 <summary> not implemented distracting ramblings about outparams </summary>
@@ -75,9 +76,3 @@ fn my_func_caller() {
 > Update: actually even automating this was miserable, and also outparams aren't really substantial ABI-wise right now, so I'm not sure I'll ever implement outparams. It's more complexity than it's worth!
 
 </details>
-
-Currently there is no meaning ascribed to multiple outputs, every backend refuses to implement them. Note that "returning a tuple" or any other composite is still one output. We would need to like, support Go or something to make this a meaningful expression.
-
-Named args [*could* be the equivalent of Swift named args](https://github.com/Gankra/abi-cafe/issues/32), where the inner and outer name can vary, but the outer name is like, part of the function name itself (and/or ABI)?
-
-[Varargs support is also TBD but has a sketch](https://github.com/Gankra/abi-cafe/issues/1#issuecomment-2200345710).
diff --git a/docs/src/kdl-script/index.md b/docs/src/kdl-script/index.md
@@ -2,7 +2,7 @@
 
 KDLScript, the [KDL](https://kdl.dev/)-based programming language!
 
-KDLScript ("Cuddle Script") is a "fake" scripting language that actually just exists to declare type/function signatures without tying ourselves to any particular language's semantics. It exists to be used by [ABI Cafe](../index.md).
+KDLScript ("Cuddle Script") is a "fake" scripting language that actually just exists to declare type/function signatures without tying ourselves to any particular language's semantics. It exists to be used by [ABI Cafe](../intro.md).
 
 Basically, KDLScript is a header format we can make as weird as we want for our own usecase:
 
@@ -36,7 +36,7 @@ fn "sum" {
 Ultimately the syntax and concepts are heavily borrowed from Rust, for a few reasons:
 
 * The author is very comfortable with Rust
-* This (and [abi-cafe](./harness/index.md)) were originally created to find bugs in rustc
+* This (and [ABI Cafe](../intro.md)) were originally created to find bugs in rustc
 * Rust is genuinely just a solid language for interfaces! (Better than C/C++)
 
 The ultimate goal of this is to test that languages can properly communicate over

diff --git a/docs/src/kdl-script/types/alias.md b/docs/src/kdl-script/types/alias.md
@@ -36,7 +36,7 @@ Note that the ordering matches Rust's `type Alias = RealType;` syntax and not C/
 
 ## I'm Normal And Can Be Trusted With Codegen
 
-[The abi-cafe codegen backends](../../harness/generate.md) will go out of their way to "remember" that a type alias exists and use it when the alias was specified there. So for instance given this definition:
+[The abi-cafe codegen backends](../../harness/combos/toolchains.md) will go out of their way to "remember" that a type alias exists and use it when the alias was specified there. So for instance given this definition:
 
 ```kdl
 enum "ComplexLongName" {

diff --git a/docs/src/kdl-script/types/arrays.md b/docs/src/kdl-script/types/arrays.md
@@ -1,6 +1,6 @@
-# KDLScript array types
+# array types
 
-Array types like `[u32; 4]` have the layout/repr you would expect from languages like C and Rust.
+KDLScript array types like `[u32; 4]` have the layout/repr you would expect from languages like C and Rust.
 
 But there's a problem with passing them by-value: C is supremely fucking weird about passing arrays by value if they're not wrapped in a struct.
 

diff --git a/docs/src/kdl-script/types/enum.md b/docs/src/kdl-script/types/enum.md
@@ -1,4 +1,4 @@
-# KDLScript enum types
+# enum types
 
 A KDLScript `enum` type is a C-like enum with no nest fields. [For a Rust-like enum (tagged union), see tagged types](./tagged.md).
 
@@ -50,7 +50,7 @@ enum "MyEnum" {
 
 If no explicit `@repr` attribute is applied (the default, which is recommended), the enum will be [eligible for repr combinatorics](../../harness/combos/reprs.md). Basically, we'll generate a version of the test where it's set to `#[repr(C)]` and version where it's set to `#[repr(Rust)]`, improving your test coverage.
 
-It's up to each [compiler / language](../../harness/combos/impls.md) to implement these attributes [however they see fit](../../harness/generate.md). But for instance we would expect Rust backends to support both layouts, and C backends to bail on the Rust repr, producing twice as many rust-calls-rust test cases.
+It's up to each [compiler / language](../../harness/combos/toolchains.md) to implement these attributes [however they see fit](../../harness/combos/toolchains.md). But for instance we would expect Rust backends to support both layouts, and C backends to bail on the Rust repr, producing twice as many rust-calls-rust test cases.
 
 Note that `repr(u32)` and friends are *not* currently eligible for repr combinatorics. If you want to test that, set it explicitly.
 
@@ -70,12 +70,12 @@ enum "IoError" {
 }
 ```
 
-It's up to each to each [compiler / language](../../harness/combos/impls.md) to implement these [however they see fit](../../harness/generate.md).
+It's up to each to each [compiler / language](../../harness/combos/toolchains.md) to implement these [however they see fit](../../harness/combos/toolchains.md).
 
 
 ## Value Initialization And Analysis
 
 When [initializing an instance of an enum](../../harness/combos/values.md), we will uniformly select a random variant to use (deterministically).
 
-When [checking the value of an enum](../../harness/check.md), we will just check its bytes. In the future [we may instead check it semantically with a match/switch](https://github.com/Gankra/abi-cafe/issues/34).
+When [checking the value of an enum](../../harness/combos/values.md), we will just check its bytes. In the future [we may instead check it semantically with a match/switch](https://github.com/Gankra/abi-cafe/issues/34).
 
diff --git a/docs/src/kdl-script/types/index.md b/docs/src/kdl-script/types/index.md
@@ -1,4 +1,4 @@
-# KDLScript Types
+# types
 
 The following kinds of types exist in KDLScript.
 

diff --git a/docs/src/kdl-script/types/primitives.md b/docs/src/kdl-script/types/primitives.md
@@ -1,6 +1,6 @@
-# KDLScript primitive types
+# primitive types
 
-There are various builtin primitives, such as:
+There are various builtin primitives in KDLScript, such as:
 
 * integers - fixed width integers
     * `i8`, `i16`, `i32`, `i64`, `i128`, `i256`

diff --git a/docs/src/kdl-script/types/pun.md b/docs/src/kdl-script/types/pun.md
@@ -1,6 +1,6 @@
-# KDLScript pun types
+# pun types
 
-A pun is the equivalent of an ifdef/cfg'd type, allowing us to declare that two wildly different declarations in different languages should in fact have the same layout and/or ABI. A pun type contains "selector blocks" which are sequentially matched on much like CSS. The first one to match wins. When lowering to a specific backend/config if no selector matches, then compilation fails.
+A KDLScript `pun` type is the equivalent of an ifdef/cfg'd type, allowing us to declare that two wildly different declarations in different languages should in fact have the same layout and/or ABI. A pun type contains "selector blocks" which are sequentially matched on much like CSS. The first one to match wins. When lowering to a specific backend/config if no selector matches, then compilation fails.
 
 Here is an example that claims that a Rust `repr(transparent)` newtype of a `u32` should match the ABI of a `uint32_t` in C/C++:
 

diff --git a/docs/src/kdl-script/types/refs.md b/docs/src/kdl-script/types/refs.md
@@ -1,6 +1,6 @@
-# KDLScript reference types
+# reference types
 
-The "value" of a reference type `&T` is its pointee for the purposes of [abi-cafe](../../intro.md). In this regard it's similar to C++ references or Rust references, where most operations automagically talk about the pointee and not the pointer. Using a reference type lets you test that something can properly be passed-by-reference, as opposed to passed-by-value.
+The "value" of a KDLScript reference type `&T` is its pointee for the purposes of [abi-cafe](../../intro.md). In this regard it's similar to C++ references or Rust references, where most operations automagically talk about the pointee and not the pointer. Using a reference type lets you test that something can properly be passed-by-reference, as opposed to passed-by-value.
 
 Reference types may appear in other composite types, indicating that the caller is responsible for allocating variables for each one and then storing pointers to them in the composite type.