dev-doc: Tutorial on basic hello world

Walk through the process to customize and build an
OpenBMC repository from within the SDK, load it into
a QEMU session, and run it

Change-Id: I06edafd0838eca968a46acc218b77026b6913211
Signed-off-by: Andrew Geissler <geissonator@yahoo.com>

1 files changed, 114 insertions, 0 deletions

diff --git a/development/sdk-hello-world.md b/development/sdk-hello-world.md
new file mode 100644
index 0000000..bf69bbf
--- /dev/null
+++ b/development/sdk-hello-world.md
@@ -0,0 +1,114 @@
+# 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 an automake based repository so it will have a bootstrap.sh script
+  for doing the basic build setups.
+  ```
+  ./bootstrap.sh
+  ./configure ${CONFIGURE_FLAGS}
+  make
+  ```
+
+### 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 the directory in your QEMU session
+  for you to copy your binary too
+
+  OpenBMC overrides the PATH variable to always look in /usr/local/bin/ first so
+  that's where we put patches for testing. From your QEMU session:
+  ```
+  mkdir -p /usr/local/bin
+  ```
+
+  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/local/bin/
+  ```
+
+### Run the Application in QEMU
+
+  1. 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.
+
+  2. 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.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!