search

ghdl / docker

Scripts to build and use docker images including GHDL
40 stars 10 forks source link

Missing installation instructions #15

Closed olofk closed 4 years ago

olofk commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 https://github.com/ghdl/ghdl/issues/166#issuecomment-494016333, 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 commented 4 years ago

@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 commented 4 years ago

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