1# Local CI Build 2 3These instructions pertain to running the upstream OpenBMC CI locally. 4 5## Install Docker 6 7Please install and configure Docker. The installation of Docker CE (Community 8Edition) varies by platform and may differ in your organization, but the 9[Docker Docs](https://docs.docker.com/install/) are a good place to start 10looking. 11 12Check that the installation was successful by running `sudo docker run 13hello-world`. 14 15Each repository is built locally within the CI using the bootstrap.sh and 16automake toolchain. 17 18## Download the CI Image 19 20Start by making a place for your CI repositories to live, and clone the CI 21scripts first: 22 23```shell 24mkdir ci_test_area 25cd ci_test_area 26git clone https://github.com/openbmc/openbmc-build-scripts.git 27``` 28 29## Add a Read-Only Repo 30 31If you just want to validate a project as it is upstream, without any of your 32own changes, you can clone it directly into the Docker directory. This example 33clones and builds phosphor-hwmon directly. The upstream CI will try building 34everything and this includes running `make check` if available. It will also run 35`format-code.sh` and check if the code is formatted properly if there is a 36`.clang-format` file present in the target repository, or if there is a script 37in the repo named `format-code.sh`. 38 39```shell 40cd /path/to/ci_test_area 41git clone https://github.com/openbmc/phosphor-hwmon 42WORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon \ 43./openbmc-build-scripts/run-unit-test-docker.sh 44``` 45 46NOTE: When running 'run-unit-test-docker.sh' make sure you do not have any 47uncommitted changes. The script runs git diff after 'format-code.sh' and 48therefore any uncommitted changes show up as output and it then fails assuming 49the code was improperly formatted. 50 51NOTE: This technique is okay if you have only a quick change on a project you 52don't work on very often, but is more difficult to use if you would rather use 53an active development branch. If you plan to develop regularly on a repo, use 54the next technique instead. 55 56## Reference an Existing Repo with `git worktree` 57 58If you're actively developing on a local copy of a repo already, or you want to 59start doing so, you should use `git worktree` instead so that the Docker 60container can reference a specific branch of your existing local repo. Learn 61more about worktree by running `git help worktree` if you're curious. 62 63This example demonstrates how to make a worktree of `phosphor-host-ipmid` in 64your Docker container. 65 66```shell 67cd /my/dir/for/phosphor-host-ipmid 68git worktree add /path/to/ci_test_area/phosphor-host-ipmid 69``` 70 71Now, if you `cd /path/to/ci_test_area`, you should see a directory 72`phosphor-host-ipmid/`, and if you enter it and run `git status` you will see 73that you're likely on a new branch named `phosphor-host-ipmid`. This is just for 74convenience, since you can't check out a branch in your worktree that's already 75checked out somewhere else; you can safely ignore or delete that branch later. 76 77However, Git won't be able to figure out how to get to your main worktree 78(`/my/dir/for/phosphor-host-ipmid`), so we'll need to mount it when we run. Open 79up `/path/to/ci_test_area/openbmc-build-scripts/run-unit-test-docker.sh` and 80find where we call `docker run`, way down at the bottom. Add an additional 81argument, remembering to escape the newline ('\'): 82 83``` 84PHOSPHOR_IPMI_HOST_PATH="/my/dir/for/phosphor-host-ipmid" 85 86docker run --blah-blah-existing-flags \ 87 -v ${PHOSPHOR_IPMI_HOST_PATH}:${PHOSPHOR_IPMI_HOST_PATH} \ 88 -other \ 89 -args 90``` 91 92Then commit this, so you can make sure not to lose it if you update the scripts 93repo: 94 95```shell 96cd openbmc-build-scripts 97git add run-unit-test-docker.sh 98git commit -m "mount phosphor-host-ipmid" 99``` 100 101The easiest workflow in this situation now looks something like this: 102 103```shell 104# Hack in the main worktree. 105cd /my/dir/for/phosphor-host-ipmid 106git checkout -b add-foo 107# Make a change. 108touch foo 109# Make sure to commit it. 110git add foo 111git commit -sm "change foo" 112# Update the Docker worktree to agree with it. 113cd /path/to/ci_test_area/phosphor-host-ipmid 114git checkout --detach add-foo 115# Now run the Docker container normally 116``` 117 118#### Interactive Docker Session 119 120To use an interactive session, you can change the `run-unit-test-docker.sh`. 121 122Replace the following (or similar): 123 124``` 125docker run --cap-add=sys_admin --rm=true \ 126 --privileged=true \ 127 -w "${WORKSPACE}" -v "${WORKSPACE}":"${WORKSPACE}" \ 128 -e "MAKEFLAGS=${MAKEFLAGS}" \ 129 -t ${DOCKER_IMG_NAME} \ 130 ${WORKSPACE}/${DBUS_UNIT_TEST_PY} -u ${UNIT_TEST} \ -f ${DBUS_SYS_CONFIG_FILE} 131``` 132 133with: 134 135``` 136docker run --cap-add=sys_admin --rm=true \ 137 --privileged=true \ 138 -w "${WORKSPACE}" -v "${WORKSPACE}":"${WORKSPACE}" \ 139 -e "MAKEFLAGS=${MAKEFLAGS}" \ 140 -it ${DOCKER_IMG_NAME} /bin/bash 141``` 142 143When you rerun `run-unit-test-docker.sh` you will be dropped into an interactive 144session. This is handy if you need to run gdb on a core dump. 145