verilator/ci/docker/buildenv/README.adoc

= Verilator Docker Build Environment

This Verilator Build container is set up to compile and test a Verilator
build. It uses the following parameters:

* Source repository (default: https://github.com/verilator/verilator)
* Source revision (default: master)
* GCC version (4.8.5, 5.5.0, 6.5.0, 7.4.0, default: 7.4.0)

The container is published as `verilator/verilator-buildenv` on
https://hub.docker.com/repository/docker/verilator/verilator-buildenv[docker hub].

To run the basic build using the current Verilator master:

    docker run -ti verilator/verilator-buildenv

To also run tests:

    docker run -ti verilator/verilator-buildenv test

To change the compiler:

    docker run -ti -e CC=gcc-4.8 -e CXX=g++-4.8 verilator/verilator-buildenv test

The tests that involve gdb are not working due to security restrictions.
To run those too:

....
docker run -ti -v ${PWD}:/tmp/repo -e REPO=/tmp/repo -e REV=`git rev-parse --short HEAD` -e CC=gcc-4.8 -e CXX=g++-4.8 --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
....

Rather then building using a remote git repository you may prefer to use a
working copy on the local filesystem. Mount the local working copy path as
a volume and use that in place of git. When doing this be careful to have
all changes committed to the local git area. To build the current HEAD from
top of a repository:

....
docker run -ti -v ${PWD}:/tmp/repo -e REPO=/tmp/repo -e REV=`git rev-parse --short HEAD` --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
....

== Rebuilding

To rebuild the Verilator-buildenv docker image, run:

    docker build .

This will also build SystemC under all supported compiler variants to
reduce the SystemC testing time.