style update, broken link, run script and dependencies

0xPolygonMiden · Sep 10, 2024 · 5947e41 · 5947e41
1 parent a48d095
commit 5947e41
Show file tree

Hide file tree

Showing 17 changed files with 77 additions and 57 deletions.
diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,15 @@ bin/midenc
 bin/litcheck
 .crates.toml
 .crates2.json
+
+# Docs platform ignores
+.vscode
+.code
+.idea
+site/
+venv/
+env/
+*.out
+node_modules/
+*DS_Store
+*.iml
diff --git a/docs/appendix/calling_conventions.md b/docs/appendix/calling_conventions.md
@@ -1,4 +1,4 @@
-# Calling Conventions
+# Calling conventions
 
 This document describes the various calling conventions recognized/handled by the compiler,
 including a specification for the interaction with the IR type system.
@@ -25,17 +25,16 @@ There are four calling conventions represented in the compiler:
   convention is allowed to have types in its signature that are/contain pointers, with certain caveats around
   those pointers.
 
-
 All four conventions above are based on the System V C ABI, tailored to the Miden VM. The only exception is
 `Fast`, which may modify the ABI arbitrarily as it sees fit, and makes no guarantees about what modifications,
 if any, it will make.
 
-# Data Representation
+## Data representation
 
 The following is a description of how the IR type system is represented in the `C` calling convention. Later,
 a description of how the other conventions extend/restrict/modify this representation will be provided.
 
-## Scalars
+### Scalars
 
 General type | C Type | IR Type | `sizeof` | Alignment (bytes) | Miden Type
 -|-|-|-|-|-
@@ -101,14 +100,14 @@ two's complement rules.
 The Miden VM only has native support for field elements, words, and `u32`; all other types are implemented in software
 using intrinsics.
 
-## Aggregates and Unions
+### Aggregates and unions
 
 Structures and unions assume the alignment of their most strictly aligned component. Each member is assigned to the
 lowest available offset with the appropriate alignment. The size of any object is always a multiple of the object's alignment.
 An array uses the same alignment as its elements. Structure and union objects can require padding to meet size and alignment
 constraints. The contents of any padding is undefined.
 
-## Memory Model
+### Memory model
 
 Interacting with memory in Miden is quite similar to WebAssembly in some ways:
 
@@ -176,12 +175,12 @@ word-aligned or element-aligned, so an unaligned load or store would require eit
 bytes starting at some arbitrary address. In practice, most loads/stores are likely to be element-aligned, so most overhead from
 emulation will come from values which cross an element or word boundary.
 
-# Function Calls
+## Function calls
 
 This section describes the conventions followed when executing a function call via `exec`, including how arguments are passed on the
 operand stack, stack frames, etc. Later, we'll cover the differences when executing calls via `call` or `syscall`.
 
-## Locals and the stack frame
+### Locals and the stack frame
 
 Miden does not have registers in the style of hardware architectures. Instead it has an operand stack, on which an arbitrary number of
 operands may be stored, and local variables. In both cases - an operand on the operand stack, or a single local variable - the value
@@ -201,7 +200,7 @@ Because there are no registers, the notion of callee-saved or caller-saved regis
 in its place, a somewhat equivalent set of rules defines the contract between caller and callee in terms of the state of the operand stack,
 those are described below in the section covering the operand stack.
 
-### The shadow stack
+#### The shadow stack
 
 Miden is a [Harvard](https://en.wikipedia.org/wiki/Harvard_architecture) architecture; as such, code and data are not in the same memory
 space. More precisely, in Miden, code is only addressable via the hash of the MAST root of that code, which must correspond to code that
@@ -222,7 +221,7 @@ constraints of the callee's calling convention).
 Languages with more elaborate requirements with regard to the stack will need to implement their own shadow stack, and emit code in function
 prologues/epilogues to manage it.
 
-### The operand stack
+#### The operand stack
 
 The Miden virtual machine is a stack machine, not a register machine. Rather than having a fixed set of registers that are used to
 store and manipulate scalar values, the Miden VM has the operand stack, which can hold an arbitrary number of operands (where each
@@ -246,7 +245,7 @@ then one of the following must happen:
   which refers to the remaining arguments on the advice provider stack. The callee must arrange to fetch the spilled arguments from the advice
   provider using that hash.
 
-### Function signatures
+#### Function signatures
 
 Miden Abstract Syntax Trees (MASTs) do not have any notion of functions, and as such are not aware of parameters, return values, etc. For
 this document, that's not a useful level of abstraction to examine. Even a step higher, Miden Assembly (MASM) has functions (procedures

diff --git a/docs/appendix/canonabi-adhocabi-mismatch.md b/docs/appendix/canonabi-adhocabi-mismatch.md
@@ -1,4 +1,4 @@
-# Canonical ABI vs Miden ABI Incompatibility
+# Canonical ABI vs Miden ABI incompatibility
 
 This document describes an issue that arises when trying to map the ad-hoc calling convention/ABI
 used by various Miden Assembly procedures, such as those comprising the transaction kernel, and
@@ -140,7 +140,7 @@ library is a part of the Miden compiler. It is not anticipated that we will have
 these; however in the near term we are going to manually map procedures to their adapter strategies,
 as we have not yet automated the pattern recognition step.
 
-### Return-via-pointer Adapter
+### Return-via-pointer adapter
 
 The return value is expected to be returned by storing its flattened representation in a pointer
 passed as an argument.
@@ -174,7 +174,7 @@ func wasm_core_add_asset(v0: f64, v1: f64, v2: f64, v3: f64, ptr: i32) {
 }
 ```
 
-### No-op Adapter
+### No-op adapter
 
 No adapter is needed. The Wasm core function type is the same as the tx kernel ad-hoc signature.
 
@@ -183,7 +183,7 @@ This Miden ABI pattern is selected if no other Miden ABI pattern is applicable a
 For example, the `get_id` function falls under this Miden ABI pattern and its calls will be translated to the tx kernel function calls without any modifications.
 
 
-## Transaction kernel functions that require manual adapter functions:
+## Transaction kernel functions that require manual adapter functions
 
 ### `get_assets`
 

diff --git a/docs/appendix/known-limitations.md b/docs/appendix/known-limitations.md
@@ -1,4 +1,4 @@
-# Known Limitations
+# Known limitations
 
 !!! tip
 
@@ -13,9 +13,9 @@ important to be aware of this when using the compiler.
 The features discussed below are broken up into sections, to make them easier to navigate and
 reference.
 
-## Rust Language Support
+## Rust language support
 
-### Floating Point Types
+### Floating point types
 
 - Status: **Unsupported**
 - Tracking Issue: N/A
@@ -34,8 +34,7 @@ first place.
 At this point in time, we have no plans to support floats, but this may change if we are able to
 find a better/more natural representation for `Felt` in WebAssembly.
 
-
-### Function Call Indirection
+### Function call indirection
 
 - Status: **Unimplemented**
 - Tracking Issue: [#32](https://github.com/0xPolygonMiden/compiler/issues/32)
@@ -55,7 +54,7 @@ will raise an error when it encounters any use of `call_indirect`.
     the amount of inlining that can occur. Even then, it may not be possible to remove some forms of
     indirection, in which case you will need to find another workaround.
 
-#### Iterator Lowered to Loop
+#### Iterator lowered to loop
 
 ```rust
 pub fn is_zeroed(bytes: &[u8; 32]) -> bool {
@@ -64,7 +63,7 @@ pub fn is_zeroed(bytes: &[u8; 32]) -> bool {
 }
 ```
 
-#### Monomorphization + Inlining
+#### Monomorphization + inlining
 
 ```rust
 pub fn call<F, T>(fun: F) -> T
@@ -84,7 +83,7 @@ fn main() {
 }
 ```
 
-#### Inlined Trait Impl
+#### Inlined trait impl
 
 ```rust
 pub trait Foo {
@@ -124,7 +123,7 @@ will be expanding the SDK rapidly over the next few weeks and months, but for th
 you encounter a missing API that you need, let us know, so we can ensure it is prioritized above
 APIs which are lesser used.
 
-### Rust/Miden FFI (Foreign Function Interface) and Interop
+### Rust/Miden FFI (foreign function interface) and interop
 
 - Status: **Internal Use Only**
 - Tracking Issue: [#304](https://github.com/0xPolygonMiden/compiler/issues/304)
@@ -148,9 +147,9 @@ procedures at a minimum, and in some cases we may require details of the calling
 This metadata does not currently exist, but is on the roadmap for inclusion into Miden Assembly
 and Miden packaging. Once present, we can open up the FFI for general use.
 
-## Core Miden Functionality
+## Core Miden functionality
 
-### Dynamic Procedure Invocation
+### Dynamic procedure invocation
 
 - Status: **Unimplemented**
 - Tracking Issue: [#32](https://github.com/0xPolygonMiden/compiler/issues/32)
@@ -175,7 +174,7 @@ the body of which drop the callee hash, fix up the operand stack as necessary, a
 simple `exec` or `call` to invoke the "real" callee. We will emit a single stub for every function
 which has its "address" taken, and use the hash of the stub in place of the actual callee hash.
 
-### Cross-Context Procedure Invocation
+### Cross-context procedure invocation
 
 - Status: **Unimplemented**
 - Tracking Issue: [#303](https://github.com/0xPolygonMiden/compiler/issues/303)
@@ -213,7 +212,7 @@ subfeatures being implemented first.
 
 ## Packaging
 
-### Package Format
+### Package format
 
 - Status: **Experimental**
 - Tracking Issue: [#121](https://github.com/0xPolygonMiden/compiler/issues/121)

diff --git a/docs/design/frontends.md b/docs/design/frontends.md
@@ -1,4 +1,4 @@
-# Supported Frontends
+# Supported front ends
 
 ## WebAssembly (Wasm)
 

diff --git a/docs/design/overview.md b/docs/design/overview.md
@@ -1,4 +1,4 @@
-# Compiler Architecture
+# Compiler architecture
 
 This is an index of various design documents for the compiler and its components. Some of these
 are planned topics, and some have documentation that hasn't been polished up yet. We'll slowly

diff --git a/docs/guides/develop_miden_in_rust.md b/docs/guides/develop_miden_in_rust.md
@@ -1,10 +1,10 @@
-# Developing Miden Programs In Rust
+# Developing Miden programs in Rust
 
 This chapter will walk through how to develop Miden programs in Rust using the standard library
 provided by the `miden-stdlib-sys` crate (see the
-[README](https://github.com/0xPolygonMiden/compiler/sdk/stdlib-sys/README.md)).
+[README](https://github.com/0xPolygonMiden/compiler/blob/main/sdk/stdlib-sys/README.md).
 
-## Getting Started
+## Getting started
 
 Import the standard library from the `miden-stdlib-sys` crate:
 

diff --git a/docs/guides/develop_miden_rollup_accounts_and_note_scripts_in_rust.md b/docs/guides/develop_miden_rollup_accounts_and_note_scripts_in_rust.md
@@ -1,3 +1,3 @@
-# Developing Miden Rollup Accounts And Note Scripts In Rust
+# Developing Miden rollup accounts and note scripts in Rust
 
-This chapter will walk through how to develop Miden rollup accounts and note scripts in Rust using the Miden SDK crate.
+This chapter walks you through how to develop Miden rollup accounts and note scripts in Rust using the Miden SDK crate.
diff --git a/docs/guides/rust_to_wasm.md b/docs/guides/rust_to_wasm.md
@@ -168,7 +168,7 @@ Which dumps the following output (may differ slightly on your machine, depending
 
 Success!
 
-## Next Steps
+## Next steps
 
 In [Compiling WebAssembly to Miden Assembly](wasm_to_masm.md), we walk through how to take the
 WebAssembly module we just compiled, and lower it to Miden Assembly using `midenc`!
diff --git a/docs/guides/wasm_to_masm.md b/docs/guides/wasm_to_masm.md
@@ -122,7 +122,7 @@ We can test our compiled program like so:
 
 Success! We got the expected result of `55`.
 
-## Next Steps
+## Next steps
 
 This guide is not comprehensive, as we have not yet examined in detail the differences between
 compiling libraries vs programs, linking together multiple libraries, packages, or discussed some of

diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,6 @@
-# Getting Started
+# Getting started
 
-Welcome to the documentation for the Miden compiler toolchain!
+Welcome to the documentation for the Miden compiler toolchain.
 
 !!! warning
 
@@ -78,7 +78,7 @@ We do not currently perform any optimizations on the IR, since we are primarily
 output of compiler backends which have already applied optimizations, at this time. This may change
 in the future, but for now it is expected that you implement your own optimization passes as needed.
 
-## Known Bugs and Limitations
+## Known bugs and limitations
 
 For the latest information on known bugs, see the [issue tracker](https://github.com/0xpolygonmiden/compiler/issues).
 

diff --git a/docs/usage/cargo-miden.md b/docs/usage/cargo-miden.md
@@ -1,4 +1,4 @@
-# Getting Started with Cargo
+# Getting started with Cargo
 
 As part of the Miden compiler toolchain, we provide a Cargo extension, `cargo-miden`, which provides
 a template to spin up a new Miden project in Rust, and takes care of orchestrating `rustc` and

diff --git a/docs/usage/debugger.md b/docs/usage/debugger.md
@@ -1,4 +1,4 @@
-# Debugging Programs
+# Debugging programs
 
 A very useful tool in the Miden compiler suite, is its TUI-based interactive debugger, accessible
 via the `midenc debug` command.
@@ -8,7 +8,7 @@ via the `midenc debug` command.
     The debugger is still quite new, and while very useful already, still has a fair number of
     UX annoyances. Please report any bugs you encounter, and we'll try to get them patched ASAP!
 
-## Getting Started
+## Getting started
 
 The debugger is launched by executing `midenc debug`, and giving it a path to a program compiled
 by `midenc compile`. See [Program Inputs](#program-inputs) for information on how to provide inputs
@@ -26,7 +26,7 @@ midenc compile foo.wasm -o foo.masl
 midenc debug foo.masl
 ```
 
-## Program Inputs
+## Program inputs
 
 To pass arguments to the program on the operand stack, or via the advice provider, you have two
 options, depending on the needs of the program:
@@ -35,7 +35,7 @@ options, depending on the needs of the program:
    is, the first argument you specify will be on top of the stack, and so on.
 2. Specify a configuration file from which to load inputs for the program, via the `--inputs` option.
 
-### Via Command Line
+### Via command line
 
 To specify the contents of the operand stack, you can do so following the raw arguments separator `--`.
 Each operand must be a valid field element value, in either decimal or hexadecimal format. For example:
@@ -48,7 +48,7 @@ If you pass arguments via the command line in conjunction with `--inputs`, then
 will be used instead of the contents of the `inputs.stack` option (if set). This lets you specify a baseline
 set of inputs, and then try out different arguments using the command line.
 
-### Via Inputs Config
+### Via inputs config
 
 While simply passing operands to the `midenc debug` command is useful, it only allows you to specify
 inputs to be passed via operand stack. To provide inputs via the advice provider, you will need to use
@@ -103,7 +103,7 @@ one you get dropped into when the debugger starts. The home page contains the fo
 * Breakpoints - displays the set of current breakpoints, along with how many were hit
   at the current instruction, when relevant
 
-### Keyboard Shortcuts
+### Keyboard shortcuts
 
 On the home page, the following keyboard shortcuts are available:
 
@@ -177,7 +177,7 @@ After a breakpoint is hit, it expires if it is one of the following types:
 
 When a breakpoint expires, it is removed from the breakpoint list on the next cycle.
 
-## Reading Memory
+## Reading memory
 
 Another useful diagnostic task is examining the contents of linear memory, to verify that expected
 data has been written. You can do this via the command prompt, using `r` (or `read`), followed by

diff --git a/docs/usage/midenc.md b/docs/usage/midenc.md
@@ -1,4 +1,4 @@
-# Getting Started with `midenc`
+# Getting started with `midenc`
 
 The `midenc` executable is the command-line interface for the compiler driver, as well as other
 helpful tools, such as the interactive debugger.
@@ -110,7 +110,7 @@ than the default path that would have been used (`target/miden/foo.masp`).
 
 See [Debugging Programs](debugger.md) for details on using `midenc debug` to debug Miden programs.
 
-## Next Steps
+## Next steps
 
 We have put together two useful guides to walk through more detail on compiling Rust to WebAssembly: