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