The workspace file

Each workspace folder can hold one <name>.hdl-workspace file next to the code. It is the project model that F5, the Flow view, the Vivado flow and the hdl command line read. The file is JSON, formatted with two spaces and keys in a fixed order, so git merges stay small.

Create it with HDL Studio: Create Workspace File or hdl workspace create. Either one lists every *.vhd as a source, finds the testbench candidates and picks the first non-testbench entity as the top.

The dashboard#

counter.hdl-workspace

countercounter.hdl-workspace

HDL Studio Workspacecounter · 2 sources · 1 testbenchHDL Studio 1.0.4

Opening a .hdl-workspace file shows a dashboard laid out like the VS Code settings editor: a table of contents on the left and groups on the right. It covers the sources, the testbenches with their last result, the top entity, the part and board, the detected toolchains, and the Synthesis and Hardware groups with buttons for each Vivado stage and for programming.

• Each testbench row runs, debugs or opens its recording. Its menu sets it as the default, opens the file or removes it.
• Edits are ordinary document edits, so Ctrl+Z undoes them.
• Open JSON in the editor title switches to the text.
• The status bar item (counter · xc7a35tcpg236-1) reopens the dashboard.

Schema#

{
  "version": 1,
  "name": "counter",                       // shown in the dashboard header and the status bar
  "standard": "08",                        // 87 | 93 | 93c | 00 | 02 | 08 | 19, ghdl --std
  "workDir": ".hdl-studio",                // GHDL library files, executables, the agent; relative to the folder
  "part": "xc7a35tcpg236-1",               // Vivado part, optional
  "board": "digilent:basys3",              // board id, optional
  "top": { "entity": "counter", "architecture": "rtl" },   // architecture optional
  "sources": [                             // files and globs, analysis order; relative to the folder
    "src/counter.vhd",
    "src/uart_tx.vhd",
    "src/tb/**/*.vhd"
  ],
  "exclude": ["build/**", "node_modules/**", ".hdl-studio/**"],
  "testbenches": [
    { "entity": "tb_counter", "file": "src/tb/tb_counter.vhd", "stopTime": "2 us", "default": true },
    { "entity": "tb_uart_tx", "file": "src/tb/tb_uart_tx.vhd" }
  ],
  "simulation": { "stopAtEntry": true, "record": true, "ghdlArgs": [], "simArgs": [] },
  "constraints": ["constraints/basys3.xdc"],
  "blockDesigns": ["bd/design_1.bd"]
}

Rules#

• Paths are POSIX, relative to the folder that holds the file. Globs use **, * and {a,b}.
• Everything is optional except version and name. Missing sources means ["**/*.{vhd,vhdl}"], missing standard means "08" and missing workDir means ".hdl-studio".
• Exactly one testbench may carry default: true; if none does, the first one is the default.
• Unknown keys are kept on save, and known keys are written in the order above.
• Toolchain paths are not in the file. They are machine settings (hdl.ghdl.path, hdl.vivado.path).

Add .hdl-studio/ to your .gitignore: it holds the GHDL library, executables, recordings and the Vivado working folder.