Skip to content

Commit f31c96d

Browse files
geissonatorgeissonator
committed
dev-environ: remove SDK and move to devtool
This is a series of patches to clean up our development tutorials. There's some miscellaneous cleanup combined with moving these from the use of the SDK to devtool. SDK usage, especially by new users of OpenBMC, can be confusing. You need to ensure you have the exact same level matching your version of openbmc/openbmc. There are consistently questions and confusion around the use of the SDK in discord and the mailing list. Although it can offer some extra speed with development, it's not a good area to have new users start with. Also, it does not seem many of our active OpenBMC developers use it, as it seems to consistently be missing packages required to build all of the OpenBMC repos. Given the above, lets refocus these intro-to-openbmc tutorials on just using bitbake and devtool. It takes a bit longer but you're guaranteed to have the correct levels and all needed packages when doing this. Change-Id: I7d50ea85a3489f702e98d7e8dca02e44886c2a5c Signed-off-by: Andrew Geissler <geissonator@yahoo.com>
1 parent 1f98100 commit f31c96d

File tree

2 files changed

+106
-126
lines changed

2 files changed

+106
-126
lines changed

‎development/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ any order you like, but the recommended flow can be found below.
77
1. [Development Environment Setup](dev-environment.md)
88

99
Start here. This shows how to setup an OpenBMC development environment using
10-
its Software Development Kit and how to start the software emulator, QEMU.
10+
its bitbake build process and how to start the software emulator, QEMU.
1111

1212
2. [Hello World](sdk-hello-world.md)
1313

‎development/dev-environment.md

