summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-start.xml
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:30:32 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 13:56:17 +0100
commit43d07a285181e64c30d98d10ff93ef50391efe59 (patch)
tree78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/dev-manual/dev-manual-start.xml
parent1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff)
downloadpoky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-start.xml')
-rw-r--r--documentation/dev-manual/dev-manual-start.xml1288
1 files changed, 0 insertions, 1288 deletions
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
deleted file mode 100644
index 9ff9ac4c8f..0000000000
--- a/documentation/dev-manual/dev-manual-start.xml
+++ /dev/null
@@ -1,1288 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='dev-manual-start'>
7
8<title>Setting Up to Use the Yocto Project</title>
9
10<para>
11 This chapter provides guidance on how to prepare to use the
12 Yocto Project.
13 You can learn about creating a team environment that develops using the
14 Yocto Project, how to set up a
15 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>,
16 how to locate Yocto Project source repositories, and how to create local
17 Git repositories.
18</para>
19
20<section id="usingpoky-changes-collaborate">
21 <title>Creating a Team Development Environment</title>
22
23 <para>
24 It might not be immediately clear how you can use the Yocto
25 Project in a team development environment, or how to scale it for a
26 large team of developers.
27 You can adapt the Yocto Project to many different use cases and
28 scenarios;
29 however, this flexibility could cause difficulties if you are trying
30 to create a working setup that scales effectively.
31 </para>
32
33 <para>
34 To help you understand how to set up this type of environment,
35 this section presents a procedure that gives you information
36 that can help you get the results you want.
37 The procedure is high-level and presents some of the project's most
38 successful experiences, practices, solutions, and available
39 technologies that have proved to work well in the past;
40 however, keep in mind, the procedure here is simply a starting point.
41 You can build off these steps and customize the procedure to fit any
42 particular working environment and set of practices.
43 <orderedlist>
44 <listitem><para>
45 <emphasis>Determine Who is Going to be Developing:</emphasis>
46 You first need to understand who is going to be doing anything
47 related to the Yocto Project and determine their roles.
48 Making this determination is essential to completing
49 subsequent steps, which are to get your equipment together
50 and set up your development environment's hardware topology.
51 </para>
52
53 <para>The following roles exist:
54 <itemizedlist>
55 <listitem><para>
56 <emphasis>Application Developer:</emphasis>
57 This type of developer does application level work
58 on top of an existing software stack.
59 </para></listitem>
60 <listitem><para>
61 <emphasis>Core System Developer:</emphasis>
62 This type of developer works on the contents of the
63 operating system image itself.
64 </para></listitem>
65 <listitem><para>
66 <emphasis>Build Engineer:</emphasis>
67 This type of developer manages Autobuilders and
68 releases. Depending on the specifics of the environment,
69 not all situations might need a Build Engineer.
70 </para></listitem>
71 <listitem><para>
72 <emphasis>Test Engineer:</emphasis>
73 This type of developer creates and manages automated
74 tests that are used to ensure all application and
75 core system development meets desired quality
76 standards.
77 </para></listitem>
78 </itemizedlist>
79 </para></listitem>
80 <listitem><para>
81 <emphasis>Gather the Hardware:</emphasis>
82 Based on the size and make-up of the team, get the hardware
83 together.
84 Ideally, any development, build, or test engineer uses
85 a system that runs a supported Linux distribution.
86 These systems, in general, should be high performance
87 (e.g. dual, six-core Xeons with 24 Gbytes of RAM and plenty
88 of disk space).
89 You can help ensure efficiency by having any machines used
90 for testing or that run Autobuilders be as high performance
91 as possible.
92 <note>
93 Given sufficient processing power, you might also consider
94 building Yocto Project development containers to be run
95 under Docker, which is described later.
96 </note>
97 </para></listitem>
98 <listitem><para>
99 <emphasis>Understand the Hardware Topology of the Environment:</emphasis>
100 Once you understand the hardware involved and the make-up
101 of the team, you can understand the hardware topology of the
102 development environment.
103 You can get a visual idea of the machines and their roles
104 across the development environment.
105
106<!--
107 The following figure shows a moderately sized Yocto Project
108 development environment.
109
110 <para role="writernotes">
111 Need figure.</para>
112-->
113
114 </para></listitem>
115 <listitem><para>
116 <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
117 Keeping your
118 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
119 (i.e. recipes, configuration files, classes, and so forth)
120 and any software you are developing under the control of an SCM
121 system that is compatible with the OpenEmbedded build system
122 is advisable.
123 Of all of the SCMs supported by BitBake, the Yocto Project team strongly
124 recommends using
125 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>.
126 Git is a distributed system that is easy to back up,
127 allows you to work remotely, and then connects back to the
128 infrastructure.
129 <note>
130 For information about BitBake, see the
131 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
132 </note></para>
133
134 <para>It is relatively easy to set up Git services and create
135 infrastructure like
136 <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
137 which is based on server software called
138 <filename>gitolite</filename> with <filename>cgit</filename>
139 being used to generate the web interface that lets you view the
140 repositories.
141 The <filename>gitolite</filename> software identifies users
142 using SSH keys and allows branch-based access controls to
143 repositories that you can control as little or as much as
144 necessary.
145 <note>
146 The setup of these services is beyond the scope of this
147 manual.
148 However, sites such as the following exist that describe
149 how to perform setup:
150 <itemizedlist>
151 <listitem><para>
152 <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
153 Describes how to install
154 <filename>gitolite</filename> on the server.
155 </para></listitem>
156 <listitem><para>
157 <ulink url='http://gitolite.com'>Gitolite</ulink>:
158 Information for <filename>gitolite</filename>.
159 </para></listitem>
160 <listitem><para>
161 <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
162 Documentation on how to create interfaces and
163 frontends for Git.
164 </para></listitem>
165 </itemizedlist>
166 </note>
167 </para></listitem>
168 <listitem><para>
169 <emphasis>Set up the Application Development Machines:</emphasis>
170 As mentioned earlier, application developers are creating
171 applications on top of existing software stacks.
172 Following are some best practices for setting up machines
173 used for application development:
174 <itemizedlist>
175 <listitem><para>
176 Use a pre-built toolchain that contains the software
177 stack itself.
178 Then, develop the application code on top of the
179 stack.
180 This method works well for small numbers of relatively
181 isolated applications.
182 </para></listitem>
183 <listitem><para>
184 Keep your cross-development toolchains updated.
185 You can do this through provisioning either as new
186 toolchain downloads or as updates through a package
187 update mechanism using <filename>opkg</filename>
188 to provide updates to an existing toolchain.
189 The exact mechanics of how and when to do this depend
190 on local policy.
191 </para></listitem>
192 <listitem><para>
193 Use multiple toolchains installed locally into
194 different locations to allow development across
195 versions.
196 </para></listitem>
197 </itemizedlist>
198 </para></listitem>
199 <listitem><para>
200 <emphasis>Set up the Core Development Machines:</emphasis>
201 As mentioned earlier, core developers work on the contents of
202 the operating system itself.
203 Following are some best practices for setting up machines
204 used for developing images:
205 <itemizedlist>
206 <listitem><para>
207 Have the
208 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
209 available on the developer workstations so developers
210 can run their own builds and directly rebuild the
211 software stack.
212 </para></listitem>
213 <listitem><para>
214 Keep the core system unchanged as much as
215 possible and do your work in layers on top of the
216 core system.
217 Doing so gives you a greater level of portability when
218 upgrading to new versions of the core system or Board
219 Support Packages (BSPs).
220 </para></listitem>
221 <listitem><para>
222 Share layers amongst the developers of a
223 particular project and contain the policy configuration
224 that defines the project.
225 </para></listitem>
226 </itemizedlist>
227 </para></listitem>
228 <listitem><para>
229 <emphasis>Set up an Autobuilder:</emphasis>
230 Autobuilders are often the core of the development
231 environment.
232 It is here that changes from individual developers are brought
233 together and centrally tested.
234 Based on this automated build and test environment, subsequent
235 decisions about releases can be made.
236 Autobuilders also allow for "continuous integration" style
237 testing of software components and regression identification
238 and tracking.</para>
239
240 <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
241 for more information and links to buildbot.
242 The Yocto Project team has found this implementation
243 works well in this role.
244 A public example of this is the Yocto Project
245 Autobuilders, which the Yocto Project team uses to test the
246 overall health of the project.</para>
247
248 <para>The features of this system are:
249 <itemizedlist>
250 <listitem><para>
251 Highlights when commits break the build.
252 </para></listitem>
253 <listitem><para>
254 Populates an
255 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate cache</ulink>
256 from which developers can pull rather than requiring
257 local builds.
258 </para></listitem>
259 <listitem><para>
260 Allows commit hook triggers, which trigger builds when
261 commits are made.
262 </para></listitem>
263 <listitem><para>
264 Allows triggering of automated image booting
265 and testing under the QuickEMUlator (QEMU).
266 </para></listitem>
267 <listitem><para>
268 Supports incremental build testing and
269 from-scratch builds.
270 </para></listitem>
271 <listitem><para>
272 Shares output that allows developer
273 testing and historical regression investigation.
274 </para></listitem>
275 <listitem><para>
276 Creates output that can be used for releases.
277 </para></listitem>
278 <listitem><para>
279 Allows scheduling of builds so that resources
280 can be used efficiently.
281 </para></listitem>
282 </itemizedlist>
283 </para></listitem>
284 <listitem><para>
285 <emphasis>Set up Test Machines:</emphasis>
286 Use a small number of shared, high performance systems
287 for testing purposes.
288 Developers can use these systems for wider, more
289 extensive testing while they continue to develop
290 locally using their primary development system.
291 </para></listitem>
292 <listitem><para>
293 <emphasis>Document Policies and Change Flow:</emphasis>
294 The Yocto Project uses a hierarchical structure and a
295 pull model.
296 Scripts exist to create and send pull requests
297 (i.e. <filename>create-pull-request</filename> and
298 <filename>send-pull-request</filename>).
299 This model is in line with other open source projects where
300 maintainers are responsible for specific areas of the project
301 and a single maintainer handles the final "top-of-tree" merges.
302 <note>
303 You can also use a more collective push model.
304 The <filename>gitolite</filename> software supports both the
305 push and pull models quite easily.
306 </note></para>
307
308 <para>As with any development environment, it is important
309 to document the policy used as well as any main project
310 guidelines so they are understood by everyone.
311 It is also a good idea to have well-structured
312 commit messages, which are usually a part of a project's
313 guidelines.
314 Good commit messages are essential when looking back in time and
315 trying to understand why changes were made.</para>
316
317 <para>If you discover that changes are needed to the core
318 layer of the project, it is worth sharing those with the
319 community as soon as possible.
320 Chances are if you have discovered the need for changes,
321 someone else in the community needs them also.
322 </para></listitem>
323 <listitem><para>
324 <emphasis>Development Environment Summary:</emphasis>
325 Aside from the previous steps, some best practices exist
326 within the Yocto Project development environment.
327 Consider the following:
328 <itemizedlist>
329 <listitem><para>
330 Use
331 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>
332 as the source control system.
333 </para></listitem>
334 <listitem><para>
335 Maintain your Metadata in layers that make sense
336 for your situation.
337 See the
338 "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
339 section in the Yocto Project Overview and Concepts
340 Manual and the
341 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
342 section for more information on layers.
343 </para></listitem>
344 <listitem><para>
345 Separate the project's Metadata and code by using
346 separate Git repositories.
347 See the
348 "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
349 section in the Yocto Project Overview and Concepts
350 Manual for information on these repositories.
351 See the
352 "<link linkend='locating-yocto-project-source-files'>Locating Yocto Project Source Files</link>"
353 section for information on how to set up local Git
354 repositories for related upstream Yocto Project
355 Git repositories.
356 </para></listitem>
357 <listitem><para>
358 Set up the directory for the shared state cache
359 (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
360 where it makes sense.
361 For example, set up the sstate cache on a system used
362 by developers in the same organization and share the
363 same source directories on their machines.
364 </para></listitem>
365 <listitem><para>
366 Set up an Autobuilder and have it populate the
367 sstate cache and source directories.
368 </para></listitem>
369 <listitem><para>
370 The Yocto Project community encourages you
371 to send patches to the project to fix bugs or add
372 features.
373 If you do submit patches, follow the project commit
374 guidelines for writing good commit messages.
375 See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
376 section.
377 </para></listitem>
378 <listitem><para>
379 Send changes to the core sooner than later
380 as others are likely to run into the same issues.
381 For some guidance on mailing lists to use, see the list
382 in the
383 "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
384 section.
385 For a description of the available mailing lists, see
386 the
387 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
388 section in the Yocto Project Reference Manual.
389 </para></listitem>
390 </itemizedlist>
391 </para></listitem>
392 </orderedlist>
393 </para>
394</section>
395
396<section id='dev-preparing-the-build-host'>
397 <title>Preparing the Build Host</title>
398
399 <para>
400 This section provides procedures to set up a system to be used as your
401 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
402 for development using the Yocto Project.
403 Your build host can be a native Linux machine (recommended), it can
404 be a machine (Linux, Mac, or Windows) that uses
405 <ulink url='https://github.com/crops/poky-container'>CROPS</ulink>,
406 which leverages
407 <ulink url='https://www.docker.com/'>Docker Containers</ulink> or it can
408 be a Windows machine capable of running Windows Subsystem For Linux v2 (WSL).
409 <note>
410 The Yocto Project is not compatible with
411 <ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux v1</ulink>.
412 It is compatible but not officially supported nor validated with WSLv2.
413 If you still decide to use WSL please upgrade to
414 <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>WSLv2</ulink>.
415 </note>
416 </para>
417
418 <para>
419 Once your build host is set up to use the Yocto Project,
420 further steps are necessary depending on what you want to
421 accomplish.
422 See the following references for information on how to prepare for
423 Board Support Package (BSP) development and kernel development:
424 <itemizedlist>
425 <listitem><para>
426 <emphasis>BSP Development:</emphasis>
427 See the
428 "<ulink url='&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work With BSP Layers</ulink>"
429 section in the Yocto Project Board Support Package (BSP)
430 Developer's Guide.
431 </para></listitem>
432 <listitem><para>
433 <emphasis>Kernel Development:</emphasis>
434 See the
435 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</ulink>"
436 section in the Yocto Project Linux Kernel Development Manual.
437 </para></listitem>
438 </itemizedlist>
439 </para>
440
441 <section id='setting-up-a-native-linux-host'>
442 <title>Setting Up a Native Linux Host</title>
443
444 <para>
445 Follow these steps to prepare a native Linux machine as your
446 Yocto Project Build Host:
447 <orderedlist>
448 <listitem><para>
449 <emphasis>Use a Supported Linux Distribution:</emphasis>
450 You should have a reasonably current Linux-based host
451 system.
452 You will have the best results with a recent release of
453 Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS as these
454 releases are frequently tested against the Yocto Project
455 and officially supported.
456 For a list of the distributions under validation and their
457 status, see the
458 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
459 in the Yocto Project Reference Manual and the wiki page at
460 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.
461 </para></listitem>
462 <listitem><para>
463 <emphasis>Have Enough Free Memory:</emphasis>
464 Your system should have at least 50 Gbytes of free disk
465 space for building images.
466 </para></listitem>
467 <listitem><para>
468 <emphasis>Meet Minimal Version Requirements:</emphasis>
469 The OpenEmbedded build system should be able to run on any
470 modern distribution that has the following versions for
471 Git, tar, Python and gcc.
472 <itemizedlist>
473 <listitem><para>
474 Git 1.8.3.1 or greater
475 </para></listitem>
476 <listitem><para>
477 tar 1.28 or greater
478 </para></listitem>
479 <listitem><para>
480 Python 3.5.0 or greater.
481 </para></listitem>
482 <listitem><para>
483 gcc 5.0 or greater.
484 </para></listitem>
485 </itemizedlist>
486 If your build host does not meet any of these three listed
487 version requirements, you can take steps to prepare the
488 system so that you can still use the Yocto Project.
489 See the
490 "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</ulink>"
491 section in the Yocto Project Reference Manual for
492 information.
493 </para></listitem>
494 <listitem><para>
495 <emphasis>Install Development Host Packages:</emphasis>
496 Required development host packages vary depending on your
497 build host and what you want to do with the Yocto
498 Project.
499 Collectively, the number of required packages is large
500 if you want to be able to cover all cases.</para>
501
502 <para>For lists of required packages for all scenarios,
503 see the
504 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host'>Required Packages for the Build Host</ulink>"
505 section in the Yocto Project Reference Manual.
506 </para></listitem>
507 </orderedlist>
508 Once you have completed the previous steps, you are ready to
509 continue using a given development path on your native Linux
510 machine.
511 If you are going to use BitBake, see the
512 "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
513 section.
514 If you are going to use the Extensible SDK, see the
515 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
516 Chapter in the Yocto Project Application Development and the
517 Extensible Software Development Kit (eSDK) manual.
518 If you want to work on the kernel, see the
519 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
520 If you are going to use Toaster, see the
521 "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
522 section in the Toaster User Manual.
523 </para>
524 </section>
525
526 <section id='setting-up-to-use-crops'>
527 <title>Setting Up to Use CROss PlatformS (CROPS)</title>
528
529 <para>
530 With
531 <ulink url='https://github.com/crops/poky-container'>CROPS</ulink>,
532 which leverages
533 <ulink url='https://www.docker.com/'>Docker Containers</ulink>,
534 you can create a Yocto Project development environment that
535 is operating system agnostic.
536 You can set up a container in which you can develop using the
537 Yocto Project on a Windows, Mac, or Linux machine.
538 </para>
539
540 <para>
541 Follow these general steps to prepare a Windows, Mac, or Linux
542 machine as your Yocto Project build host:
543 <orderedlist>
544 <listitem><para>
545 <emphasis>Determine What Your Build Host Needs:</emphasis>
546 <ulink url='https://www.docker.com/what-docker'>Docker</ulink>
547 is a software container platform that you need to install
548 on the build host.
549 Depending on your build host, you might have to install
550 different software to support Docker containers.
551 Go to the Docker installation page and read about the
552 platform requirements in
553 "<ulink url='https://docs.docker.com/install/#supported-platforms'>Supported Platforms</ulink>"
554 your build host needs to run containers.
555 </para></listitem>
556 <listitem><para>
557 <emphasis>Choose What To Install:</emphasis>
558 Depending on whether or not your build host meets system
559 requirements, you need to install "Docker CE Stable" or
560 the "Docker Toolbox".
561 Most situations call for Docker CE.
562 However, if you have a build host that does not meet
563 requirements (e.g. Pre-Windows 10 or Windows 10 "Home"
564 version), you must install Docker Toolbox instead.
565 </para></listitem>
566 <listitem><para>
567 <emphasis>Go to the Install Site for Your Platform:</emphasis>
568 Click the link for the Docker edition associated with
569 your build host's native software.
570 For example, if your build host is running Microsoft
571 Windows Version 10 and you want the Docker CE Stable
572 edition, click that link under "Supported Platforms".
573 </para></listitem>
574 <listitem><para>
575 <emphasis>Install the Software:</emphasis>
576 Once you have understood all the pre-requisites, you can
577 download and install the appropriate software.
578 Follow the instructions for your specific machine and
579 the type of the software you need to install:
580 <itemizedlist>
581 <listitem><para>
582 Install
583 <ulink url='https://docs.docker.com/docker-for-windows/install/#install-docker-for-windows-desktop-app'>Docker CE for Windows</ulink>
584 for Windows build hosts that meet requirements.
585 </para></listitem>
586 <listitem><para>
587 Install
588 <ulink url='https://docs.docker.com/docker-for-mac/install/#install-and-run-docker-for-mac'>Docker CE for Macs</ulink>
589 for Mac build hosts that meet requirements.
590 </para></listitem>
591 <listitem><para>
592 Install
593 <ulink url='https://docs.docker.com/toolbox/toolbox_install_windows/'>Docker Toolbox for Windows</ulink>
594 for Windows build hosts that do not meet Docker
595 requirements.
596 </para></listitem>
597 <listitem><para>
598 Install
599 <ulink url='https://docs.docker.com/toolbox/toolbox_install_mac/'>Docker Toolbox for MacOS</ulink>
600 for Mac build hosts that do not meet Docker
601 requirements.
602 </para></listitem>
603 <listitem><para>
604 Install
605 <ulink url='https://docs.docker.com/install/linux/docker-ce/centos/'>Docker CE for CentOS</ulink>
606 for Linux build hosts running the CentOS
607 distribution.
608 </para></listitem>
609 <listitem><para>
610 Install
611 <ulink url='https://docs.docker.com/install/linux/docker-ce/debian/'>Docker CE for Debian</ulink>
612 for Linux build hosts running the Debian
613 distribution.
614 </para></listitem>
615 <listitem><para>
616 Install
617 <ulink url='https://docs.docker.com/install/linux/docker-ce/fedora/'>Docker CE for Fedora</ulink>
618 for Linux build hosts running the Fedora
619 distribution.
620 </para></listitem>
621 <listitem><para>
622 Install
623 <ulink url='https://docs.docker.com/install/linux/docker-ce/ubuntu/'>Docker CE for Ubuntu</ulink>
624 for Linux build hosts running the Ubuntu
625 distribution.
626 </para></listitem>
627 </itemizedlist>
628 </para></listitem>
629 <listitem><para>
630 <emphasis>Optionally Orient Yourself With Docker:</emphasis>
631 If you are unfamiliar with Docker and the container
632 concept, you can learn more here -
633 <ulink url='https://docs.docker.com/get-started/'></ulink>.
634 </para></listitem>
635 <listitem><para>
636 <emphasis>Launch Docker or Docker Toolbox:</emphasis>
637 You should be able to launch Docker or the Docker Toolbox
638 and have a terminal shell on your development host.
639 </para></listitem>
640 <listitem><para>
641 <emphasis>Set Up the Containers to Use the Yocto Project:</emphasis>
642 Go to
643 <ulink url='https://github.com/crops/docker-win-mac-docs/wiki'></ulink>
644 and follow the directions for your particular
645 build host (i.e. Linux, Mac, or Windows).</para>
646
647 <para>Once you complete the setup instructions for your
648 machine, you have the Poky, Extensible SDK, and Toaster
649 containers available.
650 You can click those links from the page and learn more
651 about using each of those containers.
652 </para></listitem>
653 </orderedlist>
654 Once you have a container set up, everything is in place to
655 develop just as if you were running on a native Linux machine.
656 If you are going to use the Poky container, see the
657 "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
658 section.
659 If you are going to use the Extensible SDK container, see the
660 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
661 Chapter in the Yocto Project Application Development and the
662 Extensible Software Development Kit (eSDK) manual.
663 If you are going to use the Toaster container, see the
664 "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
665 section in the Toaster User Manual.
666 </para>
667 </section>
668
669 <section id='setting-up-to-use-wsl'>
670 <title>Setting Up to Use Windows Subsystem For Linux (WSLv2)</title>
671
672 <para>
673 With <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'>
674 Windows Subsystem for Linux (WSLv2)</ulink>, you can create a
675 Yocto Project development environment that allows you to build
676 on Windows. You can set up a Linux distribution inside Windows
677 in which you can develop using the Yocto Project.
678 </para>
679
680 <para>
681 Follow these general steps to prepare a Windows machine using WSLv2
682 as your Yocto Project build host:
683 <orderedlist>
684 <listitem><para>
685 <emphasis>Make sure your Windows 10 machine is capable of running WSLv2:</emphasis>
686
687 WSLv2 is only available for Windows 10 builds > 18917. To
688 check which build version you are running, you may open a
689 command prompt on Windows and execute the command "ver".
690 <literallayout class='monospaced'>
691 C:\Users\myuser> ver
692
693 Microsoft Windows [Version 10.0.19041.153]
694 </literallayout>
695 If your build is capable of running WSLv2 you may continue,
696 for more information on this subject or instructions on how
697 to upgrade to WSLv2 visit <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>Windows 10 WSLv2</ulink>
698 </para></listitem>
699 <listitem><para>
700 <emphasis>Install the Linux distribution of your choice inside Windows 10:</emphasis>
701 Once you know your version of Windows 10 supports WSLv2,
702 you can install the distribution of your choice from the
703 Microsoft Store.
704 Open the Microsoft Store and search for Linux. While there
705 are several Linux distributions available, the assumption
706 is that your pick will be one of the distributions supported
707 by the Yocto Project as stated on the instructions for
708 using a native Linux host.
709 After making your selection, simply click "Get" to download
710 and install the distribution.
711 </para></listitem>
712 <listitem><para>
713 <emphasis>Check your Linux distribution is using WSLv2:</emphasis>
714 Open a Windows PowerShell and run:
715 <literallayout class='monospaced'>
716 C:\WINDOWS\system32> wsl -l -v
717 NAME STATE VERSION
718 *Ubuntu Running 2
719 </literallayout>
720 Note the version column which says the WSL version being used by
721 your distribution, on compatible systems, this can be changed back
722 at any point in time.
723 </para></listitem>
724 <listitem><para>
725 <emphasis>Optionally Orient Yourself on WSL:</emphasis>
726 If you are unfamiliar with WSL, you can learn more here -
727 <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'></ulink>.
728 </para></listitem>
729 <listitem><para>
730 <emphasis>Launch your WSL Distibution:</emphasis>
731 From the Windows start menu simply launch your WSL distribution
732 just like any other application.
733 </para></listitem>
734 <listitem><para>
735 <emphasis>Optimize your WSLv2 storage often:</emphasis>
736 Due to the way storage is handled on WSLv2, the storage
737 space used by the undelying Linux distribution is not
738 reflected immedately, and since bitbake heavily uses
739 storage, after several builds, you may be unaware you
740 are running out of space. WSLv2 uses a VHDX file for
741 storage, this issue can be easily avoided by manually
742 optimizing this file often, this can be done in the
743 following way:
744 <orderedlist>
745 <listitem><para>
746 <emphasis>Find the location of your VHDX file:</emphasis>
747 First you need to find the distro app package directory,
748 to achieve this open a Windows Powershell as Administrator
749 and run:
750 <literallayout class='monospaced'>
751 C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName
752 PackageFamilyName
753 -----------------
754 CanonicalGroupLimited.UbuntuonWindows_79abcdefgh
755 </literallayout>
756 You should now replace the <replaceable>PackageFamilyName</replaceable>
757 and your <replaceable>user</replaceable> on the following
758 path to find your VHDX file: <filename>C:\Users\user\AppData\Local\Packages\PackageFamilyName\LocalState\</filename>
759 For example:
760 <literallayout class='monospaced'>
761 ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
762 Mode LastWriteTime Length Name
763 -a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx
764 </literallayout>
765 Your VHDX file path is: <filename>C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx</filename>
766 </para></listitem>
767 <listitem><para><emphasis>Optimize your VHDX file:</emphasis>
768 Open a Windows Powershell as Administrator to optimize
769 your VHDX file, shutting down WSL first:
770 <literallayout class='monospaced'>
771 C:\WINDOWS\system32> wsl --shutdown
772 C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full
773 </literallayout>
774 A progress bar should be shown while optimizing the VHDX file,
775 and storage should now be reflected correctly on the Windows
776 Explorer.
777 </para></listitem>
778 </orderedlist>
779 </para></listitem>
780 </orderedlist>
781 <note>
782 The current implementation of WSLv2 does not have out-of-the-box
783 access to external devices such as those connected through a
784 USB port, but it automatically mounts your <filename>C:</filename>
785 drive on <filename>/mnt/c/</filename> (and others), which
786 you can use to share deploy artifacts to be later flashed on
787 hardware through Windows, but your build directory should not
788 reside inside this mountpoint.
789 </note>
790 Once you have WSLv2 set up, everything is in place to
791 develop just as if you were running on a native Linux machine.
792 If you are going to use the Extensible SDK container, see the
793 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
794 Chapter in the Yocto Project Application Development and the
795 Extensible Software Development Kit (eSDK) manual.
796 If you are going to use the Toaster container, see the
797 "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
798 section in the Toaster User Manual.
799 </para>
800 </section>
801</section>
802
803<section id='locating-yocto-project-source-files'>
804 <title>Locating Yocto Project Source Files</title>
805
806 <para>
807 This section shows you how to locate, fetch and configure the source
808 files you'll need to work with the Yocto Project.
809 <note><title>Notes</title>
810 <itemizedlist>
811 <listitem><para>
812 For concepts and introductory information about Git as it
813 is used in the Yocto Project, see the
814 "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>"
815 section in the Yocto Project Overview and Concepts Manual.
816 </para></listitem>
817 <listitem><para>
818 For concepts on Yocto Project source repositories, see the
819 "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
820 section in the Yocto Project Overview and Concepts Manual."
821 </para></listitem>
822 </itemizedlist>
823 </note>
824 </para>
825
826 <section id='accessing-source-repositories'>
827 <title>Accessing Source Repositories</title>
828
829 <para>
830 Working from a copy of the upstream Yocto Project
831 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
832 is the preferred method for obtaining and using a Yocto Project
833 release.
834 You can view the Yocto Project Source Repositories at
835 <ulink url='&YOCTO_GIT_URL;'></ulink>.
836 In particular, you can find the
837 <filename>poky</filename> repository at
838 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>.
839 </para>
840
841 <para>
842 Use the following procedure to locate the latest upstream copy of
843 the <filename>poky</filename> Git repository:
844 <orderedlist>
845 <listitem><para>
846 <emphasis>Access Repositories:</emphasis>
847 Open a browser and go to
848 <ulink url='&YOCTO_GIT_URL;'></ulink> to access the
849 GUI-based interface into the Yocto Project source
850 repositories.
851 </para></listitem>
852 <listitem><para>
853 <emphasis>Select the Repository:</emphasis>
854 Click on the repository in which you are interested (e.g.
855 <filename>poky</filename>).
856 </para></listitem>
857 <listitem><para>
858 <emphasis>Find the URL Used to Clone the Repository:</emphasis>
859 At the bottom of the page, note the URL used to
860 <ulink url='&YOCTO_DOCS_OM_URL;#git-commands-clone'>clone</ulink>
861 that repository (e.g.
862 <filename>&YOCTO_GIT_URL;/poky</filename>).
863 <note>
864 For information on cloning a repository, see the
865 "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
866 section.
867 </note>
868 </para></listitem>
869 </orderedlist>
870 </para>
871 </section>
872
873 <section id='accessing-index-of-releases'>
874 <title>Accessing Index of Releases</title>
875
876 <para>
877 Yocto Project maintains an Index of Releases area that contains
878 related files that contribute to the Yocto Project.
879 Rather than Git repositories, these files are tarballs that
880 represent snapshots in time of a given component.
881 <note><title>Tip</title>
882 The recommended method for accessing Yocto Project
883 components is to use Git to clone the upstream repository and
884 work from within that locally cloned repository.
885 The procedure in this section exists should you desire a
886 tarball snapshot of any given component.
887 </note>
888 Follow these steps to locate and download a particular tarball:
889 <orderedlist>
890 <listitem><para>
891 <emphasis>Access the Index of Releases:</emphasis>
892 Open a browser and go to
893 <ulink url='&YOCTO_DL_URL;/releases'></ulink> to access the
894 Index of Releases.
895 The list represents released components (e.g.
896 <filename>bitbake</filename>,
897 <filename>sato</filename>, and so on).
898 <note>
899 The <filename>yocto</filename> directory contains the
900 full array of released Poky tarballs.
901 The <filename>poky</filename> directory in the
902 Index of Releases was historically used for very
903 early releases and exists now only for retroactive
904 completeness.
905 </note>
906 </para></listitem>
907 <listitem><para>
908 <emphasis>Select a Component:</emphasis>
909 Click on any released component in which you are interested
910 (e.g. <filename>yocto</filename>).
911 </para></listitem>
912 <listitem><para>
913 <emphasis>Find the Tarball:</emphasis>
914 Drill down to find the associated tarball.
915 For example, click on <filename>yocto-&DISTRO;</filename> to
916 view files associated with the Yocto Project &DISTRO;
917 release (e.g. <filename>poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;.tar.bz2</filename>,
918 which is the released Poky tarball).
919 </para></listitem>
920 <listitem><para>
921 <emphasis>Download the Tarball:</emphasis>
922 Click the tarball to download and save a snapshot of the
923 given component.
924 </para></listitem>
925 </orderedlist>
926 </para>
927 </section>
928
929 <section id='using-the-downloads-page'>
930 <title>Using the Downloads Page</title>
931
932 <para>
933 The
934 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
935 uses a "DOWNLOADS" page from which you can locate and download
936 tarballs of any Yocto Project release.
937 Rather than Git repositories, these files represent snapshot
938 tarballs similar to the tarballs located in the Index of Releases
939 described in the
940 "<link linkend='accessing-index-of-releases'>Accessing Index of Releases</link>"
941 section.
942 <note><title>Tip</title>
943 The recommended method for accessing Yocto Project
944 components is to use Git to clone a repository and work from
945 within that local repository.
946 The procedure in this section exists should you desire a
947 tarball snapshot of any given component.
948 </note>
949 <orderedlist>
950 <listitem><para>
951 <emphasis>Go to the Yocto Project Website:</emphasis>
952 Open The
953 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
954 in your browser.
955 </para></listitem>
956 <listitem><para>
957 <emphasis>Get to the Downloads Area:</emphasis>
958 Select the "DOWNLOADS" item from the pull-down
959 "SOFTWARE" tab menu near the top of the page.
960 </para></listitem>
961 <listitem><para>
962 <emphasis>Select a Yocto Project Release:</emphasis>
963 Use the menu next to "RELEASE" to display and choose
964 a recent or past supported Yocto Project release
965 (e.g. &DISTRO_NAME_NO_CAP;,
966 &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth).
967 <note><title>Tip</title>
968 For a "map" of Yocto Project releases to version
969 numbers, see the
970 <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Releases</ulink>
971 wiki page.
972 </note>
973 You can use the "RELEASE ARCHIVE" link to reveal a menu of
974 all Yocto Project releases.
975 </para></listitem>
976 <listitem><para>
977 <emphasis>Download Tools or Board Support Packages (BSPs):</emphasis>
978 From the "DOWNLOADS" page, you can download tools or
979 BSPs as well.
980 Just scroll down the page and look for what you need.
981 </para></listitem>
982 </orderedlist>
983 </para>
984 </section>
985
986 <section id='accessing-nightly-builds'>
987 <title>Accessing Nightly Builds</title>
988
989 <para>
990 Yocto Project maintains an area for nightly builds that contains
991 tarball releases at <ulink url='&YOCTO_AB_NIGHTLY_URL;'/>.
992 These builds include Yocto Project releases ("poky"),
993 toolchains, and builds for supported machines.
994 </para>
995
996 <para>
997 Should you ever want to access a nightly build of a particular
998 Yocto Project component, use the following procedure:
999 <orderedlist>
1000 <listitem><para>
1001 <emphasis>Locate the Index of Nightly Builds:</emphasis>
1002 Open a browser and go to
1003 <ulink url='&YOCTO_AB_NIGHTLY_URL;'/> to access the
1004 Nightly Builds.
1005 </para></listitem>
1006 <listitem><para>
1007 <emphasis>Select a Date:</emphasis>
1008 Click on the date in which you are interested.
1009 If you want the latest builds, use "CURRENT".
1010 </para></listitem>
1011 <listitem><para>
1012 <emphasis>Select a Build:</emphasis>
1013 Choose the area in which you are interested.
1014 For example, if you are looking for the most recent
1015 toolchains, select the "toolchain" link.
1016 </para></listitem>
1017 <listitem><para>
1018 <emphasis>Find the Tarball:</emphasis>
1019 Drill down to find the associated tarball.
1020 </para></listitem>
1021 <listitem><para>
1022 <emphasis>Download the Tarball:</emphasis>
1023 Click the tarball to download and save a snapshot of the
1024 given component.
1025 </para></listitem>
1026 </orderedlist>
1027 </para>
1028 </section>
1029</section>
1030
1031<section id='cloning-and-checking-out-branches'>
1032 <title>Cloning and Checking Out Branches</title>
1033
1034 <para>
1035 To use the Yocto Project for development, you need a release locally
1036 installed on your development system.
1037 This locally installed set of files is referred to as the
1038 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
1039 in the Yocto Project documentation.
1040 </para>
1041
1042 <para>
1043 The preferred method of creating your Source Directory is by using
1044 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> to clone a local
1045 copy of the upstream <filename>poky</filename> repository.
1046 Working from a cloned copy of the upstream repository allows you
1047 to contribute back into the Yocto Project or to simply work with
1048 the latest software on a development branch.
1049 Because Git maintains and creates an upstream repository with
1050 a complete history of changes and you are working with a local
1051 clone of that repository, you have access to all the Yocto
1052 Project development branches and tag names used in the upstream
1053 repository.
1054 </para>
1055
1056 <section id='cloning-the-poky-repository'>
1057 <title>Cloning the <filename>poky</filename> Repository</title>
1058
1059 <para>
1060 Follow these steps to create a local version of the
1061 upstream
1062 <ulink url='&YOCTO_DOCS_REF_URL;#poky'><filename>poky</filename></ulink>
1063 Git repository.
1064 <orderedlist>
1065 <listitem><para>
1066 <emphasis>Set Your Directory:</emphasis>
1067 Change your working directory to where you want to
1068 create your local copy of
1069 <filename>poky</filename>.
1070 </para></listitem>
1071 <listitem><para>
1072 <emphasis>Clone the Repository:</emphasis>
1073 The following example command clones the
1074 <filename>poky</filename> repository and uses
1075 the default name "poky" for your local repository:
1076 <literallayout class='monospaced'>
1077 $ git clone git://git.yoctoproject.org/poky
1078 Cloning into 'poky'...
1079 remote: Counting objects: 432160, done.
1080 remote: Compressing objects: 100% (102056/102056), done.
1081 remote: Total 432160 (delta 323116), reused 432037 (delta 323000)
1082 Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
1083 Resolving deltas: 100% (323116/323116), done.
1084 Checking connectivity... done.
1085 </literallayout>
1086 Unless you specify a specific development branch or
1087 tag name, Git clones the "master" branch, which results
1088 in a snapshot of the latest development changes for
1089 "master".
1090 For information on how to check out a specific
1091 development branch or on how to check out a local
1092 branch based on a tag name, see the
1093 "<link linkend='checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</link>"
1094 and
1095 <link linkend='checkout-out-by-tag-in-poky'>Checking Out By Tag in Poky</link>"
1096 sections, respectively.</para>
1097
1098 <para>Once the local repository is created, you can
1099 change to that directory and check its status.
1100 Here, the single "master" branch exists on your system
1101 and by default, it is checked out:
1102 <literallayout class='monospaced'>
1103 $ cd ~/poky
1104 $ git status
1105 On branch master
1106 Your branch is up-to-date with 'origin/master'.
1107 nothing to commit, working directory clean
1108 $ git branch
1109 * master
1110 </literallayout>
1111 Your local repository of poky is identical to the
1112 upstream poky repository at the time from which it was
1113 cloned.
1114 As you work with the local branch, you can periodically
1115 use the <filename>git pull &dash;&dash;rebase</filename>
1116 command to be sure you are up-to-date with the upstream
1117 branch.
1118 </para></listitem>
1119 </orderedlist>
1120 </para>
1121 </section>
1122
1123 <section id='checking-out-by-branch-in-poky'>
1124 <title>Checking Out by Branch in Poky</title>
1125
1126 <para>
1127 When you clone the upstream poky repository, you have access to
1128 all its development branches.
1129 Each development branch in a repository is unique as it forks
1130 off the "master" branch.
1131 To see and use the files of a particular development branch
1132 locally, you need to know the branch name and then specifically
1133 check out that development branch.
1134 <note>
1135 Checking out an active development branch by branch name
1136 gives you a snapshot of that particular branch at the time
1137 you check it out.
1138 Further development on top of the branch that occurs after
1139 check it out can occur.
1140 </note>
1141 <orderedlist>
1142 <listitem><para>
1143 <emphasis>Switch to the Poky Directory:</emphasis>
1144 If you have a local poky Git repository, switch to that
1145 directory.
1146 If you do not have the local copy of poky, see the
1147 "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
1148 section.
1149 </para></listitem>
1150 <listitem><para>
1151 <emphasis>Determine Existing Branch Names:</emphasis>
1152 <literallayout class='monospaced'>
1153 $ git branch -a
1154 * master
1155 remotes/origin/1.1_M1
1156 remotes/origin/1.1_M2
1157 remotes/origin/1.1_M3
1158 remotes/origin/1.1_M4
1159 remotes/origin/1.2_M1
1160 remotes/origin/1.2_M2
1161 remotes/origin/1.2_M3
1162 .
1163 .
1164 .
1165 remotes/origin/thud
1166 remotes/origin/thud-next
1167 remotes/origin/warrior
1168 remotes/origin/warrior-next
1169 remotes/origin/zeus
1170 remotes/origin/zeus-next
1171 ... and so on ...
1172 </literallayout>
1173 </para></listitem>
1174 <listitem><para>
1175 <emphasis>Check out the Branch:</emphasis>
1176 Check out the development branch in which you want to work.
1177 For example, to access the files for the Yocto Project
1178 &DISTRO; Release (&DISTRO_NAME;), use the following command:
1179 <literallayout class='monospaced'>
1180 $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
1181 Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
1182 Switched to a new branch '&DISTRO_NAME_NO_CAP;'
1183 </literallayout>
1184 The previous command checks out the "&DISTRO_NAME_NO_CAP;"
1185 development branch and reports that the branch is tracking
1186 the upstream "origin/&DISTRO_NAME_NO_CAP;" branch.</para>
1187
1188 <para>The following command displays the branches
1189 that are now part of your local poky repository.
1190 The asterisk character indicates the branch that is
1191 currently checked out for work:
1192 <literallayout class='monospaced'>
1193 $ git branch
1194 master
1195 * &DISTRO_NAME_NO_CAP;
1196 </literallayout>
1197 </para></listitem>
1198 </orderedlist>
1199 </para>
1200 </section>
1201
1202 <section id='checkout-out-by-tag-in-poky'>
1203 <title>Checking Out by Tag in Poky</title>
1204
1205 <para>
1206 Similar to branches, the upstream repository uses tags
1207 to mark specific commits associated with significant points in
1208 a development branch (i.e. a release point or stage of a
1209 release).
1210 You might want to set up a local branch based on one of those
1211 points in the repository.
1212 The process is similar to checking out by branch name except you
1213 use tag names.
1214 <note>
1215 Checking out a branch based on a tag gives you a
1216 stable set of files not affected by development on the
1217 branch above the tag.
1218 </note>
1219 <orderedlist>
1220 <listitem><para>
1221 <emphasis>Switch to the Poky Directory:</emphasis>
1222 If you have a local poky Git repository, switch to that
1223 directory.
1224 If you do not have the local copy of poky, see the
1225 "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
1226 section.
1227 </para></listitem>
1228 <listitem><para>
1229 <emphasis>Fetch the Tag Names:</emphasis>
1230 To checkout the branch based on a tag name, you need to
1231 fetch the upstream tags into your local repository:
1232 <literallayout class='monospaced'>
1233 $ git fetch --tags
1234 $
1235 </literallayout>
1236 </para></listitem>
1237 <listitem><para>
1238 <emphasis>List the Tag Names:</emphasis>
1239 You can list the tag names now:
1240 <literallayout class='monospaced'>
1241 $ git tag
1242 1.1_M1.final
1243 1.1_M1.rc1
1244 1.1_M1.rc2
1245 1.1_M2.final
1246 1.1_M2.rc1
1247 .
1248 .
1249 .
1250 yocto-2.5
1251 yocto-2.5.1
1252 yocto-2.5.2
1253 yocto-2.5.3
1254 yocto-2.6
1255 yocto-2.6.1
1256 yocto-2.6.2
1257 yocto-2.7
1258 yocto_1.5_M5.rc8
1259 </literallayout>
1260 </para></listitem>
1261 <listitem><para>
1262 <emphasis>Check out the Branch:</emphasis>
1263 <literallayout class='monospaced'>
1264 $ git checkout tags/&DISTRO_REL_TAG; -b my_yocto_&DISTRO;
1265 Switched to a new branch 'my_yocto_&DISTRO;'
1266 $ git branch
1267 master
1268 * my_yocto_&DISTRO;
1269 </literallayout>
1270 The previous command creates and checks out a local
1271 branch named "my_yocto_&DISTRO;", which is based on
1272 the commit in the upstream poky repository that has
1273 the same tag.
1274 In this example, the files you have available locally
1275 as a result of the <filename>checkout</filename>
1276 command are a snapshot of the
1277 "&DISTRO_NAME_NO_CAP;" development branch at the point
1278 where Yocto Project &DISTRO; was released.
1279 </para></listitem>
1280 </orderedlist>
1281 </para>
1282 </section>
1283</section>
1284
1285</chapter>
1286<!--
1287vim: expandtab tw=80 ts=4
1288-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-04-22 19:11:02 +0000