settings.json 告诉 Digital IDE 在当前机器上使用哪些工具、从哪里启动它们。器件、顶层、源码目录和编译参数属于工程，见 property.json 配置。安装扩展不会自动安装 Vivado、仿真器或厂商许可证，只需安装并配置实际使用的工具。

配置写在哪里

在 VS Code 命令面板（Ctrl+Shift+P）打开相应的 JSON 设置文件。Digital IDE 的设置使用完整的 digital-ide.* 键，直接放在最外层对象中；不要再包一层 digital-ide 对象。文件支持 JSONC 注释和尾随逗号。

范围	打开方式 / 位置	适合保存的内容
用户设置	Preferences: Open User Settings (JSON)	本机多个工程共用的工具安装路径。通常优先放在这里，避免将个人路径提交到工程仓库。
远程设置	连接 Remote SSH 后运行 Preferences: Open Remote Settings (JSON)	远程主机的 Linux/Windows 路径；工具必须安装在运行扩展和后端的远程主机。
工作区设置	Preferences: Open Workspace Settings (JSON)；单文件夹工程为 .vscode/settings.json	当前工程指定的仿真器或需要覆盖用户设置的工具版本。多根工作区保存在 .code-workspace 的 settings 中。

对于这些普通工具设置，工作区值覆盖用户值；在远程窗口中，远程设置覆盖本地用户设置，工作区设置再覆盖远程设置。没有设置的键才使用扩展默认值。当前工具设置未声明文件夹级 resource 作用域，不应依赖多根工作区的各文件夹配置分别选择工具；不同工具环境建议分别打开窗口。

保存 Digital IDE 设置后，扩展会同步到后端。已经运行的 Vivado 或仿真会话需要结束后重新启动，才能使用新的程序。修改系统 PATH 后，需让 VS Code / Remote SSH 扩展主机重新启动并获得新环境；只新建终端未必有效。

先按任务选择工具

要做的事情	需要准备什么
编辑 HDL、查看结构、查看已有波形	先完成 扩展与后端安装，无需为了这些功能安装所有厂商工具。
Xilinx FPGA 综合、实现、下载、IP 配置	Vivado；还要满足器件支持、许可证和下载驱动要求。
Xilinx 处理器软件构建与调试	包含 xsct 的 SDK/Vitis 工具链；调试还会使用 hw_server 和目标架构的 GDB。仅安装 Vitis GUI 不代表已有 XSCT。
Efinix FPGA 构建	按所用流程准备原版 Efinity 安装目录或 Digital IDE 的 Efinity package，二者是不同配置。
Verilog/SystemVerilog 快速仿真	选择 Verilator 或 Icarus 等一个后端。Verilator 编译模型还需要可用的 C++ 编译/构建环境；Icarus 需要 iverilog、vvp，交互仿真还涉及 iverilog-vpi 和编译环境。
VHDL / 混合语言仿真	ModelSim/Questa 和对应许可证、仿真库；完整工具目录需要包含 vsim、vlog、vcom、vlib、vmap，交互模式还需要编译 VPI 模块的 C++ 环境。
CXXRTL / VCS	CXXRTL 使用 yosys、g++ 及 Yosys CXXRTL 运行时头文件；VCS 需要厂商工具、许可证及编译环境。先让这些命令在扩展主机的 PATH 中可用。

工具路径怎么填

以下设置均为字符串。建议填写绝对路径，Windows 使用 /，例如 C:/Xilinx/Vivado/2024.1/bin；若使用反斜杠，JSON 中要写成 C:\\Xilinx\\Vivado\\2024.1\\bin。路径包含空格时也不要在字符串内容里再加一层引号。

不要把 property.json 的 ${workspace}、${plname} 等变量照搬到工具路径。校验命令虽然能展开 ~、${workspaceFolder}、${env:NAME}，实际运行的各适配器并没有统一实现这些展开规则，使用绝对路径最稳妥。

FPGA 与 SDK

