Add `bst-here` script and document itsam/use-via-docker-2

2 files changed, 92 insertions, 17 deletions

diff --git a/contrib/bst-here b/contrib/bst-here
new file mode 100644
index 000000000..1d5d79829
--- /dev/null
+++ b/contrib/bst-here
@@ -0,0 +1,68 @@
+#!/bin/bash
+#
+#  Copyright 2017 Bloomberg Finance LP
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU Lesser General Public
+#  License as published by the Free Software Foundation; either
+#  version 2 of the License, or (at your option) any later version.
+#
+#  This library is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#  Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public
+#  License along with this library. If not, see <http://www.gnu.org/licenses/>.
+#
+#  Authors:
+#        Charles Bailey <cbailey32@bloomberg.net>
+#        Sam Thursfield <sam.thursfield@codethink.co.uk>
+
+# This is a helper script for using BuildStream via Docker. See
+# docs/source/install.rst for documentation.
+
+is_tty=
+
+if test -t 0
+then
+    is_tty=y
+fi
+
+while getopts tT arg
+do
+    case $arg in
+    T)
+        is_tty=
+        ;;
+    t)
+        is_tty=y
+        ;;
+    esac
+done
+
+test "$OPTIND" -gt 1 &&
+    shift $(( OPTIND - 1 ))
+
+create_volume_if_not_exists () {
+    if ! docker volume inspect "$1" >/dev/null 2>&1
+    then
+        docker volume create --name "$1"
+    fi
+}
+
+for vol in buildstream-cache buildstream-config
+do
+    create_volume_if_not_exists "$vol"
+done
+
+exec docker run --rm -i${is_tty:+ -t} \
+                --cap-add SYS_ADMIN \
+                --device /dev/fuse \
+                --security-opt seccomp=unconfined \
+                --volume buildstream-cache:/root/.cache/buildstream \
+                --volume buildstream-config:/root/.config \
+                --volume "$PWD":/src \
+                --workdir /src \
+                buildstream/buildstream-fedora:latest \
+                "$@"
diff --git a/doc/source/docker.rst b/doc/source/docker.rst
index 74dde77c6..55e456d87 100644
--- a/doc/source/docker.rst
+++ b/doc/source/docker.rst
@@ -3,29 +3,36 @@
 BuildStream inside Docker
 =========================
 The BuildStream project provides
-`Docker images <https://hub.docker.com/r/buildstream/buildstream-fedora/>`_
+`Docker images <https://hub.docker.com/r/buildstream/buildstream-fedora>`_
 containing BuildStream and its dependencies.
 This gives you an easy way to get started using BuildStream on any Unix-like
 platform where Docker is available, including Mac OS X.
 
-To use BuildStream you will need to spawn a container from that image
-and mount your workspace directory as a volume. You will want a second volume
-to store the cache, which we can create from empty like this:
+We recommend using the
+`bst-here wrapper script <https://gitlab.com/BuildStream/buildstream/blob/master/contrib/bst-here>`_
+which automates the necessary container setup. You can download it and make
+it executable like this:
 
-::
+    mkdir -p ~/.local/bin
+    curl --get https://gitlab.com/BuildStream/buildstream/raw/master/contrib/bst-here > ~/.local/bin/bst-here
+    chmod +x ~/.local/bin/bst-here
 
-    docker volume create buildstream-cache
+Check if ``~/.local/bin`` appears in your PATH environment variable -- if it
+doesn't, you should
+`edit your ~/.profile so that it does <https://stackoverflow.com/questions/14637979/>`_.
 
-You can now run the following command to fetch the latest official Docker image
-build, and spawn a container running an interactive shell. This assumes that the
-path to all the source code you need is available in ``~/src``.
+Once ``bst-here`` is available in your PATH, you just prefix every BuildStream
+command you need to run with ``bst-here`` so that it executes through the
+wrapper. The latest version of the buildstream-fedora Docker image is
+automatically pulled if needed. The contents of your working directory will be
+made available at ``/src`` inside the container.
 
-::
+Two other volumes are set up by the ``bst-here`` script:
 
-    docker run -it \
-          --cap-add SYS_ADMIN \
-          --device /dev/fuse \
-          --security-opt seccomp=unconfined \
-          --volume ~/src:/src \
-          --volume buildstream-cache:/root/.cache \
-          buildstream/buildstream-fedora:latest /bin/bash
+ * buildstream-cache -- mounted at ``~/.cache/buildstream``
+ * buildstream-config -- mounted at ``~/.config/``
+
+These are necessary so that your BuildStream cache and configuration files
+persist between invocations of ``bst-here``. You can open a shell inside the
+container by running ``bst-here -t /bin/bash``, which is useful if for example
+you need to add something custom to ``~/.config/buildstream.conf``.