docs/testing/local-ci-build.md

# Local CI Build

These instructions pertain to running the upstream OpenBMC CI locally.

## Install Docker

Please install and configure Docker. The installation of Docker CE (Community
Edition) varies by platform and may differ in your organization, but the
[Docker Docs](https://docs.docker.com/install/) are a good place to start
looking.

Check that the installation was successful by running `sudo docker run
hello-world`.

Each repository is built locally within the CI using the bootstrap.sh and
automake toolchain.

## Download the CI Image

Start by making a place for your CI repositories to live, and clone the CI
scripts first:

```shell
mkdir ci_test_area
cd ci_test_area
git clone https://github.com/openbmc/openbmc-build-scripts.git
```

## Add a Read-Only Repo

If you just want to validate a project as it is upstream, without any of your
own changes, you can clone it directly into the Docker directory. This example
clones and builds phosphor-hwmon directly. 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`.

```shell
cd /path/to/ci_test_area
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.

NOTE: This technique is okay if you have only a quick change on a project you
don't work on very often, but is more difficult to use if you would rather use
an active development branch. If you plan to develop regularly on a repo, use
the next technique instead.

## Run CI on local changed Repo

If you have local changes in the repo, and you do not want to commit yet, it's
possible to run local CI as well by setting `NO_FORMAT_CODE=1` before running
the script.

E.g.

```shell
WORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon NO_FORMAT_CODE=1 \
./openbmc-build-scripts/run-unit-test-docker.sh
```

`NO_FORMAT_CODE=1` tells the script to skip the `format-code.sh` so that it
will not format the code and thus your repo could contain un-committed changes.

## Run CI for testing purposes only

To only invoke the test suite and not get caught up the various analysis passes
that might be run otherwise, set `TEST_ONLY=1`.

E.g.

```shell
WORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon TEST_ONLY=1 \
./openbmc-build-scripts/run-unit-test-docker.sh
```

## Reference an Existing Repo with `git worktree`

If you're actively developing on a local copy of a repo already, or you want to
start doing so, you should use `git worktree` instead so that the Docker
container can reference a specific branch of your existing local repo. Learn
more about worktree by running `git help worktree` if you're curious.

This example demonstrates how to make a worktree of `phosphor-host-ipmid` in
your Docker container.

```shell
cd /my/dir/for/phosphor-host-ipmid
git worktree add /path/to/ci_test_area/phosphor-host-ipmid
```

Now, if you `cd /path/to/ci_test_area`, you should see a directory
`phosphor-host-ipmid/`, and if you enter it and run `git status` you will see
that you're likely on a new branch named `phosphor-host-ipmid`. This is just for
convenience, since you can't check out a branch in your worktree that's already
checked out somewhere else; you can safely ignore or delete that branch later.

However, Git won't be able to figure out how to get to your main worktree
(`/my/dir/for/phosphor-host-ipmid`), so we'll need to mount it when we run. Open
up `/path/to/ci_test_area/openbmc-build-scripts/run-unit-test-docker.sh` and
find where we call `docker run`, way down at the bottom. Add an additional
argument, remembering to escape the newline ('\'):

```
PHOSPHOR_IPMI_HOST_PATH="/my/dir/for/phosphor-host-ipmid"

docker run --blah-blah-existing-flags \
  -v ${PHOSPHOR_IPMI_HOST_PATH}:${PHOSPHOR_IPMI_HOST_PATH} \
  -other \
  -args
```

Then commit this, so you can make sure not to lose it if you update the scripts
repo:

```shell
cd openbmc-build-scripts
git add run-unit-test-docker.sh
git commit -m "mount phosphor-host-ipmid"
```

The easiest workflow in this situation now looks something like this:

```shell
# Hack in the main worktree.
cd /my/dir/for/phosphor-host-ipmid
git checkout -b add-foo
# Make a change.
touch foo
# Make sure to commit it.
git add foo
git commit -sm "change foo"
# Update the Docker worktree to agree with it.
cd /path/to/ci_test_area/phosphor-host-ipmid
git checkout --detach add-foo
# Now run the Docker container normally
```

#### 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.