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 :width: 100% 102 103#. **Know that you can generate a dependency graph and learn how to do it:** 104 A dependency graph shows dependencies between recipes, tasks, and targets. 105 You can use the "-g" option with BitBake to generate this graph. When you 106 start a build and the build breaks, you could see packages you have no clue 107 about or have any idea why the build system has included them. The 108 dependency graph can clarify that confusion. You can learn more about 109 dependency graphs and how to generate them in the 110 :ref:`bitbake-user-manual/bitbake-user-manual-intro:generating dependency 111 graphs` section in the BitBake User Manual. 112 113#. **Here's how you decode "magic" folder names in tmp/work:** 114 The build system fetches, unpacks, preprocesses, and builds. If something 115 goes wrong, the build system reports to you directly the path to a folder 116 where the temporary (build/tmp) files and packages reside resulting from the 117 build. For a detailed example of this process, see the :yocto_wiki:`example 118 </Cookbook:Example:Adding_packages_to_your_OS_image>`. Unfortunately this 119 example is on an earlier release of Yocto Project. 120 121 When you perform a build, you can use the "-u" BitBake command-line option to 122 specify a user interface viewer into the dependency graph (e.g. knotty, 123 ncurses, or taskexp) that helps you understand the build dependencies better. 124 125#. **You can build more than just images:** 126 You can build and run a specific task for a specific package (including 127 devshell) or even a single recipe. When developers first start using the 128 Yocto Project, the instructions found in the 129 :doc:`brief-yoctoprojectqs/index` show how to create an image 130 and then run or flash that image. However, you can actually build just a 131 single recipe. Thus, if some dependency or recipe isn't working, you can just 132 say "bitbake foo" where "foo" is the name for a specific recipe. As you 133 become more advanced using the Yocto Project, and if builds are failing, it 134 can be useful to make sure the fetch itself works as desired. Here are some 135 valuable links: :ref:`dev-manual/development-shell:Using a Development 136 Shell` for information on how to build and run a specific task using 137 devshell. Also, the :ref:`SDK manual shows how to build out a specific recipe 138 <sdk-manual/extensible:use \`\`devtool modify\`\` to modify the source of an existing component>`. 139 140#. **An ambiguous definition: Package vs Recipe:** 141 A recipe contains instructions the build system uses to create 142 packages. Recipes and Packages are the difference between the front end and 143 the result of the build process. 144 145 As mentioned, the build system takes the recipe and creates packages from the 146 recipe's instructions. The resulting packages are related to the one thing 147 the recipe is building but are different parts (packages) of the build 148 (i.e. the main package, the doc package, the debug symbols package, the 149 separate utilities package, and so forth). The build system splits out the 150 packages so that you don't need to install the packages you don't want or 151 need, which is advantageous because you are building for small devices when 152 developing for embedded and IoT. 153 154#. **You will want to learn about and know what's packaged in the root filesystem.** 155 156#. **Create your own image recipe:** 157 There are a number of ways to create your own image recipe. We suggest you 158 create your own image recipe as opposed to appending an existing recipe. It 159 is trivial and easy to write an image recipe. Again, do not try appending to 160 an existing image recipe. Create your own and do it right from the start. 161 162#. **Finally, here is a list of the basic skills you will need as a systems 163 developer. You must be able to:** 164 165 * deal with corporate proxies 166 * add a package to an image 167 * understand the difference between a recipe and package 168 * build a package by itself and why that's useful 169 * find out what packages are created by a recipe 170 * find out what files are in a package 171 * find out what files are in an image 172 * add an ssh server to an image (enable transferring of files to target) 173 * know the anatomy of a recipe 174 * know how to create and use layers 175 * find recipes (with the :oe_layerindex:`OpenEmbedded Layer index <>`) 176 * understand difference between machine and distro settings 177 * find and use the right BSP (machine) for your hardware 178 * find examples of distro features and know where to set them 179 * understanding the task pipeline and executing individual tasks 180 * understand devtool and how it simplifies your workflow 181 * improve build speeds with shared downloads and shared state cache 182 * generate and understand a dependency graph 183 * generate and understand BitBake environment 184 * build an Extensible SDK for applications development 185 186#. **Depending on what you primary interests are with the Yocto Project, you 187 could consider any of the following reading:** 188 189 * **Look Through the Yocto Project Development Tasks Manual**: This manual 190 contains procedural information grouped to help you get set up, work with 191 layers, customize images, write new recipes, work with libraries, and use 192 QEMU. The information is task-based and spans the breadth of the Yocto 193 Project. See the :doc:`/dev-manual/index`. 194 195 * **Look Through the Yocto Project Application Development and the Extensible 196 Software Development Kit (eSDK) manual**: This manual describes how to use 197 both the standard SDK and the extensible SDK, which are used primarily for 198 application development. The :doc:`/sdk-manual/extensible` also provides 199 example workflows that use devtool. See the section 200 :ref:`sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow` 201 for more information. 202 203 * **Learn About Kernel Development**: If you want to see how to work with the 204 kernel and understand Yocto Linux kernels, see the :doc:`/kernel-dev/index`. 205 This manual provides information on how to patch the kernel, modify kernel 206 recipes, and configure the kernel. 207 208 * **Learn About Board Support Packages (BSPs)**: If you want to learn about 209 BSPs, see the :doc:`/bsp-guide/index`. This manual also provides an 210 example BSP creation workflow. See the :doc:`/bsp-guide/bsp` section. 211 212 * **Learn About Toaster**: Toaster is a web interface to the Yocto Project's 213 OpenEmbedded build system. If you are interested in using this type of 214 interface to create images, see the :doc:`/toaster-manual/index`. 215 216 * **Have Available the Yocto Project Reference Manual**: Unlike the rest of 217 the Yocto Project manual set, this manual is comprised of material suited 218 for reference rather than procedures. You can get build details, a closer 219 look at how the pieces of the Yocto Project development environment work 220 together, information on various technical details, guidance on migrating 221 to a newer Yocto Project release, reference material on the directory 222 structure, classes, and tasks. The :doc:`/ref-manual/index` also 223 contains a fairly comprehensive glossary of variables used within the Yocto 224 Project. 225 226.. include:: /boilerplate.rst 227
