diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2011-08-11 13:55:07 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2011-08-15 15:27:04 +0100 |
commit | a7e4747f499d4219c29277e80e64e4fdf604628a (patch) | |
tree | d5406ee02b946a226d64ef0314c2745b44c46383 /documentation/dev-manual/dev-manual-newbie.xml | |
parent | 8c45abc747add07ebbf9b8dc8e71c98431d7ec25 (diff) | |
download | poky-a7e4747f499d4219c29277e80e64e4fdf604628a.tar.gz |
documentation/dev-manual: Scott Garman's review comments.
Made several editing corrections for various terms and phrasings based on
Scott Garman's review.
(From yocto-docs rev: a21ba80151ce82683d45cd67ddb0728d779b007a)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-newbie.xml')
-rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 66 |
1 files changed, 36 insertions, 30 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index 060dc26344..b41141908e 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml | |||
@@ -7,7 +7,7 @@ | |||
7 | 7 | ||
8 | <para> | 8 | <para> |
9 | This chapter helps you understand the Yocto Project as an open source development project. | 9 | This chapter helps you understand the Yocto Project as an open source development project. |
10 | In general, working in an open-source environment is very different than working in a closed, | 10 | In general, working in an open-source environment is very different than working in a |
11 | proprietary environment. | 11 | proprietary environment. |
12 | Additionally, the Yocto Project uses specific tools and constructs as part of its development | 12 | Additionally, the Yocto Project uses specific tools and constructs as part of its development |
13 | environment. | 13 | environment. |
@@ -19,8 +19,8 @@ | |||
19 | <title>Open Source Philosophy</title> | 19 | <title>Open Source Philosophy</title> |
20 | 20 | ||
21 | <para> | 21 | <para> |
22 | Open source philosophy is characterized by software development directed by peer production, | 22 | Open source philosophy is characterized by software development directed by peer production |
23 | bartering, and collaboration through a concerned community of developers. | 23 | and collaboration through a concerned community of developers. |
24 | Contrast this to the more standard centralized development models used by commercial software | 24 | Contrast this to the more standard centralized development models used by commercial software |
25 | companies where a finite set of developers produce a product for sale using a defined set | 25 | companies where a finite set of developers produce a product for sale using a defined set |
26 | of procedures that ultimately result in an end-product whose architecture and source material | 26 | of procedures that ultimately result in an end-product whose architecture and source material |
@@ -61,7 +61,7 @@ | |||
61 | <para> | 61 | <para> |
62 | The Yocto Project team maintains complete source repositories for all Yocto Project files | 62 | The Yocto Project team maintains complete source repositories for all Yocto Project files |
63 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>here</ulink>. | 63 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>here</ulink>. |
64 | This web-interface of the source is organized into categories by function such as | 64 | This web-based source code browser is organized into categories by function such as |
65 | IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. | 65 | IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. |
66 | From the interface, you can click on any particular item in the "Name" column and | 66 | From the interface, you can click on any particular item in the "Name" column and |
67 | see the URL at the bottom of the page that you need to set up a Git repository for | 67 | see the URL at the bottom of the page that you need to set up a Git repository for |
@@ -132,23 +132,22 @@ | |||
132 | environment might find helpful. | 132 | environment might find helpful. |
133 | Some terms are universal but are included here just in case: | 133 | Some terms are universal but are included here just in case: |
134 | <itemizedlist> | 134 | <itemizedlist> |
135 | <listitem><para><emphasis>Image</emphasis> - An image is a complete executable file that | 135 | <listitem><para><emphasis>Image</emphasis> - An image is a collection of recipes created |
136 | runs on specific hardware or in the QEMU emulator. | 136 | with BitBake (baked) and made part of a root filesystem.</para></listitem> |
137 | Images are collections of recipes created with the Bitbake tool in the Yocto Project | ||
138 | development environment.</para></listitem> | ||
139 | <listitem><para><emphasis>Recipe</emphasis> - A set of instructions for building packages. | 137 | <listitem><para><emphasis>Recipe</emphasis> - A set of instructions for building packages. |
140 | A recipe describes where you get source code and which patches to apply. | 138 | A recipe describes where you get source code and which patches to apply. |
141 | Recipes describe dependencies for libraries or for other recipes and they | 139 | Recipes describe dependencies for libraries or for other recipes and they |
142 | also contain configuration and compilation options. | 140 | also contain configuration and compilation options. |
143 | Recipes also let you ‘install’ customizations. | 141 | Recipes also let you customize how software is installed into images. |
144 | Recipes contain the logical unit of execution, the software/images to build and | 142 | Recipes contain the logical unit of execution, the software/images to build and |
145 | use the <filename>.bb</filename> file extension.</para></listitem> | 143 | use the <filename>.bb</filename> file extension.</para></listitem> |
146 | <listitem><para><emphasis>BitBake</emphasis> - The task executor and scheduler used by Yocto Project | 144 | <listitem><para><emphasis>BitBake</emphasis> - The task executor and scheduler used by Yocto Project |
147 | to build images. | 145 | to build images. |
148 | For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'> | 146 | For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'> |
149 | BitBake documentation</ulink>.</para></listitem> | 147 | BitBake documentation</ulink>.</para></listitem> |
150 | <listitem><para><emphasis>Package</emphasis> - A collection of ‘baked’ recipes. | 148 | <listitem><para><emphasis>Package</emphasis> - The output from a baked recipe. |
151 | You ‘bake’ something by running it through Bitbake.</para></listitem> | 149 | A package is generally the compiled binaries produced from the recipe's sources. |
150 | You ‘bake’ something by running it through BitBake.</para></listitem> | ||
152 | <listitem><para><emphasis>Layer</emphasis> - A logical collection of recipes representing the core, | 151 | <listitem><para><emphasis>Layer</emphasis> - A logical collection of recipes representing the core, |
153 | a BSP, or an application stack.</para></listitem> | 152 | a BSP, or an application stack.</para></listitem> |
154 | <listitem><para><emphasis>Metadata</emphasis> - Information for a build that is generally | 153 | <listitem><para><emphasis>Metadata</emphasis> - Information for a build that is generally |
@@ -176,13 +175,13 @@ | |||
176 | A task is really just another recipe. | 175 | A task is really just another recipe. |
177 | Because task files are recipes, they end with the <filename>.bb</filename> filename | 176 | Because task files are recipes, they end with the <filename>.bb</filename> filename |
178 | extension.</para></listitem> | 177 | extension.</para></listitem> |
179 | <listitem><para><emphasis>Common OE-Core</emphasis> - A core set of metadata originating | 178 | <listitem><para><emphasis>OE-Core</emphasis> - A core set of metadata originating |
180 | with OpenEmbedded (OE) that is shared between OE and the Yocto Project.</para></listitem> | 179 | with OpenEmbedded (OE) that is shared between OE and the Yocto Project.</para></listitem> |
181 | <listitem><para><emphasis>Up-stream</emphasis> - A reference to source code or repositories | 180 | <listitem><para><emphasis>Upstream</emphasis> - A reference to source code or repositories |
182 | that are not local to the development system but located in a master area that is controlled | 181 | that are not local to the development system but located in a master area that is controlled |
183 | by the maintainer of the source code. | 182 | by the maintainer of the source code. |
184 | For example, in order for a developer to work on a particular piece of code they need to | 183 | For example, in order for a developer to work on a particular piece of code they need to |
185 | first get a copy of it from an "up-stream" source.</para></listitem> | 184 | first get a copy of it from an "upstream" source.</para></listitem> |
186 | </itemizedlist> | 185 | </itemizedlist> |
187 | </para> | 186 | </para> |
188 | </section> | 187 | </section> |
@@ -208,7 +207,7 @@ | |||
208 | MIT licensing permits the reuse of software within proprietary software as long as the | 207 | MIT licensing permits the reuse of software within proprietary software as long as the |
209 | license is distributed with that software. | 208 | license is distributed with that software. |
210 | MIT is also compatible with the GNU General Public License (GPL). | 209 | MIT is also compatible with the GNU General Public License (GPL). |
211 | Patches to the Yocto Project follow the up-stream licensing scheme. | 210 | Patches to the Yocto Project follow the upstream licensing scheme. |
212 | </para> | 211 | </para> |
213 | 212 | ||
214 | <para> | 213 | <para> |
@@ -251,14 +250,13 @@ | |||
251 | 250 | ||
252 | <para> | 251 | <para> |
253 | The Yocto Project uses Git, which is a free, open source distributed version control system. | 252 | The Yocto Project uses Git, which is a free, open source distributed version control system. |
254 | Git supports distributed development, non-linear development, can handle large projects, | 253 | Git supports distributed development, non-linear development, and can handle large projects. |
255 | cryptographic authentication of history, and toolkit design. | ||
256 | It is best that you know how to work with Git if you are going to use Yocto Project for development. | 254 | It is best that you know how to work with Git if you are going to use Yocto Project for development. |
257 | </para> | 255 | </para> |
258 | 256 | ||
259 | <para> | 257 | <para> |
260 | Git has an extensive set of commands that lets you manage and collaborate changes over the life | 258 | Git has an extensive set of commands that lets you manage changes and perform |
261 | of a project. | 259 | collaboration over the life of a project. |
262 | Conveniently though, you can manage with a small set of basic operations and workflows | 260 | Conveniently though, you can manage with a small set of basic operations and workflows |
263 | once you understand the basic philosophy behind Git. | 261 | once you understand the basic philosophy behind Git. |
264 | You do not have to be an expert in Git to be functional. | 262 | You do not have to be an expert in Git to be functional. |
@@ -358,18 +356,18 @@ | |||
358 | The Yocto Project files are maintained using Git in a "master" branch whose Git history | 356 | The Yocto Project files are maintained using Git in a "master" branch whose Git history |
359 | tracks every change and whose structure provides branches for all diverging functionality. | 357 | tracks every change and whose structure provides branches for all diverging functionality. |
360 | This is typical for open-source projects, although Git does not have to be used. | 358 | This is typical for open-source projects, although Git does not have to be used. |
361 | For the Yocto Project a key individual is responsible for "master". | 359 | For the Yocto Project a key individual called the "maintainer" is responsible for "master". |
362 | The "master" branch is the “upstream” repository where the final builds of the project occur. | 360 | The "master" branch is the “upstream” repository where the final builds of the project occur. |
363 | The maintainer is responsible for allowing changes in from other developers and for | 361 | The maintainer is responsible for allowing changes in from other developers and for |
364 | organizing the underlying branch structure to reflect release strategies and so forth. | 362 | organizing the underlying branch structure to reflect release strategies and so forth. |
365 | </para> | 363 | </para> |
366 | 364 | ||
367 | <para> | 365 | <para> |
368 | The maintainer of the project also owns a contribution repository usually known as a “contrib” area. | 366 | The project also has contribution repositories known as “contrib” areas. |
369 | The contrib area temporarily holds changes to the project that have been submitted or committed | 367 | These areas temporarily hold changes to the project that have been submitted or committed |
370 | by the Yocto Project development team and by community members that contribute to the project. | 368 | by the Yocto Project development team and by community members that contribute to the project. |
371 | The maintainer determines if the changes are qualified to be moved into the "master" branch | 369 | The maintainer determines if the changes are qualified to be moved from the "contrib" areas |
372 | of the Git repository. | 370 | into the "master" branch of the Git repository. |
373 | </para> | 371 | </para> |
374 | 372 | ||
375 | <para> | 373 | <para> |
@@ -377,12 +375,15 @@ | |||
377 | of the upstream "master" branch. | 375 | of the upstream "master" branch. |
378 | These repositories are local to their development platforms and are used to develop changes. | 376 | These repositories are local to their development platforms and are used to develop changes. |
379 | When a developer is satisfied with a particular feature or change they “push” the changes | 377 | When a developer is satisfied with a particular feature or change they “push” the changes |
380 | up to the "contrib" repository. | 378 | to the appropriate "contrib" repository. |
379 | </para> | ||
380 | |||
381 | <para> | ||
381 | Developers are responsible for keeping their local repository up-to-date with "master". | 382 | Developers are responsible for keeping their local repository up-to-date with "master". |
382 | They are also responsible for straightening out any conflicts that might arise within files | 383 | They are also responsible for straightening out any conflicts that might arise within files |
383 | that are being worked on simultaneously by more than one person. | 384 | that are being worked on simultaneously by more than one person. |
384 | All this work is done locally on the developer’s machine before anything is pushed upstream | 385 | All this work is done locally on the developer’s machine before anything is pushed to a |
385 | and examined at the maintainer’s level. | 386 | "contrib" area and examined at the maintainer’s level. |
386 | </para> | 387 | </para> |
387 | 388 | ||
388 | <para> | 389 | <para> |
@@ -395,7 +396,7 @@ | |||
395 | To summarize the environment: we have a single point of entry for changes into the project’s | 396 | To summarize the environment: we have a single point of entry for changes into the project’s |
396 | "master" branch of the Git repository, which is controlled by the project’s maintainer. | 397 | "master" branch of the Git repository, which is controlled by the project’s maintainer. |
397 | And, we have a set of developers who independently develop, test, and submit changes | 398 | And, we have a set of developers who independently develop, test, and submit changes |
398 | upstream for the maintainer to examine. | 399 | to "contrib" areas for the maintainer to examine. |
399 | The maintainer then chooses which changes are going to become permanently a part of the project. | 400 | The maintainer then chooses which changes are going to become permanently a part of the project. |
400 | </para> | 401 | </para> |
401 | 402 | ||
@@ -435,13 +436,18 @@ | |||
435 | As your project develops, you can merge code across the branches to reflect ever-increasing | 436 | As your project develops, you can merge code across the branches to reflect ever-increasing |
436 | stable states of the development.</para></listitem> | 437 | stable states of the development.</para></listitem> |
437 | <listitem><para><emphasis>Use Push and Pull</emphasis> - The push-pull workflow is based on the | 438 | <listitem><para><emphasis>Use Push and Pull</emphasis> - The push-pull workflow is based on the |
438 | concept of developers “pushing” local commits upstream to the remote repository, which is | 439 | concept of developers “pushing” local commits to a remote repository, which is |
439 | usually a contribution repository. | 440 | usually a contribution repository. |
440 | It is also based on the developers “pulling” known states of the project down into their | 441 | It is also based on the developers “pulling” known states of the project down into their |
441 | local development repositories. | 442 | local development repositories. |
442 | This workflow easily allows you to pull changes submitted by other developers from the | 443 | This workflow easily allows you to pull changes submitted by other developers from the |
443 | upstream repository into your work area ensuring that you have the most recent software | 444 | upstream repository into your work area ensuring that you have the most recent software |
444 | on which to develop.</para></listitem> | 445 | on which to develop. |
446 | The Yocto Project has two scripts named <filename>create-pull-request</filename> and | ||
447 | <filename>send-pull-request</filename> that ship with the release to facilitate this | ||
448 | workflow. | ||
449 | You can find these scripts in the local Yocto Project files Git repository in | ||
450 | <filename>scripts</filename>.</para></listitem> | ||
445 | <listitem><para><emphasis>Patch Workflow</emphasis> - This workflow allows you to notify the | 451 | <listitem><para><emphasis>Patch Workflow</emphasis> - This workflow allows you to notify the |
446 | maintainer through an email that you have a change (or patch) you would like considered | 452 | maintainer through an email that you have a change (or patch) you would like considered |
447 | for the "master" branch of the Git repository. | 453 | for the "master" branch of the Git repository. |