Development Setup

Note

To make changes to a backend, e.g. to the way a simulator or synthesis tool is called, you need to modify edalize, not fusesoc. Edalize is a separate project, see https://github.com/olofk/edalize for more information.

Get the code

The FuseSoC source code is maintained in a git repository hosted on GitHub. To improve FuseSoC itself, or to test the latest unreleased version, it is necessary to clone the git repository first.

cd your/preferred/source/directory
git clone https://github.com/olofk/fusesoc

Setup development environment

Note

If you have already installed FuseSoC, remove it first using pip3 uninstall fusesoc.

To develop FuseSoC and test the changes, the fusesoc package needs to be installed in editable or development mode. In this mode, the fusesoc command is linked to the source directory, and changes made to the source code are immediately visible when calling fusesoc.

# Install all Python packages required to develop fusesoc
pip3 install --user -r dev-requirements.txt

# Install Git pre-commit hooks, e.g. for the code formatter and lint tools
pre-commit install

# Install the fusesoc package in editable mode
pip3 install --user -e .

Note

All commands above use Python 3 and install software only for the current user. If, after this installation, the fusesoc command cannot be found adjust your PATH environment variable to include ~/.local/bin.

After this installation is completed, you can

edit files in the source directory and re-run fusesoc to immediately see the changes,
run the unit tests as outlined in the section below, and
use linter and automated code formatters.

Formatting and linting code

The FuseSoC code comes with tooling to automatically format code to conform to our expectations. These tools are installed and called through a tool called pre-commit. No setup is required: whenever you do a git commit, the necessary tools are called and your code is automatically formatted and checked for common mistakes.

To check the whole source code pre-commit can be run directly:

# check and fix all files
pre-commit run -a

Running tests

The FuseSoC contains unit tests written using the pytest framework. To run the tests in an isolated environment it is recommended to run pytest through tox, which first creates a package of the source code, installs it, and then runs the tests. This ensures that packaging and environment errors are less likely to slip through.

cd fusesoc/source/directory

# Run all tests in an isolated environment (recommended)
tox

# All arguments passed to tox after -- are passed to pytest directly.
# E.g. run a single test: use filename::method_name, e.g.
tox -- tests/test_capi2.py::test_capi2_get_tool --verbose

# Alternatively, tests can be run directly from the source tree.
# E.g. to run a single test: use filename::method_name, e.g.
python3 -m pytest

Refer to the pytest documentation for more information how tests can be run.

Note

In many installations you can replace python3 -m pytest with the shorter pytest command.

Building the documentation

The FuseSoC documentation (i.e., the thing you’re reading right now) is built from files in the doc directory in the FuseSoC source repository. The documentation is written reStructuredText, and Sphinx is used to convert the documentation into different output formats, such as HTML or PDF.

The most convenient way of working on documentation is to have a browser window open with the rendered documentation next an editor where you work on the reStructuredText files. Run the following command to build the documentation:

cd fusesoc/source/directory
tox -e doc-autobuild

The documentation is now built and can be accessed in a browser. Look for a line similar to [sphinx-autobuild] Serving on http://127.0.0.1:8000 and point your browser to the link, e.g. http://127.0.0.1:8000.

Whenever a change to a documentation file is detected the documentation will be rebuilt automatically and the refreshed in the browser without the need for further manual action (it might take a couple seconds, though).