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