diff options
Diffstat (limited to 'documentation/overview-manual/overview-manual-development-environment.xml')
-rw-r--r-- | documentation/overview-manual/overview-manual-development-environment.xml | 954 |
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 | <!-- | ||
953 | vim: expandtab tw=80 ts=4 | ||
954 | --> | ||