FuseSoC

2.4.5 verified Mon Apr 27 auth: no python

FuseSoC is a package manager and build abstraction tool for HDL (Hardware Description Language) code. Current version is 2.4.5, with a regular release cadence of several minor versions per year. It supports managing reusable HDL cores, generating simulation and synthesis build systems, and integrates with EDA tools.

pip install fusesoc

Common errors

error ModuleNotFoundError: No module named 'fusesoc' ↓

cause FuseSoC is not installed or not in the current Python environment.

fix

Run pip install fusesoc in the correct environment.

error fusesoc: error: unrecognized arguments: --work-root ↓

cause Using --work-root flag with FuseSoC versions before 2.3.

fix

Upgrade to FuseSoC 2.3 or later, or use the legacy --work option.

error ERROR: Could not find a version that satisfies the requirement fusesoc (from versions: none) ↓

cause The Python version is too old (<3.6) or too new (>=4.0).

fix

Use Python 3.6 to 3.12.

Warnings

breaking FuseSoC 2.4 migrated from setup.py to pyproject.toml. Projects relying on direct setup.py installation may break. ↓

fix Use `pip install fusesoc` or build from source with `pip install .` (pyproject.toml).

deprecated The old CAPI1 core format is deprecated. Only CAPI2 (.core) files are actively supported. ↓

fix Convert .core files to CAPI2 format as documented in the official migration guide.

gotcha Running `fusesoc run` without specifying a target may fail if the core defines multiple targets. The first target is used by default, which may not be intended. ↓

fix Explicitly specify the target with `--target` flag, e.g., `fusesoc run --target=sim`.

Imports

main
wrong
```
import fusesoc
```
correct
```
from fusesoc.main import main
```
FuseSoC is primarily a CLI tool. Importing the top-level package directly does not expose the CLI function.

Quickstart

Run FuseSoC's help from Python. For CLI usage, invoke `fusesoc` directly.

from fusesoc.main import main
import sys
sys.argv = ['fusesoc', '--help']
main()