diff --git a/ci/docker/buildenv/README.adoc b/ci/docker/buildenv/README.adoc index edb3e2b5a..c4747c890 100644 --- a/ci/docker/buildenv/README.adoc +++ b/ci/docker/buildenv/README.adoc @@ -1,7 +1,7 @@ -= Verilator Build Environment += Verilator Docker Build Environment -This container is set up to compile and test a Verilator build based -on the following parameters: +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) @@ -10,7 +10,7 @@ on the following parameters: 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: +To run the basic build using the current Verilator master: docker run -ti verilator/verilator-buildenv @@ -18,7 +18,7 @@ To also run tests: docker run -ti verilator/verilator-buildenv test -Change the compiler: +To change the compiler: docker run -ti -e CC=gcc-4.8 -e CXX=g++-4.8 verilator/verilator-buildenv test @@ -29,22 +29,21 @@ 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: +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 .... -== Under the Hood +== Rebuilding -To rebuild the image, simply run: +To rebuild the Verilator-buildenv docker image, 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. +This will also build SystemC under all supported compiler variants to +reduce the SystemC testing time. diff --git a/ci/docker/run/README.adoc b/ci/docker/run/README.adoc index 82793b878..84321ac06 100644 --- a/ci/docker/run/README.adoc +++ b/ci/docker/run/README.adoc @@ -1,49 +1,59 @@ -= Docker Container as Verilator executable += Verilator Executable Docker Container -This allows you to run Verilator easily as a docker image, e.g.: +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 is in particular useful to compare against older version or to -check when an issue was introduced. +This will install the container, run the latest Verilator and print +Verilator's version. -You will need to give it access to your files as a volume and fix the -user rights: +Containers are automatically built 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 .... -The caveat is that it can only access files below the current -directory then, a workaround is to adopt the volume and set -`-workdir`. +This method can only access files below the current directory. An +alternative is setup the volume `-workdir`. -There is a convenience script in this folder that wraps around the -docker calls: - - $ verilator-docker 3.922 --version - Verilator 3.922 2018-03-17 rev UNKNOWN_REV - -Finally, you can also work in the container by setting the entrypoint +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 -The other files in this folder all for building the containers and to -store in them. You could use it to build Verilator at a specific +You can also use the container to build Verilator at a specific commit: docker build --build-arg SOURCE_COMMIT= . == Internals -The Dockerfile is pretty straight-forward, it builds Verilator and -removes the tree after that to reduce the image size. It sets a -wrapper script (`verilator-wrap.sh`) as entrypoint. This script calls -Verilator but also copies the verilated runtime files to the `obj_dir` -or the `-Mdir` respectively. This allows the user to build the C++ -output with the matching runtime files. The wrapper patches the -generated Makefile accordingly. +The Dockerfile builds Verilator and removes the tree when completed to +reduce the image size. The entrypoint is set as 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. There is also a hook defined that is run by docker hub via automated builds.