1# OpenBMC Development Environment
2
3**Document Purpose:** How to set up an OpenBMC development environment
4
5**Audience:** Programmer familiar with Linux and BMCs
6
7**Prerequisites:** Current Linux, Mac, or Windows system
8
9### Overview
10
11OpenBMC uses the [Yocto](https://www.yoctoproject.org/) Project as its
12underlying building and distribution generation framework. The main
13OpenBMC [README](https://github.com/openbmc/openbmc/blob/master/README.md)
14provides information on getting up and going with Yocto and OpenBMC.
15There are mechanisms to use this process to build your changes but it can be
16slow and cumbersome for initial debug and validation of your software. This
17guide focuses on how to test new changes quickly using the OpenBMC Software
18Development Kit (SDK) and [QEMU](https://www.qemu.org/).
19
20The SDK is a group of packages that are built during a BitBake operation.
21BitBake is the tool used to build Yocto based distributions. The SDK provides
22all required libraries and cross compilers to build OpenBMC applications. The
23SDK is not used to build entire OpenBMC flash images, it provides a mechanism to
24compile OpenBMC applications and libraries that you can then copy onto a running
25system for testing.
26
27QEMU is a software emulator that can be used to run OpenBMC images.
28
29This doc walks through the recommended steps for setting up an OpenBMC
30development environment and installing the needed SDK.
31
32For testing purposes, this guide uses the Romulus system as the default because
33this is the system tested for each CI job, which means it's the most stable.
34
35### Install Linux Environment
36
37If you are running Linux, and are ok with installing some additional packages,
38then you can skip to step 3.
39
40The recommended OpenBMC development environment is the latest Ubuntu LTS
41release. Other versions of Linux may work but you are using that at your own
42risk. If you have Windows or Mac OS then VirtualBox is the recommended
43virtualization tool to run the development environment.
44
451. Install either [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or
46[VMware](https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html)
47onto your computer (Mac, Windows, Linux)
48
49  Both have free versions available for what you need. VirtualBox is what the
50  majority of core OpenBMC development is using. **Note:** If you want to use
51  this VM to BitBake a full OpenBMC image, you'll want to allocate as many
52  resources as possible. Ideal minimum resources are 8 threads, 16GB memory,
53  200GB hard drive. Just using for SDK builds and QEMU should work fine with the
54  normal defaults on a VM.
55
562. Install the latest Ubuntu LTS release
57
58  The majority of OpenBMC dev is on [16.04](http://releases.ubuntu.com/16.04/)
59  but whatever is most recent *should* work. The same goes for other Linux
60  distributions like Fedora but again, these are not tested nearly as much by
61  the core OpenBMC team as Ubuntu.
62
63  **VirtualBox Tips** - You'll want copy/paste working between your VM and Host.
64  To do that, once you have your VM up and running:
65  - Devices -> Insert Guest Additions CD Image (install)
66  - Devices -> Shared Clipboard -> Bidirectional
67  - reboot (the VM)
68
693. Install required packages
70
71  Refer to
72  [Prerequisite](https://github.com/openbmc/openbmc/blob/master/README.md#1-prerequisite)
73  link.
74
75  **Note** - In Ubuntu, a "sudo apt-get update" will probably be needed before
76  installing the packages.
77
78### Download and Start QEMU Session
79
801. Download latest openbmc/qemu fork of QEMU application
81
82  ```
83  wget https://openpower.xyz/job/openbmc-qemu-build-merge-x86/lastSuccessfulBuild/artifact/qemu-build/arm-softmmu/qemu-system-arm
84
85  chmod u+x qemu-system-arm
86  ```
87
882. Download the Romulus image.
89
90  ```
91  wget https://openpower.xyz/job/openbmc-build/distro=ubuntu,label=builder,target=romulus/lastSuccessfulBuild/artifact/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd
92  ```
93
943. Start QEMU with downloaded Romulus image
95
96  **Note** - For REST and SSH to work into your QEMU session, you must connect
97  up some host ports to the REST and SSH ports in your QEMU session. In this
98  example, it just uses 2222 and 2443. You can use whatever you prefer.
99  ```
100  ./qemu-system-arm -m 256 -M romulus-bmc -nographic -drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd -net nic -net user,hostfwd=:127.0.0.1:2222-:22,hostfwd=:127.0.0.1:2443-:443,hostname=qemu
101  ```
102
1034. Wait for your QEMU-based BMC to boot
104
105  Login using default root/0penBmc login (Note the 0 is a zero).
106
1075. Check the system state
108
109  You'll see a lot of services starting in the console, you can start running
110  the obmcutil tool to check the state of the OpenBMC state services. When you
111  see the following then you have successfully booted to "Ready" state.
112
113  `obmcutil state`
114
115  > CurrentBMCState     : xyz.openbmc_project.State.BMC.BMCState.Ready
116  > CurrentPowerState   : xyz.openbmc_project.State.Chassis.PowerState.Off
117  > CurrentHostState    : xyz.openbmc_project.State.Host.HostState.Off
118
119    **Note** To exit (and kill) your QEMU session run: `ctrl+a x`
120
121### Download and Install SDK
122
123To keep things organized, create a directory to store your SDK install scripts
124and directories.
125
1261. Download the latest SDK to your system (using Romulus for this walk through)
127
128  ```
129  mkdir -p ~/sdk
130  cd ~/sdk
131
132  wget https://openpower.xyz/job/openbmc-build-sdk/distro=ubuntu,target=romulus/lastSuccessfulBuild/artifact/deploy/sdk/oecore-x86_64-armv6-toolchain-nodistro.0.sh
133
134  chmod u+x oecore-x86_64-armv6-toolchain-nodistro.0.sh
135  ```
136
1372. Install the SDK
138
139  Choose an appropriate location and name. It's a good idea to include the date
140  and system supported by that SDK in the directory name. For example:
141
142  ```
143  mkdir -p ~/sdk/romulus-`date +%F`
144  ```
145
146  Run the following command to install the SDK.  When command  asks you to
147  "Enter target directory for SDK", enter the directory you created in the
148  previous step.
149
150  ```
151  ./oecore-x86_64-armv6-toolchain-nodistro.0.sh
152  ```
153
154  The installation script will indicate progress and give completion messages
155  like this:
156  ```
157  SDK has been successfully set up and is ready to be used.
158  Each time you wish to use the SDK in a new shell session, you need to source
159  the environment setup script e.g. $ . /...path-to-sdk.../environment-setup-armv6-openbmc-linux-gnueabi
160  ```
161
1623. Source yourself into the SDK
163
164  Ensure no errors. The command to do this will be provided at the end of
165  installation. To make your shell use the new SDK environment, you must source
166  its `environment-setup` script which was created in the previous step.  You
167  may wish to save the required command, for example, cut/paste the text above
168  into a README.
169
170That's it, you now have a working development environment for OpenBMC!
171