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 - GNU make &MIN_MAKE_VERSION; or greater 68 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 72:ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions` 73section 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 84 $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL; 85 86.. note:: 87 88 For host package requirements on all supported Linux distributions, 89 see the :ref:`ref-manual/system-requirements:required packages for the build host` 90 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 110Go 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: 115 116.. code-block:: shell 117 118 $ cd poky 119 $ git branch -a 120 . 121 . 122 . 123 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 . 139 140 141For this example, check out the ``&DISTRO_NAME_NO_CAP;`` branch based on the 142``&DISTRO_NAME;`` release: 143 144.. code-block:: shell 145 146 $ 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;' 149 150The previous Git checkout command creates a local branch named 151``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 161 162For more options and information about accessing Yocto Project related 163repositories, see the 164:ref:`dev-manual/start:locating yocto project source files` 165section 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 184 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 185 page of the Yocto Project Wiki. 186 187#. **Initialize the Build Environment:** From within the ``poky`` 188 directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` 189 environment 190 setup script to define Yocto Project's build environment on your 191 build host. 192 193 .. code-block:: shell 194 195 $ cd poky 196 $ source oe-init-build-env 197 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: 208 https://docs.yoctoproject.org 209 210 For more information about OpenEmbedded see their website: 211 https://www.openembedded.org/ 212 213 ### Shell environment set up for builds. ### 214 215 You can now run 'bitbake <target>' 216 217 Common targets are: 218 core-image-minimal 219 core-image-full-cmdline 220 core-image-sato 221 core-image-weston 222 meta-toolchain 223 meta-ide-support 224 225 You can also run generated QEMU images with a command like 'runqemu qemux86-64' 226 227 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 232 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 248 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. 253 254 To use such mirrors, uncomment the below lines in your ``conf/local.conf`` 255 file in the :term:`Build Directory`:: 256 257 BB_SIGNATURE_HANDLER = "OEEquivHash" 258 BB_HASHSERVE = "auto" 259 BB_HASHSERVE_UPSTREAM = "hashserv.yocto.io:8687" 260 SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH" 261 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 270 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and 271 Concepts Manual, or see 272 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command` 273 in the BitBake User Manual. 274 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 284 :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in 285 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 309#. **Find a Layer:** Many hardware layers are available. The Yocto Project 310 :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 320 $ cd poky 321 $ 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 330 The hardware layer is now available 331 next to other layers inside the Poky reference repository on your build 332 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 344 example, set the :term:`MACHINE` variable to ``cyclone5``. These 345 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 364 $ cd poky/build 365 $ 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 373 :ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script` 374 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 401 $ cd poky 402 $ 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 408:ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script` 409section 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 423- **Video Seminar:** The `Introduction to the Yocto Project and BitBake, Part 1 424 <https://youtu.be/yuE7my3KOpo>`__ and 425 `Introduction to the Yocto Project and BitBake, Part 2 426 <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. 429 430- **Yocto Project Overview and Concepts Manual:** The 431 :doc:`/overview-manual/index` is a great 432 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 443 for discussion, patch submission and announcements. There are several 444 mailing lists grouped by topic. See the 445 :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 455