Clash - A functional hardware description language

Clash is a functional hardware description language that borrows both its syntax and semantics from the functional programming language Haskell. The Clash compiler transforms these high-level descriptions to low-level synthesizable VHDL, Verilog, or SystemVerilog.

Features of Clash:

• Strongly typed, but with a very high degree of type inference, enabling both safe and fast prototyping using concise descriptions.

• Interactive REPL: load your designs in an interpreter and easily test all your component without needing to setup a test bench.

• Higher-order functions, with type inference, result in designs that are fully parametric by default.

• Synchronous sequential circuit design based on streams of values, called Signals, lead to natural descriptions of feedback loops.

• Support for multiple clock domains, with type safe clock domain crossing.

Community

Mailing list: for updates and questions join the mailing list [email protected] or read the forum

Slack: functionalprogramming.slack.com#clash (Invite yourself at fpslack.com/).

IRC: libera.chat#clash (webchat access) (or ircs://irc.libera.chat:6697/clash if you want to use a regular IRC client)

Get Clash

Check out clash-lang.org/install to install the latest stable release of Clash, or to setup a Clash project.

Get Clash from source

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

git clone [email protected]: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.

GHC compatibility

¹ GHC 9.2 contains a regression, rendering Clash error messages indecipherable. This change was reverted in 9.4.

² GHC 9.0.2 on Windows fails to compile clash-cores. We therefore don't run the Clash testsuite on CI for this combination.

³ We use Stack to test on Windows/macOS. There is no resolver yet that uses GHC 9.6, so this remains untested.

Cabal

To use Cabal you need both Cabal and GHC installed on your system. We recommend using ghcup. For more information, see https://www.haskell.org/downloads/.

To run clash use:

cabal v2-run -- 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:

# Start the default dev shell
nix develop .

# Start a dev shell with a specific GHC version
nix develop .#ghc961

You will need a modern version of nix with support for the new-style nix command and flakes (2.4 or newer). Support for these must still be manually enabled, this can be done by setting

experimental-features = nix-command flakes

in your nix.conf.

To automatically enter and exit the nix environment on directory change, you can install direnv and nix-direnv and write the following to a .envrc file in the root of this repository:

use flake

watch_file nix/*

Upon adding or changing this file you must direnv allow in order for the file to be automatically loaded / reloaded on project changes.

Individual packages / applications can also be built or run using the nix build and nix run commands, i.e.

nix build .#clash-ghc
nix run .#clashi

Related libraries and initiatives

• Clashilator: tooling to integrate Clash with Verilator. Enables fast, multithreaded simulation by compiling Clash designs to C++.
• Clash Protocols: experimental library for writing Clash circuits with bidirectional communication - such as AXI or Avalon.
• Clash Starters: starter projects to quickly get you up and running.
• Clash WaveDrom: generate wave diagrams from Clash using WaveDrom

Projects built with Clash

• Contranomy: a RISCV implementation verified using the RISC-V Formal Verification Framework.
• Space Invaders: a Clash implementation of the 1978 Space Invaders arcade machine by Taito.