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 13`sudo docker run hello-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 will 70not format the code and thus your repo could contain un-committed changes. 71 72## Run CI for testing purposes only 73 74To only invoke the test suite and not get caught up the various analysis passes 75that might be run otherwise, set `TEST_ONLY=1`. 76 77E.g. 78 79```shell 80WORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon TEST_ONLY=1 \ 81./openbmc-build-scripts/run-unit-test-docker.sh 82``` 83 84## Reference an Existing Repo with `git worktree` 85 86If you're actively developing on a local copy of a repo already, or you want to 87start doing so, you should use `git worktree` instead so that the Docker 88container can reference a specific branch of your existing local repo. Learn 89more about worktree by running `git help worktree` if you're curious. 90 91This example demonstrates how to make a worktree of `phosphor-host-ipmid` in 92your Docker container. 93 94```shell 95cd /my/dir/for/phosphor-host-ipmid 96git worktree add /path/to/ci_test_area/phosphor-host-ipmid 97``` 98 99Now, if you `cd /path/to/ci_test_area`, you should see a directory 100`phosphor-host-ipmid/`, and if you enter it and run `git status` you will see 101that you're likely on a new branch named `phosphor-host-ipmid`. This is just for 102convenience, since you can't check out a branch in your worktree that's already 103checked out somewhere else; you can safely ignore or delete that branch later. 104 105However, Git won't be able to figure out how to get to your main worktree 106(`/my/dir/for/phosphor-host-ipmid`), so we'll need to mount it when we run. Open 107up `/path/to/ci_test_area/openbmc-build-scripts/run-unit-test-docker.sh` and 108find where we call `docker run`, way down at the bottom. Add an additional 109argument, remembering to escape the newline ('\'): 110 111``` 112PHOSPHOR_IPMI_HOST_PATH="/my/dir/for/phosphor-host-ipmid" 113 114docker run --blah-blah-existing-flags \ 115 -v ${PHOSPHOR_IPMI_HOST_PATH}:${PHOSPHOR_IPMI_HOST_PATH} \ 116 -other \ 117 -args 118``` 119 120Then commit this, so you can make sure not to lose it if you update the scripts 121repo: 122 123```shell 124cd openbmc-build-scripts 125git add run-unit-test-docker.sh 126git commit -m "mount phosphor-host-ipmid" 127``` 128 129The easiest workflow in this situation now looks something like this: 130 131```shell 132# Hack in the main worktree. 133cd /my/dir/for/phosphor-host-ipmid 134git checkout -b add-foo 135# Make a change. 136touch foo 137# Make sure to commit it. 138git add foo 139git commit -sm "change foo" 140# Update the Docker worktree to agree with it. 141cd /path/to/ci_test_area/phosphor-host-ipmid 142git checkout --detach add-foo 143# Now run the Docker container normally 144``` 145 146#### Interactive Docker Session 147 148To use an interactive session, you can pass the flag `INTERACTIVE=true` to 149`run-unit-test-docker.sh` which will drop you into a bash shell with a default 150D-Bus instance. This is handy if you need to run gdb on a core dump or run a 151daemon on your workstation. 152