blob: 7ae0ddc349f2dc90c73ccdf007abd44ea7e6bc67 [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 Geissler615f2f12022-07-15 14:00:58 -050067 - GNU make &MIN_MAKE_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -050068
69If your build host does not meet any of these three listed version
70requirements, you can take steps to prepare the system so that you
71can still use the Yocto Project. See the
Andrew Geissler615f2f12022-07-15 14:00:58 -050072:ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050073section in the Yocto Project Reference Manual for information.
74
75Build Host Packages
76===================
77
78You must install essential host packages on your build host. The
79following command installs the host packages based on an Ubuntu
80distribution:
81
82.. code-block:: shell
83
Andrew Geisslereff27472021-10-29 15:35:00 -050084 $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
Andrew Geisslerc9f78652020-09-18 14:11:35 -050085
86.. note::
87
88 For host package requirements on all supported Linux distributions,
Andrew Geissler09209ee2020-12-13 08:44:15 -060089 see the :ref:`ref-manual/system-requirements:required packages for the build host`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050090 section in the Yocto Project Reference Manual.
91
92Use Git to Clone Poky
93=====================
94
95Once you complete the setup instructions for your machine, you need to
96get a copy of the Poky repository on your build host. Use the following
97commands to clone the Poky repository.
98
99.. code-block:: shell
100
101 $ git clone git://git.yoctoproject.org/poky
102 Cloning into 'poky'...
103 remote: Counting
104 objects: 432160, done. remote: Compressing objects: 100%
105 (102056/102056), done. remote: Total 432160 (delta 323116), reused
106 432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
107 Resolving deltas: 100% (323116/323116), done.
108 Checking connectivity... done.
109
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500110Go to :yocto_wiki:`Releases wiki page </Releases>`, and choose a release
111codename (such as ``&DISTRO_NAME_NO_CAP;``), corresponding to either the
112latest stable release or a Long Term Support release.
113
114Then move to the ``poky`` directory and take a look at existing branches:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500115
116.. code-block:: shell
117
118 $ cd poky
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500119 $ git branch -a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500120 .
121 .
122 .
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500123 remotes/origin/HEAD -> origin/master
124 remotes/origin/dunfell
125 remotes/origin/dunfell-next
126 .
127 .
128 .
129 remotes/origin/gatesgarth
130 remotes/origin/gatesgarth-next
131 .
132 .
133 .
134 remotes/origin/master
135 remotes/origin/master-next
136 .
137 .
138 .
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500139
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500140
141For this example, check out the ``&DISTRO_NAME_NO_CAP;`` branch based on the
142``&DISTRO_NAME;`` release:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500143
144.. code-block:: shell
145
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500146 $ git checkout -t origin/&DISTRO_NAME_NO_CAP; -b my-&DISTRO_NAME_NO_CAP;
147 Branch 'my-&DISTRO_NAME_NO_CAP;' set up to track remote branch '&DISTRO_NAME_NO_CAP;' from 'origin'.
148 Switched to a new branch 'my-&DISTRO_NAME_NO_CAP;'
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500149
150The previous Git checkout command creates a local branch named
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500151``my-&DISTRO_NAME_NO_CAP;``. The files available to you in that branch
152exactly match the repository's files in the ``&DISTRO_NAME_NO_CAP;``
153release branch.
154
155Note that you can regularly type the following command in the same directory
156to keep your local files in sync with the release branch:
157
158.. code-block:: shell
159
160 $ git pull
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500161
162For more options and information about accessing Yocto Project related
163repositories, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600164:ref:`dev-manual/start:locating yocto project source files`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500165section in the Yocto Project Development Tasks Manual.
166
167Building Your Image
168===================
169
170Use the following steps to build your image. The build process creates
171an entire Linux distribution, including the toolchain, from source.
172
173.. note::
174
175 - If you are working behind a firewall and your build host is not
176 set up for proxies, you could encounter problems with the build
177 process when fetching source code (e.g. fetcher failures or Git
178 failures).
179
180 - If you do not know your proxy settings, consult your local network
181 infrastructure resources and get that information. A good starting
182 point could also be to check your web browser settings. Finally,
183 you can find more information on the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600184 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500185 page of the Yocto Project Wiki.
186
187#. **Initialize the Build Environment:** From within the ``poky``
Andrew Geissler09209ee2020-12-13 08:44:15 -0600188 directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500189 environment
190 setup script to define Yocto Project's build environment on your
191 build host.
192
193 .. code-block:: shell
194
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500195 $ cd poky
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500196 $ source oe-init-build-env
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500197 You had no conf/local.conf file. This configuration file has therefore been
198 created for you with some default values. You may wish to edit it to, for
199 example, select a different MACHINE (target hardware). See conf/local.conf
200 for more information as common configuration options are commented.
201
202 You had no conf/bblayers.conf file. This configuration file has therefore
203 been created for you with some default values. To add additional metadata
204 layers into your configuration please add entries to conf/bblayers.conf.
205
206 The Yocto Project has extensive documentation about OE including a reference
207 manual which can be found at:
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500208 https://docs.yoctoproject.org
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500209
210 For more information about OpenEmbedded see their website:
Patrick Williams213cb262021-08-07 19:21:33 -0500211 https://www.openembedded.org/
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500212
213 ### Shell environment set up for builds. ###
214
215 You can now run 'bitbake <target>'
216
217 Common targets are:
218 core-image-minimal
Patrick Williams213cb262021-08-07 19:21:33 -0500219 core-image-full-cmdline
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500220 core-image-sato
Patrick Williams213cb262021-08-07 19:21:33 -0500221 core-image-weston
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500222 meta-toolchain
223 meta-ide-support
224
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500225 You can also run generated QEMU images with a command like 'runqemu qemux86-64'
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500226
Patrick Williams213cb262021-08-07 19:21:33 -0500227 Other commonly useful commands are:
228 - 'devtool' and 'recipetool' handle common recipe tasks
229 - 'bitbake-layers' handles common layer tasks
230 - 'oe-pkgdata-util' handles common target package tasks
231
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500232 Among other things, the script creates the :term:`Build Directory`, which is
233 ``build`` in this case and is located in the :term:`Source Directory`. After
234 the script runs, your current working directory is set to the Build
235 Directory. Later, when the build completes, the Build Directory contains all the
236 files created during the build.
237
238#. **Examine Your Local Configuration File:** When you set up the build
239 environment, a local configuration file named ``local.conf`` becomes
240 available in a ``conf`` subdirectory of the Build Directory. For this
241 example, the defaults are set to build for a ``qemux86`` target,
242 which is suitable for emulation. The package manager used is set to
243 the RPM package manager.
244
245 .. tip::
246
247 You can significantly speed up your build and guard against fetcher
Andrew Geissler595f6302022-01-24 19:11:47 +0000248 failures by using :ref:`overview-manual/concepts:shared state cache`
249 mirrors and enabling :ref:`overview-manual/concepts:hash equivalence`.
250 This way, you can use pre-built artifacts rather than building them.
251 This is relevant only when your network and the server that you use
252 can download these artifacts faster than you would be able to build them.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500253
Patrick Williams03907ee2022-05-01 06:28:52 -0500254 To use such mirrors, uncomment the below lines in your ``conf/local.conf``
Andrew Geissler595f6302022-01-24 19:11:47 +0000255 file in the :term:`Build Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500256
Andrew Geissler595f6302022-01-24 19:11:47 +0000257 BB_SIGNATURE_HANDLER = "OEEquivHash"
258 BB_HASHSERVE = "auto"
Patrick Williamsdb4c27e2022-08-05 08:10:29 -0500259 BB_HASHSERVE_UPSTREAM = "hashserv.yocto.io:8687"
Andrew Geissler615f2f12022-07-15 14:00:58 -0500260 SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500261
262#. **Start the Build:** Continue with the following command to build an OS
263 image for the target, which is ``core-image-sato`` in this example:
264
265 .. code-block:: shell
266
267 $ bitbake core-image-sato
268
269 For information on using the ``bitbake`` command, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600270 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and
Patrick Williams213cb262021-08-07 19:21:33 -0500271 Concepts Manual, or see
272 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command`
273 in the BitBake User Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500274
275#. **Simulate Your Image Using QEMU:** Once this particular image is
276 built, you can start QEMU, which is a Quick EMUlator that ships with
277 the Yocto Project:
278
279 .. code-block:: shell
280
281 $ runqemu qemux86-64
282
283 If you want to learn more about running QEMU, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600284 :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500285 the Yocto Project Development Tasks Manual.
286
287#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing
288 ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU.
289
290Customizing Your Build for Specific Hardware
291============================================
292
293So far, all you have done is quickly built an image suitable for
294emulation only. This section shows you how to customize your build for
295specific hardware by adding a hardware layer into the Yocto Project
296development environment.
297
298In general, layers are repositories that contain related sets of
299instructions and configurations that tell the Yocto Project what to do.
300Isolating related metadata into functionally specific layers facilitates
301modular development and makes it easier to reuse the layer metadata.
302
303.. note::
304
305 By convention, layer names start with the string "meta-".
306
307Follow these steps to add a hardware layer:
308
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700309#. **Find a Layer:** Many hardware layers are available. The Yocto Project
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500310 :yocto_git:`Source Repositories <>` has many hardware layers.
311 This example adds the
312 `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer.
313
314#. **Clone the Layer:** Use Git to make a local copy of the layer on your
315 machine. You can put the copy in the top level of the copy of the
316 Poky repository created earlier:
317
318 .. code-block:: shell
319
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500320 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500321 $ git clone https://github.com/kraj/meta-altera.git
322 Cloning into 'meta-altera'...
323 remote: Counting objects: 25170, done.
324 remote: Compressing objects: 100% (350/350), done.
325 remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
326 Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done.
327 Resolving deltas: 100% (13385/13385), done.
328 Checking connectivity... done.
329
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700330 The hardware layer is now available
331 next to other layers inside the Poky reference repository on your build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500332 host as ``meta-altera`` and contains all the metadata needed to
333 support hardware from Altera, which is owned by Intel.
334
335 .. note::
336
337 It is recommended for layers to have a branch per Yocto Project release.
338 Please make sure to checkout the layer branch supporting the Yocto Project
339 release you're using.
340
341#. **Change the Configuration to Build for a Specific Machine:** The
342 :term:`MACHINE` variable in the
343 ``local.conf`` file specifies the machine for the build. For this
Andrew Geissler09036742021-06-25 14:25:14 -0500344 example, set the :term:`MACHINE` variable to ``cyclone5``. These
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500345 configurations are used:
346 https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf.
347
348 .. note::
349
350 See the "Examine Your Local Configuration File" step earlier for more
351 information on configuring the build.
352
353#. **Add Your Layer to the Layer Configuration File:** Before you can use
354 a layer during a build, you must add it to your ``bblayers.conf``
355 file, which is found in the
356 :term:`Build Directory` ``conf``
357 directory.
358
359 Use the ``bitbake-layers add-layer`` command to add the layer to the
360 configuration file:
361
362 .. code-block:: shell
363
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500364 $ cd poky/build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500365 $ bitbake-layers add-layer ../meta-altera
366 NOTE: Starting bitbake server...
367 Parsing recipes: 100% |##################################################################| Time: 0:00:32
368 Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets,
369 123 skipped, 0 masked, 0 errors.
370
371 You can find
372 more information on adding layers in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600373 :ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500374 section.
375
376Completing these steps has added the ``meta-altera`` layer to your Yocto
377Project development environment and configured it to build for the
378``cyclone5`` machine.
379
380.. note::
381
382 The previous steps are for demonstration purposes only. If you were
383 to attempt to build an image for the ``cyclone5`` machine, you should
384 read the Altera ``README``.
385
386Creating Your Own General Layer
387===============================
388
389Maybe you have an application or specific set of behaviors you need to
390isolate. You can create your own general layer using the
391``bitbake-layers create-layer`` command. The tool automates layer
392creation by setting up a subdirectory with a ``layer.conf``
393configuration file, a ``recipes-example`` subdirectory that contains an
394``example.bb`` recipe, a licensing file, and a ``README``.
395
396The following commands run the tool to create a layer named
397``meta-mylayer`` in the ``poky`` directory:
398
399.. code-block:: shell
400
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500401 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500402 $ bitbake-layers create-layer meta-mylayer
403 NOTE: Starting bitbake server...
404 Add your new layer with 'bitbake-layers add-layer meta-mylayer'
405
406For more information
407on layers and how to create them, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600408:ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500409section in the Yocto Project Development Tasks Manual.
410
411Where To Go Next
412================
413
414Now that you have experienced using the Yocto Project, you might be
415asking yourself "What now?". The Yocto Project has many sources of
416information including the website, wiki pages, and user manuals:
417
418- **Website:** The :yocto_home:`Yocto Project Website <>` provides
419 background information, the latest builds, breaking news, full
420 development documentation, and access to a rich Yocto Project
421 Development Community into which you can tap.
422
Andrew Geisslerd5838332022-05-27 11:33:10 -0500423- **Video Seminar:** The `Introduction to the Yocto Project and BitBake, Part 1
Andrew Geissler9aee5002022-03-30 16:27:02 +0000424 <https://youtu.be/yuE7my3KOpo>`__ and
Andrew Geisslerd5838332022-05-27 11:33:10 -0500425 `Introduction to the Yocto Project and BitBake, Part 2
Andrew Geissler9aee5002022-03-30 16:27:02 +0000426 <https://youtu.be/iZ05TTyzGHk>`__ videos offer a video seminar
427 introducing you to the most important aspects of developing a
428 custom embedded Linux distribution with the Yocto Project.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500429
430- **Yocto Project Overview and Concepts Manual:** The
Andrew Geissler09209ee2020-12-13 08:44:15 -0600431 :doc:`/overview-manual/index` is a great
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500432 place to start to learn about the Yocto Project. This manual
433 introduces you to the Yocto Project and its development environment.
434 The manual also provides conceptual information for various aspects
435 of the Yocto Project.
436
437- **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>`
438 provides additional information on where to go next when ramping up
439 with the Yocto Project, release information, project planning, and QA
440 information.
441
442- **Yocto Project Mailing Lists:** Related mailing lists provide a forum
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700443 for discussion, patch submission and announcements. There are several
444 mailing lists grouped by topic. See the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500445 :ref:`ref-manual/resources:mailing lists`
446 section in the Yocto Project Reference Manual for a complete list of
447 Yocto Project mailing lists.
448
449- **Comprehensive List of Links and Other Documentation:** The
450 :ref:`ref-manual/resources:links and related documentation`
451 section in the Yocto Project Reference Manual provides a
452 comprehensive list of all related links and other user documentation.
453
454.. include:: /boilerplate.rst