1# Yocto in OpenBMC 2 3The Yocto Project is an open source collaboration project that provides 4templates, tools and methods to help you create custom Linux-based systems for 5embedded products regardless of the hardware architecture. 6 7OpenBMC uses the Yocto tools to manage configuration and creation of BMC 8images. 9 10## Developing with Yocto 11 12There are two main use-cases for Yocto in OpenBMC: 13 141. Building from master or existing tags 152. Developing changes for submission to master 16 17The first is the easy case, and largely involves picking the system 18configuration to build before invoking `bitbake`. Examples for 19[Palmetto](cheatsheet.md#building-for-palmetto) and 20[Zaius](cheatsheet.md#building-for-zaius) are in the 21[cheatsheet](cheatsheet.md). 22 23The second case can be helped with Yocto's `devtool`. After running 24`. openbmc-env`, a tool called `devtool` will be in your path, and can be 25applied in several ways. 26 27If you have an existing source tree you'd like to integrate, running 28`devtool modify -n ${PACKAGE} ${SRCTREE}` first creates a new Yocto layer in 29your build directory where devtool stores recipe modifications. It then 30constructs a `.bbappend` for the package recipe and uses the 31`externalsource` class to replace the download, fetch, and patch steps with 32no-ops. The result is that when you build the package, it will use the local 33source directory as is. Keep in mind that the package recipe may not perform a 34clean and depending on what you are doing, you may need to run `${PACKAGE}` 35build system's clean command in `${SRCTREE}` to clear any built objects. Also 36if you change the source, you may need to run 37`bitbake -c cleansstate ${PACKAGE}` to clear BitBake's caches. 38 39Alternatively, if you don't already have a local source tree but would still 40like to modify the package, invoking `devtool modify ${PACKAGE}` will handle 41the fetch, unpack and patch phases for you and drop a source tree into your 42default workspace location. 43 44When you are all done, run `devtool reset ${PACKAGE}` to remove the `.bbappend` 45from the devtool Yocto layer. 46 47Further information on [devtool][0] can be found in the [Yocto Mega Manual][1]. 48 49 50### Adding a file to your image 51 52There are a lot of examples of working with BitBake out there. The [recipe 53example][2] from OpenEmbedded is a great one and the premise of this OpenBMC 54tailored section. 55 56So you wrote some code. You've been scp'ing the compiled binary on to the 57OpenBMC system for a while and you know there is a better way. Have it built 58as part of your flash image. 59 60Run the devtool command to add your repo to the workspace. In my example I 61have a repo out on GitHub that contains my code. 62 63``` 64devtool add welcome https://github.com/causten/hello.git 65``` 66 67Now edit the bb file it created for you. You can just use `vim` but 68`devtool` can also edit the recipe `devtool edit-recipe welcome` without 69having to type the complete path. 70 71Add/Modify these lines. 72 73``` 74do_install () { 75 install -m 0755 -d ${D}${bindir} ${D}${datadir}/welcome 76 install -m 0644 ${S}/hello ${D}${bindir} 77 install -m 0644 ${S}/README.md ${D}${datadir}/welcome/ 78} 79``` 80 81The install directives create directories and then copies the files into them. 82Now BitBake will pick them up from the traditional `/usr/bin` and 83`/usr/shared/doc/hello/README.md`. 84 85The Final Step is to tell BitBake that you need the `welcome` recipe 86 87``` 88vim conf/local.conf 89IMAGE_INSTALL_append = " welcome" 90``` 91 92That's it, recompile and boot your system, the binary `hello` will be in 93`/usr/bin` and the `README.md` will be in `/usr/shared/doc/welcome`. 94 95 96### Know what your image has 97 98Sure you could flash and boot your system to see if your file made it, but there 99is a faster way. The `rootfs` directory down in the depths of the `build/tmp` 100path is the staging area where files are placed to be packaged. 101 102In my example to check if README.md was going to be added just do... 103 104``` 105ls build/tmp/work/${MACHINE}-openbmc-linux-gnueabi/obmc-phosphor-image/1.0-r0/rootfs/usr/share/welcome/README.md 106``` 107 108NXP wrote a few examples of [useful](https://community.nxp.com/docs/DOC-94953) 109commands with BitBake that find the file too 110 111``` 112bitbake -g obmc-phosphor-image && cat pn-depends.dot |grep welcome 113``` 114 115[0]: https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#using-devtool-in-your-sdk-workflow "devtool" 116[1]: http://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html "Yocto Mega Manual" 117[2]: http://www.embeddedlinux.org.cn/OEManual/recipes_examples.html "Recipe Example" 118