dev-environ: utilize devtool for code modifications
This moves from utilizing the SDK to using devtool in order to make a
"hello world" test. As noted in the prior commit, this is done due to
the complexity of the SDK environment vs. the more consistent (but
slower) devtool development process.
Change-Id: Iab7b6bbf82a5e36b121c1fedf916f956a35ca8e9
Signed-off-by: Andrew Geissler <geissonator@yahoo.com>
diff --git a/development/README.md b/development/README.md
index 395200d..0fcd817 100644
--- a/development/README.md
+++ b/development/README.md
@@ -9,10 +9,10 @@
Start here. This shows how to setup an OpenBMC development environment using
its bitbake build process and how to start the software emulator, QEMU.
-2. [Hello World](sdk-hello-world.md)
+2. [Hello World](devtool-hello-world.md)
- This shows how to use the Software Development Kit as you build and test your
- OpenBMC changes within QEMU.
+ This shows how to use the yocto tool, devtool, to extract an OpenBMC source
+ repository, build, and test your changes within QEMU.
3. [Web UI Development](web-ui.md)
diff --git a/development/devtool-hello-world.md b/development/devtool-hello-world.md
new file mode 100644
index 0000000..89403dc
--- /dev/null
+++ b/development/devtool-hello-world.md
@@ -0,0 +1,191 @@
+# OpenBMC Hello World using devtool
+
+**Document Purpose:** Walk through compiling and running an OpenBMC application
+in QEMU.
+
+**Prerequisites:** Completed Development Environment Setup
+[Document](https://github.com/openbmc/docs/blob/master/development/dev-environment.md)
+
+## Clone and Build a Repo
+
+devtool is a command line tool provided by the yocto distribution that allows
+you to extract a targeted repositories source code into your local bitbake
+environment and modify it.
+
+Today we'll be extracting the
+[phosphor-state-manager](https://github.com/openbmc/phosphor-state-manager.git)
+repository using devtool and modifying it.
+
+This assumes you have followed the first tutorial and are in the bitbake
+environment, right after doing the ". setup" command.
+
+1. Use devtool to extract source code
+
+ ```
+ devtool modify phosphor-state-manager
+ ```
+
+ The above command will output the directory the source code is contained in.
+
+2. Modify a source file and add a cout
+
+ ```
+ vi workspace/sources/phosphor-state-manager/bmc_state_manager_main.cpp
+ ```
+
+ Your diff should look something like this:
+
+ ```
+ +#include <iostream>
+
+ int main(int argc, char**)
+ {
+ @@ -17,6 +18,8 @@ int main(int argc, char**)
+
+ bus.request_name(BMC_BUSNAME);
+
+ + std::cout<<"Hello World" <<std::endl;
+ +
+ while (true)
+ {
+ ```
+
+3. Rebuild the flash image which will now include your change
+
+ This will be a much faster build as bitbake will utilize all of the cache
+ from your previous build, only building what is new.
+
+ ```
+ bitbake obmc-phosphor-image
+ ```
+
+ Follow the steps in the first tutorial to load your new image into a QEMU
+ session and boot it up.
+
+4. Confirm your "Hello World" made it into the new image
+
+ After you login to your QEMU session, verify the message is in the journal
+
+ ```
+ journalctl | grep "Hello World"
+ ```
+
+ You should see something like this:
+
+ ```
+ <date> romulus phosphor-bmc-state-manager[1089]: Hello World
+ ```
+
+You made a change, rebuilt the flash image to contain that change, and then
+booted that image up and verified the change made it in!
+
+## Loading an Application Directly Into a Running QEMU
+
+In this section we're going to modify the same source file, but instead of fully
+re-generating the flash image and booting QEMU again, we're going to just build
+the required binary and copy it into the running QEMU session and launch it.
+
+1. Modify your hello world
+
+ ```
+ vi workspace/sources/phosphor-state-manager/bmc_state_manager_main.cpp
+ ```
+
+ Change your cout to "Hello World Again"
+
+2. Bitbake only the phosphor-state-manager repository
+
+ Within bitbake, you can build only the repository (and it's dependencies)
+ that you are interested in. In this case, we'll just rebuild the
+ phosphor-state-manager repo to pick up your new hello world change.
+
+ ```
+ bitbake phosphor-state-manager
+ ```
+
+ Your new binary will be located at the following location relative to your
+ bitbake directory:
+ `./workspace/sources/phosphor-state-manager/oe-workdir/package/usr/bin/phosphor-bmc-state-manager`
+
+3. Create a safe file system for your application
+
+ Now is time to load your Hello World application in to QEMU virtual hardware.
+ The OpenBMC overrides the PATH variable to always look in /usr/local/bin/
+ first so you could simply scp your application in to /usr/local/bin, run it
+ and be done. That works fine for command line tests, but when you start
+ launching your applications via systemd services you will hit problems since
+ application paths are hardcoded in the service files. Let's start our journey
+ doing what the professionals do and create an overlay file system. Overlays
+ will save you time and grief. No more renaming and recovering original files,
+ no more forgetting which files you messed with during debug, and of course,
+ no more bricking the system. Log in to the QEMU instance and run these
+ commands.
+
+ ```
+ mkdir -p /tmp/persist/usr
+ mkdir -p /tmp/persist/work/usr
+ mount -t overlay -o lowerdir=/usr,upperdir=/tmp/persist/usr,workdir=/tmp/persist/work/usr overlay /usr
+ ```
+
+4. scp this binary onto your QEMU instance
+
+ If you used the default ports when starting QEMU then here is the scp command
+ to run from your phosphor-state-manager directory. If you chose your own port
+ then substitute that here for the 2222.
+
+ ```
+ scp -P 2222 ./workspace/sources/phosphor-state-manager/oe-workdir/package/usr/bin/phosphor-bmc-state-manager root@127.0.0.1:/usr/bin/
+ ```
+
+## Run the Application in QEMU
+
+1. Stop the BMC state manager service
+
+ ```
+ systemctl stop xyz.openbmc_project.State.BMC.service
+ ```
+
+2. Run the application in your QEMU session:
+
+ ```
+ phosphor-bmc-state-manager
+ ```
+
+ You'll see your "Hello World Again" message displayed. Ctrl^C to end that
+ application. In general, this is not how you will test new applications.
+ Instead, you'll be using systemd services.
+
+3. Start application via systemd service
+
+ OpenBMC uses systemd to manage its applications. There will be later
+ tutorials on this, but for now just run the following to restart the BMC
+ state service and have it pick up your new application:
+
+ ```
+ systemctl restart xyz.openbmc_project.State.BMC.service
+ ```
+
+ Since systemd started your service, the "Hello World Again" will not be
+ output to the console, but it will be in the journal. Later tutorials will
+ discuss the journal but for now just run:
+
+ ```
+ journalctl | tail
+ ```
+
+ You should see something like this in one of the journal entries:
+
+ ```
+ <date> romulus phosphor-bmc-state-manager[1089]: Hello World Again
+ ```
+
+That's it! You customized an existing BMC application, built it using devtool,
+and ran it within QEMU by both regenerating the entire flash image and patching
+it on via scp!
+
+## Advanced Workflow
+
+Once you've got a good handle on the above, there are some more advanced tools
+and wrappers you can utilize to optimize this flow. See this
+[link](https://amboar.github.io/notes/2022/01/13/openbmc-development-workflow.html)
+for more information.
diff --git a/development/sdk-hello-world.md b/development/sdk-hello-world.md
deleted file mode 100644
index d432382..0000000
--- a/development/sdk-hello-world.md
+++ /dev/null
@@ -1,138 +0,0 @@
-# OpenBMC Hello World in SDK
-
-**Document Purpose:** Walk through compiling and running an OpenBMC application
-in QEMU.
-
-**Prerequisites:** Completed Development Environment Setup
-[Document](https://github.com/openbmc/docs/blob/master/development/dev-environment.md)
-
-## Clone and Build a Repo
-
-This lesson uses
-[openbmc/phosphor-state-manager](https://github.com/openbmc/phosphor-state-manager)
-repo. To keep your repos organized, it's a good idea to keep them all under some
-common directory like ~/Code/.
-
-1. Clone the Repository
-
-```
-git clone https://github.com/openbmc/phosphor-state-manager.git
-```
-
-2. Add code to print out a Hello World
-
-```
-cd phosphor-state-manager
-vi bmc_state_manager_main.cpp
-```
-
-Your diff should look something like this:
-
-```
-+#include <iostream>
-
- int main(int argc, char**)
- {
-@@ -17,6 +18,8 @@ int main(int argc, char**)
-
- bus.request_name(BMC_BUSNAME);
-
-+ std::cout<<"Hello World" <<std::endl;
-+
- while (true)
- {
-```
-
-3. Build the Repository
-
-This is a meson based repository
-
-```
-meson build
-ninja -C build
-```
-
-## Load the Application Into QEMU
-
-1. Strip the binary you generated
-
-OpenBMC is an embedded environment so always best to load on the smallest size
-application/library
-
-```
-arm-openbmc-linux-gnueabi-strip phosphor-bmc-state-manager
-```
-
-2. Create a safe file system for your application
-
-Now is time to load your Hello World application in to QEMU virtual hardware.
-The OpenBMC overrides the PATH variable to always look in /usr/local/bin/ first
-so you could simply scp your application in to /usr/local/bin, run it and be
-done. That works fine for command line tests, but when you start launching your
-applications via systemd services you will hit problems since application paths
-are hardcoded in the service files. Let's start our journey doing what the
-professionals do and create an overlay file system. Overlays will save you time
-and grief. No more renaming and recovering original files, no more forgetting
-which files you messed with during debug, and of course, no more bricking the
-system. Log in to the QEMU instance and run these commands.
-
-```
-mkdir -p /tmp/persist/usr
-mkdir -p /tmp/persist/work/usr
-mount -t overlay -o lowerdir=/usr,upperdir=/tmp/persist/usr,workdir=/tmp/persist/work/usr overlay /usr
-```
-
-3. scp this binary onto your QEMU instance
-
-If you used the default ports when starting QEMU then here is the scp command to
-run from your phosphor-state-manager directory. If you chose your own port then
-substitute that here for the 2222.
-
-```
-scp -P 2222 phosphor-bmc-state-manager root@127.0.0.1:/usr/bin/
-```
-
-## Run the Application in QEMU
-
-1. Stop the BMC state manager service
-
-```
-systemctl stop xyz.openbmc_project.State.BMC.service
-```
-
-2. Run the application in your QEMU session:
-
-```
-phosphor-bmc-state-manager
-```
-
-You'll see your "Hello World" message displayed. Ctrl^C to end that application.
-In general, this is not how you will test new applications. Instead, you'll be
-using systemd services.
-
-3. Start application via systemd service
-
-OpenBMC uses systemd to manage its applications. There will be later tutorials
-on this, but for now just run the following to restart the BMC state service and
-have it pick up your new application:
-
-```
-systemctl restart xyz.openbmc_project.State.BMC.service
-```
-
-Since systemd started your service, the "Hello World" will not be output to the
-console, but it will be in the journal. Later tutorials will discuss the journal
-but for now just run:
-
-```
-journalctl | tail
-```
-
-You should see something like this in one of the journal entries:
-
-```
-<date> romulus phosphor-bmc-state-manager[1089]: Hello World
-```
-
-That's it! You customized an existing BMC application, built it using the SDK,
-and ran it within QEMU!