Edalize turns one EDAM description into a Vivado, Icarus or Yosys project

One description in front of a stack of incompatible EDA tools

Every EDA tool wants the same ingredients and takes them in a different shape. Verilog and VHDL sources, constraint files, memory initialisation files, IP description files, a couple of defines, some top level parameters, then a build that produces a simulation model, a netlist or an FPGA image. The project file that expresses all of that is different in Icarus, Yosys, ModelSim, Vivado, Verilator, GHDL and Quartus, and configurations cannot be carried from one simulator to another. Edalize exists to remove that translation work. You describe what files you have and what you want parameterised, and the library produces the project files that the chosen tool needs and then offers to build and run it. The user it serves is the engineer whose design has to survive a change of simulator, or who wants to hand a colleague a project file they can open in the vendor GUI and keep working in by hand.

get_edatool turns an EDAM dictionary into a backend object

The core of the library is a small object protocol. The caller assembles a dictionary, called EDAM, holding the file list, the project name, the parameters and the top level. Edalize maps that dictionary onto a backend for the selected tool, and the backend object exposes the same sequence of calls regardless of which tool is underneath. The parameter model is where most of the practical work sits. Each entry names a datatype, a default where one exists, and a paramtype such as vlogparam or plusarg, which tells Edalize whether the value belongs at compile time or at run time. Runtime parameters can be changed after configuration by handing a new name and value to the run call, so a simulation can be re-run with different plusargs without regenerating the project. The package layout separates concerns that are often confused: edalize.tools holds the tool backends, while edalize.flows and edalize.build_runners are packaged separately, so build and run execution is not tied to any single simulator.

pip install -e . plus optional reporting extras

Edalize is a plain Python module, so installation is an editable install from a checkout:

    $ cd edalize
    $ python -m pip install -e .

The runtime dependency list is deliberately short. Jinja2 provides templating and importlib_metadata is pulled in only on Python older than 3.10, so the project supports Python 3.9 and later up to but not including 4. Reporting modules sit in an optional extra because they pull in a number of dependencies used for data analysis:

    $ python -m pip install -e ".[reporting]"

That extra brings pandas and pyparsing. If you only want to generate project files and drive a build, the base install is enough, and keeping the data analysis stack out of your environment is the practical reason the split exists. The build backend is setuptools with setuptools_scm, and the version is derived from git rather than hard coded, with setuptools_scm writing the value into edalize/version.py. The pyproject also installs a script called el_docker alongside the library, which the project ships for running the flow inside a container.

A blinky simulation driven by four backend calls

The worked example in the project documentation starts from a design with a Verilog source, a testbench and a synthesis constraints file, and targets Icarus Verilog. Files are registered with their type, here verilogSource, and their path computed relative to the work root so the generated project files work from inside the build directory:

  from edalize import *
  import os
  work_root = 'build'
  files = [
    {'name' : os.path.relpath('blinky.v', work_root),
     'file_type' : 'verilogSource'},
    {'name' : os.path.relpath('blinky_tb.v', work_root),
     'file_type' : 'verilogSource'},
    {'name' : os.path.relpath('vlog_tb_utils.v', work_root),
     'file_type' : 'verilogSource'}
  ]

Parameters follow, with a top level integer parameter carrying a default and a boolean plusarg for waveform dumping:

  parameters = {'clk_freq_hz' : {'datatype' : 'int', 'default' : 1000, 'paramtype' : 'vlogparam'},
                'vcd' : {'datatype' : 'bool', 'paramtype' : 'plusarg'}}
  tool = 'icarus'
  edam = {
    'files'        : files,
    'name'         : 'blinky_project',
    'parameters'   : parameters,
    'toplevel'     : 'blinky_tb'
  }

The backend object is fetched by tool name, and the flow is configure, build, run:

  backend = get_edatool(tool)(edam=edam,
                              work_root=work_root)
  os.makedirs(work_root)
  backend.configure()
  backend.build()
  args = {'vcd' : True}
  backend.run(args)

Two details are worth noting. configure writes the project files, and the documentation points out that at that point the files in the work root are usable without Edalize, so the generated project can be handed to a GUI. Second, the tool variable is a plain string. Changing icarus to modelsim or xsim is the entire exercise the documentation suggests, and whether it works cleanly is exactly what Edalize exists to answer.

Where the abstraction stops and tool flags reappear

The common interface is a convenience layer, not a superset language for every EDA tool. Anything that is genuinely tool specific still has to travel as tool specific options in the EDAM dictionary, and the documentation is explicit that options beyond files, parameters, defines, generics and VPI library sources are passed through as tool specific choices. That is the honest boundary of the abstraction. A design that leans on a corner of Vivado, on a proprietary linter, or on a simulator flag with no equivalent elsewhere will still need per tool configuration, and Edalize will not remove it. The library is also a Python library rather than a standalone command line program, so the documented usage is a script or the Python console. The project notes that a standalone mode is planned so that projects written in other languages can feed Edalize, which means today the integration path runs through Python code. For an engineer whose flow already lives in Python that is not a problem, and for anyone whose build scripts are in another language it is a reason to wait.

Version numbering by git tags and a permissive licence

Edalize is distributed under the BSD 2-Clause licence, a short permissive licence that allows redistribution and modification under its notice and warranty conditions, and the package classifiers record it as a BSD licence. The version number is dynamic, taken from the git tags by setuptools_scm, so a checkout gives you the tag it points at rather than a version written into a file by hand. Tagged releases include v0.6.1 on 2025-04-15, v0.6.4 on 2026-01-22 and v0.6.7 on 2026-04-20, and the last push was on 2026-09-15. That is a project whose changes arrive as occasional tagged drops rather than a fixed schedule, and the version in your environment can move when you pull a different tag, so pinning is worth doing if a build has to be reproducible. The documentation lives at edalize.readthedocs.io, and the source tree carries a NEWS file as the changelog plus tests, tox.ini and a pre-commit configuration.

Editorial conclusion

Adopt Edalize if you maintain HDL that must run on more than one simulator or flow and you want the tool choice reduced to a single string in a Python script. Do not adopt it to replace a vendor GUI, to cover a tool it does not implement, or to hide tool specific flags, since anything outside the common interface still has to be passed through. Before you commit, verify that the backend for your tool exists in edalize.tools, that the parameters your design uses map to a paramtype Edalize understands, and that your target Python version sits in the 3.9 to 4 range declared by the package.

Frequently asked questions

Official sources

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