blob: ad5d8a950c29655e9881fb2acfcd611a22acb268 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3=========================
4Yocto Project Quick Build
5=========================
6
7Welcome!
8========
9
10This short document steps you through the process for a typical
11image build using the Yocto Project. The document also introduces how to
12configure a build for specific hardware. You will use Yocto Project to
13build a reference embedded OS called Poky.
14
15.. note::
16
17 - The examples in this paper assume you are using a native Linux
18 system running a recent Ubuntu Linux distribution. If the machine
19 you want to use Yocto Project on to build an image
20 (:term:`Build Host`) is not
21 a native Linux system, you can still perform these steps by using
22 CROss PlatformS (CROPS) and setting up a Poky container. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -060023 :ref:`dev-manual/start:setting up to use cross platforms (crops)`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050024 section
25 in the Yocto Project Development Tasks Manual for more
26 information.
27
28 - You may use Windows Subsystem For Linux v2 to set up a build host
29 using Windows 10.
30
31 .. note::
32
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
Andrew Geissler09209ee2020-12-13 08:44:15 -060037 See the :ref:`dev-manual/start:setting up to use windows
Andrew Geisslerc9f78652020-09-18 14:11:35 -050038 subsystem for linux (wslv2)` section in the Yocto Project Development
39 Tasks Manual for more information.
40
41If you want more conceptual or background information on the Yocto
Andrew Geissler09209ee2020-12-13 08:44:15 -060042Project, see the :doc:`/overview-manual/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050043
44Compatible Linux Distribution
45=============================
46
47Make sure your :term:`Build Host` meets the
48following requirements:
49
50- 50 Gbytes of free disk space
51
52- Runs a supported Linux distribution (i.e. recent releases of Fedora,
53 openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux
54 distributions that support the Yocto Project, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060055 :ref:`ref-manual/system-requirements:supported linux distributions`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050056 section in the Yocto Project Reference Manual. For detailed
57 information on preparing your build host, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060058 :ref:`dev-manual/start:preparing the build host`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050059 section in the Yocto Project Development Tasks Manual.
60
61-
62
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050063 - Git &MIN_GIT_VERSION; or greater
64 - tar &MIN_TAR_VERSION; or greater
65 - Python &MIN_PYTHON_VERSION; or greater.
66 - gcc &MIN_GCC_VERSION; or greater.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050067
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
70can still use the Yocto Project. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -060071:ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050072section in the Yocto Project Reference Manual for information.
73
74Build Host Packages
75===================
76
77You must install essential host packages on your build host. The
78following command installs the host packages based on an Ubuntu
79distribution:
80
81.. code-block:: shell
82
Andrew Geisslereff27472021-10-29 15:35:00 -050083 $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
Andrew Geisslerc9f78652020-09-18 14:11:35 -050084
85.. note::
86
87 For host package requirements on all supported Linux distributions,
Andrew Geissler09209ee2020-12-13 08:44:15 -060088 see the :ref:`ref-manual/system-requirements:required packages for the build host`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050089 section in the Yocto Project Reference Manual.
90
91Use Git to Clone Poky
92=====================
93
94Once you complete the setup instructions for your machine, you need to
95get a copy of the Poky repository on your build host. Use the following
96commands to clone the Poky repository.
97
98.. code-block:: shell
99
100 $ git clone git://git.yoctoproject.org/poky
101 Cloning into 'poky'...
102 remote: Counting
103 objects: 432160, done. remote: Compressing objects: 100%
104 (102056/102056), done. remote: Total 432160 (delta 323116), reused
105 432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
106 Resolving deltas: 100% (323116/323116), done.
107 Checking connectivity... done.
108
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500109Go to :yocto_wiki:`Releases wiki page </Releases>`, and choose a release
110codename (such as ``&DISTRO_NAME_NO_CAP;``), corresponding to either the
111latest stable release or a Long Term Support release.
112
113Then move to the ``poky`` directory and take a look at existing branches:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500114
115.. code-block:: shell
116
117 $ cd poky
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500118 $ git branch -a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500119 .
120 .
121 .
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500122 remotes/origin/HEAD -> origin/master
123 remotes/origin/dunfell
124 remotes/origin/dunfell-next
125 .
126 .
127 .
128 remotes/origin/gatesgarth
129 remotes/origin/gatesgarth-next
130 .
131 .
132 .
133 remotes/origin/master
134 remotes/origin/master-next
135 .
136 .
137 .
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500138
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500139
140For this example, check out the ``&DISTRO_NAME_NO_CAP;`` branch based on the
141``&DISTRO_NAME;`` release:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500142
143.. code-block:: shell
144
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500145 $ git checkout -t origin/&DISTRO_NAME_NO_CAP; -b my-&DISTRO_NAME_NO_CAP;
146 Branch 'my-&DISTRO_NAME_NO_CAP;' set up to track remote branch '&DISTRO_NAME_NO_CAP;' from 'origin'.
147 Switched to a new branch 'my-&DISTRO_NAME_NO_CAP;'
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500148
149The previous Git checkout command creates a local branch named
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500150``my-&DISTRO_NAME_NO_CAP;``. The files available to you in that branch
151exactly match the repository's files in the ``&DISTRO_NAME_NO_CAP;``
152release branch.
153
154Note that you can regularly type the following command in the same directory
155to keep your local files in sync with the release branch:
156
157.. code-block:: shell
158
159 $ git pull
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500160
161For more options and information about accessing Yocto Project related
162repositories, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600163:ref:`dev-manual/start:locating yocto project source files`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500164section in the Yocto Project Development Tasks Manual.
165
166Building Your Image
167===================
168
169Use the following steps to build your image. The build process creates
170an entire Linux distribution, including the toolchain, from source.
171
172.. note::
173
174 - If you are working behind a firewall and your build host is not
175 set up for proxies, you could encounter problems with the build
176 process when fetching source code (e.g. fetcher failures or Git
177 failures).
178
179 - If you do not know your proxy settings, consult your local network
180 infrastructure resources and get that information. A good starting
181 point could also be to check your web browser settings. Finally,
182 you can find more information on the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600183 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500184 page of the Yocto Project Wiki.
185
186#. **Initialize the Build Environment:** From within the ``poky``
Andrew Geissler09209ee2020-12-13 08:44:15 -0600187 directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500188 environment
189 setup script to define Yocto Project's build environment on your
190 build host.
191
192 .. code-block:: shell
193
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500194 $ cd poky
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500195 $ source oe-init-build-env
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500196 You had no conf/local.conf file. This configuration file has therefore been
197 created for you with some default values. You may wish to edit it to, for
198 example, select a different MACHINE (target hardware). See conf/local.conf
199 for more information as common configuration options are commented.
200
201 You had no conf/bblayers.conf file. This configuration file has therefore
202 been created for you with some default values. To add additional metadata
203 layers into your configuration please add entries to conf/bblayers.conf.
204
205 The Yocto Project has extensive documentation about OE including a reference
206 manual which can be found at:
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500207 https://docs.yoctoproject.org
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500208
209 For more information about OpenEmbedded see their website:
Patrick Williams213cb262021-08-07 19:21:33 -0500210 https://www.openembedded.org/
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500211
212 ### Shell environment set up for builds. ###
213
214 You can now run 'bitbake <target>'
215
216 Common targets are:
217 core-image-minimal
Patrick Williams213cb262021-08-07 19:21:33 -0500218 core-image-full-cmdline
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500219 core-image-sato
Patrick Williams213cb262021-08-07 19:21:33 -0500220 core-image-weston
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500221 meta-toolchain
222 meta-ide-support
223
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500224 You can also run generated QEMU images with a command like 'runqemu qemux86-64'
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500225
Patrick Williams213cb262021-08-07 19:21:33 -0500226 Other commonly useful commands are:
227 - 'devtool' and 'recipetool' handle common recipe tasks
228 - 'bitbake-layers' handles common layer tasks
229 - 'oe-pkgdata-util' handles common target package tasks
230
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500231 Among other things, the script creates the :term:`Build Directory`, which is
232 ``build`` in this case and is located in the :term:`Source Directory`. After
233 the script runs, your current working directory is set to the Build
234 Directory. Later, when the build completes, the Build Directory contains all the
235 files created during the build.
236
237#. **Examine Your Local Configuration File:** When you set up the build
238 environment, a local configuration file named ``local.conf`` becomes
239 available in a ``conf`` subdirectory of the Build Directory. For this
240 example, the defaults are set to build for a ``qemux86`` target,
241 which is suitable for emulation. The package manager used is set to
242 the RPM package manager.
243
244 .. tip::
245
246 You can significantly speed up your build and guard against fetcher
Andrew Geissler595f6302022-01-24 19:11:47 +0000247 failures by using :ref:`overview-manual/concepts:shared state cache`
248 mirrors and enabling :ref:`overview-manual/concepts:hash equivalence`.
249 This way, you can use pre-built artifacts rather than building them.
250 This is relevant only when your network and the server that you use
251 can download these artifacts faster than you would be able to build them.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500252
Andrew Geissler595f6302022-01-24 19:11:47 +0000253 To use such mirrors, uncomment the below lines in your ``local.conf``
254 file in the :term:`Build Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500255
Andrew Geissler595f6302022-01-24 19:11:47 +0000256 BB_SIGNATURE_HANDLER = "OEEquivHash"
257 BB_HASHSERVE = "auto"
258 BB_HASHSERVE_UPSTREAM = "typhoon.yocto.io:8687"
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000259 SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500260
Andrew Geissler595f6302022-01-24 19:11:47 +0000261 The above settings assumed the use of Yocto Project &YOCTO_DOC_VERSION;.
262 If you are using the development version instead, set :term:`SSTATE_MIRRORS` as follows::
263
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000264 SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500265
266#. **Start the Build:** Continue with the following command to build an OS
267 image for the target, which is ``core-image-sato`` in this example:
268
269 .. code-block:: shell
270
271 $ bitbake core-image-sato
272
273 For information on using the ``bitbake`` command, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600274 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and
Patrick Williams213cb262021-08-07 19:21:33 -0500275 Concepts Manual, or see
276 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command`
277 in the BitBake User Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500278
279#. **Simulate Your Image Using QEMU:** Once this particular image is
280 built, you can start QEMU, which is a Quick EMUlator that ships with
281 the Yocto Project:
282
283 .. code-block:: shell
284
285 $ runqemu qemux86-64
286
287 If you want to learn more about running QEMU, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600288 :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500289 the Yocto Project Development Tasks Manual.
290
291#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing
292 ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU.
293
294Customizing Your Build for Specific Hardware
295============================================
296
297So far, all you have done is quickly built an image suitable for
298emulation only. This section shows you how to customize your build for
299specific hardware by adding a hardware layer into the Yocto Project
300development environment.
301
302In general, layers are repositories that contain related sets of
303instructions and configurations that tell the Yocto Project what to do.
304Isolating related metadata into functionally specific layers facilitates
305modular development and makes it easier to reuse the layer metadata.
306
307.. note::
308
309 By convention, layer names start with the string "meta-".
310
311Follow these steps to add a hardware layer:
312
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700313#. **Find a Layer:** Many hardware layers are available. The Yocto Project
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500314 :yocto_git:`Source Repositories <>` has many hardware layers.
315 This example adds the
316 `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer.
317
318#. **Clone the Layer:** Use Git to make a local copy of the layer on your
319 machine. You can put the copy in the top level of the copy of the
320 Poky repository created earlier:
321
322 .. code-block:: shell
323
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500324 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500325 $ git clone https://github.com/kraj/meta-altera.git
326 Cloning into 'meta-altera'...
327 remote: Counting objects: 25170, done.
328 remote: Compressing objects: 100% (350/350), done.
329 remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
330 Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done.
331 Resolving deltas: 100% (13385/13385), done.
332 Checking connectivity... done.
333
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700334 The hardware layer is now available
335 next to other layers inside the Poky reference repository on your build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500336 host as ``meta-altera`` and contains all the metadata needed to
337 support hardware from Altera, which is owned by Intel.
338
339 .. note::
340
341 It is recommended for layers to have a branch per Yocto Project release.
342 Please make sure to checkout the layer branch supporting the Yocto Project
343 release you're using.
344
345#. **Change the Configuration to Build for a Specific Machine:** The
346 :term:`MACHINE` variable in the
347 ``local.conf`` file specifies the machine for the build. For this
Andrew Geissler09036742021-06-25 14:25:14 -0500348 example, set the :term:`MACHINE` variable to ``cyclone5``. These
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500349 configurations are used:
350 https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf.
351
352 .. note::
353
354 See the "Examine Your Local Configuration File" step earlier for more
355 information on configuring the build.
356
357#. **Add Your Layer to the Layer Configuration File:** Before you can use
358 a layer during a build, you must add it to your ``bblayers.conf``
359 file, which is found in the
360 :term:`Build Directory` ``conf``
361 directory.
362
363 Use the ``bitbake-layers add-layer`` command to add the layer to the
364 configuration file:
365
366 .. code-block:: shell
367
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500368 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500369 $ bitbake-layers add-layer ../meta-altera
370 NOTE: Starting bitbake server...
371 Parsing recipes: 100% |##################################################################| Time: 0:00:32
372 Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets,
373 123 skipped, 0 masked, 0 errors.
374
375 You can find
376 more information on adding layers in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600377 :ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500378 section.
379
380Completing these steps has added the ``meta-altera`` layer to your Yocto
381Project development environment and configured it to build for the
382``cyclone5`` machine.
383
384.. note::
385
386 The previous steps are for demonstration purposes only. If you were
387 to attempt to build an image for the ``cyclone5`` machine, you should
388 read the Altera ``README``.
389
390Creating Your Own General Layer
391===============================
392
393Maybe you have an application or specific set of behaviors you need to
394isolate. You can create your own general layer using the
395``bitbake-layers create-layer`` command. The tool automates layer
396creation by setting up a subdirectory with a ``layer.conf``
397configuration file, a ``recipes-example`` subdirectory that contains an
398``example.bb`` recipe, a licensing file, and a ``README``.
399
400The following commands run the tool to create a layer named
401``meta-mylayer`` in the ``poky`` directory:
402
403.. code-block:: shell
404
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500405 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500406 $ bitbake-layers create-layer meta-mylayer
407 NOTE: Starting bitbake server...
408 Add your new layer with 'bitbake-layers add-layer meta-mylayer'
409
410For more information
411on layers and how to create them, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600412:ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500413section in the Yocto Project Development Tasks Manual.
414
415Where To Go Next
416================
417
418Now that you have experienced using the Yocto Project, you might be
419asking yourself "What now?". The Yocto Project has many sources of
420information including the website, wiki pages, and user manuals:
421
422- **Website:** The :yocto_home:`Yocto Project Website <>` provides
423 background information, the latest builds, breaking news, full
424 development documentation, and access to a rich Yocto Project
425 Development Community into which you can tap.
426
Andrew Geissler9aee5002022-03-30 16:27:02 +0000427- **Video Seminar:** The `Introduction to the Yocto Project and Bitbake, Part 1
428 <https://youtu.be/yuE7my3KOpo>`__ and
429 `Introduction to the Yocto Project and Bitbake, Part 2
430 <https://youtu.be/iZ05TTyzGHk>`__ videos offer a video seminar
431 introducing you to the most important aspects of developing a
432 custom embedded Linux distribution with the Yocto Project.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500433
434- **Yocto Project Overview and Concepts Manual:** The
Andrew Geissler09209ee2020-12-13 08:44:15 -0600435 :doc:`/overview-manual/index` is a great
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500436 place to start to learn about the Yocto Project. This manual
437 introduces you to the Yocto Project and its development environment.
438 The manual also provides conceptual information for various aspects
439 of the Yocto Project.
440
441- **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>`
442 provides additional information on where to go next when ramping up
443 with the Yocto Project, release information, project planning, and QA
444 information.
445
446- **Yocto Project Mailing Lists:** Related mailing lists provide a forum
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700447 for discussion, patch submission and announcements. There are several
448 mailing lists grouped by topic. See the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500449 :ref:`ref-manual/resources:mailing lists`
450 section in the Yocto Project Reference Manual for a complete list of
451 Yocto Project mailing lists.
452
453- **Comprehensive List of Links and Other Documentation:** The
454 :ref:`ref-manual/resources:links and related documentation`
455 section in the Yocto Project Reference Manual provides a
456 comprehensive list of all related links and other user documentation.
457
458.. include:: /boilerplate.rst