This refactors the Vulkan dockerfiles into a new base image (#12)

* This refactors the Vulkan dockerfiles into a new base image,
asciidoctor-spec.dockerfile, containing the entire toolchain with the
exception of the old Roswell implementation of the chunker. The tag is
changed since this will be useful for other Khronos spec repositories
with similar needs, like glTF.

It also supports a different naming convention, <tag>.dockerfile, as
well as Dockerfile.tag, since I was tired of tedious tab completion :-)

* Remove useless comments

README.md

@@ -3,19 +3,24 @@
 Docker container specifications which package dependencies for building
 Khronos documentation and software.
 
-Images built from this repo are pushed to https://hub.docker.com/r/khronosgroup/docker-images -
-Each Dockerfile corresponds to a tag, where the extension of the Dockerfile (e.g., `openxr`, `openxr-sdk`)
-matches the name of the tag.
+Images built from this github repository are pushed to the Dockerhub
+repository
+
+https://hub.docker.com/r/khronosgroup/docker-images
+
+Each Dockerfile is named in the form 'Dockerfile.<tag>' or
+'<tag>.dockerfile', where <tag> (e.g. `openxr`, `asciidoctor-spec`) matches
+the tag for that image in the Dockerhub repository.
 
 ## Scripts
 
 In general, any additional arguments are forwarded on to `docker build`,
 so this is how you can pass `--no-cache` to force a rebuild, etc.
 
 - Single-image scripts: pass a Dockerfile name as the first argument, the tag is automatically computed.
-  - `./build-one.sh` - Just builds and tags the image locally, does not push to Docker Hub.
+  - `./build-one.sh` - Just builds and tags the image locally, does not push to Dockerhub.
     Use for testing modifications.
-  - `./build-and-push-one.sh` - Builds and tags the image locally, then pushes it to Docker Hub.
+  - `./build-and-push-one.sh` - Builds and tags the image locally, then pushes it to Dockerhub.
     Only run this once you've committed (and ideally, pushed) the corresponding changes to this Git repo.
 - `./build-and-push-all.sh` - Just calls `./build-and-push-one.sh` on the Dockerfiles listed in it.
   If you add a new Dockerfile to this repo, add it to this script too.

Dockerfile.vulkan-docs-base → asciidoctor-spec.dockerfile

@@ -1,18 +1,11 @@
-# Copyright (c) 2019-2020 The Khronos Group Inc.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
+# Copyright 2019-2021 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
 
-# This is a Docker container for Vulkan specification builds
+# This defines a Docker image for building a set of Khronos specifications
+# written using asciidoctor markup.
+# It contains the asciidoctor toolchain, and related plugins and tools.
+# Some projects may have additional toolchain requirements, and will use
+# Docker images layered on this one.
 
 from ruby:2.7
 label maintainer="Jon Leech <[email protected]>"
@@ -21,7 +14,7 @@ label maintainer="Jon Leech <[email protected]>"
 # nodejs is actually installed in the next step
 run curl -sL https://deb.nodesource.com/setup_12.x | bash -
 
-# Install required Debian packages
+# Debian packages
 # pandoc is for potential use with Markdown
 # reuse is for repository license verification
 run apt-get update -qq && \
@@ -57,8 +50,10 @@ run apt-get update -qq && \
         python3-pytest \
         python3-termcolor \
         tcsh && \
-    apt-get clean && \
-    gem install -N \
+    apt-get clean
+
+# Ruby gems providing asciidoctor and related plugins
+run gem install -N \
         asciidoctor \
         asciidoctor-diagram \
         asciidoctor-mathematical \
@@ -67,23 +62,17 @@ run apt-get update -qq && \
         json-schema \
         i18n \
         prawn-gmagick \
+        pygments.rb \
         rouge \
-        text-hyphen && \
-    pip3 install pygments reuse
+        text-hyphen
 
-# Install chunked index generation scripts and add lunr to node searchpath
+# Python packages
+run pip3 install pygments reuse
+
+# JavaScript packages
 run npm install -g escape-string-regexp he [email protected]
 env NODE_PATH /usr/lib/node_modules
 
