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[Barreleye](cheatsheet.md#building-for-barreleye) 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](http://docs.openembedded.org/usermanual/html/recipes_examples.html) 54from OpenEmbedded is a great one and the premise of this OpenBMC tailored 55section. 56 57So you wrote some code. You've been scp'ing the compiled binary on to the 58OpenBMC system for a while and you know there is a better way. Have it built 59as part of your flash image. 60 61Run the devtool command to add your repo to the workspace. In my example I 62have a repo out on GitHub that contains my code. 63 64``` 65devtool add welcome https://github.com/causten/hello.git 66``` 67 68Now edit the bb file it created for you. You can just use `vim` but 69`devtool` can also edit the recipe `devtool edit-recipe welcome` without 70having to type the complete path. 71 72Add/Modify these lines. 73 74``` 75do_install () { 76 install -m 0755 -d ${D}${bindir} ${D}${datadir}/welcome 77 install -m 0644 ${S}/hello ${D}${bindir} 78 install -m 0644 ${S}/README.md ${D}${datadir}/welcome/ 79} 80``` 81 82The install directives create directories and then copies the files into them. 83Now BitBake will pick them up from the traditional `/usr/bin` and 84`/usr/shared/doc/hello/README.md`. 85 86The Final Step is to tell BitBake that you need the `welcome` recipe 87 88``` 89vim conf/local.conf 90IMAGE_INSTALL_append = " welcome" 91``` 92 93That's it, recompile and boot your system, the binary `hello` will be in 94`/usr/bin` and the `README.md` will be in `/usr/shared/doc/welcome`. 95 96 97### Know what your image has ### 98 99Sure you could flash and boot your system to see if your file made it, but there 100is a faster way. The `rootfs` directory down in the depths of the `build/tmp` 101path is the staging area where files are placed to be packaged. 102 103In my example to check if README.md was going to be added just do... 104 105``` 106ls build/tmp/work/${MACHINE}-openbmc-linux-gnueabi/obmc-phosphor-image/1.0-r0/rootfs/usr/share/welcome/README.md 107``` 108 109NXP wrote a few examples of [useful] (https://community.nxp.com/docs/DOC-94953) 110commands with BitBake that find the file too 111 112``` 113bitbake -g obmc-phosphor-image && cat pn-depends.dot |grep welcome 114``` 115 116[0]: (http://www.yoctoproject.org/docs/2.1/mega-manual/mega-manual.html#devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe) "devtool" 117[1]: (http://www.yoctoproject.org/docs/2.1/mega-manual/mega-manual.html) "Yocto Mega Manual" 118