1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3========================================= 4What I wish I'd known about Yocto Project 5========================================= 6 7| 8 9.. note:: 10 11 Before reading further, make sure you've taken a look at the 12 :yocto_home:`Software Overview</software-overview>` page which presents the 13 definitions for many of the terms referenced here. Also, know that some of the 14 information here won't make sense now, but as you start developing, it is the 15 information you'll want to keep close at hand. These are best known methods for 16 working with Yocto Project and they are updated regularly. 17 18Using the Yocto Project is fairly easy, *until something goes wrong*. Without an 19understanding of how the build process works, you'll find yourself trying to 20troubleshoot "a black box". Here are a few items that new users wished they had 21known before embarking on their first build with Yocto Project. Feel free to 22contact us with other suggestions. 23 24#. **Use Git, not the tarball download:** 25 If you use git the software will be automatically updated with bug updates 26 because of how git works. If you download the tarball instead, you will need 27 to be responsible for your own updates. 28 29#. **Get to know the layer index:** 30 All layers can be found in the :oe_layerindex:`layer index <>`. Layers which 31 have applied for Yocto Project Compatible status (structure continuity 32 assurance and testing) can be found in the :yocto_home:`Yocto Project Compatible index 33 </software-over/layer/>`. Generally check the Compatible layer index first, 34 and if you don't find the necessary layer check the general layer index. The 35 layer index is an original artifact from the Open Embedded Project. As such, 36 that index doesn't have the curating and testing that the Yocto Project 37 provides on Yocto Project Compatible layer list, but the latter has fewer 38 entries. Know that when you start searching in the layer index that not all 39 layers have the same level of maturity, validation, or usability. Nor do 40 searches prioritize displayed results. There is no easy way to help you 41 through the process of choosing the best layer to suit your needs. 42 Consequently, it is often trial and error, checking the mailing lists, or 43 working with other developers through collaboration rooms that can help you 44 make good choices. 45 46#. **Use existing BSP layers from silicon vendors when possible:** 47 Intel, TI, NXP and others have information on what BSP layers to use with 48 their silicon. These layers have names such as "meta-intel" or "meta-ti". Try 49 not to build layers from scratch. If you do have custom silicon, use one of 50 these layers as a guide or template and familiarize yourself with the 51 :doc:`bsp-guide/index`. 52 53#. **Do not put everything into one layer:** 54 Use different layers to logically separate information in your build. As an 55 example, you could have a BSP layer, a GUI layer, a distro configuration, 56 middleware, or an application (e.g. "meta-filesystems", "meta-python", 57 "meta-intel", and so forth). Putting your entire build into one layer limits 58 and complicates future customization and reuse. Isolating information into 59 layers, on the other hand, helps keep simplify future customizations and 60 reuse. 61 62#. **Never modify the POKY layer. Never. Ever. When you update to the next 63 release, you'll lose all of your work. ALL OF IT.** 64 65#. **Don't be fooled by documentation searching results:** 66 Yocto Project documentation is always being updated. Unfortunately, when you 67 use Google to search for Yocto Project concepts or terms, Google consistently 68 searches and retrieves older versions of Yocto Project manuals. For example, 69 searching for a particular topic using Google could result in a "hit" on a 70 Yocto Project manual that is several releases old. To be sure that you are 71 using the most current Yocto Project documentation, use the drop-down menu at 72 the top of any of its page. 73 74 Many developers look through the :yocto_docs:`All-in-one 'Mega' Manual </singleindex.html>` 75 for a concept or term by doing a search through the whole page. This manual 76 is a concatenation of the core set of Yocto Project manual. Thus, a simple 77 string search using Ctrl-F in this manual produces all the "hits" for a 78 desired term or concept. Once you find the area in which you are 79 interested, you can display the actual manual, if desired. It is also 80 possible to use the search bar in the menu or in the left navigation pane. 81 82#. **Understand the basic concepts of how the build system works: the workflow:** 83 Understanding the Yocto Project workflow is important as it can help you both 84 pinpoint where trouble is occurring and how the build is breaking. The 85 workflow breaks down into the following steps: 86 87 #. Fetch – get the source code 88 #. Extract – unpack the sources 89 #. Patch – apply patches for bug fixes and new capability 90 #. Configure – set up your environment specifications 91 #. Build – compile and link 92 #. Install – copy files to target directories 93 #. Package – bundle files for installation 94 95 During "fetch", there may be an inability to find code. During "extract", 96 there is likely an invalid zip or something similar. In other words, the 97 function of a particular part of the workflow gives you an idea of what might 98 be going wrong. 99 100 .. image:: figures/yp-how-it-works-new-diagram.png 101 102#. **Know that you can generate a dependency graph and learn how to do it:** 103 A dependency graph shows dependencies between recipes, tasks, and targets. 104 You can use the "-g" option with BitBake to generate this graph. When you 105 start a build and the build breaks, you could see packages you have no clue 106 about or have any idea why the build system has included them. The 107 dependency graph can clarify that confusion. You can learn more about 108 dependency graphs and how to generate them in the 109 :ref:`bitbake-user-manual/bitbake-user-manual-intro:generating dependency 110 graphs` section in the BitBake User Manual. 111 112#. **Here's how you decode "magic" folder names in tmp/work:** 113 The build system fetches, unpacks, preprocesses, and builds. If something 114 goes wrong, the build system reports to you directly the path to a folder 115 where the temporary (build/tmp) files and packages reside resulting from the 116 build. For a detailed example of this process, see the :yocto_wiki:`example 117 </Cookbook:Example:Adding_packages_to_your_OS_image>`. Unfortunately this 118 example is on an earlier release of Yocto Project. 119 120 When you perform a build, you can use the "-u" BitBake command-line option to 121 specify a user interface viewer into the dependency graph (e.g. knotty, 122 ncurses, or taskexp) that helps you understand the build dependencies better. 123 124#. **You can build more than just images:** 125 You can build and run a specific task for a specific package (including 126 devshell) or even a single recipe. When developers first start using the 127 Yocto Project, the instructions found in the 128 :doc:`brief-yoctoprojectqs/index` show how to create an image 129 and then run or flash that image. However, you can actually build just a 130 single recipe. Thus, if some dependency or recipe isn't working, you can just 131 say "bitbake foo" where "foo" is the name for a specific recipe. As you 132 become more advanced using the Yocto Project, and if builds are failing, it 133 can be useful to make sure the fetch itself works as desired. Here are some 134 valuable links: :ref:`dev-manual/common-tasks:Using a Development 135 Shell` for information on how to build and run a specific task using 136 devshell. Also, the :ref:`SDK manual shows how to build out a specific recipe 137 <sdk-manual/extensible:use \`\`devtool modify\`\` to modify the source of an existing component>`. 138 139#. **An ambiguous definition: Package vs Recipe:** 140 A recipe contains instructions the build system uses to create 141 packages. Recipes and Packages are the difference between the front end and 142 the result of the build process. 143 144 As mentioned, the build system takes the recipe and creates packages from the 145 recipe's instructions. The resulting packages are related to the one thing 146 the recipe is building but are different parts (packages) of the build 147 (i.e. the main package, the doc package, the debug symbols package, the 148 separate utilities package, and so forth). The build system splits out the 149 packages so that you don't need to install the packages you don't want or 150 need, which is advantageous because you are building for small devices when 151 developing for embedded and IoT. 152 153#. **You will want to learn about and know what's packaged in the root filesystem.** 154 155#. **Create your own image recipe:** 156 There are a number of ways to create your own image recipe. We suggest you 157 create your own image recipe as opposed to appending an existing recipe. It 158 is trivial and easy to write an image recipe. Again, do not try appending to 159 an existing image recipe. Create your own and do it right from the start. 160 161#. **Finally, here is a list of the basic skills you will need as a systems 162 developer. You must be able to:** 163 164 * deal with corporate proxies 165 * add a package to an image 166 * understand the difference between a recipe and package 167 * build a package by itself and why that's useful 168 * find out what packages are created by a recipe 169 * find out what files are in a package 170 * find out what files are in an image 171 * add an ssh server to an image (enable transferring of files to target) 172 * know the anatomy of a recipe 173 * know how to create and use layers 174 * find recipes (with the :oe_layerindex:`OpenEmbedded Layer index <>`) 175 * understand difference between machine and distro settings 176 * find and use the right BSP (machine) for your hardware 177 * find examples of distro features and know where to set them 178 * understanding the task pipeline and executing individual tasks 179 * understand devtool and how it simplifies your workflow 180 * improve build speeds with shared downloads and shared state cache 181 * generate and understand a dependency graph 182 * generate and understand bitbake environment 183 * build an Extensible SDK for applications development 184 185#. **Depending on what you primary interests are with the Yocto Project, you 186 could consider any of the following reading:** 187 188 * **Look Through the Yocto Project Development Tasks Manual**: This manual 189 contains procedural information grouped to help you get set up, work with 190 layers, customize images, write new recipes, work with libraries, and use 191 QEMU. The information is task-based and spans the breadth of the Yocto 192 Project. See the :doc:`/dev-manual/index`. 193 194 * **Look Through the Yocto Project Application Development and the Extensible 195 Software Development Kit (eSDK) manual**: This manual describes how to use 196 both the standard SDK and the extensible SDK, which are used primarily for 197 application development. The :doc:`/sdk-manual/extensible` also provides 198 example workflows that use devtool. See the section 199 :ref:`sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow` 200 for more information. 201 202 * **Learn About Kernel Development**: If you want to see how to work with the 203 kernel and understand Yocto Linux kernels, see the :doc:`/kernel-dev/index`. 204 This manual provides information on how to patch the kernel, modify kernel 205 recipes, and configure the kernel. 206 207 * **Learn About Board Support Packages (BSPs)**: If you want to learn about 208 BSPs, see the :doc:`/bsp-guide/index`. This manual also provides an 209 example BSP creation workflow. See the :doc:`/bsp-guide/bsp` section. 210 211 * **Learn About Toaster**: Toaster is a web interface to the Yocto Project's 212 OpenEmbedded build system. If you are interested in using this type of 213 interface to create images, see the :doc:`/toaster-manual/index`. 214 215 * **Have Available the Yocto Project Reference Manual**: Unlike the rest of 216 the Yocto Project manual set, this manual is comprised of material suited 217 for reference rather than procedures. You can get build details, a closer 218 look at how the pieces of the Yocto Project development environment work 219 together, information on various technical details, guidance on migrating 220 to a newer Yocto Project release, reference material on the directory 221 structure, classes, and tasks. The :doc:`/ref-manual/index` also 222 contains a fairly comprehensive glossary of variables used within the Yocto 223 Project. 224 225.. include:: /boilerplate.rst 226
