From 0cc9e6ba1de938ada0a35cffc9cccdb5dbdd2571 Mon Sep 17 00:00:00 2001 From: Ethan Uppal <113849268+ethanuppal@users.noreply.github.com> Date: Wed, 20 Nov 2024 20:06:55 -0500 Subject: [PATCH] Let's hope this fixes the images --- docs/compiler.md | 9 ++++++++- docs/dev/calyx-pass-explorer.md | 7 ++++--- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/compiler.md b/docs/compiler.md index 088646d417..64b35aaac8 100644 --- a/docs/compiler.md +++ b/docs/compiler.md @@ -33,6 +33,7 @@ For example, the alias `all` is an ordered sequence of default passes executed when the compiler is run from the command-line. The command-line provides two options to control the execution of passes: + - `-p, --pass`: Execute this pass or alias. Overrides default alias. - `-d, --disable-pass`: Disable this pass or alias. Takes priority over `-p`. @@ -43,6 +44,10 @@ the default execution alias `all`: cargo run -- examples/futil/simple.futil -p all -d static-timing ``` +If you want to work with passes interactively (for instance, you only care about +a pass far into the `all` sequence, and it is impractical to pass 20 `-p` +options), you can [visualize them](./dev/calyx-pass-explorer.md) with the `calyx-pass-explorer` tool. + ## Providing Pass Options Some passes take options to control their behavior. The `--list-passes` command prints out the options for each pass. For example, the `tdcc` pass has the following options: @@ -53,23 +58,25 @@ tdcc: ``` The option allows us to change the behavior of the pass. To provide a pass-specific option, we use the `-x` switch: + ``` cargo run -- examples/futil/simple.futil -p tdcc -x tdcc:dump-fsm ``` Note that we specify the option of `tdcc` by prefixing it with the pass name and a colon. - ## Specifying Primitives Library The compiler implementation uses a standard library of components to compile programs. The only standard library for the compiler is located in: + ``` /primitives ``` Specify the location of the library using the `-l` flag: + ``` cargo run -- -l ./primitives ``` diff --git a/docs/dev/calyx-pass-explorer.md b/docs/dev/calyx-pass-explorer.md index 8ff04e6016..a71112858f 100644 --- a/docs/dev/calyx-pass-explorer.md +++ b/docs/dev/calyx-pass-explorer.md @@ -9,6 +9,7 @@ is just to run it on code and see what happens. Enter [`calyx-pass-explorer`](https://github.com/calyxir/calyx/tree/main/tools/calyx-pass-explorer). It's a command line tool that provides an interactive interface for visualizing how different passes affect the source code. +It's been used to debug and develop new compiler passes as well as implement new features in the compiler, so I hope you can find it useful too! > ![Example running of the tool](https://raw.githubusercontent.com/calyxir/calyx/main/tools/calyx-pass-explorer/example_v0.0.0.png) > _The above image depicts the tool's interface in v0.0.0. @@ -67,11 +68,11 @@ tool to help develop it! We'll first run `calyx-pass-explorer example0.futil`. You should get something horrific like -![Lots of random text output that doesn't make sense](./assets/horrific-interface.png) +![Lots of random text output that doesn't make sense](assets/horrific-interface.png) > [!TIP] > If you get this message: -> ![Calyx executable could not be found](./assets/calyx-missing.png) +> ![Calyx executable could not be found](assets/calyx-missing.png) > You should setup `fud` or pass the path explicitly with `-e`, as suggested. > However, we're going to update this later to look at `fud2` as well because > `fud` is now officially deprecated. @@ -82,7 +83,7 @@ What we really want is to focus on what happens to, _e.g._, the `main` component To do that, we just pass `-c main` (or `--component main`) as a flag: ![Running the tool and visualizing how the well-formed pass affects the main -component](./assets/well-formed.png) +component](assets/well-formed.png) That's a lot better, but it's still quite a bit of information. Let's break it down.