enable docker by default, documentation

README.md

@@ -53,9 +53,9 @@ goals:
    and clearer ways to use it.
 1. **maintainable**: product lifecycles run for many years, so we need a solution where
    we can build images on a number of different hosts as time marches on. We achieve this
-   through a simple and transparent docker wrapper that contains all the host dependencies
-   needed. This wrapper is invisible (the file system still lives on the host), and is
-   optional if you choose not to use it.
+   through a simple and transparent [docker wrapper](docs/docker.md) that contains all
+   the host dependencies needed. This wrapper is invisible (the file system still
+   lives on the host), and is optional if you choose not to use it.
 1. **transparent**: we try to use industry standard tools (git, bitbake, etc) where possible
    and not invent a lot of new tooling that needs to be learned to use the system.
    As an example, much of the tooling (envsetup.sh) are simple bash functions and are easy

docs/README.md

@@ -15,6 +15,7 @@ included for some of them below.
 ## Using Yoe
 
 - [Working with git submodules](git-submodules.md)
+- [Docker Integration](docker.md)
 
 ## Image Configuration
 

docs/docker.md

@@ -0,0 +1,26 @@
+# Yoe Docker Integration
+
+[up](README.md)
+
+The Yoe project provides a [docker container](https://hub.docker.com/r/yoedistro/yoe-build/)
+that has all the dependencies needed to build Yoe. This container is mostly transparent
+as it simply wraps the bitbake command. Every time you run bitbake, the container is started
+and all bitbake operations happen in the container. The build files still exist in the host
+file system so they can be accessed using any of your host tools.
+
+Using this container has the following
+benefits:
+
+- you don't have to worry about installing host dependencies
+- you can build on any Linux host distro, even those that are not compatible with Yoe
+- as host distributions are updated, then eventually become incompatible with older
+  versions of OpenEmbedded. Using a container allows you to build old version of Yoe
+  over long product life cycles.
+
+Yoe uses docker by default, but this can be disabled by setting `DOCKER_REPO=none` in your
+_\<project\>-envsetup.sh_ file. You can also set `DOCKER_REPO` to a custom container if
+you need something different.
+
+Any tool (such as `devtool`) that uses bitbake must also be run in the container. As these
+tools are not yet wrapped, you must enter the docker container first, and then run the tool.
+This can be done by running `dkr` first, which drops you into a container shell.

envsetup.sh

@@ -390,11 +390,33 @@ yoe_clean_sstate() {
 
 # Docker integration
 # set DOCKER_REPO to something like yoedistro/yoe-build:stretch
-# Note, set DOCKER_REPO outside of envsetup.sh, otherwise
-# it will get set in container, which is not what you want.
-# local.sh is a good place to set DOCKER_REPO
+# DOCKER_REPO can be set in scripts that wrap envsetup.sh
+# set DOCKER_REPO to 'none' to disable docker
+
+if [ -z "$DOCKER_REPO" ]; then
+  echo "Setting DOCKER_REPO to yoedistro/yoe-build:stretch"
+  echo "set DOCKER_REPO to 'none' to disable docker"
+  export DOCKER_REPO=yoedistro/yoe-build:stretch
+fi
+
+check_docker() {
+  if ! docker -v >/dev/null 2>&1; then
+    echo "Error, please install docker or set DOCKER_REPO=none in environment"
+    return 1
+  fi
+
+  if ! docker images -q $DOCKER_REPO >/dev/null 2>&1; then
+    echo "Error, docker image $DOCKER_REPO not installed"
+    echo "Please install it with: docker pull $DOCKER_REPO"
+    return 1
+  fi
+
+  return 0
+}
 
 dkr() {
+  check_docker || return 1
+
   CMD="$1"
 
   if [ -z "$CMD" ]; then
@@ -421,7 +443,7 @@ dkr() {
 }
 
 bitbake() {
-  if [ -z $DOCKER_REPO ]; then
+  if [ -z $DOCKER_REPO ] || [ "$DOCKER_REPO" = "none" ]; then
     ${OE_BASE}/sources/bitbake/bin/bitbake $@
   else
     dkr "${OE_BASE}/sources/bitbake/bin/bitbake $@"