Docs - Rough documentation on invoking minicargo/mrustc

2 files changed, 115 insertions, 2 deletions

diff --git a/docs/running.md b/docs/running.md
new file mode 100644
index 00000000..d665a8bd
--- /dev/null
+++ b/docs/running.md
@@ -0,0 +1,113 @@
+
+Running mrustc/minicargo
+========================
+
+The easisest way to compile code with mrustc is to use `minicargo` to build a project using a Cargo.toml file, but if
+you need extra control over the output, `mrustc` can be called directly.
+
+minicargo
+=========
+
+```
+minicargo mycrate/ -L ../libstd_crates --vendor-dir vendored/
+```
+
+The above builds the crate specified by `mycrate/Cargo.toml`, looking for compiled versions of the standard library crates in `../libstd_crates` and pre-downloaded crates.io packages in `vendored/`. The compiled crates (both `mycrate` and any of its dependencies) will be placed in the default location ( `output/`)
+
+Options
+-------
+
+- `--help, -h`
+  - Show basic help
+- `--script-overrides <dir>`
+  - Folder containing `<cratename>.txt` files that are used as if they were the output from that crate's build script (used for building libstd)
+- `--vendor-dir <dir>`
+  - Directory containing extracted crates.io packages required to build the current crate (see [https://crates.io/crates/cargo-vendor](cargo-vendor))
+- `--output-dir,-o <dir>`
+  - Specifies the output directory, used for both dependencies and the final binary.
+- `--target <name>`
+  - Cross-compile for the specified target
+- `-L <dir>`
+  - Add a directory to the crate/library search path
+- `-j <num>`
+  - Run a specified number of build jobs at once
+- `-n`
+  - Do a dry run (print the crates to be compiled, but don't build any of them)
+- `-Z <option>`
+  - Debugging/experiemental options (see below)
+
+Debugging options
+- `-Z emit-mmir`
+  - Use the `mmir` mrustc backend (for use with the "Stanalone MIRI" tool)
+
+
+mrustc
+======
+`mrustc`'s command-line interface is very similar to rustc's, taking a path to the crate root, an output directory/file, and optional library search paths and crate paths.
+
+```
+mrustc mycrate/main.rs -L ../libstd_crates --crate mylib=mylib.hir -o mycrate.exe
+```
+
+The above builds the binary crate rooted at `mycrate/main.rs` and outputs it to `mycrate.exe`. It looks for external
+crates in `../libstd_crates`, but also is told that `extern crate mylib;` should load `mylib.hir`.
+
+Options
+-------
+
+- `-L <dir>`
+  - Search for crate files (`.hir` files) in this directory
+- `-o <filename>`
+  - Write compiler output (library or executable) to this file
+- `-O`
+  - Enable optimistion
+- `-g`
+  - Emit debugging information
+- `--out-dir <dir>`
+  - Specify the output directory (alternative to `-o`)
+- `--extern <crate>=<path>`
+  - Specify the path for a given crate (instead of searching for it)
+- `--crate-tag <str>`
+  - Specify a suffix for symbols and output files
+- `--crate-name <str>`
+  - Override/set the crate name
+- `--crate-type <ty>`
+  - Override/set the crate type (rlib, bin, proc-macro)
+- `--cfg flag`
+  - Set a boolean `#[cfg]`/`cfg!` flag
+- `--cfg flag=\"val\"`
+  - Set a string `#[cfg]`/`cfg!` flag (Note: This can be repeated with the same name, adding extra options each time. You may need to escape the quotes in your shell
+- `--target <name>`
+  - Compile code for the given target (if the name has a slash in it, it's treated as the path to a target file)
+- `--test`
+  - Generate a unit test executable
+- `-C <option>`
+  - Code-generation options (see below)
+- `-Z <option>`
+  - Debugging/experiemental options (see below)
+
+Codegen options
+- `-C emit-build-command=<filename>`
+  - Write the command that would be used to invoke the C compiler to the specified file
+- `-C codegen-type=<type>`
+  - Switch codegen backends. Valid options are: `c` (The normal C backend), `mmir` (Monomorphised MIR, used for `standalone_miri`)
+- `-C emit-depfile=<filename>`
+  - Write out a makefile-style dependency file for the crate
+
+Debugging Options
+- `-Z disable-mir-opt`
+  - Disable MIR optimisations (while still enabling optimisation in the backend)
+- `-Z full-validate`
+  - Perform expensive MIR validation before translation (can spot codegen bugs, but is VERY slow)
+- `-Z full-validate-early`
+  - Perform expensive MIR validation before optimisation (even slower)
+- `-Z dump-ast`
+  - Dump the AST after expansion and name resolution complete
+- `-Z dump-hir`
+  - Dump the HIR (simplified and resolved AST) at various stages in compilation
+- `-Z dump-mir`
+  - Dump the MIR for all functions at various stages in compilation
+- `-Z stop-after=<stage>`
+  - Stop compilation after the specified stage. Valid options are `parse`, `expand`, `resolve`, `typeck`, and `mir`
+
+
diff --git a/docs/target.md b/docs/target.md
index 6b5b088d..4b6b5920 100644
--- a/docs/target.md
+++ b/docs/target.md
@@ -6,7 +6,7 @@ Mrustc supports a few targets out of the box (of varying levels of usablity), th
 `src/trans/target.cpp`. If the built-in targets aren't suitable, a custom target can be specified with the help of a
 custom target toml file.
 
-To specify a target when running `mrustc` (or `minicaro`), pass `--target <triple>` or `--target
+To specify a target when running `mrustc` (or `minicargo`), pass `--target <triple>` or `--target
 ./path/to/target.toml` (the presence of a slash, backwards or forwards, is what determines if the target is treated as
 a custom target file.
 
@@ -27,7 +27,7 @@ variant = "gnu"
 target = "arm-linux-gnu"
 ```
 
-Recreation of the `i586-windows-gnu` target (with architecture)
+Recreation of the `i586-windows-gnu` target (with architecture definition)
 ```toml
 [target]
 family = "windows"