summaryrefslogtreecommitdiffstats
path: root/documentation/brief-yoctoprojectqs/index.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/brief-yoctoprojectqs/index.rst')
-rw-r--r--documentation/brief-yoctoprojectqs/index.rst208
1 files changed, 117 insertions, 91 deletions
diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 63083cb13d..4a6f13d7ea 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
41If you want more conceptual or background information on the Yocto 34If you want more conceptual or background information on the Yocto
42Project, see the :doc:`/overview-manual/index`. 35Project, see the :doc:`/overview-manual/index`.
@@ -47,7 +40,13 @@ Compatible Linux Distribution
47Make sure your :term:`Build Host` meets the 40Make sure your :term:`Build Host` meets the
48following requirements: 41following 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 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
@@ -58,17 +57,18 @@ following requirements:
58 :ref:`dev-manual/start:preparing the build host` 57 :ref:`dev-manual/start:preparing the build host`
59 section in the Yocto Project Development Tasks Manual. 58 section in the Yocto Project Development Tasks Manual.
60 59
61- 60- Ensure that the following utilities have these minimum version numbers:
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
68If your build host does not meet any of these three listed version 68If your build host does not satisfy all of the above version
69requirements, you can take steps to prepare the system so that you 69requirements, you can take steps to prepare the system so that you
70can still use the Yocto Project. See the 70can 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`
72section in the Yocto Project Reference Manual for information. 72section in the Yocto Project Reference Manual for information.
73 73
74Build Host Packages 74Build Host Packages
@@ -78,9 +78,8 @@ You must install essential host packages on your build host. The
78following command installs the host packages based on an Ubuntu 78following command installs the host packages based on an Ubuntu
79distribution: 79distribution:
80 80
81.. code-block:: shell 81.. literalinclude:: ../tools/host_packages_scripts/ubuntu_essential.sh
82 82 :language: shell
83 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
84 83
85.. note:: 84.. note::
86 85
@@ -106,42 +105,57 @@ commands to clone the Poky repository.
106 Resolving deltas: 100% (323116/323116), done. 105 Resolving deltas: 100% (323116/323116), done.
107 Checking connectivity... done. 106 Checking connectivity... done.
108 107
109Move to the ``poky`` directory and take a look at the tags: 108Go to :yocto_wiki:`Releases wiki page </Releases>`, and choose a release
109codename (such as ``&DISTRO_NAME_NO_CAP;``), corresponding to either the
110latest stable release or a Long Term Support release.
111
112Then move to the ``poky`` directory and take a look at existing branches:
110 113
111.. code-block:: shell 114.. code-block:: shell
112 115
113 $ cd poky 116 $ cd poky
114 $ git fetch --tags 117 $ git branch -a
115 $ git tag 118 .
116 1.1_M1.final 119 .
117 1.1_M1.rc1 120 .
118 1.1_M1.rc2 121 remotes/origin/HEAD -> origin/master
119 1.1_M2.final 122 remotes/origin/dunfell
120 1.1_M2.rc1 123 remotes/origin/dunfell-next
124 .
125 .
126 .
127 remotes/origin/gatesgarth
128 remotes/origin/gatesgarth-next
129 .
121 . 130 .
122 . 131 .
132 remotes/origin/master
133 remotes/origin/master-next
123 . 134 .
124 yocto-2.5 135 .
125 yocto-2.5.1 136 .
126 yocto-2.5.2 137
127 yocto-2.6 138
128 yocto-2.6.1 139For this example, check out the ``&DISTRO_NAME_NO_CAP;`` branch based on the
129 yocto-2.6.2 140``&DISTRO_NAME;`` release:
130 yocto-2.7
131 yocto_1.5_M5.rc8
132
133For this example, check out the branch based on the
134``&DISTRO_REL_TAG;`` release:
135 141
136.. code-block:: shell 142.. code-block:: shell
137 143
138 $ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG; 144 $ git checkout -t origin/&DISTRO_NAME_NO_CAP; -b my-&DISTRO_NAME_NO_CAP;
139 Switched to a new branch 'my-&DISTRO_REL_TAG;' 145 Branch 'my-&DISTRO_NAME_NO_CAP;' set up to track remote branch '&DISTRO_NAME_NO_CAP;' from 'origin'.
146 Switched to a new branch 'my-&DISTRO_NAME_NO_CAP;'
140 147
141The previous Git checkout command creates a local branch named 148The previous Git checkout command creates a local branch named
142``my-&DISTRO_REL_TAG;``. The files available to you in that branch exactly 149``my-&DISTRO_NAME_NO_CAP;``. The files available to you in that branch
143match the repository's files in the ``&DISTRO_NAME_NO_CAP;`` development 150exactly match the repository's files in the ``&DISTRO_NAME_NO_CAP;``
144branch at the time of the Yocto Project &DISTRO_REL_TAG; release. 151release branch.
152
153Note that you can regularly type the following command in the same directory
154to keep your local files in sync with the release branch:
155
156.. code-block:: shell
157
158 $ git pull
145 159
146For more options and information about accessing Yocto Project related 160For more options and information about accessing Yocto Project related
147repositories, see the 161repositories, see the
@@ -169,14 +183,14 @@ an entire Linux distribution, including the toolchain, from source.
169 page of the Yocto Project Wiki. 183 page of the Yocto Project Wiki.
170 184
171#. **Initialize the Build Environment:** From within the ``poky`` 185#. **Initialize the Build Environment:** From within the ``poky``
172 directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` 186 directory, run the :ref:`ref-manual/structure:``oe-init-build-env```
173 environment 187 environment
174 setup script to define Yocto Project's build environment on your 188 setup script to define Yocto Project's build environment on your
175 build host. 189 build host.
176 190
177 .. code-block:: shell 191 .. code-block:: shell
178 192
179 $ cd ~/poky 193 $ cd poky
180 $ source oe-init-build-env 194 $ source oe-init-build-env
181 You had no conf/local.conf file. This configuration file has therefore been 195 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 196 created for you with some default values. You may wish to edit it to, for
@@ -189,10 +203,10 @@ an entire Linux distribution, including the toolchain, from source.
189 203
190 The Yocto Project has extensive documentation about OE including a reference 204 The Yocto Project has extensive documentation about OE including a reference
191 manual which can be found at: 205 manual which can be found at:
192 http://yoctoproject.org/documentation 206 https://docs.yoctoproject.org
193 207
194 For more information about OpenEmbedded see their website: 208 For more information about OpenEmbedded see their website:
195 http://www.openembedded.org/ 209 https://www.openembedded.org/
196 210
197 ### Shell environment set up for builds. ### 211 ### Shell environment set up for builds. ###
198 212
@@ -200,21 +214,28 @@ an entire Linux distribution, including the toolchain, from source.
200 214
201 Common targets are: 215 Common targets are:
202 core-image-minimal 216 core-image-minimal
217 core-image-full-cmdline
203 core-image-sato 218 core-image-sato
219 core-image-weston
204 meta-toolchain 220 meta-toolchain
205 meta-ide-support 221 meta-ide-support
206 222
207 You can also run generated qemu images with a command like 'runqemu qemux86-64' 223 You can also run generated QEMU images with a command like 'runqemu qemux86-64'
224
225 Other commonly useful commands are:
226 - 'devtool' and 'recipetool' handle common recipe tasks
227 - 'bitbake-layers' handles common layer tasks
228 - 'oe-pkgdata-util' handles common target package tasks
208 229
209 Among other things, the script creates the :term:`Build Directory`, which is 230 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 231 ``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 232 the script runs, your current working directory is set to the
212 Directory. Later, when the build completes, the Build Directory contains all the 233 :term:`Build Directory`. Later, when the build completes, the
213 files created during the build. 234 :term:`Build Directory` contains all the files created during the build.
214 235
215#. **Examine Your Local Configuration File:** When you set up the build 236#. **Examine Your Local Configuration File:** When you set up the build
216 environment, a local configuration file named ``local.conf`` becomes 237 environment, a local configuration file named ``local.conf`` becomes
217 available in a ``conf`` subdirectory of the Build Directory. For this 238 available in a ``conf`` subdirectory of the :term:`Build Directory`. For this
218 example, the defaults are set to build for a ``qemux86`` target, 239 example, the defaults are set to build for a ``qemux86`` target,
219 which is suitable for emulation. The package manager used is set to 240 which is suitable for emulation. The package manager used is set to
220 the RPM package manager. 241 the RPM package manager.
@@ -222,19 +243,25 @@ an entire Linux distribution, including the toolchain, from source.
222 .. tip:: 243 .. tip::
223 244
224 You can significantly speed up your build and guard against fetcher 245 You can significantly speed up your build and guard against fetcher
225 failures by using mirrors. To use mirrors, add these lines to your 246 failures by using :ref:`overview-manual/concepts:shared state cache`
226 local.conf file in the Build directory: :: 247 mirrors and enabling :ref:`overview-manual/concepts:hash equivalence`.
227 248 This way, you can use pre-built artifacts rather than building them.
228 SSTATE_MIRRORS = "\ 249 This is relevant only when your network and the server that you use
229 file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \ 250 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 \ 251
231 file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \ 252 To use such mirrors, uncomment the below lines in your ``conf/local.conf``
232 " 253 file in the :term:`Build Directory`::
233 254
234 255 BB_HASHSERVE_UPSTREAM = "wss://hashserv.yoctoproject.org/ws"
235 The previous examples showed how to add sstate paths for Yocto Project 256 SSTATE_MIRRORS ?= "file://.* http://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH"
236 &YOCTO_DOC_VERSION_MINUS_ONE;, &YOCTO_DOC_VERSION;, and a development 257 BB_HASHSERVE = "auto"
237 area. For a complete index of sstate locations, see http://sstate.yoctoproject.org/. 258 BB_SIGNATURE_HANDLER = "OEEquivHash"
259
260 The hash equivalence server needs the websockets python module version 9.1
261 or later. Debian GNU/Linux 12 (Bookworm) and later, Fedora, CentOS Stream
262 9 and later, and Ubuntu 22.04 (LTS) and later, all have a recent enough
263 package. Other supported distributions need to get the module some other
264 place than their package feed, e.g. via ``pip``.
238 265
239#. **Start the Build:** Continue with the following command to build an OS 266#. **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: 267 image for the target, which is ``core-image-sato`` in this example:
@@ -245,8 +272,9 @@ an entire Linux distribution, including the toolchain, from source.
245 272
246 For information on using the ``bitbake`` command, see the 273 For information on using the ``bitbake`` command, see the
247 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and 274 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and
248 Concepts Manual, or see the ":ref:`BitBake Command 275 Concepts Manual, or see
249 <bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command>`" section in the BitBake User Manual. 276 :ref:`bitbake-user-manual/bitbake-user-manual-intro:the bitbake command`
277 in the BitBake User Manual.
250 278
251#. **Simulate Your Image Using QEMU:** Once this particular image is 279#. **Simulate Your Image Using QEMU:** Once this particular image is
252 built, you can start QEMU, which is a Quick EMUlator that ships with 280 built, you can start QEMU, which is a Quick EMUlator that ships with
@@ -282,7 +310,7 @@ modular development and makes it easier to reuse the layer metadata.
282 310
283Follow these steps to add a hardware layer: 311Follow these steps to add a hardware layer:
284 312
285#. **Find a Layer:** Lots of hardware layers exist. The Yocto Project 313#. **Find a Layer:** Many hardware layers are available. The Yocto Project
286 :yocto_git:`Source Repositories <>` has many hardware layers. 314 :yocto_git:`Source Repositories <>` has many hardware layers.
287 This example adds the 315 This example adds the
288 `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer. 316 `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer.
@@ -293,7 +321,7 @@ Follow these steps to add a hardware layer:
293 321
294 .. code-block:: shell 322 .. code-block:: shell
295 323
296 $ cd ~/poky 324 $ cd poky
297 $ git clone https://github.com/kraj/meta-altera.git 325 $ git clone https://github.com/kraj/meta-altera.git
298 Cloning into 'meta-altera'... 326 Cloning into 'meta-altera'...
299 remote: Counting objects: 25170, done. 327 remote: Counting objects: 25170, done.
@@ -303,8 +331,8 @@ Follow these steps to add a hardware layer:
303 Resolving deltas: 100% (13385/13385), done. 331 Resolving deltas: 100% (13385/13385), done.
304 Checking connectivity... done. 332 Checking connectivity... done.
305 333
306 The hardware layer now exists 334 The hardware layer is now available
307 with other layers inside the Poky reference repository on your build 335 next to other layers inside the Poky reference repository on your build
308 host as ``meta-altera`` and contains all the metadata needed to 336 host as ``meta-altera`` and contains all the metadata needed to
309 support hardware from Altera, which is owned by Intel. 337 support hardware from Altera, which is owned by Intel.
310 338
@@ -317,7 +345,7 @@ Follow these steps to add a hardware layer:
317#. **Change the Configuration to Build for a Specific Machine:** The 345#. **Change the Configuration to Build for a Specific Machine:** The
318 :term:`MACHINE` variable in the 346 :term:`MACHINE` variable in the
319 ``local.conf`` file specifies the machine for the build. For this 347 ``local.conf`` file specifies the machine for the build. For this
320 example, set the ``MACHINE`` variable to ``cyclone5``. These 348 example, set the :term:`MACHINE` variable to ``cyclone5``. These
321 configurations are used: 349 configurations are used:
322 https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf. 350 https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf.
323 351
@@ -328,16 +356,14 @@ Follow these steps to add a hardware layer:
328 356
329#. **Add Your Layer to the Layer Configuration File:** Before you can use 357#. **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`` 358 a layer during a build, you must add it to your ``bblayers.conf``
331 file, which is found in the 359 file, which is found in the :term:`Build Directory` ``conf`` directory.
332 :term:`Build Directory` ``conf``
333 directory.
334 360
335 Use the ``bitbake-layers add-layer`` command to add the layer to the 361 Use the ``bitbake-layers add-layer`` command to add the layer to the
336 configuration file: 362 configuration file:
337 363
338 .. code-block:: shell 364 .. code-block:: shell
339 365
340 $ cd ~/poky/build 366 $ cd poky/build
341 $ bitbake-layers add-layer ../meta-altera 367 $ bitbake-layers add-layer ../meta-altera
342 NOTE: Starting bitbake server... 368 NOTE: Starting bitbake server...
343 Parsing recipes: 100% |##################################################################| Time: 0:00:32 369 Parsing recipes: 100% |##################################################################| Time: 0:00:32
@@ -346,7 +372,7 @@ Follow these steps to add a hardware layer:
346 372
347 You can find 373 You can find
348 more information on adding layers in the 374 more information on adding layers in the
349 :ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script` 375 :ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`
350 section. 376 section.
351 377
352Completing these steps has added the ``meta-altera`` layer to your Yocto 378Completing these steps has added the ``meta-altera`` layer to your Yocto
@@ -374,14 +400,14 @@ The following commands run the tool to create a layer named
374 400
375.. code-block:: shell 401.. code-block:: shell
376 402
377 $ cd ~/poky 403 $ cd poky
378 $ bitbake-layers create-layer meta-mylayer 404 $ bitbake-layers create-layer meta-mylayer
379 NOTE: Starting bitbake server... 405 NOTE: Starting bitbake server...
380 Add your new layer with 'bitbake-layers add-layer meta-mylayer' 406 Add your new layer with 'bitbake-layers add-layer meta-mylayer'
381 407
382For more information 408For more information
383on layers and how to create them, see the 409on layers and how to create them, see the
384:ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script` 410:ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`
385section in the Yocto Project Development Tasks Manual. 411section in the Yocto Project Development Tasks Manual.
386 412
387Where To Go Next 413Where To Go Next
@@ -396,12 +422,12 @@ information including the website, wiki pages, and user manuals:
396 development documentation, and access to a rich Yocto Project 422 development documentation, and access to a rich Yocto Project
397 Development Community into which you can tap. 423 Development Community into which you can tap.
398 424
399- **Developer Screencast:** The `Getting Started with the Yocto Project - 425- **Video Seminar:** The `Introduction to the Yocto Project and BitBake, Part 1
400 New Developer Screencast Tutorial <https://vimeo.com/36450321>`__ 426 <https://youtu.be/yuE7my3KOpo>`__ and
401 provides a 30-minute video created for users unfamiliar with the 427 `Introduction to the Yocto Project and BitBake, Part 2
402 Yocto Project but familiar with Linux build hosts. While this 428 <https://youtu.be/iZ05TTyzGHk>`__ videos offer a video seminar
403 screencast is somewhat dated, the introductory and fundamental 429 introducing you to the most important aspects of developing a
404 concepts are useful for the beginner. 430 custom embedded Linux distribution with the Yocto Project.
405 431
406- **Yocto Project Overview and Concepts Manual:** The 432- **Yocto Project Overview and Concepts Manual:** The
407 :doc:`/overview-manual/index` is a great 433 :doc:`/overview-manual/index` is a great
@@ -416,8 +442,8 @@ information including the website, wiki pages, and user manuals:
416 information. 442 information.
417 443
418- **Yocto Project Mailing Lists:** Related mailing lists provide a forum 444- **Yocto Project Mailing Lists:** Related mailing lists provide a forum
419 for discussion, patch submission and announcements. Several mailing 445 for discussion, patch submission and announcements. There are several
420 lists exist and are grouped according to areas of concern. See the 446 mailing lists grouped by topic. See the
421 :ref:`ref-manual/resources:mailing lists` 447 :ref:`ref-manual/resources:mailing lists`
422 section in the Yocto Project Reference Manual for a complete list of 448 section in the Yocto Project Reference Manual for a complete list of
423 Yocto Project mailing lists. 449 Yocto Project mailing lists.