完整设置名	含义与推荐填写方式	默认值 / 留空行为
digital-ide.prj.vivado.install.path	Vivado 的 bin 目录，也可填写 vivado.bat（Windows）或 vivado（Linux）的完整路径。IP 查询和校验也能识别安装根目录，但 HARD 启动对目录的处理不同，统一填 bin 可兼顾这些入口。	扩展默认 C:/Xilinx/Vivado/2018.3/bin，不是自动探测结果；显式设为 "" 后由 HARD 从 PATH 启动。
digital-ide.prj.xsdk.install.path	含有 xsct 的 bin 目录，或 xsct.bat / xsct 的完整路径。名字保留 xsdk，也用于提供 XSCT 的 Vitis 安装。	""；未配置时使用 PATH 中的 xsct。
digital-ide.efinity.install.path	原版 Efinity 安装根目录，其下必须有 bin/efinity 和 bin/efx_run（或对应平台后缀）。不能填 bin 或单个程序。	""；不自动从 PATH 推导完整安装目录。使用原版厂商流程时应显式设置。
digital-ide.prj.efinix.package.path	Digital IDE 自包含 Efinity package 的根目录，例如已准备好的 tools/efinity/package。用于依赖该 package 的生成/构建流程；后端会验证包结构。	""；需要 package 的流程会报缺少配置。它不是原版 Efinity 安装目录，也不能指向 package 的 bin 子目录。

两个 Efinity 路径不能互相替代。仅使用原版厂商流程时不必为了填满设置而配置 package；需要自包含流程时，先准备有效 package 再填写其根目录。

仿真器与辅助工具

完整设置名	含义与推荐填写方式	默认值 / 留空行为
digital-ide.prj.iverilog.install.path	可执行程序所在目录，例如 C:/iverilog/bin 或 /usr/bin。实际仿真会在该目录后分别拼接 iverilog、vvp、iverilog-vpi。不能填安装根目录或单个 iverilog.exe。	""；从 PATH 查找工具。
digital-ide.prj.modelsim.install.path	ModelSim/Questa 的 工具目录，如 Windows 的 win64 或 Linux 的 linux_x86_64；也支持识别安装目录下的常见运行时子目录。推荐直接填包含整套命令的目录，不要填单个 vsim 文件。	扩展默认 C:/modeltech64_10.4/win64；显式设为 "" 后使用 PATH 中的各工具。
digital-ide.prj.verilator.install.path	Verilator 可执行文件、其所在目录或包含 bin 的安装根目录均可；Windows 运行适配器查找 verilator.exe。	""；依次查 PATH、VERILATOR_ROOT/bin。显式填写的路径失效会直接报错，不会静默换用其他版本。
digital-ide.prj.verible.install.path	Verible 的校验路径：可填包含 verible-verilog-lint 的目录、安装根目录或程序本身。	""。当前源码只在工具链校验中使用该路径，填写它不会自动将编辑诊断/格式化切换为 Verible。
digital-ide.function.simulate.gtkwavePath	GTKWave 的校验路径，可填程序路径、目录或命令名 gtkwave。	"gtkwave"。当前源码只接入工具链校验，内置波形页面不依赖此项，也不会因设置它就自动改用外部 GTKWave。

默认值不代表已安装

Vivado 和 ModelSim 的默认值是历史 Windows 路径，在新版本安装、Linux 或 Remote SSH 环境中通常不适用。要么改成实际路径，要么显式填写空字符串并正确配置 PATH。只删除设置会恢复默认值。

仿真选项

