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 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. 33 34If you want more conceptual or background information on the Yocto 35Project, see the :doc:`/overview-manual/index`. 36 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 48 :ref:`ref-manual/system-requirements:supported linux distributions` 49 section in the Yocto Project Reference Manual. For detailed 50 information on preparing your build host, see the 51 :ref:`dev-manual/start:preparing the build host` 52 section in the Yocto Project Development Tasks Manual. 53 54- 55 56 - 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. 60 - GNU make &MIN_MAKE_VERSION; or greater 61 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 65:ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions` 66section 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 77 $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL; 78 79.. note:: 80 81 For host package requirements on all supported Linux distributions, 82 see the :ref:`ref-manual/system-requirements:required packages for the build host` 83 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 103Go 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: 108 109.. code-block:: shell 110 111 $ cd poky 112 $ git branch -a 113 . 114 . 115 . 116 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 . 132 133 134For this example, check out the ``&DISTRO_NAME_NO_CAP;`` branch based on the 135``&DISTRO_NAME;`` release: 136 137.. code-block:: shell 138 139 $ 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;' 142 143The previous Git checkout command creates a local branch named 144``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 154 155For more options and information about accessing Yocto Project related 156repositories, see the 157:ref:`dev-manual/start:locating yocto project source files` 158section 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 177 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 178 page of the Yocto Project Wiki. 179 180#. **Initialize the Build Environment:** From within the ``poky`` 181 directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` 182 environment 183 setup script to define Yocto Project's build environment on your 184 build host. 185 186 .. code-block:: shell 187 188 $ cd poky 189 $ source oe-init-build-env 190 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: 201 https://docs.yoctoproject.org 202 203 For more information about OpenEmbedded see their website: 204 https://www.openembedded.org/ 205 206 ### Shell environment set up for builds. ### 207 208 You can now run 'bitbake <target>' 209 210 Common targets are: 211 core-image-minimal 212 core-image-full-cmdline 213 core-image-sato 214 core-image-weston 215 meta-toolchain 216 meta-ide-support 217 218 You can also run generated QEMU images with a command like 'runqemu qemux86-64' 219 220 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 225 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 227 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. 230 231#. **Examine Your Local Configuration File:** When you set up the build 232 environment, a local configuration file named ``local.conf`` becomes 233 available in a ``conf`` subdirectory of the :term:`Build Directory`. For this 234 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 241 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. 246 247 To use such mirrors, uncomment the below lines in your ``conf/local.conf`` 248 file in the :term:`Build Directory`:: 249 250 BB_SIGNATURE_HANDLER = "OEEquivHash" 251 BB_HASHSERVE = "auto" 252 BB_HASHSERVE_UPSTREAM = "hashserv.yocto.io:8687" 253 SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH" 254 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 263 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and 264 Concepts Manual, or see 265 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command` 266 in the BitBake User Manual. 267 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 277 :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in 278 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 302#. **Find a Layer:** Many hardware layers are available. The Yocto Project 303 :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 313 $ cd poky 314 $ 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 323 The hardware layer is now available 324 next to other layers inside the Poky reference repository on your build 325 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 337 example, set the :term:`MACHINE` variable to ``cyclone5``. These 338 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`` 348 file, which is found in the :term:`Build Directory` ``conf`` directory. 349 350 Use the ``bitbake-layers add-layer`` command to add the layer to the 351 configuration file: 352 353 .. code-block:: shell 354 355 $ cd poky/build 356 $ 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 364 :ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script` 365 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 392 $ cd poky 393 $ 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 399:ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script` 400section 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 414- **Video Seminar:** The `Introduction to the Yocto Project and BitBake, Part 1 415 <https://youtu.be/yuE7my3KOpo>`__ and 416 `Introduction to the Yocto Project and BitBake, Part 2 417 <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. 420 421- **Yocto Project Overview and Concepts Manual:** The 422 :doc:`/overview-manual/index` is a great 423 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 434 for discussion, patch submission and announcements. There are several 435 mailing lists grouped by topic. See the 436 :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 446