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-get 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 mirrors. To use mirrors, add these lines to your 248 local.conf file in the Build directory:: 249 250 SSTATE_MIRRORS = "\ 251 file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \ 252 file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \ 253 file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \ 254 " 255 256 257 The previous examples showed how to add sstate paths for Yocto Project 258 &YOCTO_DOC_VERSION_MINUS_ONE;, &YOCTO_DOC_VERSION;, and a development 259 area. For a complete index of sstate locations, see http://sstate.yoctoproject.org/. 260 261#. **Start the Build:** Continue with the following command to build an OS 262 image for the target, which is ``core-image-sato`` in this example: 263 264 .. code-block:: shell 265 266 $ bitbake core-image-sato 267 268 For information on using the ``bitbake`` command, see the 269 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and 270 Concepts Manual, or see 271 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command` 272 in the BitBake User Manual. 273 274#. **Simulate Your Image Using QEMU:** Once this particular image is 275 built, you can start QEMU, which is a Quick EMUlator that ships with 276 the Yocto Project: 277 278 .. code-block:: shell 279 280 $ runqemu qemux86-64 281 282 If you want to learn more about running QEMU, see the 283 :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in 284 the Yocto Project Development Tasks Manual. 285 286#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing 287 ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU. 288 289Customizing Your Build for Specific Hardware 290============================================ 291 292So far, all you have done is quickly built an image suitable for 293emulation only. This section shows you how to customize your build for 294specific hardware by adding a hardware layer into the Yocto Project 295development environment. 296 297In general, layers are repositories that contain related sets of 298instructions and configurations that tell the Yocto Project what to do. 299Isolating related metadata into functionally specific layers facilitates 300modular development and makes it easier to reuse the layer metadata. 301 302.. note:: 303 304 By convention, layer names start with the string "meta-". 305 306Follow these steps to add a hardware layer: 307 308#. **Find a Layer:** Many hardware layers are available. The Yocto Project 309 :yocto_git:`Source Repositories <>` has many hardware layers. 310 This example adds the 311 `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer. 312 313#. **Clone the Layer:** Use Git to make a local copy of the layer on your 314 machine. You can put the copy in the top level of the copy of the 315 Poky repository created earlier: 316 317 .. code-block:: shell 318 319 $ cd poky 320 $ git clone https://github.com/kraj/meta-altera.git 321 Cloning into 'meta-altera'... 322 remote: Counting objects: 25170, done. 323 remote: Compressing objects: 100% (350/350), done. 324 remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219 325 Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done. 326 Resolving deltas: 100% (13385/13385), done. 327 Checking connectivity... done. 328 329 The hardware layer is now available 330 next to other layers inside the Poky reference repository on your build 331 host as ``meta-altera`` and contains all the metadata needed to 332 support hardware from Altera, which is owned by Intel. 333 334 .. note:: 335 336 It is recommended for layers to have a branch per Yocto Project release. 337 Please make sure to checkout the layer branch supporting the Yocto Project 338 release you're using. 339 340#. **Change the Configuration to Build for a Specific Machine:** The 341 :term:`MACHINE` variable in the 342 ``local.conf`` file specifies the machine for the build. For this 343 example, set the :term:`MACHINE` variable to ``cyclone5``. These 344 configurations are used: 345 https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf. 346 347 .. note:: 348 349 See the "Examine Your Local Configuration File" step earlier for more 350 information on configuring the build. 351 352#. **Add Your Layer to the Layer Configuration File:** Before you can use 353 a layer during a build, you must add it to your ``bblayers.conf`` 354 file, which is found in the 355 :term:`Build Directory` ``conf`` 356 directory. 357 358 Use the ``bitbake-layers add-layer`` command to add the layer to the 359 configuration file: 360 361 .. code-block:: shell 362 363 $ cd poky/build 364 $ bitbake-layers add-layer ../meta-altera 365 NOTE: Starting bitbake server... 366 Parsing recipes: 100% |##################################################################| Time: 0:00:32 367 Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets, 368 123 skipped, 0 masked, 0 errors. 369 370 You can find 371 more information on adding layers in the 372 :ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script` 373 section. 374 375Completing these steps has added the ``meta-altera`` layer to your Yocto 376Project development environment and configured it to build for the 377``cyclone5`` machine. 378 379.. note:: 380 381 The previous steps are for demonstration purposes only. If you were 382 to attempt to build an image for the ``cyclone5`` machine, you should 383 read the Altera ``README``. 384 385Creating Your Own General Layer 386=============================== 387 388Maybe you have an application or specific set of behaviors you need to 389isolate. You can create your own general layer using the 390``bitbake-layers create-layer`` command. The tool automates layer 391creation by setting up a subdirectory with a ``layer.conf`` 392configuration file, a ``recipes-example`` subdirectory that contains an 393``example.bb`` recipe, a licensing file, and a ``README``. 394 395The following commands run the tool to create a layer named 396``meta-mylayer`` in the ``poky`` directory: 397 398.. code-block:: shell 399 400 $ cd poky 401 $ bitbake-layers create-layer meta-mylayer 402 NOTE: Starting bitbake server... 403 Add your new layer with 'bitbake-layers add-layer meta-mylayer' 404 405For more information 406on layers and how to create them, see the 407:ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script` 408section in the Yocto Project Development Tasks Manual. 409 410Where To Go Next 411================ 412 413Now that you have experienced using the Yocto Project, you might be 414asking yourself "What now?". The Yocto Project has many sources of 415information including the website, wiki pages, and user manuals: 416 417- **Website:** The :yocto_home:`Yocto Project Website <>` provides 418 background information, the latest builds, breaking news, full 419 development documentation, and access to a rich Yocto Project 420 Development Community into which you can tap. 421 422- **Developer Screencast:** The `Getting Started with the Yocto Project - 423 New Developer Screencast Tutorial <https://vimeo.com/36450321>`__ 424 provides a 30-minute video created for users unfamiliar with the 425 Yocto Project but familiar with Linux build hosts. While this 426 screencast is somewhat dated, the introductory and fundamental 427 concepts are useful for the beginner. 428 429- **Yocto Project Overview and Concepts Manual:** The 430 :doc:`/overview-manual/index` is a great 431 place to start to learn about the Yocto Project. This manual 432 introduces you to the Yocto Project and its development environment. 433 The manual also provides conceptual information for various aspects 434 of the Yocto Project. 435 436- **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>` 437 provides additional information on where to go next when ramping up 438 with the Yocto Project, release information, project planning, and QA 439 information. 440 441- **Yocto Project Mailing Lists:** Related mailing lists provide a forum 442 for discussion, patch submission and announcements. There are several 443 mailing lists grouped by topic. See the 444 :ref:`ref-manual/resources:mailing lists` 445 section in the Yocto Project Reference Manual for a complete list of 446 Yocto Project mailing lists. 447 448- **Comprehensive List of Links and Other Documentation:** The 449 :ref:`ref-manual/resources:links and related documentation` 450 section in the Yocto Project Reference Manual provides a 451 comprehensive list of all related links and other user documentation. 452 453.. include:: /boilerplate.rst 454