安装和设置

Spinal是一个Scala库（使用Java VM的编程语言），因此需要设置Scala环境；有很多方法可以做到这一点。此外，它还生成 VHDL、Verilog 或 SystemVerilog，可供许多不同的工具使用。本节介绍支持的 SpinalHDL 描述到仿真 流程的安装方法，但可能还有其他方法。

必需/推荐的工具

在下载 SpinalHDL 工具之前，您需要安装 Scala 环境：

Java JDK，Java 环境
Scala 2，编译器和库
SBT ，Scala 程序构建工具

这些工具可以支持使用 Spinal生成代码；但在没有任何其他工具的情况下，它仅限于HDL代码生成。

要启用更多功能，我们建议：

一个 IDE（例如当前推荐的带有 Scala 插件的 IntelliJ 或带有 Metals 扩展的 VSCodium ）可获得如下功能：
- 代码建议/自动完成
- 自动构建，在代码中显示存在语法错误
- 通过单击生成代码
- 单击即可运行仿真/测试（如果设置了支持的仿真器）
支持的仿真器，例如 Verilator ，可以直接从 SpinalHDL 测试设计。
Gtkwave 查看 Verilator 在仿真过程中生成的波形。
Git 版本控制系统
用 Verilator 进行仿真所需的 C++ 工具链
一个 linux shell，需要使用 Verilator 进行仿真

Linux安装

在撰写本文时，推荐的 Scala 和 SBT 安装方法是通过 Coursier。除了 scala 工具之外，Coursier 还能够安装 Java JDK ，在下面的示例中，我们通过包管理器安装 Java。出于 Scala 版本兼容的考量，我们建议安装 JDK 17 (LTS)。

对于 Debian 或 Ubuntu，运行：

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
./cs setup
source ~/.profile

如果您想安装用于仿真和/或形式化证明的工具，我们推荐 oss-cad-suite。它包含波形查看器（gtkWave）、verilog仿真器（verilator和iverilog）、VHDL仿真器（GHDL）以及一些其他工具。如果您想自己构建工具，请查看旧版仿真工具安装说明。

首先，我们安装所需的C++工具链并下载oss-cad-suite。要使用它，我们必须为每个我们想要使用它的shell加载oss-cad-suite环境。请注意，oss-cad-suite包含一个可能会干扰系统Python安装的Python 3解释器，如果永久加载（loaded permanently）它。

前往 oss-cad-suite 发布页面获取最新版本的下载链接。您可以将 oss-cad-suite 下载/解压到您选择的文件夹中。（oss-cad-suite 的最后测试版本是 2023-10-22，但最新的版本可能也可以工作）

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 source <path to oss-cad-suite>/environment.

Mac OS X 安装

Mac OS X 上可以使用 homebrew 安装。默认情况下 homebrew 安装 Java 21，但 SpinalHDL 教程 SpinalTemplateSbt 使用 Scala 版本 2.12.16，Java 21 不支持该版本（17 仍然是推荐的 LTS 版本，https://whichjdk.com/）。因此，要安装 Java 1.7 版本，请执行以下操作：

brew install openjdk@17

然后，将其添加到您的路径（path）中。

export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"

要管理 Java 的多个版本，还必须安装 jenv。

brew install jenv

Jenv 将这些行添加到 .bash_profile 中

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

接下来你必须安装scala的交互式构建工具sbt。

brew install sbt

如果这对您有用，请告诉我们。如果这对您不起作用，您可以在此处阅读有关 Mac o SX 安装的 github 问题。 https://github.com/SpinalHDL/SpinalHDL/issues/1216

如果您想安装用于仿真和/或形式化证明的工具，我们推荐 oss-cad-suite。

Windows安装

备注

虽然可以进行本机安装，但更简单且目前推荐的方法是在 Windows 上使用 WSL。如果您想使用 WSL，请安装您选择的发行版，并按照 Linux 安装说明进行操作。WSL 实例中的数据可以从Windows访问，在 \\wsl$ 路径下。如果您想使用 IntelliJ，则必须将 Linux 版本下载到 WSL，如果您想使用 VSCode，则可以使用 Windows 版本远程编辑WSL中的数据。

在撰写本文时，推荐的安装 Scala 和 SBT 方法是通过 Coursier。除了 scala 工具之外，Coursier 还能够安装 Java JDK 来使用，在下面的示例中我们手动安装 Java。由于 Scala 兼容性原因，我们建议安装 JDK 17 (LTS)。

首先，下载并安装 Adoptium JDK 17。下载、解压并运行 Coursier 安装程序，当询问是否更新您的 PATH 变量时，选择同意。重新启动以强制更新 PATH。

