Update build docs

I'm not sure about using the name 'zettio/weave-build' for the image
here.  There's no intent to upload it to dockerhub, so including the
user name 'zettio' seems wrong.  On the other hand, I'm not sure what
the meaning of an unslashed image name is supposed to be.  Probably it
doesn't matter what a private non-pushed image is called, as long as
it doesn't clash with something.

site/building.md

@@ -3,35 +3,102 @@ title: Building Weave
 layout: default
 ---
 
-**NB** This is only necessary if you want to work on the weave code.
+You only need to build weave if you want to work on the weave codebase
+(or you just enjoy building software).
 
-## Building directly on Linux
+Apart from the `weave` shell script, weave is delivered as a set of
+container images.  There is no distribution-specific packaging, so in
+principle it shouldn't matter which Linux distribution you build
+under.  But naturally, Docker is a prerequisite (version 1.3.0 or
+later).  And it is difficult to build under Fedora because [Fedora
+does not include static
+libraries](http://fedoraproject.org/wiki/Packaging:Guidelines#Packaging_Static_Libraries).
+So we recommend building under Ubuntu.
 
-You can work on weave without using a VM if you are running the docker
-daemon outside a VM. (These instructions have only been tested on
-Ubuntu.)
+You can also build in a container under any system that supports
+Docker.  And naturally, you can run Ubuntu in a VM and build
+there.  These options are described below.
 
-To build weave you need `libpcap-dev` and `docker` (version 1.3.0 or
-later) installed. And `go` (and `git` and `hg` to fetch dependencies).
+## Building directly on Ubuntu
 
-The package name is `github.com/zettio/weave`, so assuming `$GOPATH`
-is set:
+The weave git repository should be cloned into
+`$GOPATH/src/github.com/zettio/weave`, in accordance with (the go
+workspace conventions)[https://golang.org/doc/code.html#Workspaces]:
 
 ```bash
-$ cd $GOPATH
 $ WEAVE=github.com/zettio/weave
-$ git clone https://$WEAVE src/$WEAVE
-$ cd src/$WEAVE
+$ git clone https://$WEAVE $GOPATH/src/$WEAVE
+$ cd $GOPATH/src/$WEAVE
 ```
 
-Then simply run
+Several prerequisites are needed to build weave.  To install these, in
+the weave directory do:
+
+```bash
+$ make prerequisites
+```
+
+Then to actually build, simply do:
 
 ```bash
 $ make
 ```
 
-This will build the weave router, produce a docker image
-`zettio/weave` and export that image to `/var/tmp/weave.tar`.
+This will build the weave components and package them into three
+Docker images (`zettio/weave`, `zettio/weavedns`, and
+`zettio/weavetools`).  These are then exported (as
+`/var/tmp/weave.tar`, `weavends.tar` and `weavetools.tar`).
+
+## Building in a Docker container
+
+As a preliminary step, we create a container image based on Ubuntu
+that has all the prerequisites.  This avoids the need to download and
+install them for each build.  In the `weave` directory, do:
+
+```bash
+$ docker build -t zettio/weave-build build
+```
+
+Then to actually build, do:
+
+```bash
+$ docker run -v /var/run/docker.sock:/var/run/docker.sock zettio/weave-build https://github.com/zettio/weave.git
+```
+
+This will clone the weave git repository, then do the build.
+
+Note the `-v` option to give the container access to the Docker daemon
+on the host.  When the build completes, the resulting images are
+stored in docker on the host, as when building directly under
+Ubuntu. The exported images are present under `/var/tmp/` inside the
+container, and can be retrieved using `docker cp` if needed.
+
+If you are building under a Fedora or RHEL Docker host (or another
+distribution that uses SELinux), and you have SELinux set to enforcing
+mode, it will block attempts to access `/var/run/docker.sock` inside
+the container.  See
+[dpw/selinux-dockersock](https://github.com/dpw/selinux-dockersock)
+for a way to work around this problem.
+
+The container arguments are passed to `git clone`, so for example, you
+can build from a forked repository and a specific branch with:
+
+```bash
+$ docker run -v /var/run/docker.sock:/var/run/docker.sock zettio/weave-build -b <branch name> <repo URI>
+```
+
+Alternatively, you might want to build from a weave source tree
+already present on the host.  You can do this by using the `-v` option
+to bind the bind your go workspace containing the weave repository to
+`/home/go` inside the container.  No container arguments should be
+passed in this case:
+
+```bash
+$ docker run -v /var/run/docker.sock:/var/run/docker.sock -v <host gopath>:/home/go zettio/weave-build
+```
+
+This will leave the intermediate build artifacts on the host, so that
+you can modify the weave source code and rebuild quickly.
 
 ## Building using Vagrant