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## Run CI on local changed Repo 57 58If you have local changes in the repo, and you do not want to commit yet, it's 59possible to run local CI as well by setting `NO_FORMAT_CODE=1` before running 60the script. 61 62E.g. 63 64```shell 65WORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon NO_FORMAT_CODE=1 \ 66./openbmc-build-scripts/run-unit-test-docker.sh 67``` 68 69`NO_FORMAT_CODE=1` tells the script to skip the `format-code.sh` so that it 70will not format the code and thus your repo could contain un-committed changes. 71 72## Reference an Existing Repo with `git worktree` 73 74If you're actively developing on a local copy of a repo already, or you want to 75start doing so, you should use `git worktree` instead so that the Docker 76container can reference a specific branch of your existing local repo. Learn 77more about worktree by running `git help worktree` if you're curious. 78 79This example demonstrates how to make a worktree of `phosphor-host-ipmid` in 80your Docker container. 81 82```shell 83cd /my/dir/for/phosphor-host-ipmid 84git worktree add /path/to/ci_test_area/phosphor-host-ipmid 85``` 86 87Now, if you `cd /path/to/ci_test_area`, you should see a directory 88`phosphor-host-ipmid/`, and if you enter it and run `git status` you will see 89that you're likely on a new branch named `phosphor-host-ipmid`. This is just for 90convenience, since you can't check out a branch in your worktree that's already 91checked out somewhere else; you can safely ignore or delete that branch later. 92 93However, Git won't be able to figure out how to get to your main worktree 94(`/my/dir/for/phosphor-host-ipmid`), so we'll need to mount it when we run. Open 95up `/path/to/ci_test_area/openbmc-build-scripts/run-unit-test-docker.sh` and 96find where we call `docker run`, way down at the bottom. Add an additional 97argument, remembering to escape the newline ('\'): 98 99``` 100PHOSPHOR_IPMI_HOST_PATH="/my/dir/for/phosphor-host-ipmid" 101 102docker run --blah-blah-existing-flags \ 103 -v ${PHOSPHOR_IPMI_HOST_PATH}:${PHOSPHOR_IPMI_HOST_PATH} \ 104 -other \ 105 -args 106``` 107 108Then commit this, so you can make sure not to lose it if you update the scripts 109repo: 110 111```shell 112cd openbmc-build-scripts 113git add run-unit-test-docker.sh 114git commit -m "mount phosphor-host-ipmid" 115``` 116 117The easiest workflow in this situation now looks something like this: 118 119```shell 120# Hack in the main worktree. 121cd /my/dir/for/phosphor-host-ipmid 122git checkout -b add-foo 123# Make a change. 124touch foo 125# Make sure to commit it. 126git add foo 127git commit -sm "change foo" 128# Update the Docker worktree to agree with it. 129cd /path/to/ci_test_area/phosphor-host-ipmid 130git checkout --detach add-foo 131# Now run the Docker container normally 132``` 133 134#### Interactive Docker Session 135 136To use an interactive session, you can change the `run-unit-test-docker.sh`. 137 138Replace the following (or similar): 139 140``` 141docker run --cap-add=sys_admin --rm=true \ 142 --privileged=true \ 143 -w "${WORKSPACE}" -v "${WORKSPACE}":"${WORKSPACE}" \ 144 -e "MAKEFLAGS=${MAKEFLAGS}" \ 145 -t ${DOCKER_IMG_NAME} \ 146 ${WORKSPACE}/${DBUS_UNIT_TEST_PY} -u ${UNIT_TEST} \ -f ${DBUS_SYS_CONFIG_FILE} 147``` 148 149with: 150 151``` 152docker run --cap-add=sys_admin --rm=true \ 153 --privileged=true \ 154 -w "${WORKSPACE}" -v "${WORKSPACE}":"${WORKSPACE}" \ 155 -e "MAKEFLAGS=${MAKEFLAGS}" \ 156 -it ${DOCKER_IMG_NAME} /bin/bash 157``` 158 159When you rerun `run-unit-test-docker.sh` you will be dropped into an interactive 160session. This is handy if you need to run gdb on a core dump. 161