Add Docker infrastructure (#2087)

This adds files to build and run two Docker images:

 - run: Build a Docker container that can be used as an executable
        drop-in for verilator. This can be useful to test behavior of
        older versions or a development version. The functionality is
        pretty simplistic at the moment for a start.

 - buildenv: Everything needed to build and test Verilator. Useful to
        run quick tests in the cloud or try other compilers. It can
        also serve as basis for further CI integration.

ci/docker/buildenv/Dockerfile

@@ -0,0 +1,57 @@
+# DESCRIPTION: Dockerfile for env to build and fully test Verilator
+#
+# Copyright 2020 by Stefan Wallentowitz. This program is free
+# software; you can redistribute it and/or modify it under the terms
+# of either the GNU Lesser General Public License Version 3 or the
+# Perl Artistic License Version 2.0.
+
+FROM ubuntu:18.04
+
+RUN apt-get update \
+    && DEBIAN_FRONTEND=noninteractive \
+       apt-get install --no-install-recommends -y \
+                        autoconf=2.69-11 \
+                        bc=1.07.1-2 \
+                        bison=2:3.0.4.dfsg-1build1 \
+                        build-essential=12.4ubuntu1 \
+                        ca-certificates=20180409 \
+                        cmake=3.10.2-1ubuntu2.18.04.1 \
+                        flex=2.6.4-6 \
+                        gdb=8.1-0ubuntu3.2 \
+                        gcc-6=6.5.0-2ubuntu1~18.04 \
+                        gcc-5=5.5.0-12ubuntu1 \
+                        gcc-4.8=4.8.5-4ubuntu8 \
+                        git=1:2.17.1-1ubuntu0.5 \
+                        gtkwave=3.3.86-1 \
+                        g++-6=6.5.0-2ubuntu1~18.04 \
+                        g++-5=5.5.0-12ubuntu1 \
+                        g++-4.8=4.8.5-4ubuntu8 \
+                        libfl2=2.6.4-6 \
+                        libfl-dev=2.6.4-6 \
+                        numactl=2.0.11-2.1ubuntu0.1 \
+                        perl=5.26.1-6ubuntu0.3 \
+                        python3=3.6.7-1~18.04 \
+                        wget=1.19.4-1ubuntu2.2 \
+                        zlibc=0.9k-4.3 \
+                        zlib1g=1:1.2.11.dfsg-0ubuntu2 \
+                        zlib1g-dev=1:1.2.11.dfsg-0ubuntu2 \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /tmp
+
+COPY build-systemc.sh /tmp/
+RUN ./build-systemc.sh
+
+RUN cpan install -fi Unix::Processors Parallel::Forker Bit::Vector
+
+RUN git clone https://github.com/veripool/vcddiff.git && \
+    make -C vcddiff && \
+    cp -p vcddiff/vcddiff /usr/local/bin/vcddiff && \
+    rm -rf vcddiff
+
+COPY build.sh /tmp/build.sh
+
+ENV VERILATOR_AUTHOR_SITE=1
+
+ENTRYPOINT [ "/tmp/build.sh" ]

ci/docker/buildenv/README.adoc

@@ -0,0 +1,50 @@
+= 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.

ci/docker/buildenv/build-systemc.sh

@@ -0,0 +1,29 @@
+#!/bin/bash -e
+# DESCRIPTION: Build SystemC in Ubuntu 18.04 with  different g++/gcc
+#
+# Copyright 2020 by Stefan Wallentowitz. This program is free
+# software; you can redistribute it and/or modify it under the terms
+# of either the GNU Lesser General Public License Version 3 or the
+# Perl Artistic License Version 2.0.
+
+build_variant () {
+    version=$($1 --version | grep gcc | awk '{print $4}')
+    mkdir "/usr/local/systemc-2.3.3-gcc$version"
+    mkdir build
+    cd build
+    ../configure --prefix="/usr/local/systemc-2.3.3-gcc$version" CC="$1" CXX="$2" LD="$2"
+    make -j
+    make install
+    cd ..
+    rm -r build
+}
+
+wget https://www.accellera.org/images/downloads/standards/systemc/systemc-2.3.3.tar.gz
+tar -xzf systemc-2.3.3.tar.gz
+cd systemc-2.3.3
+build_variant gcc g++
+build_variant gcc-6 g++-6
+build_variant gcc-5 g++-5
+build_variant gcc-4.8 g++-4.8
+cd ..
+rm -r systemc-2.3.3*

ci/docker/buildenv/build.sh

@@ -0,0 +1,30 @@
+#!/bin/bash -e
+# DESCRIPTION: Build Verilator (inside container)
+#
+# Copyright 2020 by Stefan Wallentowitz. This program is free
+# software; you can redistribute it and/or modify it under the terms
+# of either the GNU Lesser General Public License Version 3 or the
+# Perl Artistic License Version 2.0.
+
+: "${REPO:=https://github.com/verilator/verilator}"
+: "${REV:=master}"
+: "${CC:=gcc}"
+: "${CXX:=g++}"
+
+GCCVERSION=$(${CC} --version | grep gcc | awk '{print $4}')
+
+export SYSTEMC_INCLUDE="/usr/local/systemc-2.3.3-gcc${GCCVERSION}/include"
+export SYSTEMC_LIBDIR="/usr/local/systemc-2.3.3-gcc${GCCVERSION}/lib-linux64"
+export LD_LIBRARY_PATH=${SYSTEMC_LIBDIR}
+
+SRCS=$PWD/verilator
+
+git clone "$REPO" "$SRCS"
+cd "$SRCS"
+git checkout "$REV"
+autoconf
+./configure --enable-longtests
+make -j $(nproc)
+if [ "${1:-''}" == "test" ]; then
+    make test
+fi

ci/docker/run/Dockerfile

@@ -0,0 +1,47 @@
+# DESCRIPTION: Dockerfile for image to run Verilator inside
+#
+# Copyright 2020 by Stefan Wallentowitz. This program is free
+# software; you can redistribute it and/or modify it under the terms
+# of either the GNU Lesser General Public License Version 3 or the
+# Perl Artistic License Version 2.0.
+
+FROM ubuntu:18.04
+
+RUN apt-get update \
+    && apt-get install --no-install-recommends -y \
+                        autoconf=2.69-11 \
+                        bc=1.07.1-2 \
+                        bison=2:3.0.4.dfsg-1build1 \
+                        build-essential=12.4ubuntu1 \
+                        ca-certificates=20180409 \
+                        flex=2.6.4-6 \
+                        git=1:2.17.1-1ubuntu0.5 \
+                        libfl-dev=2.6.4-6 \
+                        perl=5.26.1-6ubuntu0.3 \
+                        python3=3.6.7-1~18.04 \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+ARG REPO=https://github.com/verilator/verilator
+ARG SOURCE_COMMIT=master
+
+WORKDIR /tmp
+
+# Add an exception for the linter, we want to cd here in one layer
+# to reduce the number of layers (and thereby size).
+# hadolint ignore=DL3003
+RUN git clone "${REPO}" verilator && \
+    cd verilator && \
+    git checkout "${SOURCE_COMMIT}" && \
+    autoconf && \
+    ./configure && \
+    make -j "$(nproc)" && \
+    make install && \
+    cd .. && \
+    rm -r verilator
+
+COPY verilator-wrap.sh /usr/local/bin/verilator-wrap.sh
+
+WORKDIR /work
+
+ENTRYPOINT [ "/usr/local/bin/verilator-wrap.sh" ]

ci/docker/run/README.adoc

@@ -0,0 +1,49 @@
+= Docker Container as Verilator executable
+
+This 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.
+
+You will need to give it access to your files as a volume and fix the
+user rights:
+
+....
+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`.
+
+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
+(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
+commit:
+
+    docker build --build-arg SOURCE_COMMIT=<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.
+
+There is also a hook defined that is run by docker hub via automated
+builds.

ci/docker/run/hooks/build

@@ -0,0 +1,9 @@
+#!/bin/bash
+# DESCRIPTION: Docker hub hook to pass SOURCE_COMMIT
+#
+# Copyright 2020 by Stefan Wallentowitz. This program is free
+# software; you can redistribute it and/or modify it under the terms
+# of either the GNU Lesser General Public License Version 3 or the
+# Perl Artistic License Version 2.0.FROM ubuntu:18.04
+
+docker build --build-arg SOURCE_COMMIT=${SOURCE_COMMIT} -f $DOCKERFILE_PATH -t $IMAGE_NAME .

ci/docker/run/verilator-docker

@@ -0,0 +1,10 @@
+#!/bin/bash
+# DESCRIPTION: Wrap a verilator call to run a docker container
+#
+# Copyright 2020 by Stefan Wallentowitz. This program is free
+# software; you can redistribute it and/or modify it under the terms
+# of either the GNU Lesser General Public License Version 3 or the
+# Perl Artistic License Version 2.0.
+
+docker pull verilator/verilator:$1 >/dev/null
+docker run -ti -v ${PWD}:/work --user $(id -u):$(id -g) verilator/verilator:$1 "${@:2}"

ci/docker/run/verilator-wrap.sh

@@ -0,0 +1,26 @@
+#!/bin/bash -e
+# DESCRIPTION: Wrap a Verilator call and copy vlt includes
+#              (inside docker container)
+#
+# Copyright 2020 by Stefan Wallentowitz. This program is free
+# software; you can redistribute it and/or modify it under the terms
+# of either the GNU Lesser General Public License Version 3 or the
+# Perl Artistic License Version 2.0.
+
+perl /usr/local/bin/verilator "$@"
+
+# Check if user set an obj_dir
+obj_dir=$(echo " $@" | grep -oP '\s--Mdir\s*\K\S+')
+if [ "$obj_dir" == "" ]; then
+    obj_dir="obj_dir"
+fi
+
+# If the run was successful: Copy required files to allow build without this container
+if [ -e ${obj_dir} ]; then
+    # Copy files required for the build
+    mkdir -p ${obj_dir}/vlt
+    cp -r /usr/local/share/verilator/bin ${obj_dir}/vlt
+    cp -r /usr/local/share/verilator/include ${obj_dir}/vlt
+    # Point Makefile to that folder
+    perl -i -pe 's/VERILATOR_ROOT = \/usr\/local\/share\/verilator/VERILATOR_ROOT = vlt/g' ${obj_dir}/*.mk
+fi