Developing cocotb

Setting Up a Development Environment

Assuming you have used cocotb prior to reading this guide, you will already have the cocotb installation prerequisites and standard development tools (editor, shell, git, etc.) installed.

First, you should fork and clone the cocotb repo to your machine. This will allow you to make changes to the cocotb source code, create pull requests, and run regressions and build documentation locally.

Additionally, you will need doxygen, for building documentation; nox, for building documentation and running regression tests; and pre-commit, to check your changes before committing them.

We recommend if you are using a Linux distribution to use your system package manager to install doxygen. Likewise, doxygen can be installed using the homebrew package manager on Mac OS. Windows contributors should download a binary distribution installer from the main website.

nox and pre-commit are Python projects and can be installed with pip:

pip install nox pre-commit

To enable pre-commit run the following command at the root of the cloned project to install the git hooks. The first run of pre-commit will build an environment for you, so it may take a while. Following runs should be much quicker.

pre-commit install

When committing, pre-commit’s hook will run, checking your changes for formatting, code smells, etc. You will see the lists of checks printed and whether they passed, were skipped, or failed. If any of the checks fail, it is recommended to fix them before opening a pull request, otherwise the pull request checks will fail as well.

Now you are ready to contribute!

Running Tests Locally

First, set up your development environment.

Our tests are managed by nox, which runs both pytest tests and our system of makefiles. The regression does not end on the first failure, but continues until all tests in the /tests and /examples directories have been run.

To run the tests locally with nox, issue the following command.

nox -s dev_test

At the end of the regression, if there were any test failures, the tests that failed will be printed. If the tests succeed you will see the message Session tests was successful printed in green.

By default the dev_test nox session runs all simulator-agnostic tests, as well as all tests which require a simulator and can be run against Icarus Verilog. Icarus Verilog must be installed.

The simulator and the toplevel language can be changed by setting the environment variables SIM and TOPLEVEL_LANG. Alternatively, the simulator-specific nox sessions can be used, as described below.

Selecting a Language and Simulator for Regression

cocotb can be used with multiple simulators, and can run tests against all of them. Nox provides a session for each valid simulator/language/GPI interface combination, from which one or multiple sessions can be selected.

The following examples are good starting points; refer to the nox command-line usage documentation for more information.

# List all available sessions.
nox -l

# Run all simulator-agnostic tests.
nox -s dev_test_nosim

# Run the simulator-specific tests against Xcelium, using a VHDL toplevel and
# the VHPI interface.
nox -s "dev_test_sim(sim='xcelium', toplevel_lang='vhdl', gpi_interface='vhpi')"

# Run all simulator-specific tests against Icarus Verilog and GHDL.
# Both simulators must be installed locally.
nox -k "dev_test_sim and (icarus or ghdl)"

Running Individual Tests Locally

Each test under /tests/test_cases/*/ and /examples/*/tests/ can be run individually. This is particularly useful if you want to run a particular test that fails the regression.

First you must install cocotb from source by navigating to the project root directory and issuing the following command:

python -m pip install .

On Windows, you must instead install cocotb from source like so:

python -m pip install --global-option build_ext --global-option --compiler=mingw32 .

Once that has been done, you can navigate to the directory containing the test you wish to run. Then you may issue an make command. For example, if you want to test with Icarus using Verilog sources:

make SIM=icarus TOPLEVEL_LANG=verilog

Building Documentation Locally

First, set up your development environment.

Documentation is built locally using nox. The last message in the output will contain a URL to the documentation you just built. Simply copy and paste the link into your browser to view it. The documentation will be built in the same location on your hard drive on every run, so you only have to refresh the page to see new changes.

To build the documentation locally on Linux or Mac, issue the following command:

nox -e docs

Building the documentation is not currently supported on Windows.