diff options
author | Nicolas Dechesne <nicolas.dechesne@linaro.org> | 2020-11-20 20:17:33 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2021-01-04 10:55:00 +0000 |
commit | fa0cb4d34b1073f215fa3c680f2316208739d53d (patch) | |
tree | ba89c1f4289fd6456af4409a6a19caf6548dfb9c /documentation/what-i-wish-id-known.rst | |
parent | a038e58f3cd82c56102444bdc5ac76c9f1550a0d (diff) | |
download | poky-fa0cb4d34b1073f215fa3c680f2316208739d53d.tar.gz |
sphinx: import docs
The Yocto Project docs was migrated from Docbook to Sphinx in YP
3.2. This 3.1 is an LTS release, and since 3.1 docs are 'close to'
the docs in 3.2, we agreed to backport sphinx docs onto 3.1.
This first patch brings all changes done in 3.2 until:
7f64574f7 README: include detailed information about sphinx
There are other changes after this commit, but they will be
selectively backported in individual patches.
This patch was generated with the following command:
git cherry-pick -n \
$(git log --reverse --oneline \
ac352ad7f95db7eeacb53c2778caa31800bd7c26..7f64574f7 \
| cut -f1 -d' ')
The following commits were applies in the dunfell docs, but not in
master, so they were first reverted (and squashed into this change). A
commit will reintroduce the content from these patches in the Sphinx
files in a followup patch.
069c27574 Documenation: Prepared for the 3.1.1 release
bd140f0f9 Documentation: Add 3.1.1 version updates missing from previous commit
17cc71a8f Documenation: Prepared for the 3.1.2 release
1a69e2c02 Documenation: Prepared for the 3.1.3 release
8910ac1c7 Documenation: Prepared for the 3.1.4 release
(From yocto-docs rev: c25fe058b88b893b0d146f3ed27320b47cdec236)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/what-i-wish-id-known.rst')
-rw-r--r-- | documentation/what-i-wish-id-known.rst | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/documentation/what-i-wish-id-known.rst b/documentation/what-i-wish-id-known.rst new file mode 100644 index 0000000000..495ebdc200 --- /dev/null +++ b/documentation/what-i-wish-id-known.rst | |||
@@ -0,0 +1,226 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ========================================= | ||
4 | What 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 | |||
18 | Using the Yocto Project is fairly easy, *until something goes wrong*. Without an | ||
19 | understanding of how the build process works, you'll find yourself trying to | ||
20 | troubleshoot "a black box". Here are a few items that new users wished they had | ||
21 | known before embarking on their first build with Yocto Project. Feel free to | ||
22 | contact 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 `layer index | ||
31 | <https://layers.openembedded.org/>`_. Layers which have applied for Yocto | ||
32 | Project Compatible status (structure continuity assurance and testing) can be | ||
33 | found in the :yocto_home:`Yocto Project Compatible index | ||
34 | </software-over/layer/>`. Generally check the Compatible layer index first, | ||
35 | and if you don't find the necessary layer check the general layer index. The | ||
36 | layer index is an original artifact from the Open Embedded Project. As such, | ||
37 | that index doesn't have the curating and testing that the Yocto Project | ||
38 | provides on Yocto Project Compatible layer list, but the latter has fewer | ||
39 | entries. Know that when you start searching in the layer index that not all | ||
40 | layers have the same level of maturity, validation, or usability. Nor do | ||
41 | searches prioritize displayed results. There is no easy way to help you | ||
42 | through the process of choosing the best layer to suit your needs. | ||
43 | Consequently, it is often trial and error, checking the mailing lists, or | ||
44 | working with other developers through collaboration rooms that can help you | ||
45 | make good choices. | ||
46 | |||
47 | #. **Use existing BSP layers from silicon vendors when possible:** | ||
48 | Intel, TI, NXP and others have information on what BSP layers to use with | ||
49 | their silicon. These layers have names such as "meta-intel" or "meta-ti". Try | ||
50 | not to build layers from scratch. If you do have custom silicon, use one of | ||
51 | these layers as a guide or template and familiarize yourself with the | ||
52 | :doc:`bsp-guide/bsp-guide`. | ||
53 | |||
54 | #. **Do not put everything into one layer:** | ||
55 | Use different layers to logically separate information in your build. As an | ||
56 | example, you could have a BSP layer, a GUI layer, a distro configuration, | ||
57 | middleware, or an application (e.g. "meta-filesystems", "meta-python", | ||
58 | "meta-intel", and so forth). Putting your entire build into one layer limits | ||
59 | and complicates future customization and reuse. Isolating information into | ||
60 | layers, on the other hand, helps keep simplify future customizations and | ||
61 | reuse. | ||
62 | |||
63 | #. **Never modify the POKY layer. Never. Ever. When you update to the next | ||
64 | release, you'll lose all of your work. ALL OF IT.** | ||
65 | |||
66 | #. **Don't be fooled by documentation searching results:** | ||
67 | Yocto Project documentation is always being updated. Unfortunately, when you | ||
68 | use Google to search for Yocto Project concepts or terms, Google consistently | ||
69 | searches and retrieves older versions of Yocto Project manuals. For example, | ||
70 | searching for a particular topic using Google could result in a "hit" on a | ||
71 | Yocto Project manual that is several releases old. To be sure that you are | ||
72 | using the most current Yocto Project documentation, use the drop-down menu at | ||
73 | the top of any of its page. | ||
74 | |||
75 | Many developers look through the :yocto_docs:`All-in-one 'Mega' Manual </singleindex.html>` | ||
76 | for a concept or term by doing a search through the whole page. This manual | ||
77 | is a concatenation of the core set of Yocto Project manual. Thus, a simple | ||
78 | string search using Ctrl-F in this manual produces all the "hits" for a | ||
79 | desired term or concept. Once you find the area in which you are | ||
80 | interested, you can display the actual manual, if desired. It is also | ||
81 | possible to use the search bar in the menu or in the left navigation pane. | ||
82 | |||
83 | #. **Understand the basic concepts of how the build system works: the workflow:** | ||
84 | Understanding the Yocto Project workflow is important as it can help you both | ||
85 | pinpoint where trouble is occurring and how the build is breaking. The | ||
86 | workflow breaks down into the following steps: | ||
87 | |||
88 | #. Fetch – get the source code | ||
89 | #. Extract – unpack the sources | ||
90 | #. Patch – apply patches for bug fixes and new capability | ||
91 | #. Configure – set up your environment specifications | ||
92 | #. Build – compile and link | ||
93 | #. Install – copy files to target directories | ||
94 | #. Package – bundle files for installation | ||
95 | |||
96 | During "fetch", there may be an inability to find code. During "extract", | ||
97 | there is likely an invalid zip or something similar. In other words, the | ||
98 | function of a particular part of the workflow gives you an idea of what might | ||
99 | be going wrong. | ||
100 | |||
101 | .. image:: figures/yp-how-it-works-new-diagram.png | ||
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/brief-yoctoprojectqs` 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/dev-manual-common-tasks: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-devtool-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 rootfs.** | ||
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 `OpenEmbedded Layer index <https://layers.openembedded.org>`_) | ||
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/dev-manual`. | ||
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/sdk-extensible` also provides | ||
199 | example workflows that use devtool. See the section | ||
200 | :ref:`sdk-manual/sdk-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/kernel-dev`. | ||
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/bsp-guide`. 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/toaster-manual`. | ||
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/ref-manual` also | ||
223 | contains a fairly comprehensive glossary of variables used within the Yocto | ||
224 | Project. | ||
225 | |||
226 | .. include:: /boilerplate.rst | ||