add local-ci-build doc
Add a document that describes how to set up a local CI build mechanism
on your machine. This walks you through what to check out from openbmc,
and then what command to run to build the package and run the
unit-tests.
Signed-off-by: Patrick Venture <venture@google.com>
Change-Id: I6cd64ef8005e47d151069310ad41013b3385a911
diff --git a/local-ci-build.md b/local-ci-build.md
new file mode 100644
index 0000000..374ec8d
--- /dev/null
+++ b/local-ci-build.md
@@ -0,0 +1,56 @@
+# Local CI Build
+
+These instructions pertain to running the upstream OpenBMC CI locally.
+
+Please install and configure Docker.
+
+Each repository is built locally within the CI using the bootstrap.sh and
+automake toolchain.
+
+The following example will clone and build phosphor-hwmon. The upstream CI
+will try building everything and this includes running `make check` if
+available. It will also run `format-code.sh` and check if the code is formatted
+properly if there is a `.clang-format` file present in the target repository,
+or if there is a script in the repo named `format-code.sh`.
+
+```
+mkdir ci_test_area
+cd ci_test_area
+git clone https://github.com/openbmc/openbmc-build-scripts.git
+git clone https://github.com/openbmc/phosphor-hwmon
+WORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon \
+./openbmc-build-scripts/run-unit-test-docker.sh
+```
+
+NOTE: When running 'run-unit-test-docker.sh' make sure you do not have any
+uncommitted changes. The script runs git diff after 'format-code.sh' and
+therefore any uncommitted changes show up as output and it then fails assuming
+the code was improperly formatted.
+
+#### Interactive Docker Session
+
+To use an interactive session, you can change the `run-unit-test-docker.sh`.
+
+Replace the following (or similar):
+
+```
+docker run --cap-add=sys_admin --rm=true \
+ --privileged=true \
+ -w "${WORKSPACE}" -v "${WORKSPACE}":"${WORKSPACE}" \
+ -e "MAKEFLAGS=${MAKEFLAGS}" \
+ -t ${DOCKER_IMG_NAME} \
+ ${WORKSPACE}/${DBUS_UNIT_TEST_PY} -u ${UNIT_TEST} \ -f ${DBUS_SYS_CONFIG_FILE}
+```
+
+with:
+
+```
+docker run --cap-add=sys_admin --rm=true \
+ --privileged=true \
+ -w "${WORKSPACE}" -v "${WORKSPACE}":"${WORKSPACE}" \
+ -e "MAKEFLAGS=${MAKEFLAGS}" \
+ -it ${DOCKER_IMG_NAME} /bin/bash
+```
+
+When you rerun `run-unit-test-docker.sh` you will be dropped into an interactive
+session. This is handy if you need to run gdb on a core dump.