完整设置名	类型与默认值	作用
digital-ide.function.simulate.fastSimulator	字符串，"verilator"	快速仿真默认后端，可选 verilator、iverilog、cxxrtl、vcs、modelsim、questa；选择名称不会安装工具。VHDL 文件入口当前直接选择 modelsim。HARD 的厂商仿真入口不由此项切换。
digital-ide.function.simulate.simulationHome	字符串，未指定	支持该设置的仿真后端的输出目录；通常保持未配置，使用工程内 .dide/ 缓存。确需自定义时使用可写的绝对路径，避免多个工程共用同一个输出目录。
digital-ide.function.simulate.xilinxLibPath	字符串，""	Xilinx 厂商仿真准备流程使用的仿真库位置；不是 Vivado 的 bin 目录，也不是普通 HDL 自定义库。库必须与所用仿真器、版本和器件族相符。
digital-ide.function.simulate.vendorCachePath	字符串，""，已弃用	旧缓存设置；当前厂商缓存统一放在工程 .dide/ 下，新配置不要再添加此项。
digital-ide.function.simulate.runInTerminal	布尔值，false	保留设置。当前仿真入口没有读取它，不能用它控制交互仿真是否在终端中运行。

当前扩展没有注册 VCS/CXXRTL 专用安装路径设置。日常配置优先使用 PATH，不要根据其他工具的命名自行推测一个设置键。更详细的仿真操作见 快速与交互仿真。

库与处理器调试的补充设置

以下库路径均为字符串，默认 ""。普通库的导入操作见 库与 IP。

完整设置名	作用
digital-ide.lib.common.path	公共 HDL 库根目录；未设置时使用扩展提供的公共库位置。
digital-ide.lib.custom.path	自定义 HDL 库根目录；property.json 中 library.hardware.custom 引用相对于该根目录解析。
digital-ide.lib.vhdl.path	语言服务使用的 VHDL 库资源目录；未设置时使用随扩展提供的资源，开发环境回退到源码中的资源目录。环境变量 DIGITAL_SERVER_VHDL_LIBRARY_PATH 可覆盖它；通常无需修改。

Xilinx 自定义 IP 仓库在 property.json 的 IP_REPO 配置。digital-ide.prj.xilinx.IP.repo.path 与 digital-ide.prj.xilinx.BD.repo.path 虽仍在设置中声明，当前源码没有对应的工程导入读取逻辑，不要靠这两个旧设置配置 IP/BD。

仅进行处理器调试时才需要检查下列设置，详细操作见 SDK：

完整设置名	类型、默认值与作用
digital-ide.xilinx.ps.hwServer.path	字符串，""。硬件服务程序完整路径；不填时尝试从 XSCT 安装位置推导，再回退到命令查找。
digital-ide.xilinx.ps.hwServer.host	字符串，"127.0.0.1"。硬件服务地址；Remote SSH 下本机地址指远程主机。
digital-ide.xilinx.ps.hwServer.port	整数，3121，范围 1–65535。硬件服务端口。
digital-ide.xilinx.ps.gdb.portBase	整数，3000，范围 1–65532。GDB 服务端口基值，需避免与其他会话冲突。
digital-ide.xilinx.ps.gdb.arm.path	字符串，""。ARM 的 arm-none-eabi-gdb 完整路径。
digital-ide.xilinx.ps.gdb.aarch64.path	字符串，""。AArch64 的 aarch64-none-elf-gdb 完整路径。
digital-ide.xilinx.ps.gdb.armR5.path	字符串，""。ARM R5 的 armr5-none-eabi-gdb 完整路径。
digital-ide.xilinx.ps.gdb.microblaze.path	字符串，""。MicroBlaze 的 microblaze-xilinx-elf-gdb 完整路径。
digital-ide.xilinx.ps.gdb.microblaze64.path	字符串，""。MicroBlaze 64 的 mb64-gdb 完整路径。

GDB 路径不填时也会尝试从 XSCT 所在安装位置推导，然后回退到命令查找。若推导失败，显式填写实际可执行文件路径；Windows 应包含 .exe 后缀。

Windows / Linux 配置示例

下面是路径写法示例，不是自动安装脚本；只保留已安装且需要使用的工具，版本和路径以当前机器为准。合并到已有设置对象中，不要覆盖其他设置。

Windows：Vivado 与 Icarus

