summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml402
1 files changed, 282 insertions, 120 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 2ff66a4b06..a15452de8b 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -205,36 +205,56 @@
205 by the maintainer of the source code. 205 by the maintainer of the source code.
206 For example, in order for a developer to work on a particular piece of code, they need to 206 For example, in order for a developer to work on a particular piece of code, they need to
207 first get a copy of it from an "upstream" source.</para></listitem> 207 first get a copy of it from an "upstream" source.</para></listitem>
208 <listitem><para id='yocto-project-files'><emphasis>Yocto Project Files:</emphasis> 208 <listitem>
209 This term refers to the directory structure created as a result of either downloading 209 <para id='yocto-project-files'><emphasis>Yocto Project Files:</emphasis>
210 and unpacking a Yocto Project release tarball or setting up a Git repository 210 This term refers to the directory structure created as a result of either downloading
211 by cloning <filename>git://git.yoctoproject.org/poky</filename>. 211 and unpacking a Yocto Project release tarball or setting up a Git repository
212 Sometimes the term "the Yocto Project Files structure" is used as well.</para> 212 by cloning <filename>git://git.yoctoproject.org/poky</filename>.
213 <para>The Yocto Project files contain BitBake, Documentation, metadata and 213 Sometimes the term "the Yocto Project Files structure" is used as well.
214 other files that all support the development environment. 214 </para>
215 Consequently, you must have the Yocto Project files in place on your development 215
216 system in order to do any development using the Yocto Project.</para> 216 <para>
217 <para>The name of the top-level directory of the Yocto Project file structure 217 The Yocto Project files contain BitBake, Documentation, metadata and
218 is derived from the Yocto Project release tarball. 218 other files that all support the development environment.
219 For example, downloading and unpacking <filename>poky-edison-6.0.tar.bz2</filename> 219 Consequently, you must have the Yocto Project files in place on your development
220 results in a Yocto Project file structure whose Yocto Project source directory is named 220 system in order to do any development using the Yocto Project.
221 <filename>poky-edison-6.0</filename>. 221 </para>
222 If you create a Git repository, then you can name the repository anything you like.</para> 222
223 <para>It is important to understand the differences between Yocto Project Files created 223 <para>
224 by unpacking a release tarball as compared to cloning 224 The name of the top-level directory of the Yocto Project file structure
225 <filename>git://git.yoctoproject.org/poky</filename>. 225 is derived from the Yocto Project release tarball.
226 When you unpack a tarball, you have an exact copy of the files based on the time of 226 For example, downloading and unpacking <filename>poky-edison-6.0.tar.bz2</filename>
227 release - a fixed release point. 227 results in a Yocto Project file structure whose Yocto Project source directory is named
228 Any changes you make to your local Yocto Project files are on top of the release. 228 <filename>poky-edison-6.0</filename>.
229 On the otherhand, when you clone the Yocto Project Git repository, you have an 229 If you create a Git repository, then you can name the repository anything you like.
230 active development repository. 230 </para>
231 In this case, any local changes you make to the Yocto Project can be later applied to active 231
232 development branches of the upstream Yocto Project Git repository.</para> 232 <para>
233 <para>You can find instruction on how to set up the Yocto Project files on your 233 It is important to understand the differences between Yocto Project Files created
234 host development system by reading 234 by unpacking a release tarball as compared to cloning
235 the 235 <filename>git://git.yoctoproject.org/poky</filename>.
236 "<ulink url='http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#getting-setup'>Getting 236 When you unpack a tarball, you have an exact copy of the files based on the time of
237 Setup</ulink>" section.</para></listitem> 237 release - a fixed release point.
238 Any changes you make to your local Yocto Project files are on top of the release.
239 On the other hand, when you clone the Yocto Project Git repository, you have an
240 active development repository.
241 In this case, any local changes you make to the Yocto Project can be later applied to active
242 development branches of the upstream Yocto Project Git repository.
243 Furthermore, with the Git repository you can create a local Git branch that
244 reflects the exact copy of the files at the time of their release.
245 You do this using Git tags that are part of the repository.
246 For more information on concepts, see the section
247 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>".
248 </para>
249
250 <para>
251 You can find instruction on how to set up the Yocto Project files on your
252 host development system by reading
253 the
254 "<ulink url='http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#getting-setup'>Getting
255 Setup</ulink>" section.
256 </para>
257 </listitem>
238 <listitem><para><emphasis>Yocto Project Build Directory:</emphasis> 258 <listitem><para><emphasis>Yocto Project Build Directory:</emphasis>
239 This term refers to the area used by the Yocto Project for builds. 259 This term refers to the area used by the Yocto Project for builds.
240 The area is created when you <filename>source</filename> the Yocto Project setup 260 The area is created when you <filename>source</filename> the Yocto Project setup
@@ -326,103 +346,245 @@
326 <para> 346 <para>
327 The Yocto Project uses Git, which is a free, open source distributed version control system. 347 The Yocto Project uses Git, which is a free, open source distributed version control system.
328 Git supports distributed development, non-linear development, and can handle large projects. 348 Git supports distributed development, non-linear development, and can handle large projects.
329 It is best that you know how to work with Git if you are going to use Yocto Project for development. 349 It is best that you have some fundamental understanding of how Git tracks projects and
350 how to work with Git if you are going to use Yocto Project for development.
351 This section provides a quick overview of how Git works and provides you with a summary
352 of some essential Git commands.
330 </para> 353 </para>
331 354
332 <para> 355 <para>
333 Git has an extensive set of commands that lets you manage changes and perform 356 For more information on Git, see
334 collaboration over the life of a project. 357 <ulink url='http://git-scm.com/documentation'></ulink>.
335 Conveniently though, you can manage with a small set of basic operations and workflows 358 If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>.
336 once you understand the basic philosophy behind Git.
337 You do not have to be an expert in Git to be functional.
338 A good place to look for instruction on a minimal set of Git commands is
339 <ulink url='http://git-scm.com/documentation'>here</ulink>.
340 If you need to download Git, you can do so
341 <ulink url='http://git-scm.com/download'>here</ulink>.
342 </para> 359 </para>
343 360
344 <para> 361 <section id='repositories-tags-and-branches'>
345 Git works by using branching techniques that track content change (not files) 362 <title>Repositories, Tags, and Branches</title>
346 within a project (e.g. a new feature or updated documentation).
347 Creating a tree-like structure based on project divergence allows for excellent historical
348 information over the life of a project.
349 This methodology also allows for an environment in which you can do lots of
350 experimentation on your project as you develop changes or new features.
351 For example, you can create a “branch”, experiment with some feature, and then
352 if you like the feature, you incorporate the branch into the tree.
353 If you don’t, you cut the branch off by deleting it.
354 </para>
355 363
356 <para> 364 <para>
357 If you don’t know much about Git, we suggest you educate 365 As mentioned earlier in section
358 yourself by visiting the links previously mentioned. 366 "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>",
359 </para> 367 the Yocto Project maintains source repositories at
368 <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
369 If you look at this web-interface of the repositories, each item is a separate
370 Git repository.
371 </para>
360 372
361 <para> 373 <para>
362 The following list briefly describes some basic Git operations as a way to get started. 374 Git repositories use branching techniques that track content change (not files)
363 As with any set of commands, this list (in most cases) simply shows the base command and 375 within a project (e.g. a new feature or updated documentation).
364 omits the many arguments they support. 376 Creating a tree-like structure based on project divergence allows for excellent historical
365 See the Git documentation for complete descriptions and strategies on how to use these commands: 377 information over the life of a project.
366 <itemizedlist> 378 This methodology also allows for an environment in which you can do lots of
367 <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository. 379 local experimentation on a project as you develop changes or new features.
368 You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem> 380 </para>
369 <listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository. 381
370 During collaboration, this command allows you to create a local repository that is on 382 <para>
371 equal footing with a fellow developer’s repository.</para></listitem> 383 A Git repository represents all development efforts for a given project.
372 <listitem><para><emphasis><filename>git add</filename>:</emphasis> Adds updated file contents 384 For example, the Git repository <filename>poky</filename> contains all changes
373 to the index that 385 and developments for Poky over the course of its entire life.
374 Git uses to track changes. 386 That means that all changes that make up all releases are captured.
375 You must add all files that have changed before you can commit them.</para></listitem> 387 The repository maintains a complete history of changes.
376 <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a “commit” that documents 388 </para>
377 the changes you made. 389
378 Commits are used for historical purposes, for determining if a maintainer of a project 390 <para>
379 will allow the change, and for ultimately pushing the change from your local Git repository 391 You can create a local copy of any repository by "cloning" it with the Git
380 into the project’s upstream (or master) repository.</para></listitem> 392 <filename>clone</filename> command.
381 <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that 393 When you clone a Git repository, you end up with an identical copy of the
382 possibly need to be added and committed.</para></listitem> 394 repository on your development system.
383 <listitem><para><emphasis><filename>git checkout &lt;branch-name&gt;</filename>:</emphasis> Changes 395 Once you have a local copy of a repository, you can take steps to develop locally.
384 your working branch. 396 For examples on how to clone Git repositories, see the section
385 This command is analogous to “cd”.</para></listitem> 397 "<link linkend='getting-setup'>Getting Set Up</link>" earlier in this manual.
386 <listitem><para><emphasis><filename>git checkout –b &lt;working-branch&gt;</filename>:</emphasis> Creates 398 </para>
387 a working branch on your local machine where you can isolate work. 399
388 It is a good idea to use local branches when adding specific features or changes. 400 <para>
389 This way if you don’t like what you have done you can easily get rid of the work.</para></listitem> 401 It is important to understand that Git tracks content change and not files.
390 <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports existing branches and 402 Git uses "branches" to organize different development efforts.
391 tells you which branch in which you are currently working.</para></listitem> 403 For example, the <filename>poky</filename> repository has
392 <listitem><para><emphasis><filename>git branch -D &lt;branch-name&gt;</filename>:</emphasis> 404 <filename>laverne</filename>, <filename>bernard</filename>,
393 Deletes an existing branch. 405 <filename>edison</filename>, and <filename>master</filename> branches among
394 You need to be in a branch other than the one you are deleting 406 others.
395 in order to delete &lt;branch-name&gt;.</para></listitem> 407 You can see all the branches by going to
396 <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information 408 <ulink url='http://git.yoctoproject.org/cgit.cgi/poky/'></ulink> and
397 from an upstream Git 409 clicking on the
398 repository and places it in your local Git repository. 410 <filename><ulink url='http://git.yoctoproject.org/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
399 You use this command to make sure you are synchronized with the repository 411 link beneath the "Branch" heading.
400 from which you are basing changes (.e.g. the master repository).</para></listitem> 412 </para>
401 <listitem><para><emphasis><filename>git push</filename>:</emphasis> Sends all your local changes you 413
402 have committed to an upstream Git repository (e.g. a contribution repository). 414 <para>
403 The maintainer of the project draws from these repositories when adding your changes to the 415 Each of these branches represents a specific area of development.
404 project’s master repository.</para></listitem> 416 The <filename>master</filename> branch represents the current or most recent
405 <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one 417 development.
406 local branch of your repository with another branch. 418 All other branches represent off-shoots of the <filename>master</filename>
407 When you create a local Git repository, the default branch is named “master”. 419 branch.
408 A typical workflow is to create a temporary branch for isolated work, make and commit your 420 </para>
409 changes, switch to your local master branch, merge the changes from the temporary branch into the 421
410 local master branch, and then delete the temporary branch.</para></listitem> 422 <para>
411 <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific 423 When you create a local copy of a Git repository, the copy has the same set
412 commits from one branch into another branch. 424 of branches as the original.
413 There are times when you might not be able to merge all the changes in one branch with 425 This means you can use Git to create a local working area (also called a branch)
414 another but need to pick out certain ones.</para></listitem> 426 that tracks a specific development branch from the source Git repository.
415 <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches 427 in other words, you can define your local Git environment to work on any development
416 and changes in your local Git repository. 428 branch in the repository.
417 This command is a good way to graphically see where things have diverged in your 429 To help illustrate, here is a set of commands that creates a local copy of the
418 local repository.</para></listitem> 430 <filename>poky</filename> Git repository and then creates and checks out a local
419 <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the 431 Git branch that tracks the Yocto Project 1.1 Release (edison) development:
420 repository.</para></listitem> 432 <literallayout class='monospaced'>
421 <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences 433 $ cd ~
422 between your local working files and the same files in the upstream Git repository that your 434 $ git clone git://git.yoctoproject.org/poky
423 branch currently tracks.</para></listitem> 435 $ cd poky
424 </itemizedlist> 436 $ git checkout edison -b edison
425 </para> 437 </literallayout>
438 In this example, the name of the top-level directory of your local Yocto Project
439 Files Git repository is <filename>poky</filename>.
440 And, the name of the local working area (or local branch) you have created and checked
441 out is named <filename>edison</filename>.
442 The files in your repository now reflect the same files that are in the
443 <filename>edison</filename> development branch of the Yocto Project's
444 <filename>poky</filename> repository.
445 It is important to understand that when you create and checkout a
446 local working branch based on a branch name,
447 your local environment matches the "tip" of that development branch
448 at the time you created your local branch, which could be
449 different than the files at the time of a similarly named release.
450 In other words, creating and checking out a local branch based on the
451 <filename>edison</filename> branch name is not the same as creating and
452 checking out a local branch based on the <filename>edison-6.0</filename>
453 release.
454 Keep reading to see how you create a local snapshot of a Yocto Project Release.
455 </para>
456
457 <para>
458 Git uses "tags" to mark specific changes in a repository.
459 Typically, a tag is used to mark a special point such as the final change
460 before a project is released.
461 You can see the tags used with the <filename>poky</filename> Git repository
462 by going to <ulink url='http://git.yoctoproject.org/cgit.cgi/poky/'></ulink> and
463 clicking on the
464 <filename><ulink url='http://git.yoctoproject.org/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
465 link beneath the "Tag" heading.
466 </para>
467
468 <para>
469 Some key tags are <filename>laverne-4.0</filename>, <filename>bernard-5.0</filename>,
470 and <filename>edison-6.0</filename>.
471 These tags represent Yocto Project releases.
472 </para>
473
474 <para>
475 When you create a local copy of the Git repository, you also have access to all the
476 tags.
477 Similar to branches, you can create and checkout a local working Git branch based
478 on a tag name.
479 When you do this, you get a snapshot of the Git repository that reflects
480 the state of the files when the change was made associated with that tag.
481 The most common use is to checkout a working branch that matches a specific
482 Yocto Project release.
483 Here is an example:
484 <literallayout class='monospaced'>
485 $ cd ~
486 $ git clone git://git.yoctoproject.org/poky
487 $ cd poky
488 $ git checkout edison-6.0 -b edison-6.0
489 </literallayout>
490 In this example, the name of the top-level directory of your local Yocto Project
491 Files Git repository is <filename>poky</filename>.
492 And, the name of the local branch you have created and checked out is
493 <filename>edison-6.0</filename>.
494 The files in your repository now exactly match the Yocto Project 1.1
495 Release (edison).
496 It is important to understand that when you create and checkout a local
497 working branch based on a tag, your environment matches a specific point
498 in time and not a development branch.
499 </para>
500 </section>
501
502 <section id='basic-commands'>
503 <title>Basic Commands</title>
504
505 <para>
506 Git has an extensive set of commands that lets you manage changes and perform
507 collaboration over the life of a project.
508 Conveniently though, you can manage with a small set of basic operations and workflows
509 once you understand the basic philosophy behind Git.
510 You do not have to be an expert in Git to be functional.
511 A good place to look for instruction on a minimal set of Git commands is
512 <ulink url='http://git-scm.com/documentation'>here</ulink>.
513 If you need to download Git, you can do so
514 <ulink url='http://git-scm.com/download'>here</ulink>.
515 </para>
516
517 <para>
518 If you don’t know much about Git, we suggest you educate
519 yourself by visiting the links previously mentioned.
520 </para>
521
522 <para>
523 The following list briefly describes some basic Git operations as a way to get started.
524 As with any set of commands, this list (in most cases) simply shows the base command and
525 omits the many arguments they support.
526 See the Git documentation for complete descriptions and strategies on how to use these commands:
527 <itemizedlist>
528 <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository.
529 You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem>
530 <listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository.
531 During collaboration, this command allows you to create a local repository that is on
532 equal footing with a fellow developer’s repository.</para></listitem>
533 <listitem><para><emphasis><filename>git add</filename>:</emphasis> Adds updated file contents
534 to the index that
535 Git uses to track changes.
536 You must add all files that have changed before you can commit them.</para></listitem>
537 <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a “commit” that documents
538 the changes you made.
539 Commits are used for historical purposes, for determining if a maintainer of a project
540 will allow the change, and for ultimately pushing the change from your local Git repository
541 into the project’s upstream (or master) repository.</para></listitem>
542 <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that
543 possibly need to be added and committed.</para></listitem>
544 <listitem><para><emphasis><filename>git checkout &lt;branch-name&gt;</filename>:</emphasis> Changes
545 your working branch.
546 This command is analogous to “cd”.</para></listitem>
547 <listitem><para><emphasis><filename>git checkout –b &lt;working-branch&gt;</filename>:</emphasis> Creates
548 a working branch on your local machine where you can isolate work.
549 It is a good idea to use local branches when adding specific features or changes.
550 This way if you don’t like what you have done you can easily get rid of the work.</para></listitem>
551 <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports existing branches and
552 tells you which branch in which you are currently working.</para></listitem>
553 <listitem><para><emphasis><filename>git branch -D &lt;branch-name&gt;</filename>:</emphasis>
554 Deletes an existing branch.
555 You need to be in a branch other than the one you are deleting
556 in order to delete &lt;branch-name&gt;.</para></listitem>
557 <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information
558 from an upstream Git
559 repository and places it in your local Git repository.
560 You use this command to make sure you are synchronized with the repository
561 from which you are basing changes (.e.g. the master repository).</para></listitem>
562 <listitem><para><emphasis><filename>git push</filename>:</emphasis> Sends all your local changes you
563 have committed to an upstream Git repository (e.g. a contribution repository).
564 The maintainer of the project draws from these repositories when adding your changes to the
565 project’s master repository.</para></listitem>
566 <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one
567 local branch of your repository with another branch.
568 When you create a local Git repository, the default branch is named “master”.
569 A typical workflow is to create a temporary branch for isolated work, make and commit your
570 changes, switch to your local master branch, merge the changes from the temporary branch into the
571 local master branch, and then delete the temporary branch.</para></listitem>
572 <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific
573 commits from one branch into another branch.
574 There are times when you might not be able to merge all the changes in one branch with
575 another but need to pick out certain ones.</para></listitem>
576 <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches
577 and changes in your local Git repository.
578 This command is a good way to graphically see where things have diverged in your
579 local repository.</para></listitem>
580 <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the
581 repository.</para></listitem>
582 <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences
583 between your local working files and the same files in the upstream Git repository that your
584 branch currently tracks.</para></listitem>
585 </itemizedlist>
586 </para>
587 </section>
426</section> 588</section>
427 589
428<section id='workflows'> 590<section id='workflows'>