这足以生成硬件。对于仿真，请继续选择以下任一选项。如果您想自己构建仿真工具，请查看旧版仿真工具安装说明。

备注

An All-in-One solution offered by SpinalHDL maintainer 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工具

We recommend to install compiler/verilator through MSYS2. Other methods of installing gcc/make/shell (e.g. chocolatey, scoop, etc.) may also work but are untested.

SpinalHDL maintainer Readon is maintaining a MSYS2 fork that default installs all needed officially available and custom built packages (also maintained by Readon here) for simulation and formal verification. It can be found here. If used then the packages installed below via pacman are already installed and those installation steps can be skipped.

目前 verilator 4.228 是已知可以工作的最新版本。

下载最新的安装程序并使用默认设置安装 MSYS2。安装结束后你应该会得到一个 MSYS2 终端，运行：

pacman -Syuu
# will (request) close down terminal
# open 'MSYS2 MINGW64' from start menu
pacman -Syuu
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

在 MSYS2 MINGW64 终端中，我们需要设置一些环境变量以使 Java/sbt 可用（您可以通过将它们添加到 MSYS2 中的 ~/.bashrc 来长期保存这些设置）：

export VERILATOR_ROOT=/mingw64/share/verilator/
export PATH=/c/Program\ Files/Eclipse\ Adoptium/jdk-17.0.8.101-hotspot/bin:$PATH
export PATH=/c/Users/User/AppData/Local/Coursier/data/bin:$PATH

有了这个，您应该能够从 MSYS2 终端运行 sbt/verilator 仿真（通过调用 sbt.bat 使用）。

用 MSYS2 实施形式化验证

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. 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*

OCI容器

也可以使用 SpinalHDL 开发容器。该容器托管在 ghcr.io/spinalhdl/docker:master ，可以与 Docker/Podman/Github Codespaces 一起使用。它用于 SpinalHDL CI 测试，因此，也可以成为本地运行的简单方法。

要使用容器，请运行例如SpinalHDL 项目根目录中的 podman run -v .:/workspace -it ghcr.io/spinalhdl/docker:master ，使项目目录在 /workspace 中可用。

请查阅您的发行版（Linux、WSL）或 Docker (Windows) 的文档，了解如何安装您想要使用容器的运行时依赖。多个编辑器/IDE（例如 VSCode、IntelliJ、Neovide）允许对容器进行远程开发。如何进行远程开发请查阅相应编辑器的文档。

在无网络的 Linux 环境中安装 SBT

备注

如果您不使用无网环境，我们建议您使用正常的 Linux 安装。（这里是无网环境安装的方法）

通常，SBT 使用在线仓库来下载和缓存项目的依赖项。该缓存位于几个文件夹中：

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

要设置无互联网环境，您可以：

在有互联网的场景下配置环境（见上文）
启动 Spinal 命令（请参阅在 CLI （命令行）中结合 SBT 使用 Spinal）来获取依赖项（例如使用入门仓库）
将缓存复制到无互联网环境。

创建第一个 SpinalHDL 项目

我们为您准备了一个现成的项目：入门仓库。

您可以下载它，或克隆它。

以下命令将项目克隆到名为 MySpinalProject 的新目录中，并初始化新的 git 历史记录：

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"

项目的目录结构

备注

这里描述的结构是默认结构，但可以轻松修改。

项目的根目录中有以下文件：

文件	描述
`build.sbt`	`sbt` 的 Scala 配置
`build.sc`	`mill` 是一个 `sbt` 的替代品，它的配置方法是
`hw/`	包含硬件描述的文件夹
`project/`	更多 Scala 配置
`README.md`	描述您的项目的 `text/markdown` 文件
`.gitignore`	版本控制中要忽略的文件列表
`.mill-version`	`mill` 的更多配置
`.scalafmt.conf`	配置自动格式化代码的规则

正如您可能猜到的，这里有趣的是 hw/。它包含四个文件夹： spinal/、 verilog/ 和 vhdl/ 保存您的 IP， gen/ 保存 Spinal 生成的 IP。

hw/spinal/ 包含一个以您的项目名称命名的文件夹。该名称以及公司名称必须在 build.sbt 和 build.sc 中设置；并且这个名称必须在 .scala 文件开头以 package yourprojectname 的形式给出。

在 hw/spinal/yourprojectname/ 中，是你的IP描述，仿真测试，形式化验证测试；还有 Config.scala，其中包含 ``Spinal``的配置。

备注

sbt 必须且**仅**在项目的根目录中使用，该目录包含 build.sbt 文件。

在 SpinalHDL 代码中使用 Spinal

现在，教程展示了如何根据您的开发环境在 SpinalHDL 代码中使用 Spinal：