docs: add guides for compiling rust->masm

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ on:
     - '*.md'
 
 env:
-  CARGO_MAKE_TOOLCHAIN: nightly-2023-08-23
+  CARGO_MAKE_TOOLCHAIN: nightly-2023-12-20
 
 jobs:
   compiler:

Cargo.toml

@@ -24,9 +24,9 @@ version = "0.1.0"
 rust-version = "1.71"
 authors = ["Miden Team"]
 description = "An intermediate representation and compiler for Miden Assembly"
-repository = "https://github.com/0xPolygonMiden/miden-ir"
-homepage = "https://github.com/0xPolygonMiden/miden-ir"
-documentation = "https://github.com/0xPolygonMiden/miden-ir"
+repository = "https://github.com/0xPolygonMiden/compiler"
+homepage = "https://github.com/0xPolygonMiden/compiler"
+documentation = "https://github.com/0xPolygonMiden/compiler"
 categories = ["Compilers"]
 keywords = ["compiler", "miden"]
 license = "MIT"

Makefile.toml

@@ -12,8 +12,6 @@ CARGO_MAKE_RUST_SCRIPT_PROVIDER = "rust-script"
 CARGO_MAKE_USE_WORKSPACE_PROFILE = true
 CARGO_MAKE_CARGO_BUILD_TEST_FLAGS = "--no-fail-fast"
 CARGO_TARGET_DIR = { value = "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/target", condition = { env_not_set = ["CARGO_TARGET_DIR"] } }
-CARGO_MAKE_TOOLCHAIN_DEFAULT = { source = "${CARGO_MAKE_CI}", default_value = "nightly", mapping = { "true" = "nightly-2023-02-24", "false" = "nightly" } }
-CARGO_MAKE_TOOLCHAIN = { value = "${CARGO_MAKE_TOOLCHAIN_DEFAULT}", condition = { env_not_set = ["CARGO_MAKE_TOOLCHAIN"] } }
 BACKTRACE_DEFAULT = { source = "${CARGO_MAKE_CI}", mapping = { "true" = "1", "false" = "0" } }
 RUST_BACKTRACE = { value = "${BACKTRACE_DEFAULT}", condition = { env_not_set = ["RUST_BACKTRACE"] } }
 MIDEN_BIN_DIR = "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/bin"
@@ -78,7 +76,6 @@ echo "*************************************"
 echo "Rust:"
 echo "    Version: ${CARGO_MAKE_RUST_VERSION}"
 echo "    Channel: ${CARGO_MAKE_RUST_CHANNEL}"
-echo "    Toolchain: ${CARGO_MAKE_TOOLCHAIN}"
 echo "    Target Arch: ${CARGO_MAKE_RUST_TARGET_ARCH}"
 echo "    Target Env: ${CARGO_MAKE_RUST_TARGET_ENV}"
 echo "    Target OS: ${CARGO_MAKE_RUST_TARGET_OS}"
@@ -136,8 +133,8 @@ args = ["bloat", "${@}"]
 [tasks.midenc]
 category = "Build"
 description = "Builds midenc and installs it to the bin folder"
-command = "rustup"
-args = ["run", "${CARGO_MAKE_TOOLCHAIN}", "cargo", "-Z", "unstable-options", "build", "-p", "midenc", "--out-dir", "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/bin"]
+command = "cargo"
+args = ["-Z", "unstable-options", "build", "-p", "midenc", "--out-dir", "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/bin"]
 
 [tasks.build]
 category = "Build"
@@ -146,40 +143,53 @@ run_task = [
   { name = ["midenc", "build-filecheck"] },
 ]
 
+[tasks.install]
+category = "Install"
+description = "Installs the compiler suite via cargo"
+run_task = [
+  { name = ["install-midenc"] },
+]
+
 [tasks.check]
 category = "Build"
 description = "Runs cargo check on the workspace"
-command = "rustup"
-args = ["run", "${CARGO_MAKE_TOOLCHAIN}", "cargo", "check", "${@}"]
+command = "cargo"
+args = ["check", "${@}"]
 
 [tasks.clean]
 category = "Build"
 description = "Clean build artifacts"
-command = "rustup"
-args = ["run", "${CARGO_MAKE_TOOLCHAIN}", "cargo", "clean", "${@}"]
+command = "cargo"
+args = ["clean", "${@}"]
 
 [tasks.test]
 category = "Test"
 description = "Runs all tests"
 dependencies = ["test-rust", "test-filecheck"]
 
+[tasks.install-midenc]
+category = "Install"
+description = "Builds midenc and installs it globally via the cargo bin directory"
+command = "cargo"
+args = ["cargo", "install", "--path", "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/midenc", "midenc"]
+
 [tasks.install-wasm-target]
 category = "Test"
 description = "Install wasm32-unknown-unknown target"
 command = "rustup"
-args = ["target", "add", "wasm32-unknown-unknown", "--toolchain", "${CARGO_MAKE_TOOLCHAIN}"]
+args = ["target", "add", "wasm32-unknown-unknown"]
 
 [tasks.install-wasm-wasi-target]
 category = "Test"
 description = "Install wasm32-wasi target"
 command = "rustup"
-args = ["target", "add", "wasm32-wasi", "--toolchain", "${CARGO_MAKE_TOOLCHAIN}"]
+args = ["target", "add", "wasm32-wasi"]
 
 [tasks.install-rust-src]
 category = "Test"
 description = "Install rust-src component"
 command = "rustup"
-args = ["component", "add", "rust-src", "--toolchain", "${CARGO_MAKE_TOOLCHAIN}"]
+args = ["component", "add", "rust-src"]
 
 [tasks.install-cargo-component]
 category = "Test"
@@ -190,8 +200,8 @@ args = ["install", "cargo-component"]
 [tasks.test-rust]
 category = "Test"
 description = "Runs tests written in Rust"
-command = "rustup"
-args = ["run", "${CARGO_MAKE_TOOLCHAIN}", "cargo", "test", "@@remove-empty(CARGO_MAKE_CARGO_VERBOSE_FLAGS)", "@@split(CARGO_MAKE_CARGO_BUILD_TEST_FLAGS, )", "${@}"]
+command = "cargo"
+args = ["test", "@@remove-empty(CARGO_MAKE_CARGO_VERBOSE_FLAGS)", "@@split(CARGO_MAKE_CARGO_BUILD_TEST_FLAGS, )", "${@}"]
 dependencies = ["install-wasm-target", "install-wasm-wasi-target", "install-rust-src", "install-cargo-component"]
 
 [tasks.test-filecheck]
@@ -215,8 +225,8 @@ dependencies = [
 [tasks.build-filecheck]
 category = "Build"
 description = "Builds the filecheck helper"
-command = "rustup"
-args = ["run", "${CARGO_MAKE_TOOLCHAIN}", "cargo", "-Z", "unstable-options", "build", "-p", "filecheck", "--release", "--out-dir", "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/bin"]
+command = "cargo"
+args = ["-Z", "unstable-options", "build", "-p", "filecheck", "--release", "--out-dir", "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/bin"]
 
 [tasks.book]
 category = "Build"

README.md

@@ -34,38 +34,6 @@ To build just the compiler:
 
     $ cargo make midenc
 
-This will build the compiler frontend and place it under the `bin` folder in the project root.
-
-    $ bin/midenc help compile
-    Usage: midenc compile [OPTIONS] [-- <INPUTS>...]
-
-    Arguments:
-      [INPUTS]...
-              Path(s) to the source file(s) to compile.
-
-              You may also use `-` as a file name to read a file from stdin.
-
-    Options:
-          --output-dir <DIR>
-              Write all compiler artifacts to DIR
-
-      -W <LEVEL>
-              Modify how warnings are treated by the compiler
-
-              [default: auto]
-
-              Possible values:
-              - none:  Disable all warnings
-              - auto:  Enable all warnings
-              - error: Promotes warnings to errors
-
-      -v, --verbose
-              When set, produces more verbose output during compilation
-
-      -h, --help
-              Print help (see a summary with '-h')
-
-
 ## Testing
 
 To run the compiler test suite:

codegen/masm/src/emulator/breakpoints.rs

@@ -304,6 +304,7 @@ impl BreakpointManager {
     }
 
     #[inline]
+    #[allow(unused)]
     pub fn should_break_on_write(&self, addr: Addr, size: u32) -> bool {
         self.matches_watchpoint(addr, size).is_some()
     }

docs/src/SUMMARY.md

@@ -1,4 +1,37 @@
-# Getting Started
+# Reference
 
-- [Design](./design/main.md)
-    - [Calling Conventions](./design/calling_conventions.md)
+[Getting Started](getting_started.md)
+
+---
+
+# Usage
+
+- [As an Executable](usage/midenc.md)
+- [As a Library]()
+- [As a Cargo extension]()
+
+# Guides
+
+- [Rust To WebAssembly](guides/rust_to_wasm.md)
+- [WebAssembly To Miden Assembly](guides/wasm_to_masm.md)
+
+# Usage
+
+- [midenc]()
+  - [compile]()
+  - [exec]()
+  - [run]()
+
+- [cargo miden]()
+
+# Architecture
+
+- [Overview](design/overview.md)
+- [Frontends]()
+- [HIR]()
+- [Code Generation]()
+- [Testing]()
+
+---
+
+[Calling Conventions](appendix/calling_conventions.md)

docs/src/design/overview.md

@@ -0,0 +1,4 @@
+# Compiler Architecture
+
+TODO
+

docs/src/getting_started.md

@@ -0,0 +1,22 @@
+# Getting Started
+
+This book attempts to provide a thorough reference for compiling to Miden Assembly 
+using one or more components of the Miden compiler suite. Which components you use, 
+and how you use them is likely to differ depending on the project, but we've tried
+to provide good coverage regardless. 
+
+There are a set of guides which are focused on documenting the workflows for specific 
+use cases that we wish to ensure are well supported, or have encountered so far, but
+if you feel there is anything missing, feel free to open an issue and we will try to
+address the missing docs as soon as possible!
+
+## Installation
+
+There are three ways you might use the Miden compiler:
+
+
+1. As an executable (via `midenc`)
+2. As a library (most likely via the `midenc-compile` and `miden-hir` crates) 
+3. As a Cargo extension (via `cargo miden`)
+
+Each of these is described in the following chapters, we hope you find this book useful!