blob: 0ccffccc60343a2c11d7d6f91dc2c1ec8cc0d8b6 [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
Patrick Williams2390b1b2022-11-03 13:47:49 -050028 - You may use version 2 of Windows Subsystem For Linux (WSL 2) to set
29 up a build host using Windows 10 or later, Windows Server 2019 or later.
30 See the :ref:`dev-manual/start:setting up to use windows subsystem for
31 linux (wsl 2)` section in the Yocto Project Development Tasks Manual
32 for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050033
34If you want more conceptual or background information on the Yocto
Andrew Geissler09209ee2020-12-13 08:44:15 -060035Project, see the :doc:`/overview-manual/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050036
37Compatible Linux Distribution
38=============================
39
40Make sure your :term:`Build Host` meets the
41following requirements:
42
Patrick Williams8e7b46e2023-05-01 14:19:06 -050043- 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.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050050
51- Runs a supported Linux distribution (i.e. recent releases of Fedora,
52 openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux
53 distributions that support the Yocto Project, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060054 :ref:`ref-manual/system-requirements:supported linux distributions`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050055 section in the Yocto Project Reference Manual. For detailed
56 information on preparing your build host, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060057 :ref:`dev-manual/start:preparing the build host`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050058 section in the Yocto Project Development Tasks Manual.
59
60-
61
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050062 - Git &MIN_GIT_VERSION; or greater
63 - tar &MIN_TAR_VERSION; or greater
64 - Python &MIN_PYTHON_VERSION; or greater.
65 - gcc &MIN_GCC_VERSION; or greater.
Andrew Geissler615f2f12022-07-15 14:00:58 -050066 - GNU make &MIN_MAKE_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 Geissler615f2f12022-07-15 14:00:58 -050071:ref:`ref-manual/system-requirements:required git, tar, python, make 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
Andrew Geisslerfc113ea2023-03-31 09:59:46 -050079distribution::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050080
Andrew Geisslerfc113ea2023-03-31 09:59:46 -050081 $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
Andrew Geisslerc9f78652020-09-18 14:11:35 -050082
83.. note::
84
85 For host package requirements on all supported Linux distributions,
Andrew Geissler09209ee2020-12-13 08:44:15 -060086 see the :ref:`ref-manual/system-requirements:required packages for the build host`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050087 section in the Yocto Project Reference Manual.
88
89Use Git to Clone Poky
90=====================
91
92Once you complete the setup instructions for your machine, you need to
93get a copy of the Poky repository on your build host. Use the following
94commands to clone the Poky repository.
95
96.. code-block:: shell
97
98 $ git clone git://git.yoctoproject.org/poky
99 Cloning into 'poky'...
100 remote: Counting
101 objects: 432160, done. remote: Compressing objects: 100%
102 (102056/102056), done. remote: Total 432160 (delta 323116), reused
103 432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
104 Resolving deltas: 100% (323116/323116), done.
105 Checking connectivity... done.
106
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500107Go 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:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112
113.. code-block:: shell
114
115 $ cd poky
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500116 $ git branch -a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117 .
118 .
119 .
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500120 remotes/origin/HEAD -> origin/master
121 remotes/origin/dunfell
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
133 .
134 .
135 .
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500136
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500137
138For this example, check out the ``&DISTRO_NAME_NO_CAP;`` branch based on the
139``&DISTRO_NAME;`` release:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500140
141.. code-block:: shell
142
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500143 $ git checkout -t origin/&DISTRO_NAME_NO_CAP; -b my-&DISTRO_NAME_NO_CAP;
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;'
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500146
147The previous Git checkout command creates a local branch named
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500148``my-&DISTRO_NAME_NO_CAP;``. The files available to you in that branch
149exactly match the repository's files in the ``&DISTRO_NAME_NO_CAP;``
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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500158
159For more options and information about accessing Yocto Project related
160repositories, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600161:ref:`dev-manual/start:locating yocto project source files`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500162section in the Yocto Project Development Tasks Manual.
163
164Building Your Image
165===================
166
167Use the following steps to build your image. The build process creates
168an entire Linux distribution, including the toolchain, from source.
169
170.. note::
171
172 - If you are working behind a firewall and your build host is not
173 set up for proxies, you could encounter problems with the build
174 process when fetching source code (e.g. fetcher failures or Git
175 failures).
176
177 - If you do not know your proxy settings, consult your local network
178 infrastructure resources and get that information. A good starting
179 point could also be to check your web browser settings. Finally,
180 you can find more information on the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600181 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500182 page of the Yocto Project Wiki.
183
184#. **Initialize the Build Environment:** From within the ``poky``
Andrew Geissler09209ee2020-12-13 08:44:15 -0600185 directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500186 environment
187 setup script to define Yocto Project's build environment on your
188 build host.
189
190 .. code-block:: shell
191
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500192 $ cd poky
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500193 $ source oe-init-build-env
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500194 You had no conf/local.conf file. This configuration file has therefore been
195 created for you with some default values. You may wish to edit it to, for
196 example, select a different MACHINE (target hardware). See conf/local.conf
197 for more information as common configuration options are commented.
198
199 You had no conf/bblayers.conf file. This configuration file has therefore
200 been created for you with some default values. To add additional metadata
201 layers into your configuration please add entries to conf/bblayers.conf.
202
203 The Yocto Project has extensive documentation about OE including a reference
204 manual which can be found at:
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500205 https://docs.yoctoproject.org
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500206
207 For more information about OpenEmbedded see their website:
Patrick Williams213cb262021-08-07 19:21:33 -0500208 https://www.openembedded.org/
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500209
210 ### Shell environment set up for builds. ###
211
212 You can now run 'bitbake <target>'
213
214 Common targets are:
215 core-image-minimal
Patrick Williams213cb262021-08-07 19:21:33 -0500216 core-image-full-cmdline
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500217 core-image-sato
Patrick Williams213cb262021-08-07 19:21:33 -0500218 core-image-weston
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500219 meta-toolchain
220 meta-ide-support
221
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500222 You can also run generated QEMU images with a command like 'runqemu qemux86-64'
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500223
Patrick Williams213cb262021-08-07 19:21:33 -0500224 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
228
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500229 Among other things, the script creates the :term:`Build Directory`, which is
230 ``build`` in this case and is located in the :term:`Source Directory`. After
Patrick Williams2390b1b2022-11-03 13:47:49 -0500231 the script runs, your current working directory is set to the
232 :term:`Build Directory`. Later, when the build completes, the
233 :term:`Build Directory` contains all the files created during the build.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500234
235#. **Examine Your Local Configuration File:** When you set up the build
236 environment, a local configuration file named ``local.conf`` becomes
Patrick Williams2390b1b2022-11-03 13:47:49 -0500237 available in a ``conf`` subdirectory of the :term:`Build Directory`. For this
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500238 example, the defaults are set to build for a ``qemux86`` target,
239 which is suitable for emulation. The package manager used is set to
240 the RPM package manager.
241
242 .. tip::
243
244 You can significantly speed up your build and guard against fetcher
Andrew Geissler595f6302022-01-24 19:11:47 +0000245 failures by using :ref:`overview-manual/concepts:shared state cache`
246 mirrors and enabling :ref:`overview-manual/concepts:hash equivalence`.
247 This way, you can use pre-built artifacts rather than building them.
248 This is relevant only when your network and the server that you use
249 can download these artifacts faster than you would be able to build them.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500250
Patrick Williams03907ee2022-05-01 06:28:52 -0500251 To use such mirrors, uncomment the below lines in your ``conf/local.conf``
Andrew Geissler595f6302022-01-24 19:11:47 +0000252 file in the :term:`Build Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500253
Andrew Geissler595f6302022-01-24 19:11:47 +0000254 BB_SIGNATURE_HANDLER = "OEEquivHash"
255 BB_HASHSERVE = "auto"
Patrick Williamsdb4c27e2022-08-05 08:10:29 -0500256 BB_HASHSERVE_UPSTREAM = "hashserv.yocto.io:8687"
Andrew Geissler615f2f12022-07-15 14:00:58 -0500257 SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500258
259#. **Start the Build:** Continue with the following command to build an OS
260 image for the target, which is ``core-image-sato`` in this example:
261
262 .. code-block:: shell
263
264 $ bitbake core-image-sato
265
266 For information on using the ``bitbake`` command, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600267 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and
Patrick Williams213cb262021-08-07 19:21:33 -0500268 Concepts Manual, or see
Andrew Geisslerfc113ea2023-03-31 09:59:46 -0500269 :ref:`bitbake-user-manual/bitbake-user-manual-intro:the bitbake command`
Patrick Williams213cb262021-08-07 19:21:33 -0500270 in the BitBake User Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500271
272#. **Simulate Your Image Using QEMU:** Once this particular image is
273 built, you can start QEMU, which is a Quick EMUlator that ships with
274 the Yocto Project:
275
276 .. code-block:: shell
277
278 $ runqemu qemux86-64
279
280 If you want to learn more about running QEMU, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600281 :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500282 the Yocto Project Development Tasks Manual.
283
284#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing
285 ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU.
286
287Customizing Your Build for Specific Hardware
288============================================
289
290So far, all you have done is quickly built an image suitable for
291emulation only. This section shows you how to customize your build for
292specific hardware by adding a hardware layer into the Yocto Project
293development environment.
294
295In general, layers are repositories that contain related sets of
296instructions and configurations that tell the Yocto Project what to do.
297Isolating related metadata into functionally specific layers facilitates
298modular development and makes it easier to reuse the layer metadata.
299
300.. note::
301
302 By convention, layer names start with the string "meta-".
303
304Follow these steps to add a hardware layer:
305
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700306#. **Find a Layer:** Many hardware layers are available. The Yocto Project
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500307 :yocto_git:`Source Repositories <>` has many hardware layers.
308 This example adds the
309 `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer.
310
311#. **Clone the Layer:** Use Git to make a local copy of the layer on your
312 machine. You can put the copy in the top level of the copy of the
313 Poky repository created earlier:
314
315 .. code-block:: shell
316
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500317 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500318 $ git clone https://github.com/kraj/meta-altera.git
319 Cloning into 'meta-altera'...
320 remote: Counting objects: 25170, done.
321 remote: Compressing objects: 100% (350/350), done.
322 remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
323 Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done.
324 Resolving deltas: 100% (13385/13385), done.
325 Checking connectivity... done.
326
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700327 The hardware layer is now available
328 next to other layers inside the Poky reference repository on your build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500329 host as ``meta-altera`` and contains all the metadata needed to
330 support hardware from Altera, which is owned by Intel.
331
332 .. note::
333
334 It is recommended for layers to have a branch per Yocto Project release.
335 Please make sure to checkout the layer branch supporting the Yocto Project
336 release you're using.
337
338#. **Change the Configuration to Build for a Specific Machine:** The
339 :term:`MACHINE` variable in the
340 ``local.conf`` file specifies the machine for the build. For this
Andrew Geissler09036742021-06-25 14:25:14 -0500341 example, set the :term:`MACHINE` variable to ``cyclone5``. These
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500342 configurations are used:
343 https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf.
344
345 .. note::
346
347 See the "Examine Your Local Configuration File" step earlier for more
348 information on configuring the build.
349
350#. **Add Your Layer to the Layer Configuration File:** Before you can use
351 a layer during a build, you must add it to your ``bblayers.conf``
Patrick Williams2390b1b2022-11-03 13:47:49 -0500352 file, which is found in the :term:`Build Directory` ``conf`` directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500353
354 Use the ``bitbake-layers add-layer`` command to add the layer to the
355 configuration file:
356
357 .. code-block:: shell
358
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500359 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500360 $ bitbake-layers add-layer ../meta-altera
361 NOTE: Starting bitbake server...
362 Parsing recipes: 100% |##################################################################| Time: 0:00:32
363 Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets,
364 123 skipped, 0 masked, 0 errors.
365
366 You can find
367 more information on adding layers in the
Andrew Geissler517393d2023-01-13 08:55:19 -0600368 :ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500369 section.
370
371Completing these steps has added the ``meta-altera`` layer to your Yocto
372Project development environment and configured it to build for the
373``cyclone5`` machine.
374
375.. note::
376
377 The previous steps are for demonstration purposes only. If you were
378 to attempt to build an image for the ``cyclone5`` machine, you should
379 read the Altera ``README``.
380
381Creating Your Own General Layer
382===============================
383
384Maybe you have an application or specific set of behaviors you need to
385isolate. You can create your own general layer using the
386``bitbake-layers create-layer`` command. The tool automates layer
387creation by setting up a subdirectory with a ``layer.conf``
388configuration file, a ``recipes-example`` subdirectory that contains an
389``example.bb`` recipe, a licensing file, and a ``README``.
390
391The following commands run the tool to create a layer named
392``meta-mylayer`` in the ``poky`` directory:
393
394.. code-block:: shell
395
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500396 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500397 $ bitbake-layers create-layer meta-mylayer
398 NOTE: Starting bitbake server...
399 Add your new layer with 'bitbake-layers add-layer meta-mylayer'
400
401For more information
402on layers and how to create them, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600403:ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500404section in the Yocto Project Development Tasks Manual.
405
406Where To Go Next
407================
408
409Now that you have experienced using the Yocto Project, you might be
410asking yourself "What now?". The Yocto Project has many sources of
411information including the website, wiki pages, and user manuals:
412
413- **Website:** The :yocto_home:`Yocto Project Website <>` provides
414 background information, the latest builds, breaking news, full
415 development documentation, and access to a rich Yocto Project
416 Development Community into which you can tap.
417
Andrew Geisslerd5838332022-05-27 11:33:10 -0500418- **Video Seminar:** The `Introduction to the Yocto Project and BitBake, Part 1
Andrew Geissler9aee5002022-03-30 16:27:02 +0000419 <https://youtu.be/yuE7my3KOpo>`__ and
Andrew Geisslerd5838332022-05-27 11:33:10 -0500420 `Introduction to the Yocto Project and BitBake, Part 2
Andrew Geissler9aee5002022-03-30 16:27:02 +0000421 <https://youtu.be/iZ05TTyzGHk>`__ videos offer a video seminar
422 introducing you to the most important aspects of developing a
423 custom embedded Linux distribution with the Yocto Project.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500424
425- **Yocto Project Overview and Concepts Manual:** The
Andrew Geissler09209ee2020-12-13 08:44:15 -0600426 :doc:`/overview-manual/index` is a great
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500427 place to start to learn about the Yocto Project. This manual
428 introduces you to the Yocto Project and its development environment.
429 The manual also provides conceptual information for various aspects
430 of the Yocto Project.
431
432- **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>`
433 provides additional information on where to go next when ramping up
434 with the Yocto Project, release information, project planning, and QA
435 information.
436
437- **Yocto Project Mailing Lists:** Related mailing lists provide a forum
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700438 for discussion, patch submission and announcements. There are several
439 mailing lists grouped by topic. See the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500440 :ref:`ref-manual/resources:mailing lists`
441 section in the Yocto Project Reference Manual for a complete list of
442 Yocto Project mailing lists.
443
444- **Comprehensive List of Links and Other Documentation:** The
445 :ref:`ref-manual/resources:links and related documentation`
446 section in the Yocto Project Reference Manual provides a
447 comprehensive list of all related links and other user documentation.
448
449.. include:: /boilerplate.rst