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