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.rst193
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
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 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
68If your build host does not meet any of these three listed version 68If your build host does not meet any of these three listed 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
@@ -76,11 +76,9 @@ Build Host Packages
76 76
77You must install essential host packages on your build host. The 77You 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 $ 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
109Move to the ``poky`` directory and take a look at the tags: 107Go to :yocto_wiki:`Releases wiki page </Releases>`, and choose a release
108codename (such as ``&DISTRO_NAME_NO_CAP;``), corresponding to either the
109latest stable release or a Long Term Support release.
110
111Then 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 138For 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
133For 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
141The previous Git checkout command creates a local branch named 147The 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
143match the repository's files in the ``&DISTRO_NAME_NO_CAP;`` development 149exactly match the repository's files in the ``&DISTRO_NAME_NO_CAP;``
144branch at the time of the Yocto Project &DISTRO_REL_TAG; release. 150release branch.
151
152Note that you can regularly type the following command in the same directory
153to keep your local files in sync with the release branch:
154
155.. code-block:: shell
156
157 $ git pull
145 158
146For more options and information about accessing Yocto Project related 159For more options and information about accessing Yocto Project related
147repositories, see the 160repositories, 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
283Follow these steps to add a hardware layer: 304Follow 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
352Completing these steps has added the ``meta-altera`` layer to your Yocto 371Completing 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
382For more information 401For more information
383on layers and how to create them, see the 402on 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`
385section in the Yocto Project Development Tasks Manual. 404section in the Yocto Project Development Tasks Manual.
386 405
387Where To Go Next 406Where 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.