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>
diff --git a/development/README.md b/development/README.md
index 2280802..395200d 100644
--- a/development/README.md
+++ b/development/README.md
@@ -7,7 +7,7 @@
1. [Development Environment Setup](dev-environment.md)
Start here. This shows how to setup an OpenBMC development environment using
- its Software Development Kit and how to start the software emulator, QEMU.
+ its bitbake build process and how to start the software emulator, QEMU.
2. [Hello World](sdk-hello-world.md)
diff --git a/development/dev-environment.md b/development/dev-environment.md
index d2fad46..a62ed0b 100644
--- a/development/dev-environment.md
+++ b/development/dev-environment.md
@@ -11,23 +11,16 @@
OpenBMC uses the [Yocto](https://www.yoctoproject.org/) Project as its
underlying building and distribution generation framework. The main OpenBMC
[README](https://github.com/openbmc/openbmc/blob/master/README.md) provides
-information on getting up and going with Yocto and OpenBMC. There are mechanisms
-to use this process to build your changes but it can be slow and cumbersome for
-initial debug and validation of your software. This guide focuses on how to test
-new changes quickly using the OpenBMC Software Development Kit (SDK) and
+information on getting up and going with Yocto and OpenBMC. This tutorial will
+walk you through utilizing bitbake to build OpenBMC firmware and boot it in
[QEMU](https://www.qemu.org/).
-The SDK is a group of packages that are built during a BitBake operation.
-BitBake is the tool used to build Yocto based distributions. The SDK provides
-all required libraries and cross compilers to build OpenBMC applications. The
-SDK is not used to build entire OpenBMC flash images, it provides a mechanism to
-compile OpenBMC applications and libraries that you can then copy onto a running
-system for testing.
-
-QEMU is a software emulator that can be used to run OpenBMC images.
+Bitbake is the build engine used by Yocto and OpenBMC to build its custom Linux
+distribution for a system. QEMU is a software emulator that can be used to run
+OpenBMC images.
This doc walks through the recommended steps for setting up an OpenBMC
-development environment and installing the needed SDK.
+development environment, building OpenBMC, and running that image in QEMU.
For testing purposes, this guide uses the Romulus system as the default because
this is the system tested for each CI job, which means it's the most stable.
@@ -42,162 +35,145 @@
risk. If you have Windows or Mac OS then VirtualBox is the recommended
virtualization tool to run the development environment.
-1. Install either [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or
+1. Install a Virtual Machine
+
+ Install either [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or
[VMware](https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html)
onto your computer (Mac, Windows, Linux)
-Both have free versions available for what you need. VirtualBox is what the
-majority of core OpenBMC development is using. **Note:** If you want to use this
-VM to BitBake a full OpenBMC image, you'll want to allocate as many resources as
-possible. Ideal minimum resources are 8 threads, 16GB memory, 200GB hard drive.
-Just using for SDK builds and QEMU should work fine with the normal defaults on
-a VM.
+ Both have free versions available for what you need. **Note:** If you want to
+ use this VM to BitBake a full OpenBMC image, you'll want to allocate as many
+ resources as possible. Ideal minimum resources are 8 threads, 16GB memory,
+ 200GB hard drive.
+
+ OpenBMC continuous integration utilizes docker to build its images. This is
+ another possibility but not covered within this document. See
+ [build-setup.sh](https://github.com/openbmc/openbmc-build-scripts/blob/master/build-setup.sh)
+ for a reference on the script CI uses to build an appropriate docker
+ container and launch bitbake within it. This also works within a podman
+ environment.
2. Install the latest Ubuntu LTS release
-The majority of OpenBMC development community uses Ubuntu. The qemu below is
-built on [18.04](http://releases.ubuntu.com/18.04/) but whatever is most recent
-_should_ work. The same goes for other Linux distributions like Fedora but
-again, these are not tested nearly as much by the core OpenBMC team as Ubuntu.
+ The majority of OpenBMC development community uses Ubuntu. The qemu below is
+ built on the latest Ubuntu LTS release but whatever is most recent _should_
+ work. The same goes for other Linux distributions like Fedora but again,
+ these are not tested nearly as much by the core OpenBMC team as Ubuntu.
-**VirtualBox Tips** - You'll want copy/paste working between your VM and Host.
-To do that, once you have your VM up and running:
+ **VirtualBox Tips** - You'll want copy/paste working between your VM and
+ Host. To do that, once you have your VM up and running:
-- Devices -> Insert Guest Additions CD Image (install)
-- Devices -> Shared Clipboard -> Bidirectional
-- reboot (the VM)
+ - Devices -> Insert Guest Additions CD Image (install)
+ - Devices -> Shared Clipboard -> Bidirectional
+ - reboot (the VM)
3. Install required packages
-Refer to
-[Prerequisite](https://github.com/openbmc/openbmc/blob/master/README.md#1-prerequisite)
-link.
+ Refer to
+ [Prerequisite](https://github.com/openbmc/openbmc/blob/master/README.md#1-prerequisite)
+ link.
-**Note** - In Ubuntu, a "sudo apt-get update" will probably be needed before
-installing the packages.
+ **Note** - In Ubuntu, a "sudo apt-get update" will probably be needed before
+ installing the packages.
-## Download and Install SDK
+## Building OpenBMC
-The OpenBMC Software Development Kit (SDK) contains a cross-toolchain and a set
-libraries for working on OpenBMC applications. The SDK is installed on the
-machine you will use to develop applications for OpenBMC and not on the BMC
-itself.
+Note this section will take you through the process of building a Romulus
+OpenBMC image. Future tutorials will build on this by having you customize the
+image. If you would like to skip the building and just try out OpenBMC and QEMU
+then you can download the latest Romulus image from
+[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)
+and skip to the
+[Download and Start QEMU Session](#download-and-start-qemu-session) section.
-Generally, SDKs for one BMC cannot be used for developing software for other
-BMCs. This can be due to platform ABI, libc or kernel differences, or any other
-number of choices made in the configuration of the firmware.
+1. Clone OpenBMC
-Romulus is the BMC platform used for the purpose of this walk-through.
+ ```
+ git clone https://github.com/openbmc/openbmc.git
+ ```
-To begin working with the SDK:
+2. Build the Romulus OpenBMC Image (note this will take 30 - 120 minutes
+ depending on your hardware)
-1. Download the latest SDK to your system. It's recommended that you create a
- directory to store your SDK scripts and installation directories to keep your
- workspace organised.
+ ```
+ . setup romulus
+ bitbake obmc-phosphor-image
+ ```
-```
-mkdir -p ~/sdk
-cd ~/sdk
-
-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
-chmod u+x oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
-```
-
-2. Install the SDK
-
-Choose an appropriate location and name. It's a good idea to include the date
-and system supported by that SDK in the directory name. For example:
-
-```
-mkdir -p ~/sdk/romulus-`date +%F`
-```
-
-Run the following command to install the SDK. When command asks you to "Enter
-target directory for SDK", enter the directory you created in the previous step.
-
-```
-./oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
-```
-
-The installation script will indicate progress and give completion messages like
-this:
-
-```
-SDK has been successfully set up and is ready to be used.
-Each time you wish to use the SDK in a new shell session, you need to source
-the environment setup script e.g. $ . /...path-to-sdk.../environment-setup-arm1176jzs-openbmc-linux-gnueabi
-```
-
-3. Source yourself into the SDK
-
-Ensure no errors. The command to do this will be provided at the end of
-installation. To make your shell use the new SDK environment, you must source
-its `environment-setup` script which was created in the previous step. You may
-wish to save the required command, for example, cut/paste the text above into a
-README.
-
-That's it, you now have a working development environment for OpenBMC!
+The Romulus image is now located in
+`build/tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd`
+relative to your current directory.
## Download and Start QEMU Session
1. Download latest openbmc/qemu fork of QEMU application
-```
-wget https://jenkins.openbmc.org/job/latest-qemu-x86/lastSuccessfulBuild/artifact/qemu/build/qemu-system-arm
+ ```
+ wget https://jenkins.openbmc.org/job/latest-qemu-x86/lastSuccessfulBuild/artifact/qemu/build/qemu-system-arm
-chmod u+x qemu-system-arm
-```
+ chmod u+x qemu-system-arm
+ ```
-2. Download the Romulus image.
+2. Copy the image generated by the build to your current directory
-```
-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
-```
+ ```
+ cp ./tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd ./
+ ```
-3. Start QEMU with downloaded Romulus image
+3. Start QEMU with the Romulus image
**Note** - For REST, SSH and IPMI to work into your QEMU session, you must
connect up some host ports to the REST, SSH and IPMI ports in your QEMU
session. In this example, it just uses 2222, 2443, 2623. You can use whatever
you prefer.
-```
-./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,hostfwd=udp:127.0.0.1:2623-:623,hostname=qemu
-```
+ ```
+ ./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,hostfwd=udp:127.0.0.1:2623-:623,hostname=qemu
+ ```
-**Note** - By default, Jenkins and openbmc-test-automation use SSH and HTTPS
-ports 22 and 443, respectively. For the IPMI port 623 is used. SSH connection to
-use a user-defined port 2222 might not be successful. To use SSH port 22, HTTPS
-port 443 and IPMI port 623:
+ If you are running within a virtual environment where you can use the real
+ ports, then you would start QEMU with the following.
-```
-./qemu-system-arm -m 256 -machine romulus-bmc -nographic \
- -drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
- -net nic \
- -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
-```
+ ```
+ ./qemu-system-arm -m 256 -machine romulus-bmc -nographic \
+ -drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
+ -net nic \
+ -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
+ ```
4. Wait for your QEMU-based BMC to boot
-Login using default root/0penBmc login (Note the 0 is a zero).
+ Login using default root/0penBmc login (Note the 0 is a zero).
5. Check the system state
-You'll see a lot of services starting in the console, you can start running the
-obmcutil tool to check the state of the OpenBMC state services. When you see the
-following then you have successfully booted to "Ready" state.
+ You'll see a lot of services starting in the console, you can start running
+ the obmcutil tool to check the state of the OpenBMC state services. When you
+ see the following then you have successfully booted to "Ready" state.
-```
-root@openbmc:~# obmcutil state
-CurrentBMCState : xyz.openbmc_project.State.BMC.BMCState.Ready
-CurrentPowerState : xyz.openbmc_project.State.Chassis.PowerState.Off
-CurrentHostState : xyz.openbmc_project.State.Host.HostState.Off
-```
+ ```
+ root@openbmc:~# obmcutil state
+ CurrentBMCState : xyz.openbmc_project.State.BMC.BMCState.Ready
+ CurrentPowerState : xyz.openbmc_project.State.Chassis.PowerState.Off
+ CurrentHostState : xyz.openbmc_project.State.Host.HostState.Off
+ ```
-**Note** To exit (and kill) your QEMU session run: `ctrl+a x`
+ **Note** To exit (and kill) your QEMU session run: `ctrl+a x`
+
+6. Test out the ssh network interface
+
+ Run these from the system you started QEMU on
+
+ ```
+ ssh root@localhost -p 2222
+ ```
+
+ Login is the same as what was used above for the default QEMU login.
+
+You've now built an OpenBMC distribution and booted it in QEMU!
## Alternative yocto QEMU
@@ -208,6 +184,10 @@
which some find be more stable. This is particularly useful when debugging at
the application level.
+This is a more advanced section and may be useful to come back to once the
+basics are working for you. The next tutorial will focus on devtool and how to
+utilize it to customize your OpenBMC image.
+
- set up a bmc build environment
```