ghdl / docker

This repository contains scripts and YAML workflows for GitHub Actions (GHA) to build and to deploy the docker 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 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. GHDL is built with the experimental --synth feature enabled.
• images, which are based on ghdl/ghdl:buster-* 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 (8 jobs -max 4-, 40 images) [twice a month]

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

• A pair of images is created in one job for each of [ ls-debian, ls-ubuntu ].
• One job is created for each of [ fedora (33 | 34), debian (buster | bullseye), ubuntu (18 | 20)], 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.

· test (15 jobs -max 3-, 30 images) [weekly]

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: [33, 34], debian: [bullseye], ubuntu: [18, 20] ] and [mcode, llvm*].
• [ fedora: [33, 34], debian: [buster, bullseye] ] and [gcc*].
• For Debian only, [buster, bullseye] and [mcode] and [--gpl].

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.

· buster (3 jobs -max 3-, 6 images) [triggered by ghdl/ghdl nightly job]

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 [ buster ] and [ mcode, llvm-7 , gcc-8.3.0 ].

ghdl/debug is created in the mcode job.

· vunit (1 job, 6 images) [triggered after workflow 'buster']

Build and push all the ghdl/vunit:* images, which are based on the ones created in the 'buster' 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 (3 jobs -max 2-, 6 images) [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 [weekly]

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

• ghdl/cosim:mcode: based on ghdl/ghdl:buster-mcode, includes GCC.
• ghdl/cosim:py: based on ghdl/ghdl:buster-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:py, includes pytest, matplotlib, numpy and Imagemagick.
  • ghdl/cosim:octave: based on ghdl/cosim:py, includes GNU Octave.
  • ghdl/cosim:xyce: based on ghdl/cosim:py, includes Xyce.

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

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-buster instead of debian:buster-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.