Command Line Interface

A VUnit object can be created from command line arguments by using the from_argv method effectively creating a custom command line tool for running tests in the user project. Source files and libraries are added to the project by using methods on the VUnit object. The configuration is followed by a call to the main method which will execute the function specified by the command line arguments and exit the script. The added source files are automatically scanned for test cases.

Usage

VUnit command line tool version 2.0.1-pre

usage: run.py [-h] [-l] [-f] [--compile] [-k] [--elaborate] [--clean]
              [-o OUTPUT_PATH] [-x XUNIT_XML] [--exit-0] [-v] [--no-color]
              [--log-level {info,error,warning,debug}] [-p NUM_THREADS] [-u]
              [--version] [-g] [--coverage [COVERAGE]]
              [--gtkwave-fmt {vcd,ghw}] [--gtkwave-args GTKWAVE_ARGS]
              [--cdslib CDSLIB] [--hdlvar HDLVAR] [--use-debug-codecs]
              [tests [tests ...]]

Positional Arguments

tests

Tests to run

Default: “*”

Named Arguments

-l, –list

Only list all test cases

Default: False

-f, –files

Only list all files in compile order

Default: False

–compile

Only compile project without running tests

Default: False

-k, –keep-compiling
 

Continue compiling even after errors only skipping files that depend on failed files

Default: False

–elaborate

Only elaborate test benches without running

Default: False

–clean

Remove output path first

Default: False

-o, –output-path
 

Output path for compilation and simulation artifacts

Default: ”./vunit_out”

-x, –xunit-xml
 Xunit test report .xml file
–exit-0

Exit with code 0 even if a test failed. Still exits with code 1 on fatal errors such as compilation failure

Default: False

-v, –verbose

Print test output immediately and not only when failure

Default: False

–no-color

Do not color output

Default: False

–log-level

Possible choices: info, error, warning, debug

Log level of VUnit internal python logging. Used for debugging

Default: “warning”

-p, –num-threads
 

Number of tests to run in parallel. Test output is not continuously written in verbose mode with p > 1

Default: 1

-u, –unique-sim
 

Do not re-use the same simulator process for running different test cases (slower)

Default: False

–version show program’s version number and exit
-g, –gui

Open test case(s) in simulator gui with top level pre loaded

Default: False

modelsim

ModelSim specific flags

–coverage Enable code coverage. Choose any combination of “bcestf”. When the flag is given with no argument, everything is enabled. Remember to run –clean when changing this as re-compilation is not triggered. Experimental feature not supported by VUnit main developers.

ghdl

GHDL specific flags

–gtkwave-fmt

Possible choices: vcd, ghw

Save .vcd or .ghw to open in gtkwave

–gtkwave-args

Arguments to pass to gtkwave

Default: “”

Incisive irun

Incisive irun-specific flags

–cdslib The cds.lib file to use. If not given, VUnit maintains its own cds.lib file.
–hdlvar The hdl.var file to use. If not given, VUnit does not use a hdl.var file.

com

Flags specific to the com message passing package

–use-debug-codecs
 

Run with debug features enabled

Default: False

Example Session

The VHDL User Guide Example can be run to produce the following output:

List all tests
> python run.py -l
lib.tb_example.all
lib.tb_example_many.test_pass
lib.tb_example_many.test_fail
Listed 3 tests
Run all tests
> python run.py -v lib.tb_example*
Running test: lib.tb_example.all
Running test: lib.tb_example_many.test_pass
Running test: lib.tb_example_many.test_fail
Running 3 tests

running lib.tb_example.all
Hello World!
pass( P=1 S=0 F=0 T=3) lib.tb_example.all (0.1 seconds)

running lib.tb_example.test_pass
This will pass
pass (P=2 S=0 F=0 T=3) lib.tb_example_many.test_pass (0.1 seconds)

running lib.tb_example.test_fail
Error: It fails
fail (P=2 S=0 F=1 T=3) lib.tb_example_many.test_fail (0.1 seconds)

==== Summary =========================================
pass lib.tb_example.all            (0.1 seconds)
pass lib.tb_example_many.test_pass (0.1 seconds)
fail lib.tb_example_many.test_fail (0.1 seconds)
======================================================
pass 2 of 3
fail 1 of 3
======================================================
Total time was 0.3 seconds
Elapsed time was 0.3 seconds
======================================================
Some failed!
Run a specific test
> python run.py -v lib.tb_example.all
Running test: lib.tb_example.all
Running 1 tests

Starting lib.tb_example.all
Hello world!
pass (P=1 S=0 F=0 T=1) lib.tb_example.all (0.1 seconds)

==== Summary ==========================
pass lib.tb_example.all (0.9 seconds)
=======================================
pass 1 of 1
=======================================
Total time was 0.9 seconds
Elapsed time was 1.2 seconds
=======================================
All passed!

Opening a Test Case in Simulator GUI

Sometimes the textual error messages and logs are not enough to pinpoint the error and a test case needs to be opened in the GUI for visual debugging using single stepping, breakpoints and wave form viewing. VUnit makes it easy to open a test case in the GUI by having a -g/--gui command line flag:

> python run.py --gui my_test_case &

This launches a simulator GUI window with the top level for the selected test case loaded and ready to run. Depending on the simulator a help text is printed were a few TCL functions are pre-defined:

# vunit_help
#   - Prints this help
# vunit_load [vsim_extra_args]
#   - Load design with correct generics for the test
#   - Optional first argument are passed as extra flags to vsim
# vunit_user_init
#   - Re-runs the user defined init file
# vunit_run
#   - Run test, must do vunit_load first
# vunit_compile
#   - Recompiles the source files
# vunit_restart
#   - Recompiles the source files
#   - and re-runs the simulation if the compile was successful

The test bench has already been loaded with the vunit_load command. Breakpoints can now be set and signals added to the log or to the waveform viewer manually by the user. The test case is then run using the vunit_run command. Recompilation can be performed without closing the GUI by running vunit_compile. It is also possible to perform run.py with the --compile flag in a separate terminal.

Continuous Integration Environment

VUnit is easily utilized with continuous integration environments such as Jenkins. Once a project run.py has been setup, tests can be run in a headless environment with standardized xUnit style output to a file.

Execute VUnit tests on CI server with XML output
 python run.py --xunit-xml test_output.xml

After tests have finished running, the test_output.xml file can be parsed using standard xUnit test parsers such as Jenkins xUnit Plugin.

Simulator Selection

VUnit automatically detects which simulators are available on the PATH environment variable and by default selects the first one found. For people who have multiple simulators installed the VUNIT_SIMULATOR environment variable can be set to one of activehdl, rivierapro, ghdl or modelsim to explicitly specify which simulator to use.

In addition to VUnit scanning the PATH the simulator executable path can be explicitly configured by setting a VUNIT_<SIMULATOR_NAME>_PATH environment variable.

Explicitly set path to GHDL executables
VUNIT_GHDL_PATH=/opt/ghdl/bin