Lines changed: 105 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -11,23 +11,16 @@
1111
OpenBMC uses the [Yocto](https://www.yoctoproject.org/) Project as its
1212
underlying building and distribution generation framework. The main OpenBMC
1313
[README](https://github.com/openbmc/openbmc/blob/master/README.md) provides
14-
information on getting up and going with Yocto and OpenBMC. There are mechanisms
15-
to use this process to build your changes but it can be slow and cumbersome for
16-
initial debug and validation of your software. This guide focuses on how to test
17-
new changes quickly using the OpenBMC Software Development Kit (SDK) and
14+
information on getting up and going with Yocto and OpenBMC. This tutorial will
15+
walk you through utilizing bitbake to build OpenBMC firmware and boot it in
1816
[QEMU](https://www.qemu.org/).
1917

20-
The SDK is a group of packages that are built during a BitBake operation.
21-
BitBake is the tool used to build Yocto based distributions. The SDK provides
22-
all required libraries and cross compilers to build OpenBMC applications. The
23-
SDK is not used to build entire OpenBMC flash images, it provides a mechanism to
24-
compile OpenBMC applications and libraries that you can then copy onto a running
25-
system for testing.
26-
27-
QEMU is a software emulator that can be used to run OpenBMC images.
18+
Bitbake is the build engine used by Yocto and OpenBMC to build its custom Linux
19+
distribution for a system. QEMU is a software emulator that can be used to run
20+
OpenBMC images.
2821

2922
This doc walks through the recommended steps for setting up an OpenBMC
30-
development environment and installing the needed SDK.
23+
development environment, building OpenBMC, and running that image in QEMU.
3124

3225
For testing purposes, this guide uses the Romulus system as the default because
3326
this is the system tested for each CI job, which means it's the most stable.
@@ -42,162 +35,145 @@ release. Other versions of Linux may work but you are using that at your own
4235
risk. If you have Windows or Mac OS then VirtualBox is the recommended
4336
virtualization tool to run the development environment.
4437

45-
1. Install either [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or
38+
1. Install a Virtual Machine
39+
40+
Install either [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or
4641
[VMware](https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html)
4742
onto your computer (Mac, Windows, Linux)
4843

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 this
51-
VM to BitBake a full OpenBMC image, you'll want to allocate as many resources as
52-
possible. Ideal minimum resources are 8 threads, 16GB memory, 200GB hard drive.
53-
Just using for SDK builds and QEMU should work fine with the normal defaults on
54-
a VM.
44+
Both have free versions available for what you need. **Note:** If you want to
45+
use this VM to BitBake a full OpenBMC image, you'll want to allocate as many
46+
resources as possible. Ideal minimum resources are 8 threads, 16GB memory,
47+
200GB hard drive.
48+
49+
OpenBMC continuous integration utilizes docker to build its images. This is
50+
another possibility but not covered within this document. See
51+
[build-setup.sh](https://github.com/openbmc/openbmc-build-scripts/blob/master/build-setup.sh)
52+
for a reference on the script CI uses to build an appropriate docker
53+
container and launch bitbake within it. This also works within a podman
54+
environment.
5555

5656
2. Install the latest Ubuntu LTS release
5757

58-
The majority of OpenBMC development community uses Ubuntu. The qemu below is
59-
built on [18.04](http://releases.ubuntu.com/18.04/) but whatever is most recent
60-
_should_ work. The same goes for other Linux distributions like Fedora but
61-
again, these are not tested nearly as much by the core OpenBMC team as Ubuntu.
58+
The majority of OpenBMC development community uses Ubuntu. The qemu below is
59+
built on the latest Ubuntu LTS release but whatever is most recent _should_
60+
work. The same goes for other Linux distributions like Fedora but again,
61+
these are not tested nearly as much by the core OpenBMC team as Ubuntu.
6262

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:
63+
**VirtualBox Tips** - You'll want copy/paste working between your VM and
64+
Host. To do that, once you have your VM up and running:
6565

66-
- Devices -> Insert Guest Additions CD Image (install)
67-
- Devices -> Shared Clipboard -> Bidirectional
68-
- reboot (the VM)
66+
- Devices -> Insert Guest Additions CD Image (install)
67+
- Devices -> Shared Clipboard -> Bidirectional
68+
- reboot (the VM)
6969

7070
3. Install required packages
7171

72-
Refer to
73-
[Prerequisite](https://github.com/openbmc/openbmc/blob/master/README.md#1-prerequisite)
74-
link.
75-
76-
**Note** - In Ubuntu, a "sudo apt-get update" will probably be needed before
77-
installing the packages.
78-
79-
## Download and Install SDK
72+
Refer to
73+
[Prerequisite](https://github.com/openbmc/openbmc/blob/master/README.md#1-prerequisite)
74+
link.
8075

81-
The OpenBMC Software Development Kit (SDK) contains a cross-toolchain and a set
82-
libraries for working on OpenBMC applications. The SDK is installed on the
83-
machine you will use to develop applications for OpenBMC and not on the BMC
84-
itself.
76+
**Note** - In Ubuntu, a "sudo apt-get update" will probably be needed before
77+
installing the packages.
8578

86-
Generally, SDKs for one BMC cannot be used for developing software for other
87-
BMCs. This can be due to platform ABI, libc or kernel differences, or any other
88-
number of choices made in the configuration of the firmware.
89-
90-
Romulus is the BMC platform used for the purpose of this walk-through.
91-
92-
To begin working with the SDK:
93-
94-
1. Download the latest SDK to your system. It's recommended that you create a
95-
directory to store your SDK scripts and installation directories to keep your
96-
workspace organised.
97-
98-
```
99-
mkdir -p ~/sdk
100-
cd ~/sdk
79+
## Building OpenBMC
10180

102-
wget https://jenkins.openbmc.org/job/latest-master-sdk/label=docker-builder,target=romulus/lastSuccessfulBuild/artifact/deploy/sdk/oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
103-
chmod u+x oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
104-
```
105-
106-
2. Install the SDK
107-
108-
Choose an appropriate location and name. It's a good idea to include the date
109-
and system supported by that SDK in the directory name. For example:
110-
111-
```
112-
mkdir -p ~/sdk/romulus-`date +%F`
113-
```
114-
115-
Run the following command to install the SDK. When command asks you to "Enter
116-
target directory for SDK", enter the directory you created in the previous step.
117-
118-
```
119-
./oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
120-
```
81+
Note this section will take you through the process of building a Romulus
82+
OpenBMC image. Future tutorials will build on this by having you customize the
83+
image. If you would like to skip the building and just try out OpenBMC and QEMU
84+
then you can download the latest Romulus image from
85+
[here](https://jenkins.openbmc.org/job/latest-master/label=docker-builder,target=romulus/lastSuccessfulBuild/artifact/openbmc/build/tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd)
86+
and skip to the
87+
[Download and Start QEMU Session](#download-and-start-qemu-session) section.
12188

122-
The installation script will indicate progress and give completion messages like
123-
this:
89+
1. Clone OpenBMC
12490

125-
```
126-
SDK has been successfully set up and is ready to be used.
127-
Each time you wish to use the SDK in a new shell session, you need to source
128-
the environment setup script e.g. $ . /...path-to-sdk.../environment-setup-arm1176jzs-openbmc-linux-gnueabi
129-
```
91+
```
92+
git clone https://github.com/openbmc/openbmc.git
93+
```
13094

131-
3. Source yourself into the SDK
95+
2. Build the Romulus OpenBMC Image (note this will take 30 - 120 minutes
96+
depending on your hardware)
13297

133-
Ensure no errors. The command to do this will be provided at the end of
134-
installation. To make your shell use the new SDK environment, you must source
135-
its `environment-setup` script which was created in the previous step. You may
136-
wish to save the required command, for example, cut/paste the text above into a
137-
README.
98+
```
99+
. setup romulus
100+
bitbake obmc-phosphor-image
101+
```
138102

139-
That's it, you now have a working development environment for OpenBMC!
103+
The Romulus image is now located in
104+
`build/tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd`
105+
relative to your current directory.
140106

141107
## Download and Start QEMU Session
142108

143109
1. Download latest openbmc/qemu fork of QEMU application
144110

145-
```
146-
wget https://jenkins.openbmc.org/job/latest-qemu-x86/lastSuccessfulBuild/artifact/qemu/build/qemu-system-arm
111+
```
112+
wget https://jenkins.openbmc.org/job/latest-qemu-x86/lastSuccessfulBuild/artifact/qemu/build/qemu-system-arm
147113
148-
chmod u+x qemu-system-arm
149-
```
114+
chmod u+x qemu-system-arm
115+
```
150116

151-
2. Download the Romulus image.
117+
2. Copy the image generated by the build to your current directory
152118

153-
```
154-
wget https://jenkins.openbmc.org/job/latest-master/label=docker-builder,target=romulus/lastSuccessfulBuild/artifact/openbmc/build/tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd
155-
```
119+
```
120+
cp ./tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd ./
121+
```
156122

157-
3. Start QEMU with downloaded Romulus image
123+
3. Start QEMU with the Romulus image
158124

159125
**Note** - For REST, SSH and IPMI to work into your QEMU session, you must
160126
connect up some host ports to the REST, SSH and IPMI ports in your QEMU
161127
session. In this example, it just uses 2222, 2443, 2623. You can use whatever
162128
you prefer.
163129

164-
```
165-
./qemu-system-arm -m 256 -M romulus-bmc -nographic \
166-
-drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
167-
-net nic \
168-
-net user,hostfwd=:127.0.0.1:2222-:22,hostfwd=:127.0.0.1:2443-:443,hostfwd=udp:127.0.0.1:2623-:623,hostname=qemu
169-
```
130+
```
131+
./qemu-system-arm -m 256 -M romulus-bmc -nographic \
132+
-drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
133+
-net nic \
134+
-net user,hostfwd=:127.0.0.1:2222-:22,hostfwd=:127.0.0.1:2443-:443,hostfwd=udp:127.0.0.1:2623-:623,hostname=qemu
135+
```
170136

171-
**Note** - By default, Jenkins and openbmc-test-automation use SSH and HTTPS
172-
ports 22 and 443, respectively. For the IPMI port 623 is used. SSH connection to
173-
use a user-defined port 2222 might not be successful. To use SSH port 22, HTTPS
174-
port 443 and IPMI port 623:
137+
If you are running within a virtual environment where you can use the real
138+
ports, then you would start QEMU with the following.
175139

176-
```
177-
./qemu-system-arm -m 256 -machine romulus-bmc -nographic \
178-
-drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
179-
-net nic \
180-
-net user,hostfwd=:127.0.0.1:22-:22,hostfwd=:127.0.0.1:443-:443,hostfwd=tcp:127.0.0.1:80-:80,hostfwd=tcp:127.0.0.1:2200-:2200,hostfwd=udp:127.0.0.1:623-:623,hostfwd=udp:127.0.0.1:664-:664,hostname=qemu
181-
```
140+
```
141+
./qemu-system-arm -m 256 -machine romulus-bmc -nographic \
142+
-drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
143+
-net nic \
144+
-net user,hostfwd=:127.0.0.1:22-:22,hostfwd=:127.0.0.1:443-:443,hostfwd=tcp:127.0.0.1:80-:80,hostfwd=tcp:127.0.0.1:2200-:2200,hostfwd=udp:127.0.0.1:623-:623,hostfwd=udp:127.0.0.1:664-:664,hostname=qemu
145+
```
182146

183147
4. Wait for your QEMU-based BMC to boot
184148

185-
Login using default root/0penBmc login (Note the 0 is a zero).
149+
Login using default root/0penBmc login (Note the 0 is a zero).
186150

187151
5. Check the system state
188152

189-
You'll see a lot of services starting in the console, you can start running the
190-
obmcutil tool to check the state of the OpenBMC state services. When you see the
191-
following then you have successfully booted to "Ready" state.
153+
You'll see a lot of services starting in the console, you can start running
154+
the obmcutil tool to check the state of the OpenBMC state services. When you
155+
see the following then you have successfully booted to "Ready" state.
192156

193-
```
194-
root@openbmc:~# obmcutil state
195-
CurrentBMCState : xyz.openbmc_project.State.BMC.BMCState.Ready
196-
CurrentPowerState : xyz.openbmc_project.State.Chassis.PowerState.Off
197-
CurrentHostState : xyz.openbmc_project.State.Host.HostState.Off
198-
```
157+
```
158+
root@openbmc:~# obmcutil state
159+
CurrentBMCState : xyz.openbmc_project.State.BMC.BMCState.Ready
160+
CurrentPowerState : xyz.openbmc_project.State.Chassis.PowerState.Off
161+
CurrentHostState : xyz.openbmc_project.State.Host.HostState.Off
162+
```
163+
164+
**Note** To exit (and kill) your QEMU session run: `ctrl+a x`
165+
166+
6. Test out the ssh network interface
199167

200-
**Note** To exit (and kill) your QEMU session run: `ctrl+a x`
168+
Run these from the system you started QEMU on
169+
170+
```
171+
ssh root@localhost -p 2222
172+
```
173+
174+
Login is the same as what was used above for the default QEMU login.
175+
176+
You've now built an OpenBMC distribution and booted it in QEMU!
201177

202178
## Alternative yocto QEMU
203179

@@ -208,6 +184,10 @@ binaries. Using yocto qemu also uses the
208184
which some find be more stable. This is particularly useful when debugging at
209185
the application level.
210186

187+
This is a more advanced section and may be useful to come back to once the
188+
basics are working for you. The next tutorial will focus on devtool and how to
189+
utilize it to customize your OpenBMC image.
190+
211191
- set up a bmc build environment
212192

213193
```

0 commit comments

Comments
 (0)