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