# Yocto in OpenBMC

The Yocto Project is an open source collaboration project that provides
templates, tools and methods to help you create custom Linux-based systems for
embedded products regardless of the hardware architecture.

OpenBMC uses the Yocto tools to manage configuration and creation of BMC
images.

## Developing with Yocto

There are two main use-cases for Yocto in OpenBMC:

1. Building from master or existing tags
2. Developing changes for submission to master

The first is the easy case, and largely involves picking the system
configuration to build before invoking `bitbake`. Examples for
[Palmetto](cheatsheet.md#building-for-palmetto) and
[Zaius](cheatsheet.md#building-for-zaius) are in the
[cheatsheet](cheatsheet.md).

The second case can be helped with Yocto's `devtool`. After running
`.  openbmc-env`, a tool called `devtool` will be in your path, and can be
applied in several ways.

If you have an existing source tree you'd like to integrate, running
`devtool modify -n ${PACKAGE} ${SRCTREE}` first creates a new Yocto layer in
your build directory where devtool stores recipe modifications. It then
constructs a `.bbappend` for the package recipe and uses the
`externalsource` class to replace the download, fetch, and patch steps with
no-ops. The result is that when you build the package, it will use the local
source directory as is. Keep in mind that the package recipe may not perform a
clean and depending on what you are doing, you may need to run `${PACKAGE}`
build system's clean command in `${SRCTREE}` to clear any built objects. Also
if you change the source, you may need to run
`bitbake -c cleansstate ${PACKAGE}` to clear BitBake's caches.

Alternatively, if you don't already have a local source tree but would still
like to modify the package, invoking `devtool modify ${PACKAGE}` will handle
the fetch, unpack and patch phases for you and drop a source tree into your
default workspace location.

When you are all done, run `devtool reset ${PACKAGE}` to remove the `.bbappend`
from the devtool Yocto layer.

Further information on [devtool][0] can be found in the [Yocto Mega Manual][1].


### Adding a file to your image

There are a lot of examples of working with BitBake out there.  The [recipe
example][2] from OpenEmbedded is a great one and the premise of this OpenBMC
tailored section.

So you wrote some code.  You've been scp'ing the compiled binary on to the
OpenBMC system for a while and you know there is a better way.  Have it built
as part of your flash image.

Run the devtool command to add your repo to the workspace.  In my example I
have a repo out on GitHub that contains my code.

```
devtool add welcome https://github.com/causten/hello.git
```

Now edit the bb file it created for you.  You can just use `vim` but
`devtool` can also edit the recipe `devtool edit-recipe welcome` without
having to type the complete path.

Add/Modify these lines.

```
do_install () {
        install -m 0755 -d ${D}${bindir} ${D}${datadir}/welcome
        install -m 0644 ${S}/hello ${D}${bindir}
        install -m 0644 ${S}/README.md ${D}${datadir}/welcome/
}
```

The install directives create directories and then copies the files into them.
Now BitBake will pick them up from the traditional `/usr/bin` and
`/usr/shared/doc/hello/README.md`.

The Final Step is to tell BitBake that you need the `welcome` recipe

```
vim conf/local.conf
IMAGE_INSTALL_append = " welcome"
```

That's it, recompile and boot your system, the binary `hello` will be in
`/usr/bin` and the `README.md` will be in `/usr/shared/doc/welcome`.


### Know what your image has

Sure you could flash and boot your system to see if your file made it, but there
is a faster way.  The `rootfs` directory down in the depths of the `build/tmp`
path is the staging area where files are placed to be packaged.

In my example to check if README.md was going to be added just do...

```
ls build/tmp/work/${MACHINE}-openbmc-linux-gnueabi/obmc-phosphor-image/1.0-r0/rootfs/usr/share/welcome/README.md
```

NXP wrote a few examples of [useful](https://community.nxp.com/docs/DOC-94953)
commands with BitBake that find the file too

```
bitbake -g obmc-phosphor-image && cat pn-depends.dot |grep welcome
```

[0]: https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#using-devtool-in-your-sdk-workflow "devtool"
[1]: http://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html "Yocto Mega Manual"
[2]: http://www.embeddedlinux.org.cn/OEManual/recipes_examples.html "Recipe Example"