diff options
Diffstat (limited to 'documentation/brief-yoctoprojectqs/index.rst')
-rw-r--r-- | documentation/brief-yoctoprojectqs/index.rst | 193 |
1 files changed, 106 insertions, 87 deletions
diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst index 63083cb13d..61c5cbec36 100644 --- a/documentation/brief-yoctoprojectqs/index.rst +++ b/documentation/brief-yoctoprojectqs/index.rst | |||
@@ -25,18 +25,11 @@ build a reference embedded OS called Poky. | |||
25 | in the Yocto Project Development Tasks Manual for more | 25 | in the Yocto Project Development Tasks Manual for more |
26 | information. | 26 | information. |
27 | 27 | ||
28 | - You may use Windows Subsystem For Linux v2 to set up a build host | 28 | - You may use version 2 of Windows Subsystem For Linux (WSL 2) to set |
29 | using Windows 10. | 29 | up a build host using Windows 10 or later, Windows Server 2019 or later. |
30 | 30 | See the :ref:`dev-manual/start:setting up to use windows subsystem for | |
31 | .. note:: | 31 | linux (wsl 2)` section in the Yocto Project Development Tasks Manual |
32 | 32 | for more information. | |
33 | The Yocto Project is not compatible with WSLv1, it is | ||
34 | compatible but not officially supported nor validated with | ||
35 | WSLv2, if you still decide to use WSL please upgrade to WSLv2. | ||
36 | |||
37 | See the :ref:`dev-manual/start:setting up to use windows | ||
38 | subsystem for linux (wslv2)` section in the Yocto Project Development | ||
39 | Tasks Manual for more information. | ||
40 | 33 | ||
41 | If you want more conceptual or background information on the Yocto | 34 | If you want more conceptual or background information on the Yocto |
42 | Project, see the :doc:`/overview-manual/index`. | 35 | Project, see the :doc:`/overview-manual/index`. |
@@ -47,7 +40,13 @@ Compatible Linux Distribution | |||
47 | Make sure your :term:`Build Host` meets the | 40 | Make sure your :term:`Build Host` meets the |
48 | following requirements: | 41 | following requirements: |
49 | 42 | ||
50 | - 50 Gbytes of free disk space | 43 | - At least &MIN_DISK_SPACE; Gbytes of free disk space, though |
44 | much more will help to run multiple builds and increase | ||
45 | performance by reusing build artifacts. | ||
46 | |||
47 | - At least &MIN_RAM; Gbytes of RAM, though a modern modern build host with as | ||
48 | much RAM and as many CPU cores as possible is strongly recommended to | ||
49 | maximize build performance. | ||
51 | 50 | ||
52 | - Runs a supported Linux distribution (i.e. recent releases of Fedora, | 51 | - Runs a supported Linux distribution (i.e. recent releases of Fedora, |
53 | openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux | 52 | openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux |
@@ -60,15 +59,16 @@ following requirements: | |||
60 | 59 | ||
61 | - | 60 | - |
62 | 61 | ||
63 | - Git 1.8.3.1 or greater | 62 | - Git &MIN_GIT_VERSION; or greater |
64 | - tar 1.28 or greater | 63 | - tar &MIN_TAR_VERSION; or greater |
65 | - Python 3.5.0 or greater. | 64 | - Python &MIN_PYTHON_VERSION; or greater. |
66 | - gcc 5.0 or greater. | 65 | - gcc &MIN_GCC_VERSION; or greater. |
66 | - GNU make &MIN_MAKE_VERSION; or greater | ||
67 | 67 | ||
68 | If your build host does not meet any of these three listed version | 68 | If your build host does not meet any of these three listed version |
69 | requirements, you can take steps to prepare the system so that you | 69 | requirements, you can take steps to prepare the system so that you |
70 | can still use the Yocto Project. See the | 70 | can still use the Yocto Project. See the |
71 | :ref:`ref-manual/system-requirements:required git, tar, python and gcc versions` | 71 | :ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions` |
72 | section in the Yocto Project Reference Manual for information. | 72 | section in the Yocto Project Reference Manual for information. |
73 | 73 | ||
74 | Build Host Packages | 74 | Build Host Packages |
@@ -76,11 +76,9 @@ Build Host Packages | |||
76 | 76 | ||
77 | You must install essential host packages on your build host. The | 77 | You must install essential host packages on your build host. The |
78 | following command installs the host packages based on an Ubuntu | 78 | following command installs the host packages based on an Ubuntu |
79 | distribution: | 79 | distribution:: |
80 | 80 | ||
81 | .. code-block:: shell | 81 | $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL; |
82 | |||
83 | $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; | ||
84 | 82 | ||
85 | .. note:: | 83 | .. note:: |
86 | 84 | ||
@@ -106,42 +104,57 @@ commands to clone the Poky repository. | |||
106 | Resolving deltas: 100% (323116/323116), done. | 104 | Resolving deltas: 100% (323116/323116), done. |
107 | Checking connectivity... done. | 105 | Checking connectivity... done. |
108 | 106 | ||
109 | Move to the ``poky`` directory and take a look at the tags: | 107 | Go to :yocto_wiki:`Releases wiki page </Releases>`, and choose a release |
108 | codename (such as ``&DISTRO_NAME_NO_CAP;``), corresponding to either the | ||
109 | latest stable release or a Long Term Support release. | ||
110 | |||
111 | Then move to the ``poky`` directory and take a look at existing branches: | ||
110 | 112 | ||
111 | .. code-block:: shell | 113 | .. code-block:: shell |
112 | 114 | ||
113 | $ cd poky | 115 | $ cd poky |
114 | $ git fetch --tags | 116 | $ git branch -a |
115 | $ git tag | 117 | . |
116 | 1.1_M1.final | 118 | . |
117 | 1.1_M1.rc1 | 119 | . |
118 | 1.1_M1.rc2 | 120 | remotes/origin/HEAD -> origin/master |
119 | 1.1_M2.final | 121 | remotes/origin/dunfell |
120 | 1.1_M2.rc1 | 122 | remotes/origin/dunfell-next |
123 | . | ||
124 | . | ||
125 | . | ||
126 | remotes/origin/gatesgarth | ||
127 | remotes/origin/gatesgarth-next | ||
128 | . | ||
129 | . | ||
130 | . | ||
131 | remotes/origin/master | ||
132 | remotes/origin/master-next | ||
121 | . | 133 | . |
122 | . | 134 | . |
123 | . | 135 | . |
124 | yocto-2.5 | 136 | |
125 | yocto-2.5.1 | 137 | |
126 | yocto-2.5.2 | 138 | For this example, check out the ``&DISTRO_NAME_NO_CAP;`` branch based on the |
127 | yocto-2.6 | 139 | ``&DISTRO_NAME;`` release: |
128 | yocto-2.6.1 | ||
129 | yocto-2.6.2 | ||
130 | yocto-2.7 | ||
131 | yocto_1.5_M5.rc8 | ||
132 | |||
133 | For this example, check out the branch based on the | ||
134 | ``&DISTRO_REL_TAG;`` release: | ||
135 | 140 | ||
136 | .. code-block:: shell | 141 | .. code-block:: shell |
137 | 142 | ||
138 | $ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG; | 143 | $ git checkout -t origin/&DISTRO_NAME_NO_CAP; -b my-&DISTRO_NAME_NO_CAP; |
139 | Switched to a new branch 'my-&DISTRO_REL_TAG;' | 144 | Branch 'my-&DISTRO_NAME_NO_CAP;' set up to track remote branch '&DISTRO_NAME_NO_CAP;' from 'origin'. |
145 | Switched to a new branch 'my-&DISTRO_NAME_NO_CAP;' | ||
140 | 146 | ||
141 | The previous Git checkout command creates a local branch named | 147 | The previous Git checkout command creates a local branch named |
142 | ``my-&DISTRO_REL_TAG;``. The files available to you in that branch exactly | 148 | ``my-&DISTRO_NAME_NO_CAP;``. The files available to you in that branch |
143 | match the repository's files in the ``&DISTRO_NAME_NO_CAP;`` development | 149 | exactly match the repository's files in the ``&DISTRO_NAME_NO_CAP;`` |
144 | branch at the time of the Yocto Project &DISTRO_REL_TAG; release. | 150 | release branch. |
151 | |||
152 | Note that you can regularly type the following command in the same directory | ||
153 | to keep your local files in sync with the release branch: | ||
154 | |||
155 | .. code-block:: shell | ||
156 | |||
157 | $ git pull | ||
145 | 158 | ||
146 | For more options and information about accessing Yocto Project related | 159 | For more options and information about accessing Yocto Project related |
147 | repositories, see the | 160 | repositories, see the |
@@ -176,7 +189,7 @@ an entire Linux distribution, including the toolchain, from source. | |||
176 | 189 | ||
177 | .. code-block:: shell | 190 | .. code-block:: shell |
178 | 191 | ||
179 | $ cd ~/poky | 192 | $ cd poky |
180 | $ source oe-init-build-env | 193 | $ source oe-init-build-env |
181 | You had no conf/local.conf file. This configuration file has therefore been | 194 | You had no conf/local.conf file. This configuration file has therefore been |
182 | created for you with some default values. You may wish to edit it to, for | 195 | created for you with some default values. You may wish to edit it to, for |
@@ -189,10 +202,10 @@ an entire Linux distribution, including the toolchain, from source. | |||
189 | 202 | ||
190 | The Yocto Project has extensive documentation about OE including a reference | 203 | The Yocto Project has extensive documentation about OE including a reference |
191 | manual which can be found at: | 204 | manual which can be found at: |
192 | http://yoctoproject.org/documentation | 205 | https://docs.yoctoproject.org |
193 | 206 | ||
194 | For more information about OpenEmbedded see their website: | 207 | For more information about OpenEmbedded see their website: |
195 | http://www.openembedded.org/ | 208 | https://www.openembedded.org/ |
196 | 209 | ||
197 | ### Shell environment set up for builds. ### | 210 | ### Shell environment set up for builds. ### |
198 | 211 | ||
@@ -200,21 +213,28 @@ an entire Linux distribution, including the toolchain, from source. | |||
200 | 213 | ||
201 | Common targets are: | 214 | Common targets are: |
202 | core-image-minimal | 215 | core-image-minimal |
216 | core-image-full-cmdline | ||
203 | core-image-sato | 217 | core-image-sato |
218 | core-image-weston | ||
204 | meta-toolchain | 219 | meta-toolchain |
205 | meta-ide-support | 220 | meta-ide-support |
206 | 221 | ||
207 | You can also run generated qemu images with a command like 'runqemu qemux86-64' | 222 | You can also run generated QEMU images with a command like 'runqemu qemux86-64' |
223 | |||
224 | Other commonly useful commands are: | ||
225 | - 'devtool' and 'recipetool' handle common recipe tasks | ||
226 | - 'bitbake-layers' handles common layer tasks | ||
227 | - 'oe-pkgdata-util' handles common target package tasks | ||
208 | 228 | ||
209 | Among other things, the script creates the :term:`Build Directory`, which is | 229 | Among other things, the script creates the :term:`Build Directory`, which is |
210 | ``build`` in this case and is located in the :term:`Source Directory`. After | 230 | ``build`` in this case and is located in the :term:`Source Directory`. After |
211 | the script runs, your current working directory is set to the Build | 231 | the script runs, your current working directory is set to the |
212 | Directory. Later, when the build completes, the Build Directory contains all the | 232 | :term:`Build Directory`. Later, when the build completes, the |
213 | files created during the build. | 233 | :term:`Build Directory` contains all the files created during the build. |
214 | 234 | ||
215 | #. **Examine Your Local Configuration File:** When you set up the build | 235 | #. **Examine Your Local Configuration File:** When you set up the build |
216 | environment, a local configuration file named ``local.conf`` becomes | 236 | environment, a local configuration file named ``local.conf`` becomes |
217 | available in a ``conf`` subdirectory of the Build Directory. For this | 237 | available in a ``conf`` subdirectory of the :term:`Build Directory`. For this |
218 | example, the defaults are set to build for a ``qemux86`` target, | 238 | example, the defaults are set to build for a ``qemux86`` target, |
219 | which is suitable for emulation. The package manager used is set to | 239 | which is suitable for emulation. The package manager used is set to |
220 | the RPM package manager. | 240 | the RPM package manager. |
@@ -222,19 +242,19 @@ an entire Linux distribution, including the toolchain, from source. | |||
222 | .. tip:: | 242 | .. tip:: |
223 | 243 | ||
224 | You can significantly speed up your build and guard against fetcher | 244 | You can significantly speed up your build and guard against fetcher |
225 | failures by using mirrors. To use mirrors, add these lines to your | 245 | failures by using :ref:`overview-manual/concepts:shared state cache` |
226 | local.conf file in the Build directory: :: | 246 | mirrors and enabling :ref:`overview-manual/concepts:hash equivalence`. |
227 | 247 | This way, you can use pre-built artifacts rather than building them. | |
228 | SSTATE_MIRRORS = "\ | 248 | This is relevant only when your network and the server that you use |
229 | file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \ | 249 | can download these artifacts faster than you would be able to build them. |
230 | file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \ | ||
231 | file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \ | ||
232 | " | ||
233 | 250 | ||
251 | To use such mirrors, uncomment the below lines in your ``conf/local.conf`` | ||
252 | file in the :term:`Build Directory`:: | ||
234 | 253 | ||
235 | The previous examples showed how to add sstate paths for Yocto Project | 254 | BB_HASHSERVE_UPSTREAM = "hashserv.yocto.io:8687" |
236 | &YOCTO_DOC_VERSION_MINUS_ONE;, &YOCTO_DOC_VERSION;, and a development | 255 | SSTATE_MIRRORS ?= "file://.* http://cdn.jsdelivr.net/yocto/sstate/all/PATH;downloadfilename=PATH" |
237 | area. For a complete index of sstate locations, see http://sstate.yoctoproject.org/. | 256 | BB_HASHSERVE = "auto" |
257 | BB_SIGNATURE_HANDLER = "OEEquivHash" | ||
238 | 258 | ||
239 | #. **Start the Build:** Continue with the following command to build an OS | 259 | #. **Start the Build:** Continue with the following command to build an OS |
240 | image for the target, which is ``core-image-sato`` in this example: | 260 | image for the target, which is ``core-image-sato`` in this example: |
@@ -245,8 +265,9 @@ an entire Linux distribution, including the toolchain, from source. | |||
245 | 265 | ||
246 | For information on using the ``bitbake`` command, see the | 266 | For information on using the ``bitbake`` command, see the |
247 | :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and | 267 | :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and |
248 | Concepts Manual, or see the ":ref:`BitBake Command | 268 | Concepts Manual, or see |
249 | <bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command>`" section in the BitBake User Manual. | 269 | :ref:`bitbake-user-manual/bitbake-user-manual-intro:the bitbake command` |
270 | in the BitBake User Manual. | ||
250 | 271 | ||
251 | #. **Simulate Your Image Using QEMU:** Once this particular image is | 272 | #. **Simulate Your Image Using QEMU:** Once this particular image is |
252 | built, you can start QEMU, which is a Quick EMUlator that ships with | 273 | built, you can start QEMU, which is a Quick EMUlator that ships with |
@@ -282,7 +303,7 @@ modular development and makes it easier to reuse the layer metadata. | |||
282 | 303 | ||
283 | Follow these steps to add a hardware layer: | 304 | Follow these steps to add a hardware layer: |
284 | 305 | ||
285 | #. **Find a Layer:** Lots of hardware layers exist. The Yocto Project | 306 | #. **Find a Layer:** Many hardware layers are available. The Yocto Project |
286 | :yocto_git:`Source Repositories <>` has many hardware layers. | 307 | :yocto_git:`Source Repositories <>` has many hardware layers. |
287 | This example adds the | 308 | This example adds the |
288 | `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer. | 309 | `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer. |
@@ -293,7 +314,7 @@ Follow these steps to add a hardware layer: | |||
293 | 314 | ||
294 | .. code-block:: shell | 315 | .. code-block:: shell |
295 | 316 | ||
296 | $ cd ~/poky | 317 | $ cd poky |
297 | $ git clone https://github.com/kraj/meta-altera.git | 318 | $ git clone https://github.com/kraj/meta-altera.git |
298 | Cloning into 'meta-altera'... | 319 | Cloning into 'meta-altera'... |
299 | remote: Counting objects: 25170, done. | 320 | remote: Counting objects: 25170, done. |
@@ -303,8 +324,8 @@ Follow these steps to add a hardware layer: | |||
303 | Resolving deltas: 100% (13385/13385), done. | 324 | Resolving deltas: 100% (13385/13385), done. |
304 | Checking connectivity... done. | 325 | Checking connectivity... done. |
305 | 326 | ||
306 | The hardware layer now exists | 327 | The hardware layer is now available |
307 | with other layers inside the Poky reference repository on your build | 328 | next to other layers inside the Poky reference repository on your build |
308 | host as ``meta-altera`` and contains all the metadata needed to | 329 | host as ``meta-altera`` and contains all the metadata needed to |
309 | support hardware from Altera, which is owned by Intel. | 330 | support hardware from Altera, which is owned by Intel. |
310 | 331 | ||
@@ -317,7 +338,7 @@ Follow these steps to add a hardware layer: | |||
317 | #. **Change the Configuration to Build for a Specific Machine:** The | 338 | #. **Change the Configuration to Build for a Specific Machine:** The |
318 | :term:`MACHINE` variable in the | 339 | :term:`MACHINE` variable in the |
319 | ``local.conf`` file specifies the machine for the build. For this | 340 | ``local.conf`` file specifies the machine for the build. For this |
320 | example, set the ``MACHINE`` variable to ``cyclone5``. These | 341 | example, set the :term:`MACHINE` variable to ``cyclone5``. These |
321 | configurations are used: | 342 | configurations are used: |
322 | https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf. | 343 | https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf. |
323 | 344 | ||
@@ -328,16 +349,14 @@ Follow these steps to add a hardware layer: | |||
328 | 349 | ||
329 | #. **Add Your Layer to the Layer Configuration File:** Before you can use | 350 | #. **Add Your Layer to the Layer Configuration File:** Before you can use |
330 | a layer during a build, you must add it to your ``bblayers.conf`` | 351 | a layer during a build, you must add it to your ``bblayers.conf`` |
331 | file, which is found in the | 352 | file, which is found in the :term:`Build Directory` ``conf`` directory. |
332 | :term:`Build Directory` ``conf`` | ||
333 | directory. | ||
334 | 353 | ||
335 | Use the ``bitbake-layers add-layer`` command to add the layer to the | 354 | Use the ``bitbake-layers add-layer`` command to add the layer to the |
336 | configuration file: | 355 | configuration file: |
337 | 356 | ||
338 | .. code-block:: shell | 357 | .. code-block:: shell |
339 | 358 | ||
340 | $ cd ~/poky/build | 359 | $ cd poky/build |
341 | $ bitbake-layers add-layer ../meta-altera | 360 | $ bitbake-layers add-layer ../meta-altera |
342 | NOTE: Starting bitbake server... | 361 | NOTE: Starting bitbake server... |
343 | Parsing recipes: 100% |##################################################################| Time: 0:00:32 | 362 | Parsing recipes: 100% |##################################################################| Time: 0:00:32 |
@@ -346,7 +365,7 @@ Follow these steps to add a hardware layer: | |||
346 | 365 | ||
347 | You can find | 366 | You can find |
348 | more information on adding layers in the | 367 | more information on adding layers in the |
349 | :ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script` | 368 | :ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script` |
350 | section. | 369 | section. |
351 | 370 | ||
352 | Completing these steps has added the ``meta-altera`` layer to your Yocto | 371 | Completing these steps has added the ``meta-altera`` layer to your Yocto |
@@ -374,14 +393,14 @@ The following commands run the tool to create a layer named | |||
374 | 393 | ||
375 | .. code-block:: shell | 394 | .. code-block:: shell |
376 | 395 | ||
377 | $ cd ~/poky | 396 | $ cd poky |
378 | $ bitbake-layers create-layer meta-mylayer | 397 | $ bitbake-layers create-layer meta-mylayer |
379 | NOTE: Starting bitbake server... | 398 | NOTE: Starting bitbake server... |
380 | Add your new layer with 'bitbake-layers add-layer meta-mylayer' | 399 | Add your new layer with 'bitbake-layers add-layer meta-mylayer' |
381 | 400 | ||
382 | For more information | 401 | For more information |
383 | on layers and how to create them, see the | 402 | on layers and how to create them, see the |
384 | :ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script` | 403 | :ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script` |
385 | section in the Yocto Project Development Tasks Manual. | 404 | section in the Yocto Project Development Tasks Manual. |
386 | 405 | ||
387 | Where To Go Next | 406 | Where To Go Next |
@@ -396,12 +415,12 @@ information including the website, wiki pages, and user manuals: | |||
396 | development documentation, and access to a rich Yocto Project | 415 | development documentation, and access to a rich Yocto Project |
397 | Development Community into which you can tap. | 416 | Development Community into which you can tap. |
398 | 417 | ||
399 | - **Developer Screencast:** The `Getting Started with the Yocto Project - | 418 | - **Video Seminar:** The `Introduction to the Yocto Project and BitBake, Part 1 |
400 | New Developer Screencast Tutorial <https://vimeo.com/36450321>`__ | 419 | <https://youtu.be/yuE7my3KOpo>`__ and |
401 | provides a 30-minute video created for users unfamiliar with the | 420 | `Introduction to the Yocto Project and BitBake, Part 2 |
402 | Yocto Project but familiar with Linux build hosts. While this | 421 | <https://youtu.be/iZ05TTyzGHk>`__ videos offer a video seminar |
403 | screencast is somewhat dated, the introductory and fundamental | 422 | introducing you to the most important aspects of developing a |
404 | concepts are useful for the beginner. | 423 | custom embedded Linux distribution with the Yocto Project. |
405 | 424 | ||
406 | - **Yocto Project Overview and Concepts Manual:** The | 425 | - **Yocto Project Overview and Concepts Manual:** The |
407 | :doc:`/overview-manual/index` is a great | 426 | :doc:`/overview-manual/index` is a great |
@@ -416,8 +435,8 @@ information including the website, wiki pages, and user manuals: | |||
416 | information. | 435 | information. |
417 | 436 | ||
418 | - **Yocto Project Mailing Lists:** Related mailing lists provide a forum | 437 | - **Yocto Project Mailing Lists:** Related mailing lists provide a forum |
419 | for discussion, patch submission and announcements. Several mailing | 438 | for discussion, patch submission and announcements. There are several |
420 | lists exist and are grouped according to areas of concern. See the | 439 | mailing lists grouped by topic. See the |
421 | :ref:`ref-manual/resources:mailing lists` | 440 | :ref:`ref-manual/resources:mailing lists` |
422 | section in the Yocto Project Reference Manual for a complete list of | 441 | section in the Yocto Project Reference Manual for a complete list of |
423 | Yocto Project mailing lists. | 442 | Yocto Project mailing lists. |