Working with projects

Tutorial · 15 minutes

A project file keeps what it takes to simulate a design: its source files in their libraries and in analysis order, the top level, the stop time and the options. You set it up once in the window, jhdlw. Then one key runs the design there, and one command runs it in a terminal or a CI job. This tutorial makes a project of the counter from Your first testbench.

1. The design

Make a folder named counter, and save in it counter.vhd and counter_tb.vhd from the first two steps of Your first testbench. The testbench checks that the counter reaches 10, prints a report and ends the run at 112 ns.

2. Make the project

Start the window, jhdlw, and choose File → New project…. Save the project in the counter folder as counter.jhdlproj. The window makes it, shows it in the Project tab beside the Hierarchy, and opens its settings on the Sources page.

1. Sources. Press Add files… and choose counter.vhd and counter_tb.vhd. Files are analyzed in the order listed, and a file must come after the files it uses, so counter.vhd goes first. If the testbench is first, press the ↓ button on its line; in the wrong order, the analysis stops with `counter` is not declared in `work`. Both files go into library work. To put a file into another library, type the library's name in its Library field.

2. Top level. On the Top level page, type the testbench as library.entity: work.counter_tb.

3. Simulation. On the Simulation page, set the Stop time to 1 us. This testbench ends the run itself; the stop time ends a run that would otherwise go on. Leave the other settings as they are.

4. Save. Press Save. The settings are checked first: a stop time that is not a time, for example, keeps the dialog open on its page and says what to write. Then the project file is written.

The Project tab now lists the two files under work. File → Project settings… (Ctrl+Shift+,), or the cog button in the tab, opens the settings again.

3. Run it

Press F5, or the Run button in the toolbar. The window analyzes the files, elaborates work.counter_tb and runs it. The Terminal shows the report done: q = 10 at 112 ns and how the run ended, and the waveform opens as the simulation runs.

4. Add signals, and keep them with the project

1. In the Hierarchy, click dut, the counter inside counter_tb.
2. The Signals tab lists its signals. Double-click n to add it to the waves. The button beside the filter box adds every signal listed.

Press F to fit the whole run in view. The window remembers this view for you. To keep it with the project, so that a colleague who opens the project sees the same signals:

1. Choose File → Save wave setup… and save it in the counter folder as counter.wavesetup.
2. Open the project settings (Ctrl+Shift+,). On the Waves page, press Add wave setups… and choose counter.wavesetup. Press Save.

When you have no view of your own yet, as on a new computer or in a colleague's copy, a run of the project shows its first wave setup. After that, you see the view you left.

5. Change the code and run again

1. In the Project tab, double-click counter_tb.vhd. It opens in the code editor, which checks the code as you type, with the project's settings.
2. Change wait for 100 ns; to wait for 50 ns;, and save the file (Ctrl+S).
3. Press F5. The window sees that a file changed and analyzes it again before the run. Now the assertion fails: the terminal shows the error q is 5 at 62 ns, with its place in counter_tb.vhd. Click the line to go there in the editor.
4. Change assert q = 10 to assert q = 5, save, and press F5 again: done: q = 5, and no error.

The signals you added stay in the waves from run to run.

6. Import a file list as a project

A file list (.f) names a design's files in analysis order, each library's files after a library NAME line, such as project.f in Your first testbench. The window makes a project of one:

1. Choose File → Import a file list (.f) as a project… and pick the file list.
2. Choose where to save the project; the window offers the list's name, here project.jhdlproj. The project gets the list's files, in the same libraries and order, with their paths relative to the project's folder.
3. The settings open: set the top level and the stop time as above, and press Save.

The file lists of the UVVM demo projects import the same way; tick Compatibility mode on the Simulation page, which UVVM needs.

7. Run it from a terminal or in CI

The project runs without the window too, with everything it says: the files in their libraries, the top level, the stop time and the options. From the counter folder:

jhdl run counter.jhdlproj

62 ns (delta 0) …/counter/counter_tb.vhd:18:12: note: done: q = 5
simulation of work.counter_tb ended at 62 ns (stopped); analysis … ms, elaboration … ms, run … ms

The report names the file with its full path (on Windows, with \). Paths in a project are relative to its folder, so jhdl run works from any folder. The exit code is 0, or 1 if a report or assertion of severity error or worse came up (the setting A command-line run fails at), so a CI job runs the same command and fails when the testbench does.

Options after the project take precedence over its own: --stop-time 10us, for example, or --wave run.jhw to keep a recording that jhdlw run.jhw opens.

8. Keep it in version control

A project file is short text, made to be kept next to the sources. Open counter.jhdlproj in a text editor:

jhdl-project 1
# ...
std 2008

library work
  source counter.vhd
  source counter_tb.vhd

top work.counter_tb
stop-time 1 us

compat off
psl off
native-code on
ieee-warnings on
stop-level failure
exit-level error

wave-setup counter.wavesetup

(# ... stands for two comment lines the window writes.) Every option is written out, so the project runs the same in a later version whose defaults differ. Paths are relative to the project's folder and written with forward slashes, so the file reads the same on Windows and Linux, in every copy of the repository.

Commit counter.jhdlproj and counter.wavesetup with the VHDL files. The window keeps your own state of the project apart, in a folder .jhdl beside the project file: the layout of the tabs, the files open in the editor and your last wave view. That is yours, not the team's, so leave it out. With git, add this line to .gitignore:

.jhdl/

Next

Projects, in the manual, is the reference: every statement of a project file, VHDL versions per library or file, generics, rule levels and recording, and how the code editor and the language server use a project.