Allow using Docker to build

Closes whatwg#55. Supercedes whatwg/html#612.

Author: defunctzombie

Diff for: .dockerignore

@@ -0,0 +1,5 @@
+.git/
+.cache/
+.temp/
+output/
+html/.git/

Diff for: Dockerfile

@@ -0,0 +1,39 @@
+FROM debian:sid
+
+## dependency installation: apache, wattsi, and other build tools
+## enable some apache mods (the ln -s lines)
+## cleanup freepascal since it is no longer needed after wattsi build
+RUN apt-get update && \
+    apt-get install -y ca-certificates curl git unzip fp-compiler-3.0.0 apache2 && \
+    cd /etc/apache2/mods-enabled && \
+    ln -s ../mods-available/headers.load && \
+    ln -s ../mods-available/expires.load && \
+    git clone https://github.com/whatwg/wattsi.git /whatwg/wattsi && \
+    cd /whatwg/wattsi && \
+    /whatwg/wattsi/build.sh && \
+    cp /whatwg/wattsi/bin/wattsi /bin/ && \
+    apt-get purge -y fp-compiler-3.0.0 && \
+    apt-get autoremove -y && \
+    rm -rf /var/lib/apt/lists/*
+
+ADD . /whatwg/build
+
+ARG html_source_dir
+ADD $html_source_dir /whatwg/html
+ENV HTML_SOURCE /whatwg/html
+
+WORKDIR /whatwg/build
+
+## build and copy assets to final apache dir
+
+ARG verbose_or_quiet_flag
+ARG no_update_flag
+
+# no_update_flag doesn't really work; .cache directory is re-created empty each time
+RUN SKIP_BUILD_UPDATE_CHECK=true ./build.sh $verbose_or_quiet_flag $no_update_flag && \
+    rm -rf /var/www/html && \
+    mv output /var/www/html && \
+    chmod -R o+rX /var/www/html && \
+    cp site.conf /etc/apache2/sites-available/000-default.conf
+
+CMD ["apache2ctl", "-DFOREGROUND"]

Diff for: README.md

@@ -2,34 +2,39 @@
 
 This repository contains the tools and instructions necessary for building the [HTML Standard](https://html.spec.whatwg.org/multipage/) from its [source](https://github.com/whatwg/html).
 
-## Prerequisites
+## Getting set up
 
-Before building, make sure you have the following commands installed on your system.
+Make sure you have `git` installed on your system, and you are using a Bash shell. (On Windows, `cmd.exe` will not work, but the Git Bash shell that comes with [Git for Windows](https://git-for-windows.github.io/) works nicely.)
 
-- `curl`, `git`, `grep`, `perl`, `unzip`
+Then, clone this ([html-build](https://github.com/whatwg/html-build)) repo:
 
-Optionally, for faster builds, you can install [Wattsi](https://github.com/whatwg/wattsi) on your system. If you don't bother with that, the build will use [Wattsi Server](https://github.com/domenic/wattsi-server).
+```
+git clone https://github.com/whatwg/html-build.git && cd html-build
+```
+
+You then have a decision to make as to how you want to do your builds: locally, on your computer, or using a [Docker](https://www.docker.com/) container. We suggest going the Docker route if and only if you are already comfortable with Docker.
 
-## Build
+## Building locally
 
-Building your own copy of the HTML Standard from its source requires just these simple steps:
+### Prerequisites
 
-1. If you want to submit a pull request to the [whatwg/html](https://github.com/whatwg/html) repo, fork it and clone your fork. (If not, you can skip this step.)
- ```
- git clone https://github.com/<username>/html.git
- ```
+To build locally, you'll need the following commands installed on your system:
 
-1. Clone this ([html-build](https://github.com/whatwg/html-build)) repo:
- ```
- git clone https://github.com/whatwg/html-build.git && cd html-build
- ```
+- `curl`, `grep`, `perl`, `unzip`
 
-1. Run the `build.sh` script from inside your `html-build` working directory, like this:
- ```
- ./build.sh
- ```
+Optionally, for faster builds, you can install [Wattsi](https://github.com/whatwg/wattsi). If you don't bother with that, the build will use [Wattsi Server](https://github.com/domenic/wattsi-server), which requires an internet connection.
 
-## Output
+### Running the build
+
+Run the `build.sh` script from inside your `html-build` working directory, like this:
+
+```
+./build.sh
+```
+
+The first time this runs, it will ask for your input on where to clone the HTML source from, or where on your system to find it if you've already done that. If you're working to submit a pull request to [whatwg/html](https://github.com/whatwg/html), be sure to give it the URL of your fork.
+
+### Output
 
 After you complete the build steps above, the build will run and generate the single-page version of the spec, the multipage version, and more. If all goes well, you should very soon have all the following in your `output/` directory:
 
@@ -42,16 +47,36 @@ After you complete the build steps above, the build will run and generate the si
 - `link-fixup.js`
 - `multipage/*`
 
-And then you're also ready to edit the `html/source` file—and after you make your changes, you can run the `build.sh` script again to see the new output.
+Now you're ready to edit the `html/source` file—and after you make your changes, you can run the `build.sh` script again to see the new output.
+
+## Building using a Docker container
+
+The Dockerized version of the build allows you to run the build entirely inside a "container" (lightweight virtual machine). This includes tricky dependencies like a local copy of Wattsi, as well as the Apache HTTP server with a setup analogous to that of https://html.spec.whatwg.org.
 
-## Options
+To perform a Dockerized build, use the `--docker` flag:
+
+```
+./build.sh --docker
+```
+
+The first time you do this, Docker will download a bunch of stuff to set up the container properly, but subsequent runs will simply build the standard and be very fast.
+
+After building the standard, this will launch a HTTP server that allows you to view the result at `http://localhost:8080`. (OS X and Windows users will need to use the IP address of their docker-machine VM instead of `localhost`. You can get this with the `docker-machine env` command.)
+
+Note that due to the way Docker works, the HTML source repository must be contained in a subdirectory of the `html-build` working directory. This will happen automatically if you let `build.sh` clone for you, but if you have a preexisting clone you'll need to move it.
+
+## A note on Git history
+
+Your clone doesn't need the HTML standard's complete revision history just for you to build the spec and contribute patches. So, if you use `build.sh` to create the clone, we don't start you out with a clone of the history. That makes your first build finish much faster. And if later you decide you do want to clone the complete history, you can still get it, by doing this:
 
-Your clone doesn't need the HTML standard's complete revision history just for you to build the spec and contribute patches. So, by default we don't start you out with a clone of the history. That makes your first build finish much faster. And if later you decide you do want to clone the complete history, you can still get it, by doing this:
 ```
 cd ./html && git fetch --unshallow
 ```
+
 That said, if you really do want to *start out* with the complete history of the repo, then run the build script for the first time like this:
+
 ```
 HTML_GIT_CLONE_OPTIONS="" ./build.sh
 ```
+
 That will clone the complete history for you. But be warned: It'll make your first build take *dramatically* longer to finish!

Diff for: build.sh

@@ -7,6 +7,7 @@ cd "$( dirname "${BASH_SOURCE[0]}" )"
 DIR=$(pwd)
 
 DO_UPDATE=true
+USE_DOCKER=false
 VERBOSE=false
 QUIET=false
 export DO_UPDATE
@@ -32,18 +33,23 @@ do
     -h|--help)
       echo "Usage: $0 [-c|--clean]"
       echo "       $0 [-h|--help]"
-      echo "Usage: $0 [-n|--no-update] [-q|--quiet] [-v|--verbose]"
+      echo "       $0 [-d|--docker]"
+      echo "       $0 [-n|--no-update] [-q|--quiet] [-v|--verbose]"
       echo
       echo "  -c|--clean      Remove downloaded dependencies and generated files (then stop)."
       echo "  -h|--help       Show this usage statement."
       echo "  -n|--no-update  Don't update before building; just build."
+      echo "  -d|--docker     Use Docker to build in and serve from a container."
       echo "  -q|--quiet      Don't emit any messages except errors/warnings."
       echo "  -v|--verbose    Show verbose output from every build step."
       exit 0
       ;;
     -n|--no-update|--no-updates)
       DO_UPDATE=false
       ;;
+    -d|--docker)
+      USE_DOCKER=true
+      ;;
     -q|--quiet)
       QUIET=true
       VERBOSE=false
@@ -58,7 +64,9 @@ do
   esac
 done
 
-if [ "$DO_UPDATE" == true ]; then
+# $SKIP_BUILD_UPDATE_CHECK is set inside the Dockerfile so that we don't check for updates both inside and outside
+# the Docker container.
+if [ "$DO_UPDATE" == true -a "$SKIP_BUILD_UPDATE_CHECK" != true ]; then
   $QUIET || echo "Checking if html-build is up to date..."
   # TODO: `git remote get-url origin` is nicer, but new in Git 2.7.
   ORIGIN_URL=$(git config --get remote.origin.url)
@@ -200,6 +208,32 @@ else
 fi
 export HTML_SOURCE
 
+if [ "$USE_DOCKER" == true ]; then
+  if [[ "$HTML_SOURCE" != $(pwd)/* ]]; then
+    echo "When using Docker, the HTML source must be checked out in a subdirectory of the html-build repo. Cannot continue."
+    exit 1
+  fi
+
+  # $SOURCE_RELATIVE helps on Windows with Git Bash, where /c/... is a symlink, which Docker doesn't like.
+  SOURCE_RELATIVE=$(realpath --relative-to=. $HTML_SOURCE)
+
+  VERBOSE_OR_QUIET_FLAG=""
+  $QUIET && VERBOSE_OR_QUIET_FLAG+="--quiet"
+  $VERBOSE && VERBOSE_OR_QUIET_FLAG+="--verbose"
+
+  NO_UPDATE_FLAG="--no-update"
+  $DO_UPDATE && NO_UPDATE_FLAG=""
+
+  docker build --tag whatwg-html \
+               --build-arg html_source_dir=$SOURCE_RELATIVE \
+               --build-arg verbose_or_quiet_flag=$VERBOSE_OR_QUIET_FLAG \
+               --build-arg no_update_flag=$NO_UPDATE_FLAG \
+               $($QUIET && echo "--quiet") .
+  docker run --rm -it -p 8080:80 whatwg-html
+  exit 0
+fi
+
+
 $QUIET || echo "Linting the source file..."
 ./lint.sh $HTML_SOURCE/source || {
   echo

Diff for: site.conf

@@ -0,0 +1,13 @@
+<VirtualHost *:80>
+    DocumentRoot /var/www/html
+
+    <Directory "/var/www/html">
+        Options Indexes FollowSymLinks
+        AllowOverride All
+        Require all granted
+    </Directory>
+
+    ErrorLog ${APACHE_LOG_DIR}/error.log
+</VirtualHost>
+
+# vim: syntax=apache ts=4 sw=4 sts=4 sr noet