FuseSoC for reusable HDL packages and multi-tool builds

Why FuseSoC exists for reusable HDL projects

FuseSoC addresses a specific problem in HDL development: IP cores and complete SoC designs often depend on tool-specific build knowledge. A project may need to simulate with Icarus Verilog on one workstation, use ModelSim or Xcelium elsewhere, synthesize for an FPGA target, or reuse a core in a larger system. FuseSoC places package management and build invocation around those HDL assets.

The intended users are engineers building or consuming reusable intellectual property. The README lists reusing existing cores, creating compile-time and run-time configurations, running regression tests against multiple simulators, porting designs to new targets, sharing code, setting up continuous integration, and generating FPGA SBOMs through the `spdxgen` filter. These are related problems rather than separate feature claims. They all depend on describing HDL components and their relationships in a form that can be reused across projects.

The project does not act as an HDL simulator itself. The README's quick start says that a supported simulator must already be installed before a simulation command can run. Its role is to coordinate package discovery, select a target and tool, and pass the resulting work to the relevant tool integration. That boundary matters. FuseSoC can reduce duplicated command knowledge, but it cannot remove the need for a simulator, synthesis implementation, lint setup, or target support.

The FuseSoC core, library, target, and filter model

The visible project layout is a Python package under `fusesoc/`, with dedicated packages for CAPI2 schemas, parsing, providers, and filters. The `pyproject.toml` also declares dependencies on `edalize`, `pyparsing`, `pyyaml`, `pydantic`, `simplesat`, `fastjsonschema`, and `argcomplete`. This package structure indicates that FuseSoC is more than a shell script around one simulator. It parses structured HDL metadata, validates it, resolves packages, and uses tool-related components.

The README describes a base library being added to a workspace, after which FuseSoC can list the cores it finds. A command such as `fusesoc run --target=sim i2c` names a core, a simulation target, and a selected simulator tool. Other tools can be selected with switches such as `--tool=modelsim` or `--tool=xcelium`. The command therefore combines at least three pieces of selection: the requested operation, the target, and the external tool.

The repository includes filters and provider packages, while the README specifically calls out `spdxgen` for FPGA SBOM generation. The README does not document the complete core-file schema, dependency-resolution order, cache behavior, or the internal data passed to each tool. Those details should be checked in the User Guide and example core files rather than inferred from command names. The documented model is still enough to identify the architecture: FuseSoC manages HDL packages and delegates tool-specific work through integrations.

Installing FuseSoC and running the first simulation

FuseSoC supports Linux, Windows, and macOS. The README says to install it as a Python package through `pip`, and points to the User Guide for the complete system requirements. The repository metadata specifies Python `>=3.10, <4`, so a supported Python interpreter is part of the installation requirement.

The following is the quick-start flow documented in the README. First, create and enter an empty workspace:

mkdir workspace
cd workspace

The command creates the `workspace` directory and changes the current shell directory into it. The directory is intended to contain the FuseSoC workspace state rather than an HDL project copied from an arbitrary location.

Next, add the FuseSoC base library:

fusesoc library add fusesoc-cores https://github.com/fusesoc/fusesoc-cores

This registers the named library and its URL with the current workspace. The README then says to list the cores discovered there:

fusesoc core list

The expected result is a list of available cores. That result confirms that the workspace and library registration are being recognized. It does not prove that a simulator is installed or that a particular core will build successfully.

For the first real simulation, install one of the supported simulators, then use the documented command:

fusesoc run --target=sim i2c

The README identifies Icarus Verilog as the tool used by this example. A user with another supported simulator can select it explicitly:

fusesoc run --tool=modelsim --target=sim i2c

The command should invoke the selected external tool for the `i2c` core's simulation target. The README also documents `--tool=xcelium` as another option. The exact availability of each tool depends on the local installation and the configuration of the core library.

What the documented workflow can and cannot replace

