Install and setup

Spinal is a Scala library 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.

Mandatory requirements

Before you download the SpinalHDL tools, you need to install a Scala environment:

Java JDK, a Java environment
SBT, a Scala build tool

These tools enable to use Spinal; but without any other tools, it is limited to code generation.

Linux Installation

For instance, to install them on the Debian distribution:

sudo apt-get install openjdk-8-jdk
sudo apt-get install scala
echo "deb https://repo.scala-sbt.org/scalasbt/debian all main" | sudo tee /etc/apt/sources.list.d/sbt.list
echo "deb https://repo.scala-sbt.org/scalasbt/debian /" | sudo tee /etc/apt/sources.list.d/sbt_old.list
curl -sL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x2EE0EA64E40A89B84B2DF73499E82A75642AC823" | sudo apt-key add
sudo apt-get update
sudo apt-get install sbt

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.

export PATH="/opt/homebrew/opt/openjdk@17/bin:$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

export PATH="$HOME/.jenv/bin:$PATH"
eval "$(jenv init -)"

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

Installing SBT in an internet-free environment

Note

If you do not need this, you can skip to the next section: Recommended requirements.

Normally, SBT uses online repositories to download and cache your projects dependencies. This cache is located in several folders:

~/.sbt
~/.cache/JNA
~/.cache/coursier

To set up an internet-free environment, you can:

Set up an environment with internet
Launch a Spinal command (see Using Spinal from CLI with SBT) to fetch dependencies (for instance using the getting started repository)
Copy the caches to the internet-free environment.

Note

You can get a portable SBT setup here: https://www.scala-sbt.org/download.html

Note

Recommended requirements

To enable more features:

An IDE (for instance IntelliJ with its Scala plugin or VSCodium with Metals extension) to get features such as:
- 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

Create a 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 history:

git clone --depth 1 https://github.com/SpinalHDL/SpinalTemplateSbt.git MySpinalProject
cd MySpinalProject
rm -rf .git
git init
git add .
git commit -m "Initial commit from template"

The directory structure of a project

Note

The structure described here is the default structure, but it can be easily modified.

In the root of the project are the following files:

File	Description
`build.sbt`	Scala configuration for `sbt`
`build.sc`	Scala configuration for `mill`, an alternative to `sbt`
`hw/`	The folder containing hardware descriptions
`project/`	More Scala configuration
`README.md`	A `text/markdown` file describing your project
`.gitignore`	List of files to ignore in versioning
`.mill-version`	More configuration for `mill`
`.scalafmt.conf`	Configuration of rules to auto-format the code

As you probably guessed it, the interesting thing here is hw/. It contains four folders: spinal/, verilog/ and vhdl/ for your IPs and gen/ 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 build.sc; and it must be the one in package yourprojectname at the beginning of .scala files.

In hw/spinal/yourprojectname/, are the descriptions of your IPs, simulation tests, formal tests; and there is Config.scala, which contains the configuration of Spinal.

Note

sbt must be used only at the root of the project, in the folder containing build.sbt.

Using Spinal on SpinalHDL code

Now the tutorial shows how to use Spinal on SpinalHDL code depending on your development environment: