readme: update guidelines, update container image names, add ref to mingw-w64-*-eda package groups

1 files changed, 48 insertions, 34 deletions

diff --git a/README.md b/README.md
index 5761bb0..07b71a5 100644
--- a/README.md
+++ b/README.md
@@ -8,13 +8,15 @@
   <a title="'push' workflow Status" href="https://github.com/ghdl/ghdl-yosys-plugin/actions?query=workflow%3Apush"><img alt="'push' workflow Status" src="https://img.shields.io/github/workflow/status/ghdl/ghdl-yosys-plugin/push?longCache=true&style=flat-square&label=push&logo=Github%20Actions&logoColor=fff"></a>
 </p>
 
-# ghdl-yosys-plugin: VHDL synthesis (based on [ghdl](https://github.com/ghdl/ghdl) and [yosys](https://github.com/YosysHQ/yosys))
+# ghdl-yosys-plugin: VHDL synthesis (based on [GHDL](https://github.com/ghdl/ghdl) and [Yosys](https://github.com/YosysHQ/yosys))
 
-**This is experimental and work in progress!** See [ghdl.rtfd.io: Using/Synthesis](http://ghdl.readthedocs.io/en/latest/using/Synthesis.html).
+**This is experimental and work in progress!** See [ghdl.github.io/ghdl: Using/Synthesis](http://ghdl.github.io/ghdl/using/Synthesis.html).
 
-- [Build as a module (shared library)](#build-as-a-module-shared-library)
+- [Build as a module](#build-as-a-module-shared-library)
+- [Build as part of Yosys](#build-as-part-of-yosys-not-recommended)
+- [Pre-built packages](#pre-built-packages)
 - [Usage](#Usage)
-- [Docker](#Docker)
+- [Containers](#Containers)
 
 > TODO: Create table with features of VHDL that are supported, WIP and pending.
 
@@ -22,8 +24,10 @@
 
 ## Build as a module (shared library)
 
-- Get and install [yosys](https://github.com/YosysHQ/yosys).
-- Get sources, build and install [ghdl](https://github.com/ghdl/ghdl). Ensure that GHDL is configured with synthesis features (enabled by default since v0.37). See [Building GHDL](https://github.com/ghdl/ghdl#building-ghdl).
+> On Windows, Yosys does not support loading modules dynamically. Therefore, this build approach is not possible. See [*Build as part of Yosys*](#build-as-part-of-yosys-not-recommended) below.
+
+- Get and install [Yosys](https://github.com/YosysHQ/yosys).
+- Get sources, build and install [GHDL](https://github.com/ghdl/ghdl). Ensure that GHDL is configured with synthesis features (enabled by default since v0.37). See [Building GHDL](https://github.com/ghdl/ghdl#building-ghdl).
 
 > NOTE: GHDL must be built with at least version of 8 GNAT (`gnat-8`).
 
@@ -37,7 +41,7 @@ The output is a shared library (`ghdl.so` on GNU/Linux), which can be used direc
 
 To install the module, the library must be copied to `YOSYS_PREFIX/share/yosys/plugins/ghdl.so`, where `YOSYS_PREFIX` is the installation path of yosys. This can be achieved through a make target: `make install`.
 
-Alternatively, the shared library can be copied/installed along with ghdl:
+Alternatively, the shared library can be copied/installed along with GHDL:
 
 ```sh
 cp ghdl.so "$GHDL_PREFIX/lib/ghdl_yosys.so"
@@ -46,9 +50,34 @@ yosys-config --exec mkdir -p --datdir/plugins
 yosys-config --exec ln -s "$GHDL_PREFIX/lib/ghdl_yosys.so" --datdir/plugins/ghdl.so
 ```
 
+## Build as part of yosys (not recommended)
+
+- Get and build GHDL as in the previous section.
+
+- Get [Yosys](https://github.com/YosysHQ/yosys) sources.
+
+- Get ghdl-yosys-plugin and:
+  - Copy `src/*` to `yosys/frontends/ghdl`.
+  - Configure Yosys by adding (to) `Makefile.conf`:
+
+```makefile
+ENABLE_GHDL := 1
+GHDL_DIR := <ghdl install dir>
+```
+
+- Build and install Yosys.
+
+## Pre-built packages
+
+Some projects provide pre-built packages including GHDL, Yosys and ghdl-yosys-plugin. Unless you have specific requirements (targeting a different arch, OS, build options...), we suggest using one of the following solutions before building ghdl-yosys-plugin from sources.
+
+- [open-tool-forge/fpga-toolchain](https://github.com/open-tool-forge/fpga-toolchain) provides tarballs for GNU/Linux, Windows or macOS, including statically built EDA tools. Packages are available for x86 or amd64.
+
+- On Windows, there is a package group in [MSYS2](https://www.msys2.org/) repositories named [mingw-w64-x86_64-eda](https://packages.msys2.org/group/mingw-w64-x86_64-eda)|[mingw-w64-i686-eda](https://packages.msys2.org/group/mingw-w64-i686-eda). See [hdl/MINGW-packages](https://github.com/hdl/MINGW-packages).
+
 ## Usage
 
-Example for icestick, using ghdl, yosys, nextpnr and icestorm:
+Example for IceStick, using GHDL, Yosys, nextpnr and icestorm:
 
 ```sh
 cd examples/icestick/leds/
@@ -58,7 +87,8 @@ ghdl -a leds.vhdl
 ghdl -a spin1.vhdl
 
 # Synthesize the design.
-# NOTE: if ghdl is built as a module, set MODULE to '-m ghdl' or '-m path/to/ghdl.so'
+# NOTE: if GHDL is built as a module, set MODULE to '-m ghdl' or '-m path/to/ghdl.so',
+#       otherwise, unset it.
 yosys $MODULE -p 'ghdl leds; synth_ice40 -json leds.json'
 
 # P&R
@@ -71,21 +101,21 @@ icepack leds.asc leds.bin
 iceprog leds.bin
 ```
 
-Alternatively, it is possible to analyze, elaborate and synthesize VHDL sources at once, instead of calling ghdl and yosys in two steps. In this example:
+Alternatively, it is possible to analyze, elaborate and synthesize VHDL sources at once, instead of calling GHDL and Yosys in two steps. In this example:
 
 ```
 yosys $MODULE -p 'ghdl leds.vhdl spin1.vhdl -e leds; synth_ice40 -json leds.json'
 ```
 
-## Docker
+## Containers
 
-Docker image [`ghdl/synth:beta`](https://hub.docker.com/r/ghdl/synth/tags) includes yosys and the ghdl module (shared library). These can be used to synthesize designs straightaway. For example:
+Container (aka Docker/Podman) image [`hdlc/ghdl:yosys`](https://hub.docker.com/r/hdlc/ghdl/tags) includes GHDL, Yosys and the ghdl-yosys-plugin module (shared library). These can be used to synthesize designs straightaway. For example:
 
 ```sh
 docker run --rm -t \
   -v $(pwd)/examples/icestick/leds:/src \
   -w /src \
-  ghdl/synth:beta \
+  hdlc/ghdl:yosys \
   yosys -m ghdl -p 'ghdl leds.vhdl blink.vhdl -e leds; synth_ice40 -json leds.json'
 ```
 
@@ -98,29 +128,13 @@ cd examples/icestick/leds/
 
 DOCKER_CMD="$(command -v winpty) docker run --rm -it -v /$(pwd)://wrk -w //wrk"
 
-$DOCKER_CMD ghdl/synth:beta     yosys -m ghdl -p 'ghdl leds.vhdl rotate4.vhdl -e leds; synth_ice40 -json leds.json'
-$DOCKER_CMD ghdl/synth:nextpnr  nextpnr-ice40 --hx1k --json leds.json --pcf leds.pcf --asc leds.asc
-$DOCKER_CMD ghdl/synth:icestorm icepack leds.asc leds.bin
+$DOCKER_CMD hdlc/ghdl:yosys    yosys -m ghdl -p 'ghdl leds.vhdl rotate4.vhdl -e leds; synth_ice40 -json leds.json'
+$DOCKER_CMD hdlc/nextpnr:ice40 nextpnr-ice40 --hx1k --json leds.json --pcf leds.pcf --asc leds.asc
+$DOCKER_CMD hdlc/icestorm      icepack leds.asc leds.bin
 
 iceprog leds.bin
 ```
 
-> NOTE: on GNU/Linux, it should be possible to use `iceprog` through `ghdl/synth:icestorm`. On Windows and macOS, accessing USB/COM ports of the host from containers seems not to be supported yet. Therefore, `iceprog` is required to be available on the host.
-
-## Build as part of yosys (not recommended)
-
-- Get and build ghdl as in the previous section.
-
-- Get [yosys](https://github.com/YosysHQ/yosys) sources.
-
-- Get ghdl-yosys-plugin and:
-  - Patch yosys sources using `yosys.diff`.
-  - Copy `src/*` to `yosys/frontends/ghdl`.
-  - Configure yosys by adding (to) `Makefile.conf`:
-
-```makefile
-ENABLE_GHDL := 1
-GHDL_DIR := <ghdl install dir>
-```
+See [hdl/containers](https://github.com/hdl/containers) for further info about containers including other EDA tools.
 
-- Build and install yosys.
+> NOTE: on GNU/Linux, it should be possible to use board programming tools through `hdlc/icestorm`. On Windows and macOS, accessing USB/COM ports of the host from containers is challenging. Therefore, board programming tools need to be available on the host. Windows users can find several board programming tools available as [MSYS2](https://www.msys2.org/) packages. See [mingw-w64-x86_64-eda](https://packages.msys2.org/group/mingw-w64-x86_64-eda)|[mingw-w64-i686-eda](https://packages.msys2.org/group/mingw-w64-i686-eda) and [hdl/MINGW-packages](https://github.com/hdl/MINGW-packages).