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