Hacking on the Clash Compiler

Prerequisites

Hacking on Clash requires more dependencies than simply running Clash. The test suite requires having a tool available to synthesize any backend being tested. This means you need:

ghdl installed to test VHDL
iverilog installed to test Verilog
ModelSim installed to test SystemVerilog
SymbiYosys and Z3 installed to test Verilog and SystemVerilog

Get Clash from source

Get the source code using Git and enter the cloned directory:

git clone git@github.com:clash-lang/clash-compiler.git

# Alternatively, if you haven't setup SSH keys with GitHub:
# git clone https://github.com/clash-lang/clash-compiler.git

cd clash-compiler

To check out a released version, use:

git checkout v1.2.3

To checkout a release branch use:

git checkout 1.2

Note that release branches might contain non-released patches.

Cabal

To use Cabal you need both Cabal and GHC installed on your system. For Linux and MacOS users we recommend using ghcup. Windows users are recommended to use the Haskell Platform.

To run clash use:

cabal v2-run --write-ghc-environment-files=always -- clash

If this fails, make sure you've got an up-to-date package index:

cabal update

Stack

Install Stack and run:

stack run -- clash

Nix

Or use Nix to get a shell with the clash and clashi binaries on your PATH:

nix-shell

Subprojects

The Clash compiler consists of different cabal libraries, which together provide a complete compiler. Primarily, this consists of

clash-ghc

The frontend of the compiler, using parts of the GHC frontend. This provides the ability to load modules, translate GHC Core to Clash Core, and implements the clash and clashi executables.

A lot of the code in this library is separated by the version of GHC it works with. For example, src-bin-9.0 is specific to GHC 9.0.x.

clash-lib

The backend of the compiler, exposed as a library. This is the largest library in the project, and includes the various ASTs (e.g. Core, Netlist), normalization, code generation, and primitives / black boxes.

clash-prelude

The standard library for Clash as a language. This includes anything that is used to develop hardware in Clash, such as Signals, Clocks and combinators for common forms of state machine.

The clash-prelude library also re-exports parts of the Haskell base library, allowing circuit designs to reuse common functions and definitions.

The repository also contains other libraries. These either provide additional functionality which is not required, or are not yet production-ready. These are

clash-cosim

Co-simulation for Clash, allowing Verilog to be run inline as though it were a normal Haskell function. This provides a QuasiQuoter for use in Haskell.

Warning

This library is very experimental, and is not guaranteed to work with the most recent development version of Clash.

clash-term

A development tool for analyzing how the normalizer in clash-lib affects the core of a particular design. It allows the result of each different optimizer pass to be seen for debugging purposes.

clash-lib-hedgehog

Hedgehog Generators for clash-lib.

clash-prelude-hedgehog

Hedgehog Generators for clash-prelude.

Keyboard shortcuts