1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 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 23 :ref:`dev-manual/start:setting up to use cross platforms (crops)` 24 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 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 41If you want more conceptual or background information on the Yocto 42Project, see the :doc:`/overview-manual/index`. 43 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 55 :ref:`ref-manual/system-requirements:supported linux distributions` 56 section in the Yocto Project Reference Manual. For detailed 57 information on preparing your build host, see the 58 :ref:`dev-manual/start:preparing the build host` 59 section in the Yocto Project Development Tasks Manual. 60 61- 62 63 - 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. 67 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 71:ref:`ref-manual/system-requirements:required git, tar, python and gcc versions` 72section 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 83 $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL; 84 85.. note:: 86 87 For host package requirements on all supported Linux distributions, 88 see the :ref:`ref-manual/system-requirements:required packages for the build host` 89 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 109Go 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: 114 115.. code-block:: shell 116 117 $ cd poky 118 $ git branch -a 119 . 120 . 121 . 122 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 . 138 139 140For this example, check out the ``&DISTRO_NAME_NO_CAP;`` branch based on the 141``&DISTRO_NAME;`` release: 142 143.. code-block:: shell 144 145 $ 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;' 148 149The previous Git checkout command creates a local branch named 150``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 160 161For more options and information about accessing Yocto Project related 162repositories, see the 163:ref:`dev-manual/start:locating yocto project source files` 164section 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 183 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 184 page of the Yocto Project Wiki. 185 186#. **Initialize the Build Environment:** From within the ``poky`` 187 directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` 188 environment 189 setup script to define Yocto Project's build environment on your 190 build host. 191 192 .. code-block:: shell 193 194 $ cd poky 195 $ source oe-init-build-env 196 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: 207 https://docs.yoctoproject.org 208 209 For more information about OpenEmbedded see their website: 210 https://www.openembedded.org/ 211 212 ### Shell environment set up for builds. ### 213 214 You can now run 'bitbake <target>' 215 216 Common targets are: 217 core-image-minimal 218 core-image-full-cmdline 219 core-image-sato 220 core-image-weston 221 meta-toolchain 222 meta-ide-support 223 224 You can also run generated QEMU images with a command like 'runqemu qemux86-64' 225 226 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 231 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 247 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. 252 253 To use such mirrors, uncomment the below lines in your ``local.conf`` 254 file in the :term:`Build Directory`:: 255 256 BB_SIGNATURE_HANDLER = "OEEquivHash" 257 BB_HASHSERVE = "auto" 258 BB_HASHSERVE_UPSTREAM = "typhoon.yocto.io:8687" 259 SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH" 260 261 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 264 SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH" 265 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 274 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and 275 Concepts Manual, or see 276 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command` 277 in the BitBake User Manual. 278 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 288 :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in 289 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 313#. **Find a Layer:** Many hardware layers are available. The Yocto Project 314 :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 324 $ cd poky 325 $ 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 334 The hardware layer is now available 335 next to other layers inside the Poky reference repository on your build 336 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 348 example, set the :term:`MACHINE` variable to ``cyclone5``. These 349 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 368 $ cd poky/build 369 $ 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 377 :ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script` 378 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 405 $ cd poky 406 $ 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 412:ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script` 413section 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 427- **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. 433 434- **Yocto Project Overview and Concepts Manual:** The 435 :doc:`/overview-manual/index` is a great 436 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 447 for discussion, patch submission and announcements. There are several 448 mailing lists grouped by topic. See the 449 :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 459