Install and setup
Spinal is a Scala library (a programming language using the Java VM) so it requires setting up a Scala environment; there are many ways to do so. Also, it generates VHDL, Verilog or SystemVerilog, which can be used by many different tools. This section describes the supported way to install a SpinalHDL description to Simulation flow, but there can be many variations.
Before you download the SpinalHDL tools, you need to install a Scala environment:
These tools enable to use Spinal; but without any other tools, it is limited to HDL code generation.
To enable more features we recommend:
Code suggestions / completion
Automatic build with syntax errors right in the code
Generate code with a single click
Run simulation / tests with a single click (if a supported simulator is set up)
A supported simulator like Verilator to test the design right from SpinalHDL.
Gtkwave to view the waves generated by Verilator during simulation.
Git for version control system
A C++ toolchain, needed for simulating with Verilator
A linux shell, needed for simulating with Verilator
At time of writing the recommended way of installing Scala and SBT is via Coursier. Coursier is able to in addition to the scala tools install a Java JDK to use, in the example below we install Java from the package manager. We recommend to install JDK 17 (LTS) because of compatibility with the used Scala version.
For Debian or Ubuntu we run:
sudo apt-get update
sudo apt-get install openjdk-17-jdk-headless curl git
curl -fL "https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-linux.gz" | gzip -d > cs
chmod +x cs
# should find the just installed jdk, agree to cs' questions for adding to your PATH
If you want to install the tools for simulation and/or formal proofs, we recommend oss-cad-suite. It contains a waveform viewer (gtkWave), verilog simulators (verilator and iverilog), VHDL simulator (GHDL) and other tools. In case you want to build the tools yourself have a look at the legacy simulation tool installation instructions.
We first install the needed C++ toolchain and download oss-cad-suite. To use it we must load the oss-cad-suite environment for each shell we want to use it in. Note that oss-cad-suite contains a Python 3 interpreter that may interfere with the system Python installation if loaded permanently.
Go to the oss-cad-suite release page to get the download link for the latest version. You can download/extract oss-cad-suite to a folder of your choice. (last tested version of oss-cad-suite is 2023-10-22, but more recent ones will most likely also work)
sudo apt-get install make gcc g++ zlib1g-dev
curl -fLO <download link>
tar xzf <file that you downloaded>
To use oss-cad-suite in a shell you need to load it’s environment, e.g. via
souce <path to oss-cad-suite>/environment.
Mac OS X Installation
You can use homebrew to install on Mac OS X. By default homebrew installs Java 21, but the SpinalHDL tutorial SpinalTemplateSbt uses Scala version 2.12.16, which is not supported by Java 21 (17 is still the recommended LTS version, https://whichjdk.com/). So to install Java version 1.7 do:
brew install openjdk@17
And then add this to your path.
To manage multiple versions of Java it is also essential to have jenv installed.
brew install jenv
Jenv added these lines to my .bash_profile
eval "$(jenv init -)"
Next you have to install scala’s interactive build tool sbt.
brew install sbt
If this works for you, please let us know. If this does not work for you, you can read the github issue about Mac o SX installation here. https://github.com/SpinalHDL/SpinalHDL/issues/1216
If you want to install the tools for simulation and/or formal proofs, we recommend oss-cad-suite.
While a native installation is possible the simpler and currently recommended way is to use WSL on Windows.
If you want to use WSL, install it, a distribution of your choice and
follow the Linux installation instructions. Data in your WSL instance can be accessed from windows under
In case you want to use IntelliJ you’ll have to download the Linux version to WSL, if you want to use VSCode then the Windows
version can be used to remotely edit in WSL.
At time of writing the recommended way of installing Scala and SBT is via Coursier. Coursier is able to in addition to the scala tools install a Java JDK to use, in the example below we install Java manually. We recommend to install JDK 17 (LTS) because of compatibility with Scala.
This is sufficient for generating hardware. For simulation continue with either choice below. In case you want to build the tools yourself have a look at the legacy simulation tool installation instructions.
An All-in-One solution offered by SpinalHDL maintainer Readon <https://github.com/Readon> is available to install and run SpinalHDL with Verilator simulation and formal verification via SymbiYosys.
Download it and install the environment anywhere on your disk.
Start the build environment by clicking on the MSYS2-MINGW64 icon in the Start menu and use the MSYS2 default console.
An alternative is to use the Windows Terminal or a Tabby-like application and use the startup command
%MSYS2_ROOT%\msys2_shell.cmd -defterm -here -no-start -mingw64, where the
%MSYS2_ROOT% is the location of the msys2 installation.
It is worth noting that if you want to use it offline, you should carefully select the libraries that the project depends on, otherwise you will need to download the packages manually.
See the README for the repos for more details.
MSYS2 verilator for simulation
We recommend to install compiler/verilator through MSYS2 <https://www.msys2.org>. Other methods of installing gcc/make/shell (e.g. chocolatey, scoop, etc.) may also work but are untested.
SpinalHDL maintainer Readon <https://github.com/Readon> is maintaining a MSYS2 fork that default
installs all needed officially available and custom built packages (also maintained by Readon here <https://github.com/Readon/MINGW-SpinalHDL>)
for simulation and formal verification. It can be found here <https://github.com/Readon/msys2-installer>.
If used then the packages installed below via
pacman are already installed and those
installation steps can be skipped.
Currently verilator 4.228 is latest available version known to work.
Download the latest installer and install MSYS2 with default settings. You should get a MSYS2 terminal at the end of the installation, there run:
# will (request) close down terminal
# open 'MSYS2 MINGW64' from start menu
pacman -S --needed base-devel mingw-w64-x86_64-toolchain mingw-w64-x86_64-iverilog mingw-w64-x86_64-ghdl-llvm git
curl -O https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-verilator-4.228-1-any.pkg.tar.zst
pacman -U mingw-w64-x86_64-verilator-4.228-1-any.pkg.tar.zst
In a MSYS2 MINGW64 terminal we need to set some environment variables to make Java/sbt available (you can make these
settings persistent by adding them to
~/.bashrc in MSYS2):
export PATH=/c/Program\ Files/Eclipse\ Adoptium/jdk-22.214.171.124-hotspot/bin:$PATH
With this you should be able to run sbt/verilator simulations from MSYS2 terminals (sbt via calling
MSYS2 for formal verification
In addition to the steps above we also need to install yosys, sby, z3 and yices. Both yosys(yosys-smtbmc workable) and sby are not available as official MSYS2 packages, but packages are provided by Readon <https://github.com/Readon>. If you used their installer then these steps are not needed (you should check if there are newer packages available).
pacman -S mingw-w64-x86_64-z3 mingw-w64-x86_64-yices mingw-w64-x86_64-autotools mingw-w64-x86_64-python3-pip
python3 -m pip install click
curl -OL https://github.com/Readon/MINGW-SpinalHDL/releases/download/v0.4.9/mingw-w64-x86_64-yosys-0.31-1-any.pkg.tar.zst
curl -OL https://github.com/Readon/MINGW-SpinalHDL/releases/download/v0.4.9/mingw-w64-x86_64-python-sby-0.31-1-any.pkg.tar.zst
pacman -U *-yosys-*.pkg.tar.*
pacman -U *-python-sby-*.pkg.tar*
A container for SpinalHDL development is available as well.
The container is hosted at
ghcr.io/spinalhdl/docker:master and can be used with Docker/Podman/Github Codespaces.
It is used for the SpinalHDL CI regression and can therefore be an easy way to run the CI commands locally.
To run the container run e.g.
podman run -v .:/workspace -it ghcr.io/spinalhdl/docker:master in a SpinalHDL project
root directory, making the project directory available in
Please consult the documentation of you Distribution (Linux, WSL) or Docker (Windows) on how to install the container runtime you want to use. Multiple editors/IDEs (e.g. VSCode, IntelliJ, Neovide) allow for remote development in a container. Please consult the documentation of the editor on how to do remote development.
Installing SBT in an internet-free Linux environment
If you are not using an air-gapped environment we recommend to go with the normal linux installation. (which is a subset of the installation for an air-gapped environment)
Normally, SBT uses online repositories to download and cache your projects dependencies. This cache is located in several folders:
To set up an internet-free environment, you can:
Create a first SpinalHDL project
We have prepared a ready-to-go project for you the: getting started repository.
You can download it, or clone it.
The following commands clone the project into a new directory named
MySpinalProject and initialize a fresh
git clone --depth 1 https://github.com/SpinalHDL/SpinalTemplateSbt.git MySpinalProject
rm -rf .git
git add .
git commit -m "Initial commit from template"
The directory structure of a project
The structure described here is the default structure, but it can be easily modified.
In the root of the project are the following files:
Scala configuration for
Scala configuration for
The folder containing hardware descriptions
More Scala configuration
List of files to ignore in versioning
More configuration for
Configuration of rules to auto-format the code
As you probably guessed it, the interesting thing here is
hw/. It contains
vhdl/ for your IPs and
for IPs generated with Spinal.
hw/spinal/ contains a folder named after your project name. This name must
be set in
build.sbt (along with the company name) and in
it must be the one in
package yourprojectname at the beginning of
hw/spinal/yourprojectname/, are the descriptions of your IPs, simulation
tests, formal tests; and there is
Config.scala, which contains the
sbt must be used only at the root of the project, in the folder
Using Spinal on SpinalHDL code
Now the tutorial shows how to use Spinal on SpinalHDL code depending on your development environment: