documentation/poky-ref-manual/ref-variables.xml: SRC_URI glossary updated

Fixes [YOCTO_#1939]

Expanded the definition for the SRC_URI variable in the glossary.
The new information includes protocol types and SRC_URI options.

(From yocto-docs rev: 033d58cd2ec2a579fa085bcca1e5d0ad4dd65708)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 125 insertions, 1 deletions

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 720980f733..d71d25023c 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1826,7 +1826,131 @@ recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
 
         <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
             <glossdef>
-                <para>The list of source files - local or remote.</para>
+                <para>The list of source files - local or remote.
+                    This variable tells the OpenEmbedded build system which bits to pull
+                    in for the build and how to pull them in.
+                    For example, if the recipe only needs to fetch a tarball from the 
+                    internet, the recipe uses a single <filename>SRC_URI</filename> entry.
+                    On the other hand, if the recipe needs to fetch a tarball, apply
+                    two patches, and include a custom file, the recipe would include four
+                    instances of the variable.</para>
+                <para>The following list explains the available URI protocols:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>file://</filename> -</emphasis> Fetches files, which is usually
+                            a file shipped with the metadata, from the local machine. 
+                            The path is relative to the 
+                            <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> 
+                            variable.
+                            Thus, the build system searches, in order, from the following directories,
+                            which are assumed to be a subdirectories of the directory in which the 
+                            recipe file resides:
+                            <itemizedlist>
+                                <listitem><para><emphasis><filename>${PN}</filename> -</emphasis> The package name 
+                                    with any special suffix (i.e. <filename>bash-native</filename>, 
+                                    <filename>bash</filename>).
+                                    <note>The package name (<filename>PN</filename>) includes the special suffix 
+                                    <filename>-native</filename> for native recipes, 
+                                    <filename>-cross</filename> for cross recipes, a Multilib suffix 
+                                    for Multilib recipes, and so forth).</note></para></listitem>
+                                <listitem><para><emphasis><filename>${PF}</filename> - </emphasis>
+                                    <filename>${PN}-${EXTENDPE}${PV}-${PR}</filename>.
+                                    The package name including all version and revision numbers 
+                                    (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
+                                    <filename>bash-4.2-r1/</filename>).</para></listitem>
+                                <listitem><para><emphasis><filename>${P}</filename> -</emphasis> 
+                                    <filename>${PN}-${PV}</filename>. 
+                                    The package name and version (i.e. <filename>bash-4.2</filename>).
+                                    </para></listitem>
+                                <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis> The 
+                                    base package name without any special suffix or version numbers.
+                                    </para></listitem>
+                                <listitem><para><emphasis><filename>${BP}</filename> -</emphasis> 
+                                    <filename>${BPN}-${PV}</filename>.
+                                    The base package name and version but without any special 
+                                    package name suffix.</para></listitem>
+                                <listitem><para><emphasis>Files -</emphasis> Files beneath the directory in which the recipe
+                                    resides.</para></listitem>
+                                <listitem><para><emphasis>Directory -</emphasis> The directory itself in which the recipe
+                                    resides.</para></listitem>
+                            </itemizedlist></para></listitem>
+                        <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a 
+                            Bazaar revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a 
+                            Git revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from 
+                            an OSC (OpenSuse Build service) revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from 
+                            a repo (Git) repository.</para></listitem>
+                        <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from 
+                            an SVK revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from 
+                            the Internet using <filename>http</filename>.</para></listitem>
+                        <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files 
+                            from the Internet using <filename>https</filename>.</para></listitem>
+                        <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files 
+                            from the Internet using <filename>ftp</filename>.</para></listitem>
+                        <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from 
+                            a CVS revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from 
+                            a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from 
+                            a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from 
+                            a secure shell.</para></listitem>
+                        <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from 
+                            a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
+                    </itemizedlist>
+                </para>
+                <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
+                    Here are standard options:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply 
+                            the patch or not. 
+                            The default action is to apply the patch.</para></listitem>
+                        <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which 
+                            striplevel to use when applying the patch.
+                            The default level is 1.</para></listitem>
+                    </itemizedlist>
+                </para>
+                <para>Here are options specific to recipes building code from a revision control system:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>mindate</filename> -</emphasis> Only applies 
+                            the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link> 
+                            is equal to or greater than <filename>mindate</filename>.</para></listitem>
+                        <listitem><para><emphasis><filename>maxdate</filename> -</emphasis> Only applies 
+                            the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link> 
+                            is not later than <filename>mindate</filename>.</para></listitem>
+                        <listitem><para><emphasis><filename>minrev</filename> -</emphasis> Only applies 
+                            the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> 
+                            is equal to or greater than <filename>minrev</filename>.</para></listitem>
+                        <listitem><para><emphasis><filename>maxrev</filename> -</emphasis> Only applies 
+                            the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> 
+                            is not later than <filename>maxrev</filename>.</para></listitem>
+                        <listitem><para><emphasis><filename>rev</filename> -</emphasis> Only applies the 
+                            patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> 
+                            is equal to <filename>rev</filename>.</para></listitem>
+                        <listitem><para><emphasis><filename>notrev</filename> -</emphasis> Only applies 
+                            the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> 
+                            is not equal to <filename>rev</filename>.</para></listitem>
+                    </itemizedlist>
+                </para>
+                <para>Here are some additional options worth mentioning:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls 
+                            whether or not to unpack the file if it is an archive.
+                            The default action is to upack the file.</para></listitem>
+                        <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file 
+                            (or extracts its contents) into the specified 
+                            subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
+                            This option is useful for unusual tarballs or other archives that 
+                            don't have their files already in a subdirectory within the archive.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a 
+                            name to be used for association with <filename>SRC_URI</filename> checksums 
+                            when you have more than one file specified in <filename>SRC_URI</filename>.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
             </glossdef>
         </glossentry>