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 1.8.3.1 or greater 64 - tar 1.28 or greater 65 - Python 3.5.0 or greater. 66 - gcc 5.0 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 109Move to the ``poky`` directory and take a look at the tags: 110 111.. code-block:: shell 112 113 $ cd poky 114 $ git fetch --tags 115 $ git tag 116 1.1_M1.final 117 1.1_M1.rc1 118 1.1_M1.rc2 119 1.1_M2.final 120 1.1_M2.rc1 121 . 122 . 123 . 124 yocto-2.5 125 yocto-2.5.1 126 yocto-2.5.2 127 yocto-2.6 128 yocto-2.6.1 129 yocto-2.6.2 130 yocto-2.7 131 yocto_1.5_M5.rc8 132 133For this example, check out the branch based on the 134``&DISTRO_REL_TAG;`` release: 135 136.. code-block:: shell 137 138 $ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG; 139 Switched to a new branch 'my-&DISTRO_REL_TAG;' 140 141The previous Git checkout command creates a local branch named 142``my-&DISTRO_REL_TAG;``. The files available to you in that branch exactly 143match the repository's files in the ``&DISTRO_NAME_NO_CAP;`` development 144branch at the time of the Yocto Project &DISTRO_REL_TAG; release. 145 146For more options and information about accessing Yocto Project related 147repositories, see the 148:ref:`dev-manual/start:locating yocto project source files` 149section in the Yocto Project Development Tasks Manual. 150 151Building Your Image 152=================== 153 154Use the following steps to build your image. The build process creates 155an entire Linux distribution, including the toolchain, from source. 156 157.. note:: 158 159 - If you are working behind a firewall and your build host is not 160 set up for proxies, you could encounter problems with the build 161 process when fetching source code (e.g. fetcher failures or Git 162 failures). 163 164 - If you do not know your proxy settings, consult your local network 165 infrastructure resources and get that information. A good starting 166 point could also be to check your web browser settings. Finally, 167 you can find more information on the 168 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 169 page of the Yocto Project Wiki. 170 171#. **Initialize the Build Environment:** From within the ``poky`` 172 directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` 173 environment 174 setup script to define Yocto Project's build environment on your 175 build host. 176 177 .. code-block:: shell 178 179 $ cd ~/poky 180 $ source oe-init-build-env 181 You had no conf/local.conf file. This configuration file has therefore been 182 created for you with some default values. You may wish to edit it to, for 183 example, select a different MACHINE (target hardware). See conf/local.conf 184 for more information as common configuration options are commented. 185 186 You had no conf/bblayers.conf file. This configuration file has therefore 187 been created for you with some default values. To add additional metadata 188 layers into your configuration please add entries to conf/bblayers.conf. 189 190 The Yocto Project has extensive documentation about OE including a reference 191 manual which can be found at: 192 http://yoctoproject.org/documentation 193 194 For more information about OpenEmbedded see their website: 195 http://www.openembedded.org/ 196 197 ### Shell environment set up for builds. ### 198 199 You can now run 'bitbake <target>' 200 201 Common targets are: 202 core-image-minimal 203 core-image-sato 204 meta-toolchain 205 meta-ide-support 206 207 You can also run generated qemu images with a command like 'runqemu qemux86-64' 208 209 Among other things, the script creates the :term:`Build Directory`, which is 210 ``build`` in this case and is located in the :term:`Source Directory`. After 211 the script runs, your current working directory is set to the Build 212 Directory. Later, when the build completes, the Build Directory contains all the 213 files created during the build. 214 215#. **Examine Your Local Configuration File:** When you set up the build 216 environment, a local configuration file named ``local.conf`` becomes 217 available in a ``conf`` subdirectory of the Build Directory. For this 218 example, the defaults are set to build for a ``qemux86`` target, 219 which is suitable for emulation. The package manager used is set to 220 the RPM package manager. 221 222 .. tip:: 223 224 You can significantly speed up your build and guard against fetcher 225 failures by using mirrors. To use mirrors, add these lines to your 226 local.conf file in the Build directory: :: 227 228 SSTATE_MIRRORS = "\ 229 file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \ 230 file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \ 231 file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \ 232 " 233 234 235 The previous examples showed how to add sstate paths for Yocto Project 236 &YOCTO_DOC_VERSION_MINUS_ONE;, &YOCTO_DOC_VERSION;, and a development 237 area. For a complete index of sstate locations, see http://sstate.yoctoproject.org/. 238 239#. **Start the Build:** Continue with the following command to build an OS 240 image for the target, which is ``core-image-sato`` in this example: 241 242 .. code-block:: shell 243 244 $ bitbake core-image-sato 245 246 For information on using the ``bitbake`` command, see the 247 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and 248 Concepts Manual, or see the ":ref:`BitBake Command 249 <bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command>`" section in the BitBake User Manual. 250 251#. **Simulate Your Image Using QEMU:** Once this particular image is 252 built, you can start QEMU, which is a Quick EMUlator that ships with 253 the Yocto Project: 254 255 .. code-block:: shell 256 257 $ runqemu qemux86-64 258 259 If you want to learn more about running QEMU, see the 260 :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in 261 the Yocto Project Development Tasks Manual. 262 263#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing 264 ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU. 265 266Customizing Your Build for Specific Hardware 267============================================ 268 269So far, all you have done is quickly built an image suitable for 270emulation only. This section shows you how to customize your build for 271specific hardware by adding a hardware layer into the Yocto Project 272development environment. 273 274In general, layers are repositories that contain related sets of 275instructions and configurations that tell the Yocto Project what to do. 276Isolating related metadata into functionally specific layers facilitates 277modular development and makes it easier to reuse the layer metadata. 278 279.. note:: 280 281 By convention, layer names start with the string "meta-". 282 283Follow these steps to add a hardware layer: 284 285#. **Find a Layer:** Lots of hardware layers exist. The Yocto Project 286 :yocto_git:`Source Repositories <>` has many hardware layers. 287 This example adds the 288 `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer. 289 290#. **Clone the Layer:** Use Git to make a local copy of the layer on your 291 machine. You can put the copy in the top level of the copy of the 292 Poky repository created earlier: 293 294 .. code-block:: shell 295 296 $ cd ~/poky 297 $ git clone https://github.com/kraj/meta-altera.git 298 Cloning into 'meta-altera'... 299 remote: Counting objects: 25170, done. 300 remote: Compressing objects: 100% (350/350), done. 301 remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219 302 Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done. 303 Resolving deltas: 100% (13385/13385), done. 304 Checking connectivity... done. 305 306 The hardware layer now exists 307 with other layers inside the Poky reference repository on your build 308 host as ``meta-altera`` and contains all the metadata needed to 309 support hardware from Altera, which is owned by Intel. 310 311 .. note:: 312 313 It is recommended for layers to have a branch per Yocto Project release. 314 Please make sure to checkout the layer branch supporting the Yocto Project 315 release you're using. 316 317#. **Change the Configuration to Build for a Specific Machine:** The 318 :term:`MACHINE` variable in the 319 ``local.conf`` file specifies the machine for the build. For this 320 example, set the ``MACHINE`` variable to ``cyclone5``. These 321 configurations are used: 322 https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf. 323 324 .. note:: 325 326 See the "Examine Your Local Configuration File" step earlier for more 327 information on configuring the build. 328 329#. **Add Your Layer to the Layer Configuration File:** Before you can use 330 a layer during a build, you must add it to your ``bblayers.conf`` 331 file, which is found in the 332 :term:`Build Directory` ``conf`` 333 directory. 334 335 Use the ``bitbake-layers add-layer`` command to add the layer to the 336 configuration file: 337 338 .. code-block:: shell 339 340 $ cd ~/poky/build 341 $ bitbake-layers add-layer ../meta-altera 342 NOTE: Starting bitbake server... 343 Parsing recipes: 100% |##################################################################| Time: 0:00:32 344 Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets, 345 123 skipped, 0 masked, 0 errors. 346 347 You can find 348 more information on adding layers in the 349 :ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script` 350 section. 351 352Completing these steps has added the ``meta-altera`` layer to your Yocto 353Project development environment and configured it to build for the 354``cyclone5`` machine. 355 356.. note:: 357 358 The previous steps are for demonstration purposes only. If you were 359 to attempt to build an image for the ``cyclone5`` machine, you should 360 read the Altera ``README``. 361 362Creating Your Own General Layer 363=============================== 364 365Maybe you have an application or specific set of behaviors you need to 366isolate. You can create your own general layer using the 367``bitbake-layers create-layer`` command. The tool automates layer 368creation by setting up a subdirectory with a ``layer.conf`` 369configuration file, a ``recipes-example`` subdirectory that contains an 370``example.bb`` recipe, a licensing file, and a ``README``. 371 372The following commands run the tool to create a layer named 373``meta-mylayer`` in the ``poky`` directory: 374 375.. code-block:: shell 376 377 $ cd ~/poky 378 $ bitbake-layers create-layer meta-mylayer 379 NOTE: Starting bitbake server... 380 Add your new layer with 'bitbake-layers add-layer meta-mylayer' 381 382For more information 383on layers and how to create them, see the 384:ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script` 385section in the Yocto Project Development Tasks Manual. 386 387Where To Go Next 388================ 389 390Now that you have experienced using the Yocto Project, you might be 391asking yourself "What now?". The Yocto Project has many sources of 392information including the website, wiki pages, and user manuals: 393 394- **Website:** The :yocto_home:`Yocto Project Website <>` provides 395 background information, the latest builds, breaking news, full 396 development documentation, and access to a rich Yocto Project 397 Development Community into which you can tap. 398 399- **Developer Screencast:** The `Getting Started with the Yocto Project - 400 New Developer Screencast Tutorial <https://vimeo.com/36450321>`__ 401 provides a 30-minute video created for users unfamiliar with the 402 Yocto Project but familiar with Linux build hosts. While this 403 screencast is somewhat dated, the introductory and fundamental 404 concepts are useful for the beginner. 405 406- **Yocto Project Overview and Concepts Manual:** The 407 :doc:`/overview-manual/index` is a great 408 place to start to learn about the Yocto Project. This manual 409 introduces you to the Yocto Project and its development environment. 410 The manual also provides conceptual information for various aspects 411 of the Yocto Project. 412 413- **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>` 414 provides additional information on where to go next when ramping up 415 with the Yocto Project, release information, project planning, and QA 416 information. 417 418- **Yocto Project Mailing Lists:** Related mailing lists provide a forum 419 for discussion, patch submission and announcements. Several mailing 420 lists exist and are grouped according to areas of concern. See the 421 :ref:`ref-manual/resources:mailing lists` 422 section in the Yocto Project Reference Manual for a complete list of 423 Yocto Project mailing lists. 424 425- **Comprehensive List of Links and Other Documentation:** The 426 :ref:`ref-manual/resources:links and related documentation` 427 section in the Yocto Project Reference Manual provides a 428 comprehensive list of all related links and other user documentation. 429 430.. include:: /boilerplate.rst 431