假设 Vivado 安装在 C:/Xilinx/Vivado/2024.1，Icarus 安装在 C:/iverilog：

{
  "digital-ide.prj.vivado.install.path": "C:/Xilinx/Vivado/2024.1/bin",
  "digital-ide.prj.iverilog.install.path": "C:/iverilog/bin",
  "digital-ide.function.simulate.fastSimulator": "iverilog"
}

Linux / Remote SSH：Vivado、XSCT 与 Verilator

假设厂商工具安装在 /opt/Xilinx，Verilator 位于 /usr/bin：

{
  "digital-ide.prj.vivado.install.path": "/opt/Xilinx/Vivado/2024.1/bin",
  "digital-ide.prj.xsdk.install.path": "/opt/Xilinx/Vitis/2024.1/bin",
  "digital-ide.prj.verilator.install.path": "/usr/bin/verilator",
  "digital-ide.function.simulate.fastSimulator": "verilator"
}

使用已经配置好的 PATH

若扩展主机的环境已包含所需命令，可显式清空历史默认路径。以下示例选择 ModelSim/Questa 工具链：

{
  "digital-ide.prj.vivado.install.path": "",
  "digital-ide.prj.modelsim.install.path": "",
  "digital-ide.function.simulate.fastSimulator": "modelsim"
}

空路径会被工具链校验跳过，因此需要在相同运行环境检查命令，并通过一次实际仿真/构建验证。终端 shell 自己加载的环境不一定与扩展主机一致。

验证配置是否生效

1. 保存设置，确认编辑的是当前本地或远程窗口的正确设置范围。
2. 在 TOOL Options → Validate Configured Toolchains 执行校验，也可从命令面板搜索该命令。结果会显示在 TOOL 树中。
3. 当前校验覆盖 Vivado、XSCT、Efinity、ModelSim/Questa、Icarus、Verible、Verilator 和 GTKWave，只检查显式设置且非空的项。显示 No configured toolchains 不等于工具未安装；默认值和空值不会触发检测。
4. 查看解析出的可执行文件、版本与错误。绿色勾只说明该版本命令执行成功并被识别，不保证许可证、C++ 编译器、配套程序、仿真库或板卡驱动可用，也不保证某个安装根目录适用于所有运行入口。
5. 用当前工程执行一次最小仿真，或在 HARD 中 Launch。查看 Output 中实际命令、工作目录和首个错误；PS 调试、Efinity package、VCS/CXXRTL 需要另行验证。

可以在对应主机终端检查所选工具。例如 Linux：

command -v verilator
verilator --version
g++ --version
make --version

Windows PowerShell（对应上面的 Icarus 示例）：

& 'C:/iverilog/bin/iverilog.exe' -V
& 'C:/iverilog/bin/vvp.exe' -V

常见问题

现象	检查与处理
文件存在但提示找不到程序	检查目录/文件类型是否填对，尤其 Icarus 要目录、Efinity 要安装根目录；确认路径属于实际扩展主机。
终端可以运行，扩展不能运行	检查终端是否额外加载了厂商环境脚本；让启动 VS Code / 远程后端的环境也获得相同 PATH、许可证和动态库设置，再重启扩展主机。
Linux 出现 Windows 旧路径	在远程设置中覆盖 Vivado/ModelSim 默认值，并检查是否被工作区设置再次覆盖。
校验通过，仿真仍失败	检查配套命令、C++/VPI 环境、语言支持和厂商仿真库。ModelSim 的 vsim -version 成功不代表 vlog、vcom 或许可证可用。
Permission denied / 动态库缺失	检查执行权限及厂商运行依赖。不要仅为了通过版本检查随意移动厂商安装目录中的单个程序。
切换设置后仍使用旧版本	结束现有工具会话后重新 Launch；检查工作区覆盖项和 Output 中的实际路径，必要时重新加载窗口。

安装 · 工程配置（property.json） · 快速仿真 · FPGA 构建