Missing installation instructions

[olofk]

It would be great to have some quick instructions for getting started for people like me who haven't used docker all that much. I tried running docker pull ghdl/ghdl as it was mentioned here but I just get

Using default tag: latest
Error response from daemon: manifest for ghdl/ghdl:latest not found

so I guess there's something I'm missing

[olofk]

Aha, docker pull ghdl/ghdl:sid-gcc-9.1.0 did the trick. Is there a reason why the same image is built for three different linux distributions? Can I just pick any of them?

[eine]

Hi @olofk!

I tried running docker pull ghdl/ghdl as it was mentioned here

so I guess there's something I'm missing

There is no 'default' (ghdl/ghdl:latest) image; that's why docker pull ghdl/ghdl fails. It is unfortunate that dockerhub suggest the command without ensuring that a valid tag exists.

Aha, docker pull ghdl/ghdl:sid-gcc-9.1.0 did the trick. (...) Can I just pick any of them?

Yes, you can pick any of the 'ready-to-use' images. These are ghdl/ghdl:*, ghdl/vunit:*, ghdl/synth:* or ghdl/ext:*. For synth and ext repositories, latest tags exist. Hence, it won't fail:

docker pull ghdl/synth
docker pull ghdl/ext

Is there a reason why the same image is built for three different linux distributions?

We use docker images in CI environments to test that GHDL can be successfully built and executed in multiple distributions. Currently, we use the two latest versions of Debian, Ubuntu and Fedora. Plus, GHDL supports three different backends. Hence, we have a test matrix of 2 * 3 * 3 = 18 images. That's why there are at least 18 tags for ghdl/build, ghdl/run and ghdl/ghdl.

You can pick whichever you feel more comfortable with. However, there is precisely a reported issue about ghdl/ghdl:sid-gcc-9.1.0 (see ghdl/ghdl#883). We use Debian Buster as a reference to build other images (such as ghdl/synth:*, ghdl/vunit:* or ghdl/ext:*), so you might want to stick with it. Regarding the backend, I normally suggest to use mcode, unless you need to generate executable binaries or if your host arch is not x86. Then, use LLVM. GCC is only suggested if you need code coverage.

It would be great to have some quick instructions for getting started for people like me who haven't used docker all that much.

In the current master branch, there is USE_CASES.md. See section Let's have some fun!. Note that some of the tags mentioned there might not exist anymore (such as ghdl/ghdl:stretch* or ghdl/ghdl:ubuntu14* or ghdl/ext:vunit*).

There is WIP in my fork: https://github.com/1138-4EB/ghdl-docker. You will find that the README contains more details about which tags (images) you will find in each repository and which is the content/tools available in each of them. I expect to merge it here when GitHub Actions are enabled for the GHDL organization.

Regarding 'experimental' features of GHDL. In https://github.com/ghdl/ghdl-language-server#ready-to-use-docker-images you will find instructions to use ghdl/ext:latest. It includes GHDL with LLVM backend, LSP server, LSP client for VSCode, VUnit and GtkWave. There is a screencast in Gitter June 17, 2019 4:33 PM. By the same token, in https://github.com/tgingold/ghdlsynth-beta#docker you will find instructions to use ghdl/synth:* images.

As you see, this is mostly a utility repo, where we create docker images that are used in other repositories of the organization (or of @tgingold). Hence, it is unlikely that we provide better documentation for users who are new to docker. However, as commented in ghdl/ghdl#166 (comment), and in August 15, 2019 1:36 PM, it'd be great to have documentation properly added to https://ghdl.rtfd.io. That's what we'll try to do if we ever have time.

[eine]

@olofk, you might find the Makefile in https://github.com/antonblanchard/ghdl-yosys-blink (#21), as it shows how to generate a bitstream from VHDL sources, using the images provided in this repo.

[olofk]

Thanks. I hope to find some time to play with that at some point. But I guess the original issue can be closed now as I managed to get it running after learning a bit more about how docker works