verilator/ci/docker/buildenv

= Verilator Build Environment

This container is set up to compile and test a Verilator build based
on 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 of current master:

    docker run -ti verilator/verilator-buildenv

To also run tests:

    docker run -ti verilator/verilator-buildenv test

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
....

You may want to avoid pushing your changes to a remote repository and
instead use a local working copy. You can mount the local working copy
path as a volume and use this as repo. Be careful, that it can only
use committed changes, so you may want to use a work-in-progress
commit or so. 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
....

== Under the Hood

To rebuild the image, simply run:

    docker build .

It will build SystemC in all supported compiler variants to reduce the
impact on testing cycles. A build script will be the entrypoint to the
container that will perform a standard build and test procedure.