xref: /openbmc/docs/testing/local-ci-build.md (revision 99585d46)
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