1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3*********************************** 4Setting Up to Use the Yocto Project 5*********************************** 6 7This chapter provides guidance on how to prepare to use the Yocto 8Project. You can learn about creating a team environment to develop 9using the Yocto Project, how to set up a :ref:`build 10host <dev-manual/start:preparing the build host>`, how to locate 11Yocto Project source repositories, and how to create local Git 12repositories. 13 14Creating a Team Development Environment 15======================================= 16 17It might not be immediately clear how you can use the Yocto Project in a 18team development environment, or how to scale it for a large team of 19developers. You can adapt the Yocto Project to many different use cases 20and scenarios; however, this flexibility could cause difficulties if you 21are trying to create a working setup that scales effectively. 22 23To help you understand how to set up this type of environment, this 24section presents a procedure that gives you information that can help 25you get the results you want. The procedure is high-level and presents 26some of the project's most successful experiences, practices, solutions, 27and available technologies that have proved to work well in the past; 28however, keep in mind, the procedure here is simply a starting point. 29You can build off these steps and customize the procedure to fit any 30particular working environment and set of practices. 31 321. *Determine Who is Going to be Developing:* You first need to 33 understand who is going to be doing anything related to the Yocto 34 Project and determine their roles. Making this determination is 35 essential to completing subsequent steps, which are to get your 36 equipment together and set up your development environment's 37 hardware topology. 38 39 Here are possible roles: 40 41 - *Application Developer:* This type of developer does application 42 level work on top of an existing software stack. 43 44 - *Core System Developer:* This type of developer works on the 45 contents of the operating system image itself. 46 47 - *Build Engineer:* This type of developer manages Autobuilders and 48 releases. Depending on the specifics of the environment, not all 49 situations might need a Build Engineer. 50 51 - *Test Engineer:* This type of developer creates and manages 52 automated tests that are used to ensure all application and core 53 system development meets desired quality standards. 54 552. *Gather the Hardware:* Based on the size and make-up of the team, 56 get the hardware together. Ideally, any development, build, or test 57 engineer uses a system that runs a supported Linux distribution. 58 These systems, in general, should be high performance (e.g. dual, 59 six-core Xeons with 24 Gbytes of RAM and plenty of disk space). You 60 can help ensure efficiency by having any machines used for testing 61 or that run Autobuilders be as high performance as possible. 62 63 .. note:: 64 65 Given sufficient processing power, you might also consider 66 building Yocto Project development containers to be run under 67 Docker, which is described later. 68 693. *Understand the Hardware Topology of the Environment:* Once you 70 understand the hardware involved and the make-up of the team, you 71 can understand the hardware topology of the development environment. 72 You can get a visual idea of the machines and their roles across the 73 development environment. 74 754. *Use Git as Your Source Control Manager (SCM):* Keeping your 76 :term:`Metadata` (i.e. recipes, 77 configuration files, classes, and so forth) and any software you are 78 developing under the control of an SCM system that is compatible 79 with the OpenEmbedded build system is advisable. Of all of the SCMs 80 supported by BitBake, the Yocto Project team strongly recommends using 81 :ref:`overview-manual/development-environment:git`. 82 Git is a distributed system 83 that is easy to back up, allows you to work remotely, and then 84 connects back to the infrastructure. 85 86 .. note:: 87 88 For information about BitBake, see the 89 :doc:`bitbake:index`. 90 91 It is relatively easy to set up Git services and create 92 infrastructure like :yocto_git:`/`, which is based on 93 server software called ``gitolite`` with ``cgit`` being used to 94 generate the web interface that lets you view the repositories. The 95 ``gitolite`` software identifies users using SSH keys and allows 96 branch-based access controls to repositories that you can control as 97 little or as much as necessary. 98 99 .. note:: 100 101 The setup of these services is beyond the scope of this manual. 102 However, here are sites describing how to perform setup: 103 104 - `Gitolite <https://gitolite.com>`__: Information for 105 ``gitolite``. 106 107 - `Interfaces, frontends, and 108 tools <https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools>`__: 109 Documentation on how to create interfaces and frontends for 110 Git. 111 1125. *Set up the Application Development Machines:* As mentioned earlier, 113 application developers are creating applications on top of existing 114 software stacks. Following are some best practices for setting up 115 machines used for application development: 116 117 - Use a pre-built toolchain that contains the software stack 118 itself. Then, develop the application code on top of the stack. 119 This method works well for small numbers of relatively isolated 120 applications. 121 122 - Keep your cross-development toolchains updated. You can do this 123 through provisioning either as new toolchain downloads or as 124 updates through a package update mechanism using ``opkg`` to 125 provide updates to an existing toolchain. The exact mechanics of 126 how and when to do this depend on local policy. 127 128 - Use multiple toolchains installed locally into different 129 locations to allow development across versions. 130 1316. *Set up the Core Development Machines:* As mentioned earlier, core 132 developers work on the contents of the operating system itself. 133 Following are some best practices for setting up machines used for 134 developing images: 135 136 - Have the :term:`OpenEmbedded Build System` available on 137 the developer workstations so developers can run their own builds 138 and directly rebuild the software stack. 139 140 - Keep the core system unchanged as much as possible and do your 141 work in layers on top of the core system. Doing so gives you a 142 greater level of portability when upgrading to new versions of 143 the core system or Board Support Packages (BSPs). 144 145 - Share layers amongst the developers of a particular project and 146 contain the policy configuration that defines the project. 147 1487. *Set up an Autobuilder:* Autobuilders are often the core of the 149 development environment. It is here that changes from individual 150 developers are brought together and centrally tested. Based on this 151 automated build and test environment, subsequent decisions about 152 releases can be made. Autobuilders also allow for "continuous 153 integration" style testing of software components and regression 154 identification and tracking. 155 156 See ":yocto_ab:`Yocto Project Autobuilder <>`" for more 157 information and links to buildbot. The Yocto Project team has found 158 this implementation works well in this role. A public example of 159 this is the Yocto Project Autobuilders, which the Yocto Project team 160 uses to test the overall health of the project. 161 162 The features of this system are: 163 164 - Highlights when commits break the build. 165 166 - Populates an :ref:`sstate 167 cache <overview-manual/concepts:shared state cache>` from which 168 developers can pull rather than requiring local builds. 169 170 - Allows commit hook triggers, which trigger builds when commits 171 are made. 172 173 - Allows triggering of automated image booting and testing under 174 the QuickEMUlator (QEMU). 175 176 - Supports incremental build testing and from-scratch builds. 177 178 - Shares output that allows developer testing and historical 179 regression investigation. 180 181 - Creates output that can be used for releases. 182 183 - Allows scheduling of builds so that resources can be used 184 efficiently. 185 1868. *Set up Test Machines:* Use a small number of shared, high 187 performance systems for testing purposes. Developers can use these 188 systems for wider, more extensive testing while they continue to 189 develop locally using their primary development system. 190 1919. *Document Policies and Change Flow:* The Yocto Project uses a 192 hierarchical structure and a pull model. There are scripts to create and 193 send pull requests (i.e. ``create-pull-request`` and 194 ``send-pull-request``). This model is in line with other open source 195 projects where maintainers are responsible for specific areas of the 196 project and a single maintainer handles the final "top-of-tree" 197 merges. 198 199 .. note:: 200 201 You can also use a more collective push model. The ``gitolite`` 202 software supports both the push and pull models quite easily. 203 204 As with any development environment, it is important to document the 205 policy used as well as any main project guidelines so they are 206 understood by everyone. It is also a good idea to have 207 well-structured commit messages, which are usually a part of a 208 project's guidelines. Good commit messages are essential when 209 looking back in time and trying to understand why changes were made. 210 211 If you discover that changes are needed to the core layer of the 212 project, it is worth sharing those with the community as soon as 213 possible. Chances are if you have discovered the need for changes, 214 someone else in the community needs them also. 215 21610. *Development Environment Summary:* Aside from the previous steps, 217 here are best practices within the Yocto Project development 218 environment: 219 220 - Use :ref:`overview-manual/development-environment:git` as the source control 221 system. 222 223 - Maintain your Metadata in layers that make sense for your 224 situation. See the ":ref:`overview-manual/yp-intro:the yocto project layer model`" 225 section in the Yocto Project Overview and Concepts Manual and the 226 ":ref:`dev-manual/common-tasks:understanding and creating layers`" 227 section for more information on layers. 228 229 - Separate the project's Metadata and code by using separate Git 230 repositories. See the ":ref:`overview-manual/development-environment:yocto project source repositories`" 231 section in the Yocto Project Overview and Concepts Manual for 232 information on these repositories. See the 233 ":ref:`dev-manual/start:locating yocto project source files`" 234 section for information on how to set up local Git repositories 235 for related upstream Yocto Project Git repositories. 236 237 - Set up the directory for the shared state cache 238 (:term:`SSTATE_DIR`) where 239 it makes sense. For example, set up the sstate cache on a system 240 used by developers in the same organization and share the same 241 source directories on their machines. 242 243 - Set up an Autobuilder and have it populate the sstate cache and 244 source directories. 245 246 - The Yocto Project community encourages you to send patches to the 247 project to fix bugs or add features. If you do submit patches, 248 follow the project commit guidelines for writing good commit 249 messages. See the 250 ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" 251 section. 252 253 - Send changes to the core sooner than later as others are likely 254 to run into the same issues. For some guidance on mailing lists 255 to use, see the list in the 256 ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" 257 section. For a description 258 of the available mailing lists, see the ":ref:`resources-mailinglist`" section in 259 the Yocto Project Reference Manual. 260 261Preparing the Build Host 262======================== 263 264This section provides procedures to set up a system to be used as your 265:term:`Build Host` for 266development using the Yocto Project. Your build host can be a native 267Linux machine (recommended), it can be a machine (Linux, Mac, or 268Windows) that uses `CROPS <https://github.com/crops/poky-container>`__, 269which leverages `Docker Containers <https://www.docker.com/>`__ or it 270can be a Windows machine capable of running Windows Subsystem For Linux 271v2 (WSL). 272 273.. note:: 274 275 The Yocto Project is not compatible with 276 `Windows Subsystem for Linux v1 <https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux>`__. 277 It is compatible but not officially supported nor validated with 278 WSLv2. If you still decide to use WSL please upgrade to 279 `WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__. 280 281Once your build host is set up to use the Yocto Project, further steps 282are necessary depending on what you want to accomplish. See the 283following references for information on how to prepare for Board Support 284Package (BSP) development and kernel development: 285 286- *BSP Development:* See the ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`" 287 section in the Yocto Project Board Support Package (BSP) Developer's 288 Guide. 289 290- *Kernel Development:* See the ":ref:`kernel-dev/common:preparing the build host to work on the kernel`" 291 section in the Yocto Project Linux Kernel Development Manual. 292 293Setting Up a Native Linux Host 294------------------------------ 295 296Follow these steps to prepare a native Linux machine as your Yocto 297Project Build Host: 298 2991. *Use a Supported Linux Distribution:* You should have a reasonably 300 current Linux-based host system. You will have the best results with 301 a recent release of Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS 302 as these releases are frequently tested against the Yocto Project and 303 officially supported. For a list of the distributions under 304 validation and their status, see the ":ref:`Supported Linux 305 Distributions <detailed-supported-distros>`" 306 section in the Yocto Project Reference Manual and the wiki page at 307 :yocto_wiki:`Distribution Support </Distribution_Support>`. 308 3092. *Have Enough Free Memory:* Your system should have at least 50 Gbytes 310 of free disk space for building images. 311 3123. *Meet Minimal Version Requirements:* The OpenEmbedded build system 313 should be able to run on any modern distribution that has the 314 following versions for Git, tar, Python and gcc. 315 316 - Git &MIN_GIT_VERSION; or greater 317 318 - tar &MIN_TAR_VERSION; or greater 319 320 - Python &MIN_PYTHON_VERSION; or greater. 321 322 - gcc &MIN_GCC_VERSION; or greater. 323 324 If your build host does not meet any of these listed version 325 requirements, you can take steps to prepare the system so that you 326 can still use the Yocto Project. See the 327 ":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`" 328 section in the Yocto Project Reference Manual for information. 329 3304. *Install Development Host Packages:* Required development host 331 packages vary depending on your build host and what you want to do 332 with the Yocto Project. Collectively, the number of required packages 333 is large if you want to be able to cover all cases. 334 335 For lists of required packages for all scenarios, see the 336 ":ref:`ref-manual/system-requirements:required packages for the build host`" 337 section in the Yocto Project Reference Manual. 338 339Once you have completed the previous steps, you are ready to continue 340using a given development path on your native Linux machine. If you are 341going to use BitBake, see the 342":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" 343section. If you are going 344to use the Extensible SDK, see the ":doc:`/sdk-manual/extensible`" Chapter in the Yocto 345Project Application Development and the Extensible Software Development 346Kit (eSDK) manual. If you want to work on the kernel, see the :doc:`/kernel-dev/index`. If you are going to use 347Toaster, see the ":doc:`/toaster-manual/setup-and-use`" 348section in the Toaster User Manual. 349 350Setting Up to Use CROss PlatformS (CROPS) 351----------------------------------------- 352 353With `CROPS <https://github.com/crops/poky-container>`__, which 354leverages `Docker Containers <https://www.docker.com/>`__, you can 355create a Yocto Project development environment that is operating system 356agnostic. You can set up a container in which you can develop using the 357Yocto Project on a Windows, Mac, or Linux machine. 358 359Follow these general steps to prepare a Windows, Mac, or Linux machine 360as your Yocto Project build host: 361 3621. *Determine What Your Build Host Needs:* 363 `Docker <https://www.docker.com/what-docker>`__ is a software 364 container platform that you need to install on the build host. 365 Depending on your build host, you might have to install different 366 software to support Docker containers. Go to the Docker installation 367 page and read about the platform requirements in "`Supported 368 Platforms <https://docs.docker.com/engine/install/#supported-platforms>`__" 369 your build host needs to run containers. 370 3712. *Choose What To Install:* Depending on whether or not your build host 372 meets system requirements, you need to install "Docker CE Stable" or 373 the "Docker Toolbox". Most situations call for Docker CE. However, if 374 you have a build host that does not meet requirements (e.g. 375 Pre-Windows 10 or Windows 10 "Home" version), you must install Docker 376 Toolbox instead. 377 3783. *Go to the Install Site for Your Platform:* Click the link for the 379 Docker edition associated with your build host's native software. For 380 example, if your build host is running Microsoft Windows Version 10 381 and you want the Docker CE Stable edition, click that link under 382 "Supported Platforms". 383 3844. *Install the Software:* Once you have understood all the 385 pre-requisites, you can download and install the appropriate 386 software. Follow the instructions for your specific machine and the 387 type of the software you need to install: 388 389 - Install `Docker Desktop on 390 Windows <https://docs.docker.com/docker-for-windows/install/#install-docker-desktop-on-windows>`__ 391 for Windows build hosts that meet requirements. 392 393 - Install `Docker Desktop on 394 MacOs <https://docs.docker.com/docker-for-mac/install/#install-and-run-docker-desktop-on-mac>`__ 395 for Mac build hosts that meet requirements. 396 397 - Install `Docker Engine on 398 CentOS <https://docs.docker.com/engine/install/centos/>`__ 399 for Linux build hosts running the CentOS distribution. 400 401 - Install `Docker Engine on 402 Debian <https://docs.docker.com/engine/install/debian/>`__ 403 for Linux build hosts running the Debian distribution. 404 405 - Install `Docker Engine for 406 Fedora <https://docs.docker.com/engine/install/fedora/>`__ 407 for Linux build hosts running the Fedora distribution. 408 409 - Install `Docker Engine for 410 Ubuntu <https://docs.docker.com/engine/install/ubuntu/>`__ 411 for Linux build hosts running the Ubuntu distribution. 412 4135. *Optionally Orient Yourself With Docker:* If you are unfamiliar with 414 Docker and the container concept, you can learn more here - 415 https://docs.docker.com/get-started/. 416 4176. *Launch Docker or Docker Toolbox:* You should be able to launch 418 Docker or the Docker Toolbox and have a terminal shell on your 419 development host. 420 4217. *Set Up the Containers to Use the Yocto Project:* Go to 422 https://github.com/crops/docker-win-mac-docs/wiki and follow 423 the directions for your particular build host (i.e. Linux, Mac, or 424 Windows). 425 426 Once you complete the setup instructions for your machine, you have 427 the Poky, Extensible SDK, and Toaster containers available. You can 428 click those links from the page and learn more about using each of 429 those containers. 430 431Once you have a container set up, everything is in place to develop just 432as if you were running on a native Linux machine. If you are going to 433use the Poky container, see the 434":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" 435section. If you are going to use the Extensible SDK container, see the 436":doc:`/sdk-manual/extensible`" Chapter in the Yocto 437Project Application Development and the Extensible Software Development 438Kit (eSDK) manual. If you are going to use the Toaster container, see 439the ":doc:`/toaster-manual/setup-and-use`" 440section in the Toaster User Manual. 441 442Setting Up to Use Windows Subsystem For Linux (WSLv2) 443----------------------------------------------------- 444 445With `Windows Subsystem for Linux 446(WSLv2) <https://docs.microsoft.com/en-us/windows/wsl/wsl2-about>`__, 447you can create a Yocto Project development environment that allows you 448to build on Windows. You can set up a Linux distribution inside Windows 449in which you can develop using the Yocto Project. 450 451Follow these general steps to prepare a Windows machine using WSLv2 as 452your Yocto Project build host: 453 4541. *Make sure your Windows 10 machine is capable of running WSLv2:* 455 WSLv2 is only available for Windows 10 builds > 18917. To check which 456 build version you are running, you may open a command prompt on 457 Windows and execute the command "ver". 458 :: 459 460 C:\Users\myuser> ver 461 462 Microsoft Windows [Version 10.0.19041.153] 463 464 If your build is capable of running 465 WSLv2 you may continue, for more information on this subject or 466 instructions on how to upgrade to WSLv2 visit `Windows 10 467 WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/wsl2-install>`__ 468 4692. *Install the Linux distribution of your choice inside Windows 10:* 470 Once you know your version of Windows 10 supports WSLv2, you can 471 install the distribution of your choice from the Microsoft Store. 472 Open the Microsoft Store and search for Linux. While there are 473 several Linux distributions available, the assumption is that your 474 pick will be one of the distributions supported by the Yocto Project 475 as stated on the instructions for using a native Linux host. After 476 making your selection, simply click "Get" to download and install the 477 distribution. 478 4793. *Check your Linux distribution is using WSLv2:* Open a Windows 480 PowerShell and run:: 481 482 C:\WINDOWS\system32> wsl -l -v 483 NAME STATE VERSION 484 *Ubuntu Running 2 485 486 Note the version column which says the WSL version 487 being used by your distribution, on compatible systems, this can be 488 changed back at any point in time. 489 4904. *Optionally Orient Yourself on WSL:* If you are unfamiliar with WSL, 491 you can learn more here - 492 https://docs.microsoft.com/en-us/windows/wsl/wsl2-about. 493 4945. *Launch your WSL Distibution:* From the Windows start menu simply 495 launch your WSL distribution just like any other application. 496 4976. *Optimize your WSLv2 storage often:* Due to the way storage is 498 handled on WSLv2, the storage space used by the undelying Linux 499 distribution is not reflected immedately, and since bitbake heavily 500 uses storage, after several builds, you may be unaware you are 501 running out of space. WSLv2 uses a VHDX file for storage, this issue 502 can be easily avoided by manually optimizing this file often, this 503 can be done in the following way: 504 505 1. *Find the location of your VHDX file:* 506 507 First you need to find the distro app package directory, to achieve this 508 open a Windows Powershell as Administrator and run:: 509 510 C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName 511 PackageFamilyName 512 ----------------- 513 CanonicalGroupLimited.UbuntuonWindows_79abcdefgh 514 515 516 You should now 517 replace the PackageFamilyName and your user on the following path 518 to find your VHDX file:: 519 520 ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ 521 Mode LastWriteTime Length Name 522 -a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx 523 524 Your VHDX file path is: 525 ``C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx`` 526 527 2a. *Optimize your VHDX file using Windows Powershell:* 528 529 To use the ``optimize-vhd`` cmdlet below, first install the Hyper-V 530 option on Windows. Then, open a Windows Powershell as Administrator to 531 optimize your VHDX file, shutting down WSL first:: 532 533 C:\WINDOWS\system32> wsl --shutdown 534 C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full 535 536 A progress bar should be shown while optimizing the 537 VHDX file, and storage should now be reflected correctly on the 538 Windows Explorer. 539 540 2b. *Optimize your VHDX file using DiskPart:* 541 542 The ``optimize-vhd`` cmdlet noted in step 2a above is provided by 543 Hyper-V. Not all SKUs of Windows can install Hyper-V. As an alternative, 544 use the DiskPart tool. To start, open a Windows command prompt as 545 Administrator to optimize your VHDX file, shutting down WSL first:: 546 547 C:\WINDOWS\system32> wsl --shutdown 548 C:\WINDOWS\system32> diskpart 549 550 DISKPART> select vdisk file="<path_to_VHDX_file>" 551 DISKPART> attach vdisk readonly 552 DISKPART> compact vdisk 553 DISKPART> exit 554 555.. note:: 556 557 The current implementation of WSLv2 does not have out-of-the-box 558 access to external devices such as those connected through a USB 559 port, but it automatically mounts your ``C:`` drive on ``/mnt/c/`` 560 (and others), which you can use to share deploy artifacts to be later 561 flashed on hardware through Windows, but your build directory should 562 not reside inside this mountpoint. 563 564Once you have WSLv2 set up, everything is in place to develop just as if 565you were running on a native Linux machine. If you are going to use the 566Extensible SDK container, see the ":doc:`/sdk-manual/extensible`" Chapter in the Yocto 567Project Application Development and the Extensible Software Development 568Kit (eSDK) manual. If you are going to use the Toaster container, see 569the ":doc:`/toaster-manual/setup-and-use`" 570section in the Toaster User Manual. 571 572Locating Yocto Project Source Files 573=================================== 574 575This section shows you how to locate, fetch and configure the source 576files you'll need to work with the Yocto Project. 577 578.. note:: 579 580 - For concepts and introductory information about Git as it is used 581 in the Yocto Project, see the ":ref:`overview-manual/development-environment:git`" 582 section in the Yocto Project Overview and Concepts Manual. 583 584 - For concepts on Yocto Project source repositories, see the 585 ":ref:`overview-manual/development-environment:yocto project source repositories`" 586 section in the Yocto Project Overview and Concepts Manual." 587 588Accessing Source Repositories 589----------------------------- 590 591Working from a copy of the upstream :ref:`dev-manual/start:accessing source repositories` is the 592preferred method for obtaining and using a Yocto Project release. You 593can view the Yocto Project Source Repositories at 594:yocto_git:`/`. In particular, you can find the ``poky`` 595repository at :yocto_git:`/poky`. 596 597Use the following procedure to locate the latest upstream copy of the 598``poky`` Git repository: 599 6001. *Access Repositories:* Open a browser and go to 601 :yocto_git:`/` to access the GUI-based interface into the 602 Yocto Project source repositories. 603 6042. *Select the Repository:* Click on the repository in which you are 605 interested (e.g. ``poky``). 606 6073. *Find the URL Used to Clone the Repository:* At the bottom of the 608 page, note the URL used to clone that repository 609 (e.g. :yocto_git:`/poky`). 610 611 .. note:: 612 613 For information on cloning a repository, see the 614 ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" section. 615 616Accessing Index of Releases 617--------------------------- 618 619Yocto Project maintains an Index of Releases area that contains related 620files that contribute to the Yocto Project. Rather than Git 621repositories, these files are tarballs that represent snapshots in time 622of a given component. 623 624.. note:: 625 626 The recommended method for accessing Yocto Project components is to 627 use Git to clone the upstream repository and work from within that 628 locally cloned repository. However, this section documents how to 629 use a tarball snapshot of any given component. 630 631Follow these steps to locate and download a particular tarball: 632 6331. *Access the Index of Releases:* Open a browser and go to 634 :yocto_dl:`Index of Releases </releases>`. The 635 list represents released components (e.g. ``bitbake``, ``sato``, and 636 so on). 637 638 .. note:: 639 640 The ``yocto`` directory contains the full array of released Poky 641 tarballs. The ``poky`` directory in the Index of Releases was 642 historically used for very early releases and exists now only for 643 retroactive completeness. 644 6452. *Select a Component:* Click on any released component in which you 646 are interested (e.g. ``yocto``). 647 6483. *Find the Tarball:* Drill down to find the associated tarball. For 649 example, click on ``yocto-&DISTRO;`` to view files associated with the 650 Yocto Project &DISTRO; release. 651 6524. *Download the Tarball:* Click the tarball to download and save a 653 snapshot of the given component. 654 655Using the Downloads Page 656------------------------ 657 658The :yocto_home:`Yocto Project Website <>` uses a "DOWNLOADS" page 659from which you can locate and download tarballs of any Yocto Project 660release. Rather than Git repositories, these files represent snapshot 661tarballs similar to the tarballs located in the Index of Releases 662described in the ":ref:`dev-manual/start:accessing index of releases`" section. 663 6641. *Go to the Yocto Project Website:* Open The 665 :yocto_home:`Yocto Project Website <>` in your browser. 666 6672. *Get to the Downloads Area:* Select the "DOWNLOADS" item from the 668 pull-down "SOFTWARE" tab menu near the top of the page. 669 6703. *Select a Yocto Project Release:* Use the menu next to "RELEASE" to 671 display and choose a recent or past supported Yocto Project release 672 (e.g. &DISTRO_NAME_NO_CAP;, &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth). 673 674 .. note:: 675 676 For a "map" of Yocto Project releases to version numbers, see the 677 :yocto_wiki:`Releases </Releases>` wiki page. 678 679 You can use the "RELEASE ARCHIVE" link to reveal a menu of all Yocto 680 Project releases. 681 6824. *Download Tools or Board Support Packages (BSPs):* From the 683 "DOWNLOADS" page, you can download tools or BSPs as well. Just scroll 684 down the page and look for what you need. 685 686Cloning and Checking Out Branches 687================================= 688 689To use the Yocto Project for development, you need a release locally 690installed on your development system. This locally installed set of 691files is referred to as the :term:`Source Directory` 692in the Yocto Project documentation. 693 694The preferred method of creating your Source Directory is by using 695:ref:`overview-manual/development-environment:git` to clone a local copy of the upstream 696``poky`` repository. Working from a cloned copy of the upstream 697repository allows you to contribute back into the Yocto Project or to 698simply work with the latest software on a development branch. Because 699Git maintains and creates an upstream repository with a complete history 700of changes and you are working with a local clone of that repository, 701you have access to all the Yocto Project development branches and tag 702names used in the upstream repository. 703 704Cloning the ``poky`` Repository 705------------------------------- 706 707Follow these steps to create a local version of the upstream 708:term:`Poky` Git repository. 709 7101. *Set Your Directory:* Change your working directory to where you want 711 to create your local copy of ``poky``. 712 7132. *Clone the Repository:* The following example command clones the 714 ``poky`` repository and uses the default name "poky" for your local 715 repository:: 716 717 $ git clone git://git.yoctoproject.org/poky 718 Cloning into 'poky'... 719 remote: Counting objects: 432160, done. 720 remote: Compressing objects: 100% (102056/102056), done. 721 remote: Total 432160 (delta 323116), reused 432037 (delta 323000) 722 Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done. 723 Resolving deltas: 100% (323116/323116), done. 724 Checking connectivity... done. 725 726 Unless you 727 specify a specific development branch or tag name, Git clones the 728 "master" branch, which results in a snapshot of the latest 729 development changes for "master". For information on how to check out 730 a specific development branch or on how to check out a local branch 731 based on a tag name, see the 732 ":ref:`dev-manual/start:checking out by branch in poky`" and 733 ":ref:`dev-manual/start:checking out by tag in poky`" sections, respectively. 734 735 Once the local repository is created, you can change to that 736 directory and check its status. The ``master`` branch is checked out 737 by default:: 738 739 $ cd poky 740 $ git status 741 On branch master 742 Your branch is up-to-date with 'origin/master'. 743 nothing to commit, working directory clean 744 $ git branch 745 * master 746 747 Your local repository of poky is identical to the 748 upstream poky repository at the time from which it was cloned. As you 749 work with the local branch, you can periodically use the 750 ``git pull --rebase`` command to be sure you are up-to-date 751 with the upstream branch. 752 753Checking Out by Branch in Poky 754------------------------------ 755 756When you clone the upstream poky repository, you have access to all its 757development branches. Each development branch in a repository is unique 758as it forks off the "master" branch. To see and use the files of a 759particular development branch locally, you need to know the branch name 760and then specifically check out that development branch. 761 762.. note:: 763 764 Checking out an active development branch by branch name gives you a 765 snapshot of that particular branch at the time you check it out. 766 Further development on top of the branch that occurs after check it 767 out can occur. 768 7691. *Switch to the Poky Directory:* If you have a local poky Git 770 repository, switch to that directory. If you do not have the local 771 copy of poky, see the 772 ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" 773 section. 774 7752. *Determine Existing Branch Names:* 776 :: 777 778 $ git branch -a 779 * master 780 remotes/origin/1.1_M1 781 remotes/origin/1.1_M2 782 remotes/origin/1.1_M3 783 remotes/origin/1.1_M4 784 remotes/origin/1.2_M1 785 remotes/origin/1.2_M2 786 remotes/origin/1.2_M3 787 . . . 788 remotes/origin/thud 789 remotes/origin/thud-next 790 remotes/origin/warrior 791 remotes/origin/warrior-next 792 remotes/origin/zeus 793 remotes/origin/zeus-next 794 ... and so on ... 795 7963. *Check out the Branch:* Check out the development branch in which you 797 want to work. For example, to access the files for the Yocto Project 798 &DISTRO; Release (&DISTRO_NAME;), use the following command:: 799 800 $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; 801 Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin. 802 Switched to a new branch '&DISTRO_NAME_NO_CAP;' 803 804 The previous command checks out the "&DISTRO_NAME_NO_CAP;" development 805 branch and reports that the branch is tracking the upstream 806 "origin/&DISTRO_NAME_NO_CAP;" branch. 807 808 The following command displays the branches that are now part of your 809 local poky repository. The asterisk character indicates the branch 810 that is currently checked out for work:: 811 812 $ git branch 813 master 814 * &DISTRO_NAME_NO_CAP; 815 816Checking Out by Tag in Poky 817--------------------------- 818 819Similar to branches, the upstream repository uses tags to mark specific 820commits associated with significant points in a development branch (i.e. 821a release point or stage of a release). You might want to set up a local 822branch based on one of those points in the repository. The process is 823similar to checking out by branch name except you use tag names. 824 825.. note:: 826 827 Checking out a branch based on a tag gives you a stable set of files 828 not affected by development on the branch above the tag. 829 8301. *Switch to the Poky Directory:* If you have a local poky Git 831 repository, switch to that directory. If you do not have the local 832 copy of poky, see the 833 ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" 834 section. 835 8362. *Fetch the Tag Names:* To checkout the branch based on a tag name, 837 you need to fetch the upstream tags into your local repository:: 838 839 $ git fetch --tags 840 $ 841 8423. *List the Tag Names:* You can list the tag names now:: 843 844 $ git tag 845 1.1_M1.final 846 1.1_M1.rc1 847 1.1_M1.rc2 848 1.1_M2.final 849 1.1_M2.rc1 850 . 851 . 852 . 853 yocto-2.5 854 yocto-2.5.1 855 yocto-2.5.2 856 yocto-2.5.3 857 yocto-2.6 858 yocto-2.6.1 859 yocto-2.6.2 860 yocto-2.7 861 yocto_1.5_M5.rc8 862 863 8644. *Check out the Branch:* 865 :: 866 867 $ git checkout tags/yocto-&DISTRO; -b my_yocto_&DISTRO; 868 Switched to a new branch 'my_yocto_&DISTRO;' 869 $ git branch 870 master 871 * my_yocto_&DISTRO; 872 873 The previous command creates and 874 checks out a local branch named "my_yocto_&DISTRO;", which is based on 875 the commit in the upstream poky repository that has the same tag. In 876 this example, the files you have available locally as a result of the 877 ``checkout`` command are a snapshot of the "&DISTRO_NAME_NO_CAP;" 878 development branch at the point where Yocto Project &DISTRO; was 879 released. 880