From 8a6fbf0749ea73bde96b7c97bffdaabbf8ca0a94 Mon Sep 17 00:00:00 2001
From: Bruce Leidl <bruce@subgraph.com>
Date: Sat, 3 Feb 2018 11:04:57 -0500
Subject: [PATCH] Updated build instructions

---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 44 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index ab53d66..147dde8 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,49 @@
+# Building Citadel
 
+## Set up Docker
 
-## Very basic build instructions
+Building citadel requires that you have Docker CE installed on the build host.  The version of Docker
+provided by your Linux distribution will probably not work and you should follow the following instructions
+instead:
+
+  * [Installing Docker CE on Debian](https://docs.docker.com/install/linux/docker-ce/debian/)
+  * [Installing Docker CE on Fedora](https://docs.docker.com/install/linux/docker-ce/fedora/)
+
+After installing Docker you may need to start the docker daemon.
+
+    $ systemctl start docker
+
+If you want the docker daemon to start automatically on boot you also need to enable it.
+
+    $ systemctl enable docker
+
+You may optionally add your user account to the `docker` group so that you can issue docker commands without using
+sudo.  
+
+**Warning:** This is more convenient but be careful because containers can be configured to share any file on the host. 
+A user with access to the docker group can easily escalate privileges to root while the docker daemon is running.
+
+    $ sudo usermod -aG docker $USER
+
+## Building with Docker
+
+A `Makefile` is provided which only contains a couple of simple targets that execute docker commands to set up and run the 
+builder container.
+
+To create the builder docker image use the following command.  You only need to do this one time, but if you run it again
+Docker will realize that the Dockerfile has not changed and do nothing.
+
+    $ make docker-image
+
+To run a shell inside the docker build container:
+
+    $ make docker-shell
+
+The shell will run in the build directory and be configured to run build commands with `bitbake`.  
+
+To build a full citadel image:
 
-    $ source setup-build-env
     $ bitbake citadel-image
 
-## Git subtrees included
-
-    $ git subtree add --prefix poky git://git.yoctoproject.org/poky.git master --squash
-    $ git subtree add --prefix meta-intel  git://git.yoctoproject.org/meta-intel.git master --squash
-    $ git gc && git prune
-
-* `https://www.atlassian.com/blog/git/alternatives-to-git-submodule-git-subtree`
-* `https://legacy-developer.atlassian.com/blog/2015/05/the-power-of-git-subtree/`
+The build will take several hours the first time, but for later builds the build system will use cached artifacts stored 
+in `citadel/build/sstate-cache` for components that have not changed and new builds will usually only take a few minutes.