-# Install Roswell and asciidoctor-chunker. Need at least this specific
-# version (later may be OK, too). There seems to be no roswell APT
-# repository.
-run curl -fsSL -o roswell.deb https://github.com/roswell/roswell/releases/download/v20.01.14.104/roswell_20.01.14.104-1_amd64.deb && \
-    dpkg -i roswell.deb && \
-    ros install alexandria lquery cl-fad && \
-    mkdir -p $HOME/common-lisp && \
-    (cd $HOME/common-lisp && git clone https://github.com/wshito/asciidoctor-chunker.git)
-
 # Ensure the proper locale is installed and used - not present in ruby image
 # See https://serverfault.com/questions/54591/how-to-install-change-locale-on-debian#54597
 run apt-get install -y -qq locales && \

build-and-push-all.sh

@@ -1,13 +1,14 @@
 #!/bin/bash
-# Copyright (c) 2019-2021, The Khronos Group Inc.
+# Copyright 2019-2021 The Khronos Group Inc.
 # SPDX-License-Identifier: Apache-2.0
 
 set -e
 
 (
     cd $(dirname $0)
-    ./build-and-push-one.sh Dockerfile.vulkan-docs-base "$@"
-    ./build-and-push-one.sh Dockerfile.vulkan-docs "$@"
+    ./build-and-push-one.sh asciidoctor-spec.dockerfile "$@"
+    ./build-and-push-one.sh vulkan-docs-base.dockerfile "$@"
+    ./build-and-push-one.sh vulkan-docs.dockerfile "$@"
     ./build-and-push-one.sh Dockerfile.openxr-base.202102 "$@"
     ./build-and-push-one.sh Dockerfile.openxr.202102 "$@"
     ./build-and-push-one.sh Dockerfile.openxr-sdk.202102 "$@"

build-and-push-one.sh

@@ -1,9 +1,10 @@
 #!/bin/bash
-# Copyright (c) 2019-2021, The Khronos Group Inc.
+# Copyright 2019-2021, The Khronos Group Inc.
 # SPDX-License-Identifier: Apache-2.0
 
 # Pass a dockerfile name.
-# The dockerfile's extension is used as the tag within the repo.
+# The tag portion of the name is used as the tag within the repo.
+# Name format can be either tag.dockerfile or Dockerfile.tag
 
 set -e
 
@@ -14,6 +15,7 @@ REPO="khronosgroup/docker-images"
     DOCKERFILE=$1
     shift
     TAG=${DOCKERFILE#Dockerfile.}
+    TAG=${TAG%.dockerfile}
     if [ "$TAG" == "Dockerfile" ]; then
         TAG=latest
     fi

build-one.sh

@@ -1,9 +1,10 @@
 #!/bin/bash
-# Copyright (c) 2019-2021, The Khronos Group Inc.
+# Copyright 2019-2021, The Khronos Group Inc.
 # SPDX-License-Identifier: Apache-2.0
 
 # Pass a dockerfile name.
-# The dockerfile's extension is used as the tag within the repo.
+# The tag portion of the name is used as the tag within the repo.
+# Name format can be either tag.dockerfile or Dockerfile.tag
 
 set -e
 
@@ -14,5 +15,6 @@ REPO="khronosgroup/docker-images"
     DOCKERFILE=$1
     shift
     TAG=${DOCKERFILE#Dockerfile.}
+    TAG=${TAG%.dockerfile}
     docker build "$@" . -f "$DOCKERFILE" -t "$REPO:$TAG"
 )

entrypoint.vulkan.sh

@@ -39,6 +39,14 @@ fi
 export HOME=/home/$USER
 export USER
 
+# This is a temporary workaround until the JavaScript version of the chunker
+# is supported. If running as non-root, link to the neccessary user install
+# directories for the chunker.
+if test $USER != root ; then
+    ln -s /root/common-lisp $HOME/common-lisp
+    ln -s /root/.roswell $HOME/.roswell
+fi
+
 echo "HOME=$HOME USER=$USER CONTAINER_CWD=$CONTAINER_CWD"
 
 if [ "${CONTAINER_CWD}" ]; then

vulkan-docs-base.dockerfile

@@ -0,0 +1,22 @@
+# Copyright 2019-2021 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# This is a Docker container for Vulkan specification builds.
+# It just layers the Roswell implementation of the asciidoctor chunker onto
+# the asciidoctor-spec base image.
+
+from khronosgroup/docker-images:asciidoctor-spec
+label maintainer="Jon Leech <[email protected]>"
+
+# Install Roswell and asciidoctor-chunker.
+# We need at least this specific version of Roswell.
+# A specific commit of the chunker is pulled because the old Common Lisp
+# version of the chunker was moved after this commit.
+run curl -fsSL -o roswell.deb https://github.com/roswell/roswell/releases/download/v20.01.14.104/roswell_20.01.14.104-1_amd64.deb && \
+    dpkg -i roswell.deb && \
+    ros install alexandria lquery cl-fad
+run mkdir -p $HOME/common-lisp && \
+    cd $HOME/common-lisp && \
+    git clone https://github.com/wshito/asciidoctor-chunker.git && \
+    cd asciidoctor-chunker && \
+    git checkout -q e01f15ede36346924cd11adfa6a966183dbab412

vulkan-docs.dockerfile

@@ -0,0 +1,15 @@
+# Copyright 2019-2021 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# This is a Docker container for Vulkan specification builds
+
+from khronosgroup/docker-images:vulkan-docs-base
+label maintainer="Jon Leech <[email protected]>"
+
+# Add the entrypoint to the image, and ensure files installed in root (under
+# .roswell/ and common-lisp/) are accessible by the entrypoint when run as
+# other users.
+COPY entrypoint.vulkan.sh /root/entrypoint.vulkan.sh
+RUN chmod +x /root/entrypoint.vulkan.sh ; chmod go+rx /root
+
+ENTRYPOINT ["/root/entrypoint.vulkan.sh"]