Installation Guide

This document describes how to set up and use the Anvil compiler.

1. Setup Instructions

Install the prerequisite (opam) Install the OCaml package manager opam by following the official instructions: https://opam.ocaml.org/doc/Install.html

Clone the repository

git clone https://github.com/jasonyu1996/anvil.git

Navigate to the project directory
```
cd anvil
```
Install project dependencies only
```
opam install . --deps-only
```

At this point, all required dependencies are available. You can now proceed in one of two ways, depending on whether you want a local development build or a global installation.

Option 1: Local Build (for Development)

This option builds and runs the compiler without installing it globally.

Build the project
```
eval $(opam env)
dune build
```
Run the compiler locally
```
dune exec anvil -- <args>
```

This method is recommended for development and testing, as it avoids reinstalling the package after every change.

Option 2: Global Installation (as an opam Package)

This option installs Anvil into the current opam switch and makes the anvil binary available system-wide (within the switch).

Install the package
```
opam install .
```

This command pins the package to the current directory, builds it, and installs the anvil binary globally.

2. Compiler Usage

After installation, the compiler can be invoked as follows:

For local builds:

dune exec anvil -- [options] <file1> [<file2>] ...

For global installations:
```
anvil [options] <file1> [<file2>] ...
```

The input files must use the .anvil extension.

Following are the available command-line options:

-disable-lt-checks: Disable lifetime-related checks.
-O <opt-level>: Specify optimization level. (Currently : 0, 1, 2; Default : 2)
-verbose: Enable verbose output.
-o <output-file>: Specify output file name, generates <output-file>.anvil.sv emits to stdout if not provided.
-just-check: Only type-check the source file without generating code.
-json-output : Output compilation results in JSON format.
-strict-dtc: Enable strict data type checks (prevents abstract data types conversion).
-help: Display help information.

Note : The -O option currently supports optimization levels 0, 1, 2 for codegen optimizations. However 3 is used for optimizations that may results in not generating clk and reset signals in the output SystemVerilog code. Useful when generating code for combinational circuits such as ALUs. The compiler infers combinational circuits and warns the user if clk/reset are not generated when optimizations level 3 is used.

Example Usage

dune exec anvil -- -verbose -O 2 -o example_output example.anvil 

This command compiles example.anvil with:

verbose debug output enabled, and
optimisation level set to 2 (highest codegen optimization).
generates output file example_output.anvil.sv.

dune exec anvil -- -just-check example.anvil

This command type-checks example.anvil without generating code.