Awesome

This repository contains scripts and YAML workflows for GitHub Actions (GHA) to build and to deploy the container images that are used and/or published by the GHDL GitHub organization. All of them are pushed to hub.docker.com/u/ghdl.

ATTENTION: Some images related to synthesis and PnR were moved to hdl/containers and hub.docker.com/u/hdlc. See DEPRECATED.

Images for development (i.e., building and/or testing ghdl):

• images include development/build depedendencies for ghdl.
• images include runtime dependencies for ghdl.
• images include the content of ghdl tarballs built in ghdl/build images.
• image is based on ghdl/build:buster-mcode and ghdl/pkg:buster-mcode; includes Python pip, GNAT GPS, Graphviz and GDB.

Ready-to-use images:

• images, which are based on correponding ghdl/run images, include ghdl along with minimum runtime dependencies.
• images, which are based on ghdl/ghdl:bookworm-* images, include ghdl along with VUnit.
  • *-master variants include latest VUnit (master branch), while others include the latest stable release (installed through pip).
• GHDL and complements (ghdl-language-server, GtkWave, VUnit, etc.).
• GHDL and other tools for co-simulation such as SciPy, Xyce or GNU Octave.

See USE_CASES.md if you are looking for usage examples from a user perspective.

GHA workflows

· base

Build and push all the ghdl/build:* and ghdl/run:* docker images. :

• A pair of images is created in one job for [ ls ].
• One job is created for each of [ fedora (37 | 38), debian (buster | bullseye | bookworm), ubuntu (20 | 22)], and six images are created in each job; two (ghdl/build:*, ghdl/run:*) for each supported backend [ mcode, llvm*, gcc ].
  • ghdl/debug:base is created in the debian buster job.
  • ghdl/build:doc is created in the debian bookworm job.

· test

Build and push almost all the ghdl/ghdl:* and ghdl/pkg:* images. A pair of images is created in one job for each combination of:

• [ fedora: [37, 38], debian: [bullseye], ubuntu: [20, 22] ] and [mcode, llvm*].
• [ fedora: [37, 38], debian: [bullseye] ] and [gcc*].
• For Debian only, [bullseye, bookworm] and [mcode] and [--gpl].
• For Debian Buster, only [mcode].
  • ghdl/debug is created in this job.

The procedure in each job is as follows:

• Repo ghdl/ghdl is cloned.
• ghdl is built in the corresponding ghdl/build:* image.
• A ghdl/ghdl:* image is created based on the corresponding ghdl/run:* image.
• The testsuite is executed inside the ghdl/ghdl:* image created in the previous step.
• If successful, a ghdl/pkg:* image is created from scratch, with the content of the tarball built in the first step.
• ghdl/ghdl:* and ghdl/pkg:* images are pushed to hub.docker.com/u/ghdl.

NOTE: images with GCC backend include lcov for code coverage analysis.

· bookworm [scheduled daily]

Complement of ghdl.yml, to be run after each successful run of the main workflow in ghdl/ghdl. One job is scheduled for each combination of [ bookworm ] and [ mcode, llvm-14 , gcc-12.3.0 ].

· vunit [triggered after workflow 'bookworm']

Build and push all the ghdl/vunit:* images, which are based on the ones created in the 'bookworm' workflow.

• Two versions are published for each backend: one with latest stable VUnit (from PyPI) and one with the latest master (from Git).
• Images with GCC backend include lcov and gcovr for code coverage analysis.

· ext [triggered after workflow 'vunit']

Build and push all the ghdl/ext:* images:

• ls: ghdl/ext:ls-debian and ghdl/ext:ls-ubuntu (a job for each of them). These include ghdl/ghdl, the ghdl/ghdl-language-server backend and the vscode-client (precompiled but not preinstalled).
• gui:
  • ghdl/ext:gtkwave: includes GtkWave (gtk3) on top of ghdl/vunit:llvm-master.
  • ghdl/ext:broadway: adds a script to ghdl/ext:gtkwave in order to launch a Broadway server that allows to use GtkWave from a web browser.
  • ghdl/ext:ls-vunit: includes VUnit (master) on top of ghdl/ext:ls-debian.
  • ghdl/ext:latest: includes GtkWave on top of ghdl/ext:ls-vunit.

· cosim

See ghdl/ghdl-cosim: docker and ghdl.github.io/ghdl-cosim/vhpidirect/examples/vffi_user.

• ghdl/cosim:mcode: based on ghdl/ghdl:bookworm-mcode, includes GCC.
• ghdl/cosim:py: based on ghdl/ghdl:bookworm-llvm-7, includes Python.
  • ghdl/cosim:vunit-cocotb: based on ghdl/cosim:py, includes VUnit, cocotb and g++ (required by cocotb).
    • ghdl/cosim:matplotlib: based on ghdl/cosim:vunit-cocotb, includes pytest, matplotlib, numpy and Imagemagick.
    • ghdl/cosim:octave: based on ghdl/cosim:vunit-cocotb, includes GNU Octave.
    • ghdl/cosim:xyce: based on ghdl/cosim:vunit-cocotb, includes Xyce.

NOTE: *-slim variants of matplotlib, octave and xyce images are provided too. Those are based on ghdl/cosim:py, instead of ghdl/cosim:vunit-cocotb.

Packaging

Multiple artifacts of GHDL are generated in these workflows. For example, each job in test.yml generates a tarball that is then installed in a ghdl/ghdl:* image, and the content is published in a ghdl/pkg:* image. These resources might be useful for users/developers who:

• Want to use a base image which is compatible but different from the ones we use. E.g., use python:3-slim-bookworm instead of debian:bookworm-slim.
• Do not want to build and test GHDL every time.

However, it is discouraged to use these pre-built artifacts to install GHDL on host systems.