From 69e17588e8e1b3349e1079f66dc54fd1b72badb6 Mon Sep 17 00:00:00 2001
From: lia <167905060+lia-viam@users.noreply.github.com>
Date: Mon, 4 Nov 2024 14:35:00 -0500
Subject: [PATCH] Update README.md for module dev Docker (#315)

---
 README.md | 56 +++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 38 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index f017a68f5..324c58180 100644
--- a/README.md
+++ b/README.md
@@ -23,24 +23,44 @@ NOTE: Windows is not supported. If you are using Windows, build the project in W
 
 ## Using Docker for Development
 
-A Docker description is included which will install the required
-packages.
-1. Create a new docker image from one of the provided docker
-   files. From the root directory of this project (where this README
-   is located), run `docker build -t cpp . -f
-   etc/docker/Dockerfile.debian.bullseye` (other files are provided
-   for Ubuntu Focal and Ubuntu Jammy as well as Debian Sid). Run the
-   new image in a container that has your local project directory
-   mounted to the filesystem. This will ensure that you can continue
-   to develop locally on your machine, and all files will be
-   automatically synced into the docker environment. To create the
-   environment and open a shell to it, run the command `docker run
-   --rm -it -v "$PWD":/usr/src/viam-cpp-sdk -w /usr/src/viam-cpp-sdk
-   cpp /bin/bash`
-1. Start developing! You can develop as you normally would, using the
-   files on your local filesystem. When it comes time to
-   testing/building/running the program, do so inside the docker
-   environment you opened in the previous step.
+Some Dockerfiles are provided for C++ SDK development, either for developing
+on the SDK itself, or for module development. The docker images are split up
+into base images, found in [etc/docker/base-images](etc/docker/base-images), and
+an [SDK build image](etc/docker/Dockerfile.sdk-build). The base images install
+apt packages required to build and develop the SDK, whereas the SDK build image
+is meant to be built on top of a base image using multi-stage Docker building.
+
+From the root of this repository, run
+```shell
+docker build -t base/bullseye -f etc/docker/base-images/Dockerfile.debian.bullseye .
+```
+This will create a Debian Bullseye base image. Note the use of the `-t base/bullseye`
+arg to assign a tag to the image, which is important for the next step. You can then
+use `Dockerfile.sdk-build` in a couple different ways.
+
+```shell
+docker build --build-arg BASE_TAG=base/bullseye --build-arg GIT_TAG=[...] -f etc/docker/Dockerfile.sdk-build .
+```
+
+This will use `base/bullseye` as a base to build the SDK version provided in `GIT_TAG`,
+which should be a tagged release version. The SDK will be cloned from 
+https://github.com/viamrobotics/viam-cpp-sdk/. This is the recommended approach for
+C++ module development, which should generally be done against a tagged release.
+
+You can also do
+```shell
+docker build --build-arg BASE_TAG=base/bullseye --build-arg REPO_SETUP=copy -f etc/docker/Dockerfile.sdk-build .
+```
+
+Note the use of the build argument `REPO_SETUP=copy`, which adds a Docker instruction
+to copy the SDK repo from the current working directory, rather than cloning from 
+GitHub. This approach may make more sense for developing on the SDK itself, or if
+your C++ SDK development relies on a localversion of the SDK.
+
+The examples above illustrated the use of several `--build-arg` arguments, namely
+`BASE_TAG`, `GIT_TAG`, and `REPO_SETUP`. Please see 
+[Dockerfile.sdk-build](etc/docker/Dockerfile.sdk-build) for a complete account of
+all build arguments and their defaults.
 
 ## Building Documentation Locally for Testing
 The C++ sdk uses [Doxygen](https://www.doxygen.nl/) to generate documentation.