Installation Guide

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

1. Setup Instructions

Install opam, the OCaml package manager, by following the official installation instructions.

Clone the repository

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

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

With the required dependencies installed, choose either 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 avoids reinstalling the package after every change, making it the recommended option for development and testing.

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.

The compiler accepts the following 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>: Write the output to <output-file>.anvil.sv. If this option is omitted, emit the output to standard output.
-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 (the highest codegen optimization). It generates the output file example_output.anvil.sv.

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

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