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 Binary files /dev/null and b/documentation/ref-manual/figures/source-input.png 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 @@ + +
+ Sources + + + In order for the OpenEmbedded build system to create an image or + any target, it must be able to access source files. + The main + Yocto Project Development Environment figure + represents source files using the "Upstream Project Releases", + "Local Projects", and "SCMs (optional)" boxes. + The figure represents mirrors, which also play a role in locating + source files, with the "Source Mirror(s)" box. + + + + The method by which source files are ultimately organized is + a function of the project. + For example, for released software, projects tend to use tarballs + or other archived files that can capture the state of a release + guaranteeing that it is statically represented. + On the other hand, for a project that is more dynamic or + experimental in nature, a project might keep source files in a + repository controlled by a Source Control Manager (SCM) such as + Git. + Pulling source from a repository allows you to control + the point in the repository (the revision) from which you want to + build software. + Finally, a combination of the two might exist, which would give the + consumer a choice when deciding where to get source files. + + + + BitBake uses the + SRC_URI + variable to point to source files regardless of their location. + Each recipe must have a SRC_URI variable + that points to the source. + + + + Another area that plays a significant role in where source files + comes from is pointed to by the + DL_DIR + variable. + This area is a cache that can hold previously downloaded source. + Judicious use of a DL_DIR directory can + save the build system a trip across the Internet when looking + for files. + A good method for using a download directory is to have + DL_DIR point to an area outside of your + Build Directory. + Doing so allows you to safely delete the Build Directory's + /work/tmp directory if needed without fear + of removing any downloaded source file. + + + + The remainder of this section provides a deeper look into the + source files and the mirrors. + Here is a more detailed look at the source file area of the + base figure: + + + +
+ Upstream Project Releases + + + Upstream project releases exist anywhere in the form of an + archived file (e.g. tarball or zip file). + These files correspond to individual recipes. + For example, the figure uses specific releases each for + BusyBox, Qt, and Dbus. + An archive file can be for any released product that can be + built using a recipe. + +
+ +
+ Local Projects + + + Local projects are custom bits of software the user provides. + These bits reside somewhere local to a project - perhaps + a directory into which the user checks in items (e.g. + a local directory that contains tarballs or repositories + used by the group). + + + + The canonical method through which to include a local project + is to use the + externalsrc.bbclass + class to include local project. + You use a recipe's append file to override or instruct the + recipe to point to the local directory on your disk to pull + in the whole source tree. + Should you ever need to override that, you can use the + Build Directory's local.conf file. + + + + For information on how to use the + externalsrc.bbclass, see the + "Using External Source - externalsrc.bbclass" + section. + +
+ +
+ Source Control Managers (Optional) + + + Another place the build system can get source files from is + through an SCM such as Git or Subversion. + In this case, a repository is cloned or checked out. + The do_fetch task inside BitBake uses + the SRC_URI + variable and the argument's prefix to determine the correct + fetcher module. + + + + When fetching a repository, BitBake uses the + SRCREV + variable to determine the specific revision from which to + build. + +
+ +
+ Source Mirror(s) + + + Two kinds of mirrors exist: pre-mirrors and regular mirrors. + BitBake checks pre-mirrors before looking upstream for any + source files. + Pre-mirrors are appropriate when you have a shared directory + that is not a directory defined by the + DL_DIR + variable. + A Pre-mirror typically points to a shared directory that is + local to your organization. + + + + Regular mirrors can be any site across the Internet that is + used as an alternative location for source code should the + primary site not be functioning for some reason or another. + +
+