173f9bc12SGunnar Mills# Local CI Build 273f9bc12SGunnar Mills 373f9bc12SGunnar MillsThese instructions pertain to running the upstream OpenBMC CI locally. 473f9bc12SGunnar Mills 573f9bc12SGunnar Mills## Install Docker 673f9bc12SGunnar Mills 773f9bc12SGunnar MillsPlease install and configure Docker. The installation of Docker CE (Community 873f9bc12SGunnar MillsEdition) varies by platform and may differ in your organization, but the 973f9bc12SGunnar Mills[Docker Docs](https://docs.docker.com/install/) are a good place to start 1073f9bc12SGunnar Millslooking. 1173f9bc12SGunnar Mills 12*f4febd00SPatrick WilliamsCheck that the installation was successful by running 13*f4febd00SPatrick Williams`sudo docker run hello-world`. 1473f9bc12SGunnar Mills 1573f9bc12SGunnar MillsEach repository is built locally within the CI using the bootstrap.sh and 1673f9bc12SGunnar Millsautomake toolchain. 1773f9bc12SGunnar Mills 1873f9bc12SGunnar Mills## Download the CI Image 1973f9bc12SGunnar Mills 2073f9bc12SGunnar MillsStart by making a place for your CI repositories to live, and clone the CI 2173f9bc12SGunnar Millsscripts first: 2273f9bc12SGunnar Mills 2373f9bc12SGunnar Mills```shell 2473f9bc12SGunnar Millsmkdir ci_test_area 2573f9bc12SGunnar Millscd ci_test_area 2673f9bc12SGunnar Millsgit clone https://github.com/openbmc/openbmc-build-scripts.git 2773f9bc12SGunnar Mills``` 2873f9bc12SGunnar Mills 2973f9bc12SGunnar Mills## Add a Read-Only Repo 3073f9bc12SGunnar Mills 3173f9bc12SGunnar MillsIf you just want to validate a project as it is upstream, without any of your 3273f9bc12SGunnar Millsown changes, you can clone it directly into the Docker directory. This example 3373f9bc12SGunnar Millsclones and builds phosphor-hwmon directly. The upstream CI will try building 3473f9bc12SGunnar Millseverything and this includes running `make check` if available. It will also run 3573f9bc12SGunnar Mills`format-code.sh` and check if the code is formatted properly if there is a 3673f9bc12SGunnar Mills`.clang-format` file present in the target repository, or if there is a script 3773f9bc12SGunnar Millsin the repo named `format-code.sh`. 3873f9bc12SGunnar Mills 3973f9bc12SGunnar Mills```shell 4073f9bc12SGunnar Millscd /path/to/ci_test_area 4173f9bc12SGunnar Millsgit clone https://github.com/openbmc/phosphor-hwmon 4273f9bc12SGunnar MillsWORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon \ 4373f9bc12SGunnar Mills./openbmc-build-scripts/run-unit-test-docker.sh 4473f9bc12SGunnar Mills``` 4573f9bc12SGunnar Mills 4673f9bc12SGunnar MillsNOTE: When running 'run-unit-test-docker.sh' make sure you do not have any 4773f9bc12SGunnar Millsuncommitted changes. The script runs git diff after 'format-code.sh' and 4873f9bc12SGunnar Millstherefore any uncommitted changes show up as output and it then fails assuming 4973f9bc12SGunnar Millsthe code was improperly formatted. 5073f9bc12SGunnar Mills 5173f9bc12SGunnar MillsNOTE: This technique is okay if you have only a quick change on a project you 5273f9bc12SGunnar Millsdon't work on very often, but is more difficult to use if you would rather use 5373f9bc12SGunnar Millsan active development branch. If you plan to develop regularly on a repo, use 5473f9bc12SGunnar Millsthe next technique instead. 5573f9bc12SGunnar Mills 56579b1cb9SLei YU## Run CI on local changed Repo 57579b1cb9SLei YU 58579b1cb9SLei YUIf you have local changes in the repo, and you do not want to commit yet, it's 59579b1cb9SLei YUpossible to run local CI as well by setting `NO_FORMAT_CODE=1` before running 60579b1cb9SLei YUthe script. 61579b1cb9SLei YU 62579b1cb9SLei YUE.g. 63579b1cb9SLei YU 64579b1cb9SLei YU```shell 65579b1cb9SLei YUWORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon NO_FORMAT_CODE=1 \ 66579b1cb9SLei YU./openbmc-build-scripts/run-unit-test-docker.sh 67579b1cb9SLei YU``` 68579b1cb9SLei YU 69*f4febd00SPatrick Williams`NO_FORMAT_CODE=1` tells the script to skip the `format-code.sh` so that it will 70*f4febd00SPatrick Williamsnot format the code and thus your repo could contain un-committed changes. 71579b1cb9SLei YU 724e997b04SAndrew Jeffery## Run CI for testing purposes only 734e997b04SAndrew Jeffery 744e997b04SAndrew JefferyTo only invoke the test suite and not get caught up the various analysis passes 754e997b04SAndrew Jefferythat might be run otherwise, set `TEST_ONLY=1`. 764e997b04SAndrew Jeffery 774e997b04SAndrew JefferyE.g. 784e997b04SAndrew Jeffery 794e997b04SAndrew Jeffery```shell 804e997b04SAndrew JefferyWORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon TEST_ONLY=1 \ 814e997b04SAndrew Jeffery./openbmc-build-scripts/run-unit-test-docker.sh 824e997b04SAndrew Jeffery``` 834e997b04SAndrew Jeffery 8473f9bc12SGunnar Mills## Reference an Existing Repo with `git worktree` 8573f9bc12SGunnar Mills 8673f9bc12SGunnar MillsIf you're actively developing on a local copy of a repo already, or you want to 8773f9bc12SGunnar Millsstart doing so, you should use `git worktree` instead so that the Docker 8873f9bc12SGunnar Millscontainer can reference a specific branch of your existing local repo. Learn 8973f9bc12SGunnar Millsmore about worktree by running `git help worktree` if you're curious. 9073f9bc12SGunnar Mills 9173f9bc12SGunnar MillsThis example demonstrates how to make a worktree of `phosphor-host-ipmid` in 9273f9bc12SGunnar Millsyour Docker container. 9373f9bc12SGunnar Mills 9473f9bc12SGunnar Mills```shell 9573f9bc12SGunnar Millscd /my/dir/for/phosphor-host-ipmid 9673f9bc12SGunnar Millsgit worktree add /path/to/ci_test_area/phosphor-host-ipmid 9773f9bc12SGunnar Mills``` 9873f9bc12SGunnar Mills 9973f9bc12SGunnar MillsNow, if you `cd /path/to/ci_test_area`, you should see a directory 10073f9bc12SGunnar Mills`phosphor-host-ipmid/`, and if you enter it and run `git status` you will see 10173f9bc12SGunnar Millsthat you're likely on a new branch named `phosphor-host-ipmid`. This is just for 10273f9bc12SGunnar Millsconvenience, since you can't check out a branch in your worktree that's already 10373f9bc12SGunnar Millschecked out somewhere else; you can safely ignore or delete that branch later. 10473f9bc12SGunnar Mills 10573f9bc12SGunnar MillsHowever, Git won't be able to figure out how to get to your main worktree 10673f9bc12SGunnar Mills(`/my/dir/for/phosphor-host-ipmid`), so we'll need to mount it when we run. Open 10773f9bc12SGunnar Millsup `/path/to/ci_test_area/openbmc-build-scripts/run-unit-test-docker.sh` and 10873f9bc12SGunnar Millsfind where we call `docker run`, way down at the bottom. Add an additional 10973f9bc12SGunnar Millsargument, remembering to escape the newline ('\'): 11073f9bc12SGunnar Mills 11173f9bc12SGunnar Mills``` 11273f9bc12SGunnar MillsPHOSPHOR_IPMI_HOST_PATH="/my/dir/for/phosphor-host-ipmid" 11373f9bc12SGunnar Mills 11473f9bc12SGunnar Millsdocker run --blah-blah-existing-flags \ 11573f9bc12SGunnar Mills -v ${PHOSPHOR_IPMI_HOST_PATH}:${PHOSPHOR_IPMI_HOST_PATH} \ 11673f9bc12SGunnar Mills -other \ 11773f9bc12SGunnar Mills -args 11873f9bc12SGunnar Mills``` 11973f9bc12SGunnar Mills 12073f9bc12SGunnar MillsThen commit this, so you can make sure not to lose it if you update the scripts 12173f9bc12SGunnar Millsrepo: 12273f9bc12SGunnar Mills 12373f9bc12SGunnar Mills```shell 12473f9bc12SGunnar Millscd openbmc-build-scripts 12573f9bc12SGunnar Millsgit add run-unit-test-docker.sh 12673f9bc12SGunnar Millsgit commit -m "mount phosphor-host-ipmid" 12773f9bc12SGunnar Mills``` 12873f9bc12SGunnar Mills 12973f9bc12SGunnar MillsThe easiest workflow in this situation now looks something like this: 13073f9bc12SGunnar Mills 13173f9bc12SGunnar Mills```shell 13273f9bc12SGunnar Mills# Hack in the main worktree. 13373f9bc12SGunnar Millscd /my/dir/for/phosphor-host-ipmid 13473f9bc12SGunnar Millsgit checkout -b add-foo 13573f9bc12SGunnar Mills# Make a change. 13673f9bc12SGunnar Millstouch foo 13773f9bc12SGunnar Mills# Make sure to commit it. 13873f9bc12SGunnar Millsgit add foo 13973f9bc12SGunnar Millsgit commit -sm "change foo" 14073f9bc12SGunnar Mills# Update the Docker worktree to agree with it. 14173f9bc12SGunnar Millscd /path/to/ci_test_area/phosphor-host-ipmid 14273f9bc12SGunnar Millsgit checkout --detach add-foo 14373f9bc12SGunnar Mills# Now run the Docker container normally 14473f9bc12SGunnar Mills``` 14573f9bc12SGunnar Mills 14673f9bc12SGunnar Mills#### Interactive Docker Session 14773f9bc12SGunnar Mills 148f65ecc5bSBenjamin FairTo use an interactive session, you can pass the flag `INTERACTIVE=true` to 149f65ecc5bSBenjamin Fair`run-unit-test-docker.sh` which will drop you into a bash shell with a default 150f65ecc5bSBenjamin FairD-Bus instance. This is handy if you need to run gdb on a core dump or run a 151f65ecc5bSBenjamin Fairdaemon on your workstation. 152