FuseSoC is most useful when the same HDL is consumed through several workflows. The README explicitly connects it with simulation regressions, linting, formal verification, FPGA image creation, continuous integration, and portability between targets. That makes it a candidate for repositories containing reusable RTL or VHDL, especially when engineers want to describe supported targets and tool choices outside individual shell scripts.

There are real limits to that approach. A core must have enough metadata for FuseSoC to know what files belong to it, which targets and tools are valid, and how configurations are formed. The README does not show a complete `CAPI2` core file, nor does it explain migration rules for existing Makefiles or proprietary build scripts. Engineers should not assume that adding FuseSoC automatically makes an unsupported FPGA board or simulator work.

The project also does not remove external-tool licensing and setup. The commands select tools such as ModelSim and Xcelium, but the README does not state how those tools are installed or licensed. Likewise, the mention of FPGA SBOM generation identifies an integration path, not a complete compliance process. FuseSoC can produce or invoke the named filter flow, while responsibility for interpreting the resulting SBOM remains outside what the repository README documents.

This makes adoption a design decision rather than a simple installation. The practical question is whether the project has enough stable IP and target metadata to justify a shared abstraction. A one-off design with a single tool and no reuse may gain little from adding a package layer.

FuseSoC versus tool-specific HDL build scripts

The closest alternative is a repository-specific set of Makefiles or shell scripts for each simulator, synthesis tool, and FPGA target. That approach keeps the build close to the existing toolchain and can be very direct when a project has only one flow. It also avoids introducing FuseSoC core metadata and package-management conventions.

The difference is the source of truth. Tool-specific scripts encode commands and dependencies separately for each workflow. FuseSoC is intended to manage cores and expose targets through a common command surface, allowing a core library to be consumed by more than one project and tool. The README's `run --target=sim` examples demonstrate that shared selection model. The repository's CAPI2, parser, provider, and filter packages further indicate that the project is built around structured descriptions and extensions rather than one fixed Makefile.

That abstraction also introduces a compatibility cost. Existing projects may need their HDL files, dependencies, and target definitions represented in FuseSoC's format. The README does not document a migration utility or promise automatic conversion of arbitrary build scripts. Tool-specific scripts remain easier to understand when a project is small and has only one supported target. FuseSoC becomes more defensible when reuse, simulator variation, or CI consistency is a recurring requirement.

Maintenance, upgrades, and the permissive BSD-2-Clause license

The repository is not archived, and the last push was on 2026-10-15. Recent releases listed for the project are FuseSoC 2.4.7 on 2026-09-08, 2.4.6 on 2026-05-11, and 2.4.5 on 2025-11-13. These dates show recent repository activity and published releases, but they do not establish that every integration is compatible with every external tool.

The project metadata declares `requires-python = ">=3.10, <4"` and a set of Python dependencies. An upgrade can therefore involve Python compatibility, dependency changes, tool integration changes, and changes to the behavior expected by existing core libraries. The README points contributors to the Developer Guide, and the repository includes `NEWS`, which is the appropriate project-specific place to inspect before changing a pinned version. The README does not document a formal upgrade compatibility matrix, so teams should verify release notes and core-file requirements rather than assume that every upgrade is transparent.

FuseSoC is licensed under the permissive 2-clause BSD license. The README says this permits use, modification, and distribution, and directs readers to the `LICENSE` file for details. That statement concerns FuseSoC itself. It does not grant rights to external simulators, synthesis tools, board files, or third-party IP that a FuseSoC project may consume. License review should therefore cover both the FuseSoC dependency and every HDL core or external tool introduced by the build.

Editorial conclusion

Adopt FuseSoC when an FPGA or ASIC team needs reusable HDL packages and a common workflow across supported tools. Do not choose it as a replacement for the simulators, synthesis tools, or board-specific implementation flow themselves. Verify first that your HDL files can be represented by FuseSoC core files, that the required EDA tools are installed, and that the project license obligations are acceptable.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-2-Clause
3. olofk/fusesoc on GitHub
4. README
5. Releases