[gnome-continuous-yocto/gnomeostree-3.28-rocko: 1484/8267] bitbake: bitbake-user-manual: Addeds support for the Perforce Fetcher

[Emmanuele Bassi <ebassi src gnome org>]

commit 35081f55185a8a9804c21b16cd4600ba70646a10
Author: Andrew Bradford <andrew bradford kodakalaris com>
Date:   Thu Jul 14 11:42:56 2016 -0700

    bitbake: bitbake-user-manual: Addeds support for the Perforce Fetcher
    
    Added a new Perforce Fetcher section in the same spirit as the existing
    sections for other supported fetchers.  Changes included the new section,
    removal of the bulleted item that mentioned this fetcher as an
    "additional" fetcher, and the creation of a new variable in the glossary
    named P4DIR.
    
    (Bitbake rev: 47e03b1789ee1c18407dbac33a6c235752019865)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 .../bitbake-user-manual-fetching.xml               |   69 ++++++++++++++++++--
 .../bitbake-user-manual-ref-variables.xml          |   11 +++-
 2 files changed, 74 insertions(+), 6 deletions(-)
---
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml 
b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml
index f168cfa..2a3340b 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml
@@ -670,8 +670,8 @@
                             The <filename>module</filename> and <filename>vob</filename>
                             options are combined to create the <filename>load</filename> rule in
                             the view config spec.
-                            As an example, consider the <filename>vob</filename> and 
-                            <filename>module</filename> values from the 
+                            As an example, consider the <filename>vob</filename> and
+                            <filename>module</filename> values from the
                             <filename>SRC_URI</filename> statement at the start of this section.
                             Combining those values results in the following:
                             <literallayout class='monospaced'>
@@ -716,6 +716,68 @@
             </para>
         </section>
 
+        <section id='perforce-fetcher'>
+            <title>Perforce Fetcher (<filename>p4://</filename>)</title>
+
+            <para>
+                This fetcher submodule fetches code from the
+                <ulink url='https://www.perforce.com/'>Perforce</ulink>
+                source control system.
+                The executable used is specified by
+                <filename>FETCHCMD_p4</filename>, which defaults
+                to "p4".
+                The fetcher's temporary working directory is set by
+                <link linkend='var-P4DIR'><filename>P4DIR</filename></link>,
+                which defaults to "DL_DIR/p4".
+            </para>
+
+            <para>
+                To use this fetcher, make sure your recipe has proper
+                <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
+                <link linkend='var-SRCREV'><filename>SRCREV</filename></link>, and
+                <link linkend='var-PV'><filename>PV</filename></link> values.
+                The p4 executable is able to use the config file defined by your
+                system's <filename>P4CONFIG</filename> environment variable in
+                order to define the Perforce server URL and port, username, and
+                password if you do not wish to keep those values in a recipe
+                itself.
+                If you choose not to use <filename>P4CONFIG</filename>,
+                or to explicitly set variables that <filename>P4CONFIG</filename>
+                can contain, you can specify the <filename>P4PORT</filename> value,
+                which is the server's URL and port number, and you can
+                specify a username and password directly in your recipe within
+                <filename>SRC_URI</filename>.
+            </para>
+
+            <para>
+                Here is an example that relies on <filename>P4CONFIG</filename>
+                to specify the server URL and port, username, and password, and
+                fetches the Head Revision:
+                <literallayout class='monospaced'>
+    SRC_URI = "p4://example-depot/main/source/..."
+    SRCREV = "${AUTOREV}"
+    PV = "p4-${SRCPV}"
+    S = "${WORKDIR}/p4"
+                </literallayout>
+            </para>
+
+            <para>
+                Here is an example that specifies the server URL and port,
+                username, and password, and fetches a Revision based on a Label:
+                <literallayout class='monospaced'>
+    P4PORT = "tcp:p4server.example.net:1666"
+    SRC_URI = "p4://user:passwd@example-depot/main/source/..."
+    SRCREV = "release-1.0"
+    PV = "p4-${SRCPV}"
+    S = "${WORKDIR}/p4"
+                </literallayout>
+                <note>
+                    You should always set <filename>S</filename>
+                    to <filename>"${WORKDIR}/p4"</filename> in your recipe.
+                </note>
+            </para>
+        </section>
+
         <section id='other-fetchers'>
             <title>Other Fetchers</title>
 
@@ -726,9 +788,6 @@
                         Bazaar (<filename>bzr://</filename>)
                         </para></listitem>
                     <listitem><para>
-                        Perforce (<filename>p4://</filename>)
-                        </para></listitem>
-                    <listitem><para>
                         Trees using Git Annex (<filename>gitannex://</filename>)
                         </para></listitem>
                     <listitem><para>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml 
b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
index e26422a..e81f3ed 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
@@ -52,7 +52,7 @@
        <link linkend='var-MIRRORS'>M</link>
 <!--               <link linkend='var-glossary-n'>N</link> -->
        <link linkend='var-OVERRIDES'>O</link>
-       <link linkend='var-PACKAGES'>P</link>
+       <link linkend='var-P4DIR'>P</link>
 <!--       <link linkend='var-QMAKE_PROFILES'>Q</link> -->
        <link linkend='var-RDEPENDS'>R</link>
        <link linkend='var-SECTION'>S</link>
@@ -1769,6 +1769,15 @@
 
     <glossdiv id='var-glossary-p'><title>P</title>
 
+        <glossentry id='var-P4DIR'><glossterm>P4DIR</glossterm>
+            <glossdef>
+                <para>
+                    The directory in which a local copy of a Perforce depot
+                    is stored when it is fetched.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
             <glossdef>
                 <para>The list of packages the recipe creates.