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 http://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-sato 219 meta-toolchain 220 meta-ide-support 221 222 You can also run generated QEMU images with a command like 'runqemu qemux86-64' 223 224 Among other things, the script creates the :term:`Build Directory`, which is 225 ``build`` in this case and is located in the :term:`Source Directory`. After 226 the script runs, your current working directory is set to the Build 227 Directory. Later, when the build completes, the Build Directory contains all the 228 files created during the build. 229 230#. **Examine Your Local Configuration File:** When you set up the build 231 environment, a local configuration file named ``local.conf`` becomes 232 available in a ``conf`` subdirectory of the Build Directory. For this 233 example, the defaults are set to build for a ``qemux86`` target, 234 which is suitable for emulation. The package manager used is set to 235 the RPM package manager. 236 237 .. tip:: 238 239 You can significantly speed up your build and guard against fetcher 240 failures by using mirrors. To use mirrors, add these lines to your 241 local.conf file in the Build directory:: 242 243 SSTATE_MIRRORS = "\ 244 file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \ 245 file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \ 246 file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \ 247 " 248 249 250 The previous examples showed how to add sstate paths for Yocto Project 251 &YOCTO_DOC_VERSION_MINUS_ONE;, &YOCTO_DOC_VERSION;, and a development 252 area. For a complete index of sstate locations, see http://sstate.yoctoproject.org/. 253 254#. **Start the Build:** Continue with the following command to build an OS 255 image for the target, which is ``core-image-sato`` in this example: 256 257 .. code-block:: shell 258 259 $ bitbake core-image-sato 260 261 For information on using the ``bitbake`` command, see the 262 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and 263 Concepts Manual, or see the ":ref:`BitBake Command 264 <bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command>`" section in the BitBake User Manual. 265 266#. **Simulate Your Image Using QEMU:** Once this particular image is 267 built, you can start QEMU, which is a Quick EMUlator that ships with 268 the Yocto Project: 269 270 .. code-block:: shell 271 272 $ runqemu qemux86-64 273 274 If you want to learn more about running QEMU, see the 275 :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in 276 the Yocto Project Development Tasks Manual. 277 278#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing 279 ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU. 280 281Customizing Your Build for Specific Hardware 282============================================ 283 284So far, all you have done is quickly built an image suitable for 285emulation only. This section shows you how to customize your build for 286specific hardware by adding a hardware layer into the Yocto Project 287development environment. 288 289In general, layers are repositories that contain related sets of 290instructions and configurations that tell the Yocto Project what to do. 291Isolating related metadata into functionally specific layers facilitates 292modular development and makes it easier to reuse the layer metadata. 293 294.. note:: 295 296 By convention, layer names start with the string "meta-". 297 298Follow these steps to add a hardware layer: 299 300#. **Find a Layer:** Many hardware layers are available. The Yocto Project 301 :yocto_git:`Source Repositories <>` has many hardware layers. 302 This example adds the 303 `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer. 304 305#. **Clone the Layer:** Use Git to make a local copy of the layer on your 306 machine. You can put the copy in the top level of the copy of the 307 Poky repository created earlier: 308 309 .. code-block:: shell 310 311 $ cd poky 312 $ git clone https://github.com/kraj/meta-altera.git 313 Cloning into 'meta-altera'... 314 remote: Counting objects: 25170, done. 315 remote: Compressing objects: 100% (350/350), done. 316 remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219 317 Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done. 318 Resolving deltas: 100% (13385/13385), done. 319 Checking connectivity... done. 320 321 The hardware layer is now available 322 next to other layers inside the Poky reference repository on your build 323 host as ``meta-altera`` and contains all the metadata needed to 324 support hardware from Altera, which is owned by Intel. 325 326 .. note:: 327 328 It is recommended for layers to have a branch per Yocto Project release. 329 Please make sure to checkout the layer branch supporting the Yocto Project 330 release you're using. 331 332#. **Change the Configuration to Build for a Specific Machine:** The 333 :term:`MACHINE` variable in the 334 ``local.conf`` file specifies the machine for the build. For this 335 example, set the ``MACHINE`` variable to ``cyclone5``. These 336 configurations are used: 337 https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf. 338 339 .. note:: 340 341 See the "Examine Your Local Configuration File" step earlier for more 342 information on configuring the build. 343 344#. **Add Your Layer to the Layer Configuration File:** Before you can use 345 a layer during a build, you must add it to your ``bblayers.conf`` 346 file, which is found in the 347 :term:`Build Directory` ``conf`` 348 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/common-tasks: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/common-tasks: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- **Developer Screencast:** The `Getting Started with the Yocto Project - 415 New Developer Screencast Tutorial <https://vimeo.com/36450321>`__ 416 provides a 30-minute video created for users unfamiliar with the 417 Yocto Project but familiar with Linux build hosts. While this 418 screencast is somewhat dated, the introductory and fundamental 419 concepts are useful for the beginner. 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