blob: cfdd14ae4ad92afda04242fcd14eae9300f68d22 [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
43- 50 Gbytes of free disk space
44
45- Runs a supported Linux distribution (i.e. recent releases of Fedora,
46 openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux
47 distributions that support the Yocto Project, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060048 :ref:`ref-manual/system-requirements:supported linux distributions`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050049 section in the Yocto Project Reference Manual. For detailed
50 information on preparing your build host, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060051 :ref:`dev-manual/start:preparing the build host`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050052 section in the Yocto Project Development Tasks Manual.
53
54-
55
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050056 - Git &MIN_GIT_VERSION; or greater
57 - tar &MIN_TAR_VERSION; or greater
58 - Python &MIN_PYTHON_VERSION; or greater.
59 - gcc &MIN_GCC_VERSION; or greater.
Andrew Geissler615f2f12022-07-15 14:00:58 -050060 - GNU make &MIN_MAKE_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -050061
62If your build host does not meet any of these three listed version
63requirements, you can take steps to prepare the system so that you
64can still use the Yocto Project. See the
Andrew Geissler615f2f12022-07-15 14:00:58 -050065:ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050066section in the Yocto Project Reference Manual for information.
67
68Build Host Packages
69===================
70
71You must install essential host packages on your build host. The
72following command installs the host packages based on an Ubuntu
73distribution:
74
75.. code-block:: shell
76
Andrew Geisslereff27472021-10-29 15:35:00 -050077 $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
Andrew Geisslerc9f78652020-09-18 14:11:35 -050078
79.. note::
80
81 For host package requirements on all supported Linux distributions,
Andrew Geissler09209ee2020-12-13 08:44:15 -060082 see the :ref:`ref-manual/system-requirements:required packages for the build host`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050083 section in the Yocto Project Reference Manual.
84
85Use Git to Clone Poky
86=====================
87
88Once you complete the setup instructions for your machine, you need to
89get a copy of the Poky repository on your build host. Use the following
90commands to clone the Poky repository.
91
92.. code-block:: shell
93
94 $ git clone git://git.yoctoproject.org/poky
95 Cloning into 'poky'...
96 remote: Counting
97 objects: 432160, done. remote: Compressing objects: 100%
98 (102056/102056), done. remote: Total 432160 (delta 323116), reused
99 432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
100 Resolving deltas: 100% (323116/323116), done.
101 Checking connectivity... done.
102
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500103Go to :yocto_wiki:`Releases wiki page </Releases>`, and choose a release
104codename (such as ``&DISTRO_NAME_NO_CAP;``), corresponding to either the
105latest stable release or a Long Term Support release.
106
107Then move to the ``poky`` directory and take a look at existing branches:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500108
109.. code-block:: shell
110
111 $ cd poky
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500112 $ git branch -a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500113 .
114 .
115 .
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500116 remotes/origin/HEAD -> origin/master
117 remotes/origin/dunfell
118 remotes/origin/dunfell-next
119 .
120 .
121 .
122 remotes/origin/gatesgarth
123 remotes/origin/gatesgarth-next
124 .
125 .
126 .
127 remotes/origin/master
128 remotes/origin/master-next
129 .
130 .
131 .
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500132
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500133
134For this example, check out the ``&DISTRO_NAME_NO_CAP;`` branch based on the
135``&DISTRO_NAME;`` release:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500136
137.. code-block:: shell
138
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500139 $ git checkout -t origin/&DISTRO_NAME_NO_CAP; -b my-&DISTRO_NAME_NO_CAP;
140 Branch 'my-&DISTRO_NAME_NO_CAP;' set up to track remote branch '&DISTRO_NAME_NO_CAP;' from 'origin'.
141 Switched to a new branch 'my-&DISTRO_NAME_NO_CAP;'
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500142
143The previous Git checkout command creates a local branch named
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500144``my-&DISTRO_NAME_NO_CAP;``. The files available to you in that branch
145exactly match the repository's files in the ``&DISTRO_NAME_NO_CAP;``
146release branch.
147
148Note that you can regularly type the following command in the same directory
149to keep your local files in sync with the release branch:
150
151.. code-block:: shell
152
153 $ git pull
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500154
155For more options and information about accessing Yocto Project related
156repositories, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600157:ref:`dev-manual/start:locating yocto project source files`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500158section in the Yocto Project Development Tasks Manual.
159
160Building Your Image
161===================
162
163Use the following steps to build your image. The build process creates
164an entire Linux distribution, including the toolchain, from source.
165
166.. note::
167
168 - If you are working behind a firewall and your build host is not
169 set up for proxies, you could encounter problems with the build
170 process when fetching source code (e.g. fetcher failures or Git
171 failures).
172
173 - If you do not know your proxy settings, consult your local network
174 infrastructure resources and get that information. A good starting
175 point could also be to check your web browser settings. Finally,
176 you can find more information on the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600177 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500178 page of the Yocto Project Wiki.
179
180#. **Initialize the Build Environment:** From within the ``poky``
Andrew Geissler09209ee2020-12-13 08:44:15 -0600181 directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500182 environment
183 setup script to define Yocto Project's build environment on your
184 build host.
185
186 .. code-block:: shell
187
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500188 $ cd poky
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500189 $ source oe-init-build-env
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500190 You had no conf/local.conf file. This configuration file has therefore been
191 created for you with some default values. You may wish to edit it to, for
192 example, select a different MACHINE (target hardware). See conf/local.conf
193 for more information as common configuration options are commented.
194
195 You had no conf/bblayers.conf file. This configuration file has therefore
196 been created for you with some default values. To add additional metadata
197 layers into your configuration please add entries to conf/bblayers.conf.
198
199 The Yocto Project has extensive documentation about OE including a reference
200 manual which can be found at:
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500201 https://docs.yoctoproject.org
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500202
203 For more information about OpenEmbedded see their website:
Patrick Williams213cb262021-08-07 19:21:33 -0500204 https://www.openembedded.org/
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500205
206 ### Shell environment set up for builds. ###
207
208 You can now run 'bitbake <target>'
209
210 Common targets are:
211 core-image-minimal
Patrick Williams213cb262021-08-07 19:21:33 -0500212 core-image-full-cmdline
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500213 core-image-sato
Patrick Williams213cb262021-08-07 19:21:33 -0500214 core-image-weston
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500215 meta-toolchain
216 meta-ide-support
217
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500218 You can also run generated QEMU images with a command like 'runqemu qemux86-64'
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500219
Patrick Williams213cb262021-08-07 19:21:33 -0500220 Other commonly useful commands are:
221 - 'devtool' and 'recipetool' handle common recipe tasks
222 - 'bitbake-layers' handles common layer tasks
223 - 'oe-pkgdata-util' handles common target package tasks
224
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500225 Among other things, the script creates the :term:`Build Directory`, which is
226 ``build`` in this case and is located in the :term:`Source Directory`. After
Patrick Williams2390b1b2022-11-03 13:47:49 -0500227 the script runs, your current working directory is set to the
228 :term:`Build Directory`. Later, when the build completes, the
229 :term:`Build Directory` contains all the files created during the build.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500230
231#. **Examine Your Local Configuration File:** When you set up the build
232 environment, a local configuration file named ``local.conf`` becomes
Patrick Williams2390b1b2022-11-03 13:47:49 -0500233 available in a ``conf`` subdirectory of the :term:`Build Directory`. For this
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500234 example, the defaults are set to build for a ``qemux86`` target,
235 which is suitable for emulation. The package manager used is set to
236 the RPM package manager.
237
238 .. tip::
239
240 You can significantly speed up your build and guard against fetcher
Andrew Geissler595f6302022-01-24 19:11:47 +0000241 failures by using :ref:`overview-manual/concepts:shared state cache`
242 mirrors and enabling :ref:`overview-manual/concepts:hash equivalence`.
243 This way, you can use pre-built artifacts rather than building them.
244 This is relevant only when your network and the server that you use
245 can download these artifacts faster than you would be able to build them.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500246
Patrick Williams03907ee2022-05-01 06:28:52 -0500247 To use such mirrors, uncomment the below lines in your ``conf/local.conf``
Andrew Geissler595f6302022-01-24 19:11:47 +0000248 file in the :term:`Build Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500249
Andrew Geissler595f6302022-01-24 19:11:47 +0000250 BB_SIGNATURE_HANDLER = "OEEquivHash"
251 BB_HASHSERVE = "auto"
Patrick Williamsdb4c27e2022-08-05 08:10:29 -0500252 BB_HASHSERVE_UPSTREAM = "hashserv.yocto.io:8687"
Andrew Geissler615f2f12022-07-15 14:00:58 -0500253 SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500254
255#. **Start the Build:** Continue with the following command to build an OS
256 image for the target, which is ``core-image-sato`` in this example:
257
258 .. code-block:: shell
259
260 $ bitbake core-image-sato
261
262 For information on using the ``bitbake`` command, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600263 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and
Patrick Williams213cb262021-08-07 19:21:33 -0500264 Concepts Manual, or see
265 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command`
266 in the BitBake User Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500267
268#. **Simulate Your Image Using QEMU:** Once this particular image is
269 built, you can start QEMU, which is a Quick EMUlator that ships with
270 the Yocto Project:
271
272 .. code-block:: shell
273
274 $ runqemu qemux86-64
275
276 If you want to learn more about running QEMU, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600277 :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500278 the Yocto Project Development Tasks Manual.
279
280#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing
281 ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU.
282
283Customizing Your Build for Specific Hardware
284============================================
285
286So far, all you have done is quickly built an image suitable for
287emulation only. This section shows you how to customize your build for
288specific hardware by adding a hardware layer into the Yocto Project
289development environment.
290
291In general, layers are repositories that contain related sets of
292instructions and configurations that tell the Yocto Project what to do.
293Isolating related metadata into functionally specific layers facilitates
294modular development and makes it easier to reuse the layer metadata.
295
296.. note::
297
298 By convention, layer names start with the string "meta-".
299
300Follow these steps to add a hardware layer:
301
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700302#. **Find a Layer:** Many hardware layers are available. The Yocto Project
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500303 :yocto_git:`Source Repositories <>` has many hardware layers.
304 This example adds the
305 `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer.
306
307#. **Clone the Layer:** Use Git to make a local copy of the layer on your
308 machine. You can put the copy in the top level of the copy of the
309 Poky repository created earlier:
310
311 .. code-block:: shell
312
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500313 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500314 $ git clone https://github.com/kraj/meta-altera.git
315 Cloning into 'meta-altera'...
316 remote: Counting objects: 25170, done.
317 remote: Compressing objects: 100% (350/350), done.
318 remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
319 Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done.
320 Resolving deltas: 100% (13385/13385), done.
321 Checking connectivity... done.
322
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700323 The hardware layer is now available
324 next to other layers inside the Poky reference repository on your build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500325 host as ``meta-altera`` and contains all the metadata needed to
326 support hardware from Altera, which is owned by Intel.
327
328 .. note::
329
330 It is recommended for layers to have a branch per Yocto Project release.
331 Please make sure to checkout the layer branch supporting the Yocto Project
332 release you're using.
333
334#. **Change the Configuration to Build for a Specific Machine:** The
335 :term:`MACHINE` variable in the
336 ``local.conf`` file specifies the machine for the build. For this
Andrew Geissler09036742021-06-25 14:25:14 -0500337 example, set the :term:`MACHINE` variable to ``cyclone5``. These
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500338 configurations are used:
339 https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf.
340
341 .. note::
342
343 See the "Examine Your Local Configuration File" step earlier for more
344 information on configuring the build.
345
346#. **Add Your Layer to the Layer Configuration File:** Before you can use
347 a layer during a build, you must add it to your ``bblayers.conf``
Patrick Williams2390b1b2022-11-03 13:47:49 -0500348 file, which is found in the :term:`Build Directory` ``conf`` directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500349
350 Use the ``bitbake-layers add-layer`` command to add the layer to the
351 configuration file:
352
353 .. code-block:: shell
354
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500355 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500356 $ bitbake-layers add-layer ../meta-altera
357 NOTE: Starting bitbake server...
358 Parsing recipes: 100% |##################################################################| Time: 0:00:32
359 Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets,
360 123 skipped, 0 masked, 0 errors.
361
362 You can find
363 more information on adding layers in the
Andrew Geissler517393d2023-01-13 08:55:19 -0600364 :ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500365 section.
366
367Completing these steps has added the ``meta-altera`` layer to your Yocto
368Project development environment and configured it to build for the
369``cyclone5`` machine.
370
371.. note::
372
373 The previous steps are for demonstration purposes only. If you were
374 to attempt to build an image for the ``cyclone5`` machine, you should
375 read the Altera ``README``.
376
377Creating Your Own General Layer
378===============================
379
380Maybe you have an application or specific set of behaviors you need to
381isolate. You can create your own general layer using the
382``bitbake-layers create-layer`` command. The tool automates layer
383creation by setting up a subdirectory with a ``layer.conf``
384configuration file, a ``recipes-example`` subdirectory that contains an
385``example.bb`` recipe, a licensing file, and a ``README``.
386
387The following commands run the tool to create a layer named
388``meta-mylayer`` in the ``poky`` directory:
389
390.. code-block:: shell
391
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500392 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500393 $ bitbake-layers create-layer meta-mylayer
394 NOTE: Starting bitbake server...
395 Add your new layer with 'bitbake-layers add-layer meta-mylayer'
396
397For more information
398on layers and how to create them, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600399:ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500400section in the Yocto Project Development Tasks Manual.
401
402Where To Go Next
403================
404
405Now that you have experienced using the Yocto Project, you might be
406asking yourself "What now?". The Yocto Project has many sources of
407information including the website, wiki pages, and user manuals:
408
409- **Website:** The :yocto_home:`Yocto Project Website <>` provides
410 background information, the latest builds, breaking news, full
411 development documentation, and access to a rich Yocto Project
412 Development Community into which you can tap.
413
Andrew Geisslerd5838332022-05-27 11:33:10 -0500414- **Video Seminar:** The `Introduction to the Yocto Project and BitBake, Part 1
Andrew Geissler9aee5002022-03-30 16:27:02 +0000415 <https://youtu.be/yuE7my3KOpo>`__ and
Andrew Geisslerd5838332022-05-27 11:33:10 -0500416 `Introduction to the Yocto Project and BitBake, Part 2
Andrew Geissler9aee5002022-03-30 16:27:02 +0000417 <https://youtu.be/iZ05TTyzGHk>`__ videos offer a video seminar
418 introducing you to the most important aspects of developing a
419 custom embedded Linux distribution with the Yocto Project.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500420
421- **Yocto Project Overview and Concepts Manual:** The
Andrew Geissler09209ee2020-12-13 08:44:15 -0600422 :doc:`/overview-manual/index` is a great
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500423 place to start to learn about the Yocto Project. This manual
424 introduces you to the Yocto Project and its development environment.
425 The manual also provides conceptual information for various aspects
426 of the Yocto Project.
427
428- **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>`
429 provides additional information on where to go next when ramping up
430 with the Yocto Project, release information, project planning, and QA
431 information.
432
433- **Yocto Project Mailing Lists:** Related mailing lists provide a forum
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700434 for discussion, patch submission and announcements. There are several
435 mailing lists grouped by topic. See the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500436 :ref:`ref-manual/resources:mailing lists`
437 section in the Yocto Project Reference Manual for a complete list of
438 Yocto Project mailing lists.
439
440- **Comprehensive List of Links and Other Documentation:** The
441 :ref:`ref-manual/resources:links and related documentation`
442 section in the Yocto Project Reference Manual provides a
443 comprehensive list of all related links and other user documentation.
444
445.. include:: /boilerplate.rst