summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-07-16 15:03:16 +0300
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-08-13 13:18:41 +0100
commitdc7f6e7d3002632245bfcc7e0a126f2179732292 (patch)
tree2afd0f1ee45bb2fb14163f5af756d75869623a8a /documentation/ref-manual
parentf3b97fade2ad0943e531e3b08bd87bed45697b3d (diff)
downloadpoky-dc7f6e7d3002632245bfcc7e0a126f2179732292.tar.gz
ref-manual: First draft of the "Sources" section added.
Fixes [YOCTO #2808] The "Sources" section provides a more detailed look at where BitBake gets source files from. This change included the first draft of the text and the first draft of the expanded figure. (From yocto-docs rev: 4e432a05666e67c6494486f392a05f629c6c148a) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/figures/source-input.pngbin0 -> 41019 bytes
-rw-r--r--documentation/ref-manual/technical-details.xml153
2 files changed, 153 insertions, 0 deletions
diff --git a/documentation/ref-manual/figures/source-input.png b/documentation/ref-manual/figures/source-input.png
new file mode 100644
index 0000000000..33c1699dc5
--- /dev/null
+++ b/documentation/ref-manual/figures/source-input.png
Binary files differ
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 2233fe89ec..ffc635a1ce 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -589,6 +589,159 @@
589 </para> 589 </para>
590 </section> 590 </section>
591 </section> 591 </section>
592
593 <section id="sources-dev-environment">
594 <title>Sources</title>
595
596 <para>
597 In order for the OpenEmbedded build system to create an image or
598 any target, it must be able to access source files.
599 The main
600 <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment figure</link>
601 represents source files using the "Upstream Project Releases",
602 "Local Projects", and "SCMs (optional)" boxes.
603 The figure represents mirrors, which also play a role in locating
604 source files, with the "Source Mirror(s)" box.
605 </para>
606
607 <para>
608 The method by which source files are ultimately organized is
609 a function of the project.
610 For example, for released software, projects tend to use tarballs
611 or other archived files that can capture the state of a release
612 guaranteeing that it is statically represented.
613 On the other hand, for a project that is more dynamic or
614 experimental in nature, a project might keep source files in a
615 repository controlled by a Source Control Manager (SCM) such as
616 Git.
617 Pulling source from a repository allows you to control
618 the point in the repository (the revision) from which you want to
619 build software.
620 Finally, a combination of the two might exist, which would give the
621 consumer a choice when deciding where to get source files.
622 </para>
623
624 <para>
625 BitBake uses the
626 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
627 variable to point to source files regardless of their location.
628 Each recipe must have a <filename>SRC_URI</filename> variable
629 that points to the source.
630 </para>
631
632 <para>
633 Another area that plays a significant role in where source files
634 comes from is pointed to by the
635 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
636 variable.
637 This area is a cache that can hold previously downloaded source.
638 Judicious use of a <filename>DL_DIR</filename> directory can
639 save the build system a trip across the Internet when looking
640 for files.
641 A good method for using a download directory is to have
642 <filename>DL_DIR</filename> point to an area outside of your
643 Build Directory.
644 Doing so allows you to safely delete the Build Directory's
645 <filename>/work/tmp</filename> directory if needed without fear
646 of removing any downloaded source file.
647 </para>
648
649 <para>
650 The remainder of this section provides a deeper look into the
651 source files and the mirrors.
652 Here is a more detailed look at the source file area of the
653 base figure:
654 <imagedata fileref="figures/source-input.png" align="center" width="7in" depth="7.5in" />
655 </para>
656
657 <section id='upstream-project-releases'>
658 <title>Upstream Project Releases</title>
659
660 <para>
661 Upstream project releases exist anywhere in the form of an
662 archived file (e.g. tarball or zip file).
663 These files correspond to individual recipes.
664 For example, the figure uses specific releases each for
665 BusyBox, Qt, and Dbus.
666 An archive file can be for any released product that can be
667 built using a recipe.
668 </para>
669 </section>
670
671 <section id='local-projects'>
672 <title>Local Projects</title>
673
674 <para>
675 Local projects are custom bits of software the user provides.
676 These bits reside somewhere local to a project - perhaps
677 a directory into which the user checks in items (e.g.
678 a local directory that contains tarballs or repositories
679 used by the group).
680 </para>
681
682 <para>
683 The canonical method through which to include a local project
684 is to use the
685 <link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>
686 class to include local project.
687 You use a recipe's append file to override or instruct the
688 recipe to point to the local directory on your disk to pull
689 in the whole source tree.
690 Should you ever need to override that, you can use the
691 Build Directory's <filename>local.conf</filename> file.
692 </para>
693
694 <para>
695 For information on how to use the
696 <filename>externalsrc.bbclass</filename>, see the
697 "<link linkend='ref-classes-externalsrc'>Using External Source - <filename>externalsrc.bbclass</filename></link>"
698 section.
699 </para>
700 </section>
701
702 <section id='scms'>
703 <title>Source Control Managers (Optional)</title>
704
705 <para>
706 Another place the build system can get source files from is
707 through an SCM such as Git or Subversion.
708 In this case, a repository is cloned or checked out.
709 The <filename>do_fetch</filename> task inside BitBake uses
710 the <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
711 variable and the argument's prefix to determine the correct
712 fetcher module.
713 </para>
714
715 <para>
716 When fetching a repository, BitBake uses the
717 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
718 variable to determine the specific revision from which to
719 build.
720 </para>
721 </section>
722
723 <section id='source-mirrors'>
724 <title>Source Mirror(s)</title>
725
726 <para>
727 Two kinds of mirrors exist: pre-mirrors and regular mirrors.
728 BitBake checks pre-mirrors before looking upstream for any
729 source files.
730 Pre-mirrors are appropriate when you have a shared directory
731 that is not a directory defined by the
732 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
733 variable.
734 A Pre-mirror typically points to a shared directory that is
735 local to your organization.
736 </para>
737
738 <para>
739 Regular mirrors can be any site across the Internet that is
740 used as an alternative location for source code should the
741 primary site not be functioning for some reason or another.
742 </para>
743 </section>
744 </section>
592</section> 745</section>
593 746
594<section id="cross-development-toolchain-generation"> 747<section id="cross-development-toolchain-generation">