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.
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
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.
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
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.