summaryrefslogtreecommitdiffstats
path: root/documentation/overview-manual/overview-manual-development-environment.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/overview-manual/overview-manual-development-environment.xml')
-rw-r--r--documentation/overview-manual/overview-manual-development-environment.xml954
1 files changed, 0 insertions, 954 deletions
diff --git a/documentation/overview-manual/overview-manual-development-environment.xml b/documentation/overview-manual/overview-manual-development-environment.xml
deleted file mode 100644
index 08ad071316..0000000000
--- a/documentation/overview-manual/overview-manual-development-environment.xml
+++ /dev/null
@@ -1,954 +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='overview-development-environment'>
7<title>The Yocto Project Development Environment</title>
8
9<para>
10 This chapter takes a look at the Yocto Project development
11 environment.
12 The chapter provides Yocto Project Development environment concepts that
13 help you understand how work is accomplished in an open source environment,
14 which is very different as compared to work accomplished in a closed,
15 proprietary environment.
16</para>
17
18<para>
19 Specifically, this chapter addresses open source philosophy, source
20 repositories, workflows, Git, and licensing.
21</para>
22
23<section id='open-source-philosophy'>
24 <title>Open Source Philosophy</title>
25
26 <para>
27 Open source philosophy is characterized by software development
28 directed by peer production and collaboration through an active
29 community of developers.
30 Contrast this to the more standard centralized development models
31 used by commercial software companies where a finite set of developers
32 produces a product for sale using a defined set of procedures that
33 ultimately result in an end product whose architecture and source
34 material are closed to the public.
35 </para>
36
37 <para>
38 Open source projects conceptually have differing concurrent agendas,
39 approaches, and production.
40 These facets of the development process can come from anyone in the
41 public (community) who has a stake in the software project.
42 The open source environment contains new copyright, licensing, domain,
43 and consumer issues that differ from the more traditional development
44 environment.
45 In an open source environment, the end product, source material,
46 and documentation are all available to the public at no cost.
47 </para>
48
49 <para>
50 A benchmark example of an open source project is the Linux kernel,
51 which was initially conceived and created by Finnish computer science
52 student Linus Torvalds in 1991.
53 Conversely, a good example of a non-open source project is the
54 <trademark class='registered'>Windows</trademark> family of operating
55 systems developed by
56 <trademark class='registered'>Microsoft</trademark> Corporation.
57 </para>
58
59 <para>
60 Wikipedia has a good historical description of the Open Source
61 Philosophy
62 <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>.
63 You can also find helpful information on how to participate in the
64 Linux Community
65 <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>.
66 </para>
67</section>
68
69<section id='gs-the-development-host'>
70 <title>The Development Host</title>
71
72 <para>
73 A development host or
74 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
75 is key to using the Yocto Project.
76 Because the goal of the Yocto Project is to develop images or
77 applications that run on embedded hardware, development of those
78 images and applications generally takes place on a system not
79 intended to run the software - the development host.
80 </para>
81
82 <para>
83 You need to set up a development host in order to use it with the
84 Yocto Project.
85 Most find that it is best to have a native Linux machine function as
86 the development host.
87 However, it is possible to use a system that does not run Linux
88 as its operating system as your development host.
89 When you have a Mac or Windows-based system, you can set it up
90 as the development host by using
91 <ulink url='https://github.com/crops/poky-container'>CROPS</ulink>,
92 which leverages
93 <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
94 Once you take the steps to set up a CROPS machine, you effectively
95 have access to a shell environment that is similar to what you see
96 when using a Linux-based development host.
97 For the steps needed to set up a system using CROPS, see the
98 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
99 section in the Yocto Project Development Tasks Manual.
100 </para>
101
102 <para>
103 If your development host is going to be a system that runs a Linux
104 distribution, steps still exist that you must take to prepare the
105 system for use with the Yocto Project.
106 You need to be sure that the Linux distribution on the system is
107 one that supports the Yocto Project.
108 You also need to be sure that the correct set of host packages are
109 installed that allow development using the Yocto Project.
110 For the steps needed to set up a development host that runs Linux,
111 see the
112 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host'>Setting Up a Native Linux Host</ulink>"
113 section in the Yocto Project Development Tasks Manual.
114 </para>
115
116 <para>
117 Once your development host is set up to use the Yocto Project,
118 several methods exist for you to do work in the Yocto Project
119 environment:
120 <itemizedlist>
121 <listitem><para>
122 <emphasis>Command Lines, BitBake, and Shells:</emphasis>
123 Traditional development in the Yocto Project involves using the
124 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>,
125 which uses BitBake, in a command-line environment from a shell
126 on your development host.
127 You can accomplish this from a host that is a native Linux
128 machine or from a host that has been set up with CROPS.
129 Either way, you create, modify, and build images and
130 applications all within a shell-based environment using
131 components and tools available through your Linux distribution
132 and the Yocto Project.</para>
133
134 <para>For a general flow of the build procedures, see the
135 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>"
136 section in the Yocto Project Development Tasks Manual.
137 </para></listitem>
138 <listitem><para>
139 <emphasis>Board Support Package (BSP) Development:</emphasis>
140 Development of BSPs involves using the Yocto Project to
141 create and test layers that allow easy development of
142 images and applications targeted for specific hardware.
143 To development BSPs, you need to take some additional steps
144 beyond what was described in setting up a development host.
145 </para>
146
147 <para>The
148 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>
149 provides BSP-related development information.
150 For specifics on development host preparation, see the
151 "<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>"
152 section in the Yocto Project Board Support Package (BSP)
153 Developer's Guide.
154 </para></listitem>
155 <listitem><para>
156 <emphasis>Kernel Development:</emphasis>
157 If you are going to be developing kernels using the Yocto
158 Project you likely will be using <filename>devtool</filename>.
159 A workflow using <filename>devtool</filename> makes kernel
160 development quicker by reducing iteration cycle times.</para>
161
162 <para>The
163 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>
164 provides kernel-related development information.
165 For specifics on development host preparation, see the
166 "<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>"
167 section in the Yocto Project Linux Kernel Development Manual.
168 </para></listitem>
169 <listitem><para>
170 <emphasis>Using Toaster:</emphasis>
171 The other Yocto Project development method that involves an
172 interface that effectively puts the Yocto Project into the
173 background is Toaster.
174 Toaster provides an interface to the OpenEmbedded build system.
175 The interface enables you to configure and run your builds.
176 Information about builds is collected and stored in a database.
177 You can use Toaster to configure and start builds on multiple
178 remote build servers.</para>
179
180 <para>For steps that show you how to set up your development
181 host to use Toaster and on how to use Toaster in general,
182 see the
183 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
184 </para></listitem>
185 </itemizedlist>
186 </para>
187</section>
188
189<section id='yocto-project-repositories'>
190 <title>Yocto Project Source Repositories</title>
191
192 <para>
193 The Yocto Project team maintains complete source repositories for all
194 Yocto Project files at
195 <ulink url='&YOCTO_GIT_URL;'></ulink>.
196 This web-based source code browser is organized into categories by
197 function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and
198 so forth.
199 From the interface, you can click on any particular item in the "Name"
200 column and see the URL at the bottom of the page that you need to clone
201 a Git repository for that particular item.
202 Having a local Git repository of the
203 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
204 which is usually named "poky", allows
205 you to make changes, contribute to the history, and ultimately enhance
206 the Yocto Project's tools, Board Support Packages, and so forth.
207 </para>
208
209 <para>
210 For any supported release of Yocto Project, you can also go to the
211 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and
212 select the "DOWNLOADS" item from the "SOFTWARE" menu and get a
213 released tarball of the <filename>poky</filename> repository, any
214 supported BSP tarball, or Yocto Project tools.
215 Unpacking these tarballs gives you a snapshot of the released
216 files.
217 <note><title>Notes</title>
218 <itemizedlist>
219 <listitem><para>
220 The recommended method for setting up the Yocto Project
221 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
222 and the files for supported BSPs
223 (e.g., <filename>meta-intel</filename>) is to use
224 <link linkend='git'>Git</link> to create a local copy of
225 the upstream repositories.
226 </para></listitem>
227 <listitem><para>
228 Be sure to always work in matching branches for both
229 the selected BSP repository and the Source Directory
230 (i.e. <filename>poky</filename>) repository.
231 For example, if you have checked out the "master" branch
232 of <filename>poky</filename> and you are going to use
233 <filename>meta-intel</filename>, be sure to checkout the
234 "master" branch of <filename>meta-intel</filename>.
235 </para></listitem>
236 </itemizedlist>
237 </note>
238 </para>
239
240 <para>
241 In summary, here is where you can get the project files needed for
242 development:
243 <itemizedlist>
244 <listitem><para id='source-repositories'>
245 <emphasis>
246 <ulink url='&YOCTO_GIT_URL;'>Source Repositories:</ulink>
247 </emphasis>
248 This area contains IDE Plugins, Matchbox, Poky, Poky Support,
249 Tools, Yocto Linux Kernel, and Yocto Metadata Layers.
250 You can create local copies of Git repositories for each of
251 these areas.</para>
252
253 <para>
254 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
255 For steps on how to view and access these upstream Git
256 repositories, see the
257 "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-source-repositories'>Accessing Source Repositories</ulink>"
258 Section in the Yocto Project Development Tasks Manual.
259 </para></listitem>
260 <listitem><para><anchor id='index-downloads' />
261 <emphasis>
262 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink>
263 </emphasis>
264 This is an index of releases such as Poky, Pseudo, installers
265 for cross-development toolchains, miscellaneous support
266 and all released versions of Yocto Project in the form of
267 images or tarballs.
268 Downloading and extracting these files does not produce a local
269 copy of the Git repository but rather a snapshot of a
270 particular release or image.</para>
271
272 <para>
273 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" />
274 For steps on how to view and access these files, see the
275 "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-index-of-releases'>Accessing Index of Releases</ulink>"
276 section in the Yocto Project Development Tasks Manual.
277 </para></listitem>
278 <listitem><para id='downloads-page'>
279 <emphasis>"DOWNLOADS" page for the
280 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
281 </emphasis></para>
282
283 <para>The Yocto Project website includes a "DOWNLOADS" page
284 accessible through the "SOFTWARE" menu that allows you to
285 download any Yocto Project release, tool, and Board Support
286 Package (BSP) in tarball form.
287 The tarballs are similar to those found in the
288 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink>
289 area.</para>
290
291 <para>
292 <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
293 For steps on how to use the "DOWNLOADS" page, see the
294 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-downloads-page'>Using the Downloads Page</ulink>"
295 section in the Yocto Project Development Tasks Manual.
296 </para></listitem>
297 </itemizedlist>
298 </para>
299</section>
300
301<section id='gs-git-workflows-and-the-yocto-project'>
302 <title>Git Workflows and the Yocto Project</title>
303
304 <para>
305 Developing using the Yocto Project likely requires the use of
306 <link linkend='git'>Git</link>.
307 Git is a free, open source distributed version control system
308 used as part of many collaborative design environments.
309 This section provides workflow concepts using the Yocto Project and
310 Git.
311 In particular, the information covers basic practices that describe
312 roles and actions in a collaborative development environment.
313 <note>
314 If you are familiar with this type of development environment, you
315 might not want to read this section.
316 </note>
317 </para>
318
319 <para>
320 The Yocto Project files are maintained using Git in "branches"
321 whose Git histories track every change and whose structures
322 provide branches for all diverging functionality.
323 Although there is no need to use Git, many open source projects do so.
324 <para>
325
326 </para>
327 For the Yocto Project, a key individual called the "maintainer" is
328 responsible for the integrity of the "master" branch of a given Git
329 repository.
330 The "master" branch is the "upstream" repository from which final or
331 most recent builds of a project occur.
332 The maintainer is responsible for accepting changes from other
333 developers and for organizing the underlying branch structure to
334 reflect release strategies and so forth.
335 <note>
336 For information on finding out who is responsible for (maintains)
337 a particular area of code in the Yocto Project, see the
338 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
339 section of the Yocto Project Development Tasks Manual.
340 </note>
341 </para>
342
343 <para>
344 The Yocto Project <filename>poky</filename> Git repository also has an
345 upstream contribution Git repository named
346 <filename>poky-contrib</filename>.
347 You can see all the branches in this repository using the web interface
348 of the
349 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
350 within the "Poky Support" area.
351 These branches hold changes (commits) to the project that have been
352 submitted or committed by the Yocto Project development team and by
353 community members who contribute to the project.
354 The maintainer determines if the changes are qualified to be moved
355 from the "contrib" branches into the "master" branch of the Git
356 repository.
357 </para>
358
359 <para>
360 Developers (including contributing community members) create and
361 maintain cloned repositories of upstream branches.
362 The cloned repositories are local to their development platforms and
363 are used to develop changes.
364 When a developer is satisfied with a particular feature or change,
365 they "push" the change to the appropriate "contrib" repository.
366 </para>
367
368 <para>
369 Developers are responsible for keeping their local repository
370 up-to-date with whatever upstream branch they are working against.
371 They are also responsible for straightening out any conflicts that
372 might arise within files that are being worked on simultaneously by
373 more than one person.
374 All this work is done locally on the development host before
375 anything is pushed to a "contrib" area and examined at the maintainer's
376 level.
377 </para>
378
379 <para>
380 A somewhat formal method exists by which developers commit changes
381 and push them into the "contrib" area and subsequently request that
382 the maintainer include them into an upstream branch.
383 This process is called "submitting a patch" or "submitting a change."
384 For information on submitting patches and changes, see the
385 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
386 section in the Yocto Project Development Tasks Manual.
387 </para>
388
389 <para>
390 In summary, a single point of entry
391 exists for changes into a "master" or development branch of the
392 Git repository, which is controlled by the project's maintainer.
393 And, a set of developers exist who independently develop, test, and
394 submit changes to "contrib" areas for the maintainer to examine.
395 The maintainer then chooses which changes are going to become a
396 permanent part of the project.
397 </para>
398
399 <para>
400 <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
401 </para>
402
403 <para>
404 While each development environment is unique, there are some best
405 practices or methods that help development run smoothly.
406 The following list describes some of these practices.
407 For more information about Git workflows, see the workflow topics in
408 the
409 <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
410 <itemizedlist>
411 <listitem><para>
412 <emphasis>Make Small Changes:</emphasis>
413 It is best to keep the changes you commit small as compared to
414 bundling many disparate changes into a single commit.
415 This practice not only keeps things manageable but also allows
416 the maintainer to more easily include or refuse changes.
417 </para></listitem>
418 <listitem><para>
419 <emphasis>Make Complete Changes:</emphasis>
420 It is also good practice to leave the repository in a
421 state that allows you to still successfully build your project.
422 In other words, do not commit half of a feature,
423 then add the other half as a separate, later commit.
424 Each commit should take you from one buildable project state
425 to another buildable state.
426 </para></listitem>
427 <listitem><para>
428 <emphasis>Use Branches Liberally:</emphasis>
429 It is very easy to create, use, and delete local branches in
430 your working Git repository on the development host.
431 You can name these branches anything you like.
432 It is helpful to give them names associated with the particular
433 feature or change on which you are working.
434 Once you are done with a feature or change and have merged it
435 into your local master branch, simply discard the temporary
436 branch.
437 </para></listitem>
438 <listitem><para>
439 <emphasis>Merge Changes:</emphasis>
440 The <filename>git merge</filename> command allows you to take
441 the changes from one branch and fold them into another branch.
442 This process is especially helpful when more than a single
443 developer might be working on different parts of the same
444 feature.
445 Merging changes also automatically identifies any collisions
446 or "conflicts" that might happen as a result of the same lines
447 of code being altered by two different developers.
448 </para></listitem>
449 <listitem><para>
450 <emphasis>Manage Branches:</emphasis>
451 Because branches are easy to use, you should use a system
452 where branches indicate varying levels of code readiness.
453 For example, you can have a "work" branch to develop in, a
454 "test" branch where the code or change is tested, a "stage"
455 branch where changes are ready to be committed, and so forth.
456 As your project develops, you can merge code across the
457 branches to reflect ever-increasing stable states of the
458 development.
459 </para></listitem>
460 <listitem><para>
461 <emphasis>Use Push and Pull:</emphasis>
462 The push-pull workflow is based on the concept of developers
463 "pushing" local commits to a remote repository, which is
464 usually a contribution repository.
465 This workflow is also based on developers "pulling" known
466 states of the project down into their local development
467 repositories.
468 The workflow easily allows you to pull changes submitted by
469 other developers from the upstream repository into your
470 work area ensuring that you have the most recent software
471 on which to develop.
472 The Yocto Project has two scripts named
473 <filename>create-pull-request</filename> and
474 <filename>send-pull-request</filename> that ship with the
475 release to facilitate this workflow.
476 You can find these scripts in the <filename>scripts</filename>
477 folder of the
478 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
479 For information on how to use these scripts, see the
480 "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</ulink>"
481 section in the Yocto Project Development Tasks Manual.
482 </para></listitem>
483 <listitem><para>
484 <emphasis>Patch Workflow:</emphasis>
485 This workflow allows you to notify the maintainer through an
486 email that you have a change (or patch) you would like
487 considered for the "master" branch of the Git repository.
488 To send this type of change, you format the patch and then
489 send the email using the Git commands
490 <filename>git format-patch</filename> and
491 <filename>git send-email</filename>.
492 For information on how to use these scripts, see the
493 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
494 section in the Yocto Project Development Tasks Manual.
495 </para></listitem>
496 </itemizedlist>
497 </para>
498</section>
499
500<section id='git'>
501 <title>Git</title>
502
503 <para>
504 The Yocto Project makes extensive use of Git, which is a
505 free, open source distributed version control system.
506 Git supports distributed development, non-linear development,
507 and can handle large projects.
508 It is best that you have some fundamental understanding
509 of how Git tracks projects and how to work with Git if
510 you are going to use the Yocto Project for development.
511 This section provides a quick overview of how Git works and
512 provides you with a summary of some essential Git commands.
513 <note><title>Notes</title>
514 <itemizedlist>
515 <listitem><para>
516 For more information on Git, see
517 <ulink url='http://git-scm.com/documentation'></ulink>.
518 </para></listitem>
519 <listitem><para>
520 If you need to download Git, it is recommended that you add
521 Git to your system through your distribution's "software
522 store" (e.g. for Ubuntu, use the Ubuntu Software feature).
523 For the Git download page, see
524 <ulink url='http://git-scm.com/download'></ulink>.
525 </para></listitem>
526 <listitem><para>
527 For information beyond the introductory nature in this
528 section, see the
529 "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
530 section in the Yocto Project Development Tasks Manual.
531 </para></listitem>
532 </itemizedlist>
533 </note>
534 </para>
535
536 <section id='repositories-tags-and-branches'>
537 <title>Repositories, Tags, and Branches</title>
538
539 <para>
540 As mentioned briefly in the previous section and also in the
541 "<link linkend='gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</link>"
542 section, the Yocto Project maintains source repositories at
543 <ulink url='&YOCTO_GIT_URL;'></ulink>.
544 If you look at this web-interface of the repositories, each item
545 is a separate Git repository.
546 </para>
547
548 <para>
549 Git repositories use branching techniques that track content
550 change (not files) within a project (e.g. a new feature or updated
551 documentation).
552 Creating a tree-like structure based on project divergence allows
553 for excellent historical information over the life of a project.
554 This methodology also allows for an environment from which you can
555 do lots of local experimentation on projects as you develop
556 changes or new features.
557 </para>
558
559 <para>
560 A Git repository represents all development efforts for a given
561 project.
562 For example, the Git repository <filename>poky</filename> contains
563 all changes and developments for that repository over the course
564 of its entire life.
565 That means that all changes that make up all releases are captured.
566 The repository maintains a complete history of changes.
567 </para>
568
569 <para>
570 You can create a local copy of any repository by "cloning" it
571 with the <filename>git clone</filename> command.
572 When you clone a Git repository, you end up with an identical
573 copy of the repository on your development system.
574 Once you have a local copy of a repository, you can take steps to
575 develop locally.
576 For examples on how to clone Git repositories, see the
577 "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
578 section in the Yocto Project Development Tasks Manual.
579 </para>
580
581 <para>
582 It is important to understand that Git tracks content change and
583 not files.
584 Git uses "branches" to organize different development efforts.
585 For example, the <filename>poky</filename> repository has
586 several branches that include the current "&DISTRO_NAME_NO_CAP;"
587 branch, the "master" branch, and many branches for past
588 Yocto Project releases.
589 You can see all the branches by going to
590 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
591 clicking on the
592 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
593 link beneath the "Branch" heading.
594 </para>
595
596 <para>
597 Each of these branches represents a specific area of development.
598 The "master" branch represents the current or most recent
599 development.
600 All other branches represent offshoots of the "master" branch.
601 </para>
602
603 <para>
604 When you create a local copy of a Git repository, the copy has
605 the same set of branches as the original.
606 This means you can use Git to create a local working area
607 (also called a branch) that tracks a specific development branch
608 from the upstream source Git repository.
609 in other words, you can define your local Git environment to
610 work on any development branch in the repository.
611 To help illustrate, consider the following example Git commands:
612 <literallayout class='monospaced'>
613 $ cd ~
614 $ git clone git://git.yoctoproject.org/poky
615 $ cd poky
616 $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
617 </literallayout>
618 In the previous example after moving to the home directory, the
619 <filename>git clone</filename> command creates a
620 local copy of the upstream <filename>poky</filename> Git repository.
621 By default, Git checks out the "master" branch for your work.
622 After changing the working directory to the new local repository
623 (i.e. <filename>poky</filename>), the
624 <filename>git checkout</filename> command creates
625 and checks out a local branch named "&DISTRO_NAME_NO_CAP;", which
626 tracks the upstream "origin/&DISTRO_NAME_NO_CAP;" branch.
627 Changes you make while in this branch would ultimately affect
628 the upstream "&DISTRO_NAME_NO_CAP;" branch of the
629 <filename>poky</filename> repository.
630 </para>
631
632 <para>
633 It is important to understand that when you create and checkout a
634 local working branch based on a branch name,
635 your local environment matches the "tip" of that particular
636 development branch at the time you created your local branch,
637 which could be different from the files in the "master" branch
638 of the upstream repository.
639 In other words, creating and checking out a local branch based on
640 the "&DISTRO_NAME_NO_CAP;" branch name is not the same as
641 checking out the "master" branch in the repository.
642 Keep reading to see how you create a local snapshot of a Yocto
643 Project Release.
644 </para>
645
646 <para>
647 Git uses "tags" to mark specific changes in a repository branch
648 structure.
649 Typically, a tag is used to mark a special point such as the final
650 change (or commit) before a project is released.
651 You can see the tags used with the <filename>poky</filename> Git
652 repository by going to
653 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
654 clicking on the
655 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
656 link beneath the "Tag" heading.
657 </para>
658
659 <para>
660 Some key tags for the <filename>poky</filename> repository are
661 <filename>jethro-14.0.3</filename>,
662 <filename>morty-16.0.1</filename>,
663 <filename>pyro-17.0.0</filename>, and
664 <filename>&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>.
665 These tags represent Yocto Project releases.
666 </para>
667
668 <para>
669 When you create a local copy of the Git repository, you also
670 have access to all the tags in the upstream repository.
671 Similar to branches, you can create and checkout a local working
672 Git branch based on a tag name.
673 When you do this, you get a snapshot of the Git repository that
674 reflects the state of the files when the change was made associated
675 with that tag.
676 The most common use is to checkout a working branch that matches
677 a specific Yocto Project release.
678 Here is an example:
679 <literallayout class='monospaced'>
680 $ cd ~
681 $ git clone git://git.yoctoproject.org/poky
682 $ cd poky
683 $ git fetch --tags
684 $ git checkout tags/rocko-18.0.0 -b my_rocko-18.0.0
685 </literallayout>
686 In this example, the name of the top-level directory of your
687 local Yocto Project repository is <filename>poky</filename>.
688 After moving to the <filename>poky</filename> directory, the
689 <filename>git fetch</filename> command makes all the upstream
690 tags available locally in your repository.
691 Finally, the <filename>git checkout</filename> command
692 creates and checks out a branch named "my-rocko-18.0.0" that is
693 based on the upstream branch whose "HEAD" matches the
694 commit in the repository associated with the "rocko-18.0.0" tag.
695 The files in your repository now exactly match that particular
696 Yocto Project release as it is tagged in the upstream Git
697 repository.
698 It is important to understand that when you create and
699 checkout a local working branch based on a tag, your environment
700 matches a specific point in time and not the entire development
701 branch (i.e. from the "tip" of the branch backwards).
702 </para>
703 </section>
704
705 <section id='basic-commands'>
706 <title>Basic Commands</title>
707
708 <para>
709 Git has an extensive set of commands that lets you manage changes
710 and perform collaboration over the life of a project.
711 Conveniently though, you can manage with a small set of basic
712 operations and workflows once you understand the basic
713 philosophy behind Git.
714 You do not have to be an expert in Git to be functional.
715 A good place to look for instruction on a minimal set of Git
716 commands is
717 <ulink url='http://git-scm.com/documentation'>here</ulink>.
718 </para>
719
720 <para>
721 The following list of Git commands briefly describes some basic
722 Git operations as a way to get started.
723 As with any set of commands, this list (in most cases) simply shows
724 the base command and omits the many arguments it supports.
725 See the Git documentation for complete descriptions and strategies
726 on how to use these commands:
727 <itemizedlist>
728 <listitem><para>
729 <emphasis><filename>git init</filename>:</emphasis>
730 Initializes an empty Git repository.
731 You cannot use Git commands unless you have a
732 <filename>.git</filename> repository.
733 </para></listitem>
734 <listitem><para id='git-commands-clone'>
735 <emphasis><filename>git clone</filename>:</emphasis>
736 Creates a local clone of a Git repository that is on
737 equal footing with a fellow developer's Git repository
738 or an upstream repository.
739 </para></listitem>
740 <listitem><para>
741 <emphasis><filename>git add</filename>:</emphasis>
742 Locally stages updated file contents to the index that
743 Git uses to track changes.
744 You must stage all files that have changed before you
745 can commit them.
746 </para></listitem>
747 <listitem><para>
748 <emphasis><filename>git commit</filename>:</emphasis>
749 Creates a local "commit" that documents the changes you
750 made.
751 Only changes that have been staged can be committed.
752 Commits are used for historical purposes, for determining
753 if a maintainer of a project will allow the change,
754 and for ultimately pushing the change from your local
755 Git repository into the project's upstream repository.
756 </para></listitem>
757 <listitem><para>
758 <emphasis><filename>git status</filename>:</emphasis>
759 Reports any modified files that possibly need to be
760 staged and gives you a status of where you stand regarding
761 local commits as compared to the upstream repository.
762 </para></listitem>
763 <listitem><para>
764 <emphasis><filename>git checkout</filename> <replaceable>branch-name</replaceable>:</emphasis>
765 Changes your local working branch and in this form
766 assumes the local branch already exists.
767 This command is analogous to "cd".
768 </para></listitem>
769 <listitem><para>
770 <emphasis><filename>git checkout –b</filename> <replaceable>working-branch</replaceable> <replaceable>upstream-branch</replaceable>:</emphasis>
771 Creates and checks out a working branch on your local
772 machine.
773 The local branch tracks the upstream branch.
774 You can use your local branch to isolate your work.
775 It is a good idea to use local branches when adding
776 specific features or changes.
777 Using isolated branches facilitates easy removal of
778 changes if they do not work out.
779 </para></listitem>
780 <listitem><para><emphasis><filename>git branch</filename>:</emphasis>
781 Displays the existing local branches associated with your
782 local repository.
783 The branch that you have currently checked out is noted
784 with an asterisk character.
785 </para></listitem>
786 <listitem><para>
787 <emphasis><filename>git branch -D</filename> <replaceable>branch-name</replaceable>:</emphasis>
788 Deletes an existing local branch.
789 You need to be in a local branch other than the one you
790 are deleting in order to delete
791 <replaceable>branch-name</replaceable>.
792 </para></listitem>
793 <listitem><para>
794 <emphasis><filename>git pull --rebase</filename>:</emphasis>
795 Retrieves information from an upstream Git repository
796 and places it in your local Git repository.
797 You use this command to make sure you are synchronized with
798 the repository from which you are basing changes
799 (.e.g. the "master" branch).
800 The "--rebase" option ensures that any local commits you
801 have in your branch are preserved at the top of your
802 local branch.
803 </para></listitem>
804 <listitem><para>
805 <emphasis><filename>git push</filename> <replaceable>repo-name</replaceable> <replaceable>local-branch</replaceable><filename>:</filename><replaceable>upstream-branch</replaceable>:</emphasis>
806 Sends all your committed local changes to the upstream Git
807 repository that your local repository is tracking
808 (e.g. a contribution repository).
809 The maintainer of the project draws from these repositories
810 to merge changes (commits) into the appropriate branch
811 of project's upstream repository.
812 </para></listitem>
813 <listitem><para>
814 <emphasis><filename>git merge</filename>:</emphasis>
815 Combines or adds changes from one
816 local branch of your repository with another branch.
817 When you create a local Git repository, the default branch
818 is named "master".
819 A typical workflow is to create a temporary branch that is
820 based off "master" that you would use for isolated work.
821 You would make your changes in that isolated branch,
822 stage and commit them locally, switch to the "master"
823 branch, and then use the <filename>git merge</filename>
824 command to apply the changes from your isolated branch
825 into the currently checked out branch (e.g. "master").
826 After the merge is complete and if you are done with
827 working in that isolated branch, you can safely delete
828 the isolated branch.
829 </para></listitem>
830 <listitem><para>
831 <emphasis><filename>git cherry-pick</filename> <replaceable>commits</replaceable>:</emphasis>
832 Choose and apply specific commits from one branch
833 into another branch.
834 There are times when you might not be able to merge
835 all the changes in one branch with
836 another but need to pick out certain ones.
837 </para></listitem>
838 <listitem><para>
839 <emphasis><filename>gitk</filename>:</emphasis>
840 Provides a GUI view of the branches and changes in your
841 local Git repository.
842 This command is a good way to graphically see where things
843 have diverged in your local repository.
844 <note>
845 You need to install the <filename>gitk</filename>
846 package on your development system to use this
847 command.
848 </note>
849 </para></listitem>
850 <listitem><para>
851 <emphasis><filename>git log</filename>:</emphasis>
852 Reports a history of your commits to the repository.
853 This report lists all commits regardless of whether you
854 have pushed them upstream or not.
855 </para></listitem>
856 <listitem><para>
857 <emphasis><filename>git diff</filename>:</emphasis>
858 Displays line-by-line differences between a local
859 working file and the same file as understood by Git.
860 This command is useful to see what you have changed
861 in any given file.
862 </para></listitem>
863 </itemizedlist>
864 </para>
865 </section>
866</section>
867
868<section id='licensing'>
869 <title>Licensing</title>
870
871 <para>
872 Because open source projects are open to the public, they have
873 different licensing structures in place.
874 License evolution for both Open Source and Free Software has an
875 interesting history.
876 If you are interested in this history, you can find basic information
877 here:
878 <itemizedlist>
879 <listitem><para>
880 <ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink>
881 </para></listitem>
882 <listitem><para>
883 <ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license history</ulink>
884 </para></listitem>
885 </itemizedlist>
886 </para>
887
888 <para>
889 In general, the Yocto Project is broadly licensed under the
890 Massachusetts Institute of Technology (MIT) License.
891 MIT licensing permits the reuse of software within proprietary
892 software as long as the license is distributed with that software.
893 MIT is also compatible with the GNU General Public License (GPL).
894 Patches to the Yocto Project follow the upstream licensing scheme.
895 You can find information on the MIT license
896 <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>.
897 You can find information on the GNU GPL
898 <ulink url='http://www.opensource.org/licenses/LGPL-3.0'>here</ulink>.
899 </para>
900
901 <para>
902 When you build an image using the Yocto Project, the build process
903 uses a known list of licenses to ensure compliance.
904 You can find this list in the
905 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
906 at <filename>meta/files/common-licenses</filename>.
907 Once the build completes, the list of all licenses found and used
908 during that build are kept in the
909 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
910 at <filename>tmp/deploy/licenses</filename>.
911 </para>
912
913 <para>
914 If a module requires a license that is not in the base list, the
915 build process generates a warning during the build.
916 These tools make it easier for a developer to be certain of the
917 licenses with which their shipped products must comply.
918 However, even with these tools it is still up to the developer to
919 resolve potential licensing issues.
920 </para>
921
922 <para>
923 The base list of licenses used by the build process is a combination
924 of the Software Package Data Exchange (SPDX) list and the Open
925 Source Initiative (OSI) projects.
926 <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of
927 the Linux Foundation that maintains a specification for a standard
928 format for communicating the components, licenses, and copyrights
929 associated with a software package.
930 <ulink url='http://opensource.org'>OSI</ulink> is a corporation
931 dedicated to the Open Source Definition and the effort for reviewing
932 and approving licenses that conform to the Open Source Definition
933 (OSD).
934 </para>
935
936 <para>
937 You can find a list of the combined SPDX and OSI licenses that the
938 Yocto Project uses in the
939 <filename>meta/files/common-licenses</filename> directory in your
940 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
941 </para>
942
943 <para>
944 For information that can help you maintain compliance with various
945 open source licensing during the lifecycle of a product created using
946 the Yocto Project, see the
947 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
948 section in the Yocto Project Development Tasks Manual.
949 </para>
950</section>
951</chapter>
952<!--
953vim: expandtab tw=80 ts=4
954-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-04-24 00:58:08 +0000