.. Copyright 2003-2025 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
Verilator Executable Docker Container
=====================================
The Verilator Executable Docker Container allows you to run Verilator
easily as a docker image, e.g.:
::
docker run -ti verilator/verilator:latest --version
This will pull the container from `Docker Hub
<https://hub.docker.com/r/verilator/verilator>`_, run the latest Verilator
and print Verilator's version.
Containers are automatically built and pushed to docker hub for all
released versions, so you may easily compare results across versions, e.g.:
::
docker run -ti verilator/verilator:4.030 --version
Verilator needs to read and write files on the local system. To simplify
this process, use the ``verilator-docker`` convenience script. This script
takes the version number, and all remaining arguments are passed through to
Verilator. e.g.:
::
./verilator-docker 4.030 --version
or
::
./verilator-docker 4.030 --cc test.v
If you prefer not to use ``verilator-docker`` you must give the container
access to your files as a volume with appropriate user rights. For example
to Verilate test.v:
::
docker run -ti -v ${PWD}:/work --user $(id -u):$(id -g) verilator/verilator:latest --cc test.v
This method can only access files below the current directory. An
alternative is setup the volume ``-workdir``.
You can also work in the container by setting the entrypoint (don't forget
to mount a volume if you want your work persistent):
::
docker run -ti --entrypoint /bin/bash verilator/verilator:latest
You can also use the container to build Verilator at a specific commit:
::
docker build --build-arg SOURCE_COMMIT=<commit> .
Internals
---------
The Dockerfile builds Verilator and removes the tree when completed to
reduce the image size. The entrypoint is a wrapper script
(``verilator-wrap.sh``). That script 1. calls Verilator, and 2. copies the
Verilated runtime files to the ``obj_dir`` or the ``-Mdir`` respectively.
This allows the user to have the files to they may later build the C++
output with the matching runtime files. The wrapper also patches the
Verilated Makefile accordingly.
A hook is also defined and run by Docker Hub via automated builds.
24117bc599