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