JanusHDL

Command reference

Last updated: 

This chapter lists every option, environment variable, window command and key in one place. The other chapters explain them.

jhdl

jhdl [options] FILE.vhd... [-f FILES.f]...
jhdl run PROJECT.jhdlproj [options]
jhdl PROJECT.jhdlproj [options]

Analyzes the files in order, elaborates the top level and runs it. run runs a project file; options given after the project take precedence over its settings (Running simulations from the command line).

Sources and libraries

Option Effect
FILE.vhd A file to analyze, into the current --work library
-f FILES.f Analyze the files a file list names: library NAME lines choose the library, other lines are paths relative to the file list, # starts a comment. May be repeated
--work NAME The library for the files that follow on the command line (default work)
--std 93\|02\|08\|19 The VHDL version, also as 1993, 2002, 2008, 2019 (default 08)
-DNAME=VALUE Define an identifier for VHDL-2019 conditional analysis (`if); undefined identifiers are empty
--psl Also read PSL in -- psl comments

Diagnostics

Option Effect
--compat Compatibility mode: code the LRM forbids but whose meaning is clear is a warning, and simulated as written (the rules marked error (--compat: warning) in --rules; UVVM needs it)
--allow RULE Do not report the rule's diagnostics
--warn RULE Report them as warnings
--deny RULE Report them as errors
--rules List the diagnostic rules with their levels, and exit
--keep-going After analysis errors, report them and elaborate anyway; a top level that does not depend on the units in error runs (the exit code is still 1)

Elaboration and the run

Option Effect
--top NAME The top level: entity, library.entity or a configuration (default: the entity analyzed last)
-gNAME=VALUE Set a generic of the top level; with a path (-guut.sub.width=8), of that instance below the top, replacing its actual. The value is written as VHDL writes a literal of the generic's type: 42, 16#FF#, 1.5, 20ns, idle, 1 or '1', 0101, x"A5", (1, 2, 3) (Generics)
--stop-time TIME Stop at this time, such as 10us or "2.5 ms" (default: run until nothing is left to simulate)
--stop-level note\|warning\|error\|failure The least severity of a report that stops the simulation (default failure)
--exit-level note\|warning\|error\|failure The least severity of a report that makes the exit code non-zero (default error)
--order-seed N Run the processes of each cycle in a fixed order drawn from N (default: JanusHDL's own order)
--ieee-warnings on\|off Whether assertions inside the IEEE packages report (default on)
--jit on\|off Compile what qualifies to native code (default on); off runs everything in the interpreter, with the same results
--max-memory SIZE Stop with an error when the run uses more memory than SIZE: bytes, or with K, M, G, T (default 4G; 0 = no limit)
--quiet Print only reports and assertions of severity error and failure (and run-time errors)

Recording and caching

Option Effect
--wave FILE Record every signal into a waveform database, written while the run goes on, with the design's structure and delta cycles
--wave-deltas on\|off Whether the waveform database keeps each time step's delta cycles (default on)
--vcd FILE Record every signal into a VCD file, written at the end of the run (with --wave too: both are written)
--cache FILE Keep the analysis in FILE and load it next time while no file changed (each file with the same VHDL version)
--analyze-only Analyze (and with --cache, save the analysis), then exit

Other

Option Effect
--write-libraries DIR Write the sources of the built-in libraries into DIR, and exit
--version, -V Print the version, and exit
--help, -h Print the usage, and exit

Exit codes

Code Meaning
0 Passed
1 Analysis or elaboration failed (also with --keep-going), a run-time error occurred, a report reached the exit level, or the VCD file or waveform database could not be written
2 A wrong command line, or a file, file list or project file that cannot be read
3 The run exceeded --max-memory

Environment variables

Variable Effect
JHDL_JIT=off Run everything in the interpreter, as --jit off, in jhdl and in the window
JHDL_ORDER_SEED=N Run under process order seed N, as --order-seed N; takes precedence over a project's order-seed
JHDL_PHASES=1 Print the time of analysis (or of loading it from the cache), elaboration and the run, as each finishes
JHDL_PEAK_MEMORY=1 Print the run's peak memory use at the end

jhdlw

jhdlw [FILE.jhw | FILE.vcd | PROJECT.jhdlproj] [options]
jhdlw --run PROJECT.jhdlproj|FILES.f|FILE.vhd [--top LIB.ENTITY] [--stop-time TIME] [options]
jhdlw --demo | --stress | --vhdl-demo [options]

Options may come before or after the file, in any order. One thing is opened: a file, a demo or --run. An unknown option or a missing value is an error that prints the usage (exit code 2).

Argument Effect
FILE.vcd, FILE.jhw Open a VCD file or a waveform database
PROJECT.jhdlproj Open a project
--run FILE Simulate a project, file list or VHDL file at start-up, with the output in the terminal (a project is opened too). A file list or VHDL file runs with the defaults (VHDL-2008, no generics), not with what the Run dialog remembers
--top LIB.ENTITY With --run: the top level
--stop-time TIME With --run: when the run ends
--setup FILE.wavesetup Show this wave setup once the waveform is open
--demo Open the built-in demo waveform, with all its signals shown
--stress Open a generated waveform of about 29 million changes
--vhdl-demo Simulate a small built-in VHDL design and show the result
--renderer auto\|gpu\|software Which graphics adapter draws the window: a graphics card if there is one (auto, the default), a graphics card only, or software only
--version, --help Print the version, or the usage
Environment variable Effect
JHDL_RENDERER=auto\|gpu\|software As --renderer
JHDL_GUI_STATE=FILE Keep the window's settings and layout in FILE instead of your user settings
JHDL_FRAME_STATS=1 Show the time each frame takes to draw, in the status bar
JHDL_JIT=off Simulations in the window run in the interpreter only

jhdl-lsp

jhdl-lsp
jhdl-lsp --check DIR [--project PROJECT.jhdlproj|FILES.f] [--compat]
jhdl-lsp --order FILES.f
jhdl-lsp --version
Form Effect
jhdl-lsp The language server, over its standard input and output; editors start it (External editors and the language server)
--check DIR [--project FILE] [--compat] Analyze the design in DIR as the server would (with --project, from that project or file list; with --compat, in compatibility mode), print the diagnostics and a summary; exit code 1 if there are errors
--order FILES.f Print the file list with its files in dependency order
--version Print the version

Initialization options: projectFile (a project or a file list, relative to the workspace), std (93, 02, 08 or 19; a project's own versions take precedence) and compat (true for compatibility mode).

The front ends for existing scripts

The commands in the compat folders, and what each accepts, are in Running existing scripts.

GUI commands

Every command is in the command palette (Ctrl+Shift+P or F1) under the name below, and most are in a menu. Keys marked waves act while no text field has the keyboard; keys marked editor act while the code editor has it, and then come before the same key elsewhere.

File

Command Keys
Open waveform… Ctrl+O
Reload waveform Ctrl+R
New project…
Open project…
Import a file list (.f) as a project…
Project settings… Ctrl+Shift+,
Save project
Close project
Open wave setup… Ctrl+Shift+O
Save wave setup… Ctrl+S
Save the waves as an image (PNG or SVG)…
Open file in editor… Ctrl+E
Save file Ctrl+S (editor)
Save all files Ctrl+Shift+S
Close file Ctrl+W (editor)
Open demo waveform
Open stress-test waveform (about 29M changes)
Simulate the VHDL demo design
Quit Ctrl+Q

Edit

Command Keys
Find in file Ctrl+F (editor)
Replace in file Ctrl+H (editor)
Find next / Find previous F3 / Shift+F3 (editor)
Find in files Ctrl+Shift+F
Go to line… Ctrl+G (editor)
Toggle line comment Ctrl+/ (editor)
Add selection to next match Ctrl+D (editor)
Fold all / Unfold all

View

Command Keys
Show all commands Ctrl+Shift+P, F1
Show or hide the hierarchy (and the signals) Ctrl+B
Show or hide the terminal Ctrl+J
Show problems Ctrl+Shift+M
Show or hide the minimap
Split the editor right Ctrl+Shift+I (editor)
Split the editor down Ctrl+Shift+D (editor)
Close the editor pane Ctrl+Shift+W (editor)
Show or hide the project
Reset the layout
Bring every tab back into the main window
Zoom to fit F (waves)
Zoom in + or = (waves)
Zoom out − (waves)
Theme: follow system, JanusHDL Dark, JanusHDL Light, One Dark, Dracula, Nord, Solarized Light

Simulate

Command Keys
Run simulation… Ctrl+Shift+R
Run / continue F5
Pause F6
Run for the step time F10
Restart: back to time 0 Ctrl+Shift+F5
Stop Shift+F5
Clear terminal

Signals

Command Keys
Filter signals Ctrl+F
Add all signals of the selected scope
Insert divider above the selected signal Ctrl+D (waves)
Add an expression of signals E (waves)
Cursor to the previous / next change of the selected signal Ctrl+← / Ctrl+→ (waves)
Find a value of the selected signal / (waves)
Find the next / previous change to the value F3 / Shift+F3 (waves)
Add a marker at the cursor M (waves)
Cursor to the previous / next marker Alt+← / Alt+→ (waves)
Remove the markers and the second cursor
Why this value?
Show the dataflow and schematic of the selected signal
Show the delta cycles of the time step at the cursor
Remove selected signal Delete (waves)
Remove all signals

Also in the palette, without a menu: Pan left / Pan right (← / →, waves) and Select the signal above / below (↑ / ↓, waves).

Help

Command Keys
Keyboard shortcuts
Licenses
About JanusHDL

Mouse actions in the wave view

Action Effect
Ctrl+wheel, or a pinch Zoom around the pointer
Wheel Scroll the rows
Shift+wheel, drag Pan in time (dragging up or down scrolls the rows)
Click Place the cursor (it snaps to a change of the signal under the pointer nearby) and select that row
Shift+click Place the second cursor
Click a name; Ctrl+click; Shift+click Select a row; pick rows one by one; pick a run of rows
Drag a name Reorder rows
Double-click a name, or click its arrow Open or close a record, array, vector or group
Right-click a name Radix, analog drawing, color, copy path, divider, group, open or close, change an expression, remove
Drag a marker's flag Move the marker; right-click it to rename or remove it; double-click it to bring the cursor there
Drop a file Open a waveform or a project, apply a wave setup, or simulate a file list or VHDL file
Right-click a tab Move it to a window of its own, or back

The editor's keys are listed in The code editor.

Files

File What it is
.vhd, .vhdl (also .vht, .vho) VHDL sources
.f A file list: library NAME lines and file paths (File lists)
.jhdlproj A project file (Projects)
.jhdl/NAME.state Your state of project NAME: layout, open files, last view; not for version control
.jhw A waveform database, written by jhdl --wave and by the window's runs
.vcd A Value Change Dump file
.wavesetup A wave setup: what the wave view shows (Wave setup files)
A cache file (any name) The saved analysis of --cache