安装和设置

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>

要在 shell 中使用 oss-cad-suite，您需要加载它的环境，例如通过 souce <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。

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

备注

SpinalHDL 维护者 Readon <https://github.com/Readon> 提供的一体化解决方案可用于安装和运行 SpinalHDL，并通过 Verilator 仿真、通过 SymbiYosys 进行形式化验证。下载 安装程序 并将该环境安装在磁盘上的任何位置。单击“开始”菜单中的 MSYS2-MINGW64 图标启动构建环境，并使用 MSYS2 默认控制台。另一种方法是使用“Windows Terminal”或类似 Tabby 的应用程序，并使用启动命令 %MSYS2_ROOT%\msys2_shell.cmd -defterm -here -no-start -mingw64，其中 %MSYS2_ROOT% 是 msys2 安装的位置。值得注意的是，如果要离线使用，要仔细选择项目所依赖的库，否则需要手动下载安装包。有关更多详细信息，请参阅对应仓库的自述文件。

用于仿真的 MSYS2 verilator工具

我们建议通过 MSYS2 <https://www.msys2.org> 安装编译器/仿真器。其他安装 gcc/make/shell 的方法（例如 Chocolatey、scoop 等）也可能有效，但未经测试。

SpinalHDL 维护者 Readon <https://github.com/Readon> 正在维护一个 MSYS2 分支，默认安装所有需要的官方可用和自定义构建的软件包（也由 Readon 在 此处 <https://github.com/Readon/ MINGW-SpinalHDL> 维护) 用于仿真和形式化验证。可以在 此处 <https://github.com/Readon/msys2-installer> 找到。如果使用该安装包，则已经安装了下面通过 pacman 安装的软件包，并且可以跳过这些安装步骤。

目前 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 实施形式化验证

除了上面的步骤之外，我们还需要安装yosys、sby、z3和yices。 yosys(可用的yosys-smtbmc) 和 sby 并不使用 MSYS2 官方提供的包（无法使用），而是由 Readon <https://github.com/Readon> 提供。如果您使用他们的安装程序，则不需要后面这些步骤（您应该检查是否有更新的软件包可用）。

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

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

1. 在有互联网的场景下配置环境（见上文）

2. 启动 Spinal 命令（请参阅 在 CLI （命令行）中结合 SBT 使用 Spinal）来获取依赖项（例如使用 入门 仓库）

3. 将缓存复制到无互联网环境。

创建第一个 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：

• 在 CLI （命令行）中结合 SBT 使用 Spinal

• 在 VSCodium 中使用 Spinal

• 从 IntelliJ IDEA 使用 Spinal