[gnome-continuous-yocto/gnomeostree-3.28-rocko: 6716/8267] dev-manual: Moved devshell and python shell workflow sections.

[Emmanuele Bassi <ebassi src gnome org>]

commit b15a65b8ea60032cf113196420a16183d0a0585a
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Mon Jul 3 09:44:07 2017 -0700

    dev-manual: Moved devshell and python shell workflow sections.
    
    Fixes [YOCTO #11630]
    
    These two sections can stand alone as tasks.  I moved them to the
    "Common Tasks" chapter.
    
    (From yocto-docs rev: 60c810a9682f8a110fe7c7e4d0d40583a7d72735)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 .../dev-manual/dev-manual-common-tasks.xml         |  175 ++++++++++++++++++++
 documentation/dev-manual/dev-manual-model.xml      |  175 --------------------
 2 files changed, 175 insertions(+), 175 deletions(-)
---
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml 
b/documentation/dev-manual/dev-manual-common-tasks.xml
index b01871b..c6efcf6 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4202,6 +4202,181 @@
         </para>
     </section>
 
+    <section id="platdev-appdev-devshell">
+        <title>Using a Development Shell</title>
+
+        <para>
+            When debugging certain commands or even when just editing packages,
+            <filename>devshell</filename> can be a useful tool.
+            When you invoke <filename>devshell</filename>, all tasks up to and
+            including
+            <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
+            are run for the specified target.
+            Then, a new terminal is opened and you are placed in
+            <filename>${</filename><ulink 
url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
+            the source directory.
+            In the new terminal, all the OpenEmbedded build-related environment variables are
+            still defined so you can use commands such as <filename>configure</filename> and
+            <filename>make</filename>.
+            The commands execute just as if the OpenEmbedded build system were executing them.
+            Consequently, working this way can be helpful when debugging a build or preparing
+            software to be used with the OpenEmbedded build system.
+        </para>
+
+        <para>
+            Following is an example that uses <filename>devshell</filename> on a target named
+            <filename>matchbox-desktop</filename>:
+            <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop -c devshell
+            </literallayout>
+        </para>
+
+        <para>
+            This command spawns a terminal with a shell prompt within the OpenEmbedded build environment.
+            The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
+            variable controls what type of shell is opened.
+        </para>
+
+        <para>
+            For spawned terminals, the following occurs:
+            <itemizedlist>
+                <listitem><para>The <filename>PATH</filename> variable includes the
+                    cross-toolchain.</para></listitem>
+                <listitem><para>The <filename>pkgconfig</filename> variables find the correct
+                    <filename>.pc</filename> files.</para></listitem>
+                <listitem><para>The <filename>configure</filename> command finds the
+                    Yocto Project site files as well as any other necessary files.</para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Within this environment, you can run configure or compile
+            commands as if they were being run by
+            the OpenEmbedded build system itself.
+            As noted earlier, the working directory also automatically changes to the
+            Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
+        </para>
+
+        <para>
+            To manually run a specific task using <filename>devshell</filename>,
+            run the corresponding <filename>run.*</filename> script in
+            the
+            <filename>${</filename><ulink 
url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp</filename>
+            directory (e.g.,
+            <filename>run.do_configure.</filename><replaceable>pid</replaceable>).
+            If a task's script does not exist, which would be the case if the task was
+            skipped by way of the sstate cache, you can create the task by first running
+            it outside of the <filename>devshell</filename>:
+            <literallayout class='monospaced'>
+     $ bitbake -c <replaceable>task</replaceable>
+            </literallayout>
+            <note><title>Notes</title>
+                <itemizedlist>
+                    <listitem><para>Execution of a task's <filename>run.*</filename>
+                        script and BitBake's execution of a task are identical.
+                        In other words, running the script re-runs the task
+                        just as it would be run using the
+                        <filename>bitbake -c</filename> command.
+                        </para></listitem>
+                    <listitem><para>Any <filename>run.*</filename> file that does not
+                        have a <filename>.pid</filename> extension is a
+                        symbolic link (symlink) to the most recent version of that
+                        file.
+                        </para></listitem>
+                </itemizedlist>
+            </note>
+        </para>
+
+        <para>
+            Remember, that the <filename>devshell</filename> is a mechanism that allows
+            you to get into the BitBake task execution environment.
+            And as such, all commands must be called just as BitBake would call them.
+            That means you need to provide the appropriate options for
+            cross-compilation and so forth as applicable.
+        </para>
+
+        <para>
+            When you are finished using <filename>devshell</filename>, exit the shell
+            or close the terminal window.
+        </para>
+
+        <note><title>Notes</title>
+            <itemizedlist>
+                <listitem><para>
+                    It is worth remembering that when using <filename>devshell</filename>
+                    you need to use the full compiler name such as 
<filename>arm-poky-linux-gnueabi-gcc</filename>
+                    instead of just using <filename>gcc</filename>.
+                    The same applies to other applications such as <filename>binutils</filename>,
+                    <filename>libtool</filename> and so forth.
+                    BitBake sets up environment variables such as <filename>CC</filename>
+                    to assist applications, such as <filename>make</filename> to find the correct tools.
+                    </para></listitem>
+                <listitem><para>
+                    It is also worth noting that <filename>devshell</filename> still works over
+                    X11 forwarding and similar situations.
+                    </para></listitem>
+            </itemizedlist>
+        </note>
+    </section>
+
+    <section id="platdev-appdev-devpyshell">
+        <title>Using a Development Python Shell</title>
+
+        <para>
+            Similar to working within a development shell as described in
+            the previous section, you can also spawn and work within an
+            interactive Python development shell.
+            When debugging certain commands or even when just editing packages,
+            <filename>devpyshell</filename> can be a useful tool.
+            When you invoke <filename>devpyshell</filename>, all tasks up to and
+            including
+            <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
+            are run for the specified target.
+            Then a new terminal is opened.
+            Additionally, key Python objects and code are available in the same
+            way they are to BitBake tasks, in particular, the data store 'd'.
+            So, commands such as the following are useful when exploring the data
+            store and running functions:
+            <literallayout class='monospaced'>
+     pydevshell> d.getVar("STAGING_DIR", True)
+     '/media/build1/poky/build/tmp/sysroots'
+     pydevshell> d.getVar("STAGING_DIR", False)
+     '${TMPDIR}/sysroots'
+     pydevshell> d.setVar("FOO", "bar")
+     pydevshell> d.getVar("FOO", True)
+     'bar'
+     pydevshell> d.delVar("FOO")
+     pydevshell> d.getVar("FOO", True)
+     pydevshell> bb.build.exec_func("do_unpack", d)
+     pydevshell>
+            </literallayout>
+            The commands execute just as if the OpenEmbedded build system were executing them.
+            Consequently, working this way can be helpful when debugging a build or preparing
+            software to be used with the OpenEmbedded build system.
+        </para>
+
+        <para>
+            Following is an example that uses <filename>devpyshell</filename> on a target named
+            <filename>matchbox-desktop</filename>:
+            <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop -c devpyshell
+            </literallayout>
+        </para>
+
+        <para>
+            This command spawns a terminal and places you in an interactive
+            Python interpreter within the OpenEmbedded build environment.
+            The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
+            variable controls what type of shell is opened.
+        </para>
+
+        <para>
+            When you are finished using <filename>devpyshell</filename>, you
+            can exit the shell either by using Ctrl+d or closing the terminal
+            window.
+        </para>
+    </section>
+
     <section id='platdev-building-targets-with-multiple-configurations'>
         <title>Building Targets with Multiple Configurations</title>
 
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 173871a..aeaa3fd 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -718,179 +718,4 @@
     </section>
 </section>
 
-<section id="platdev-appdev-devshell">
-    <title>Using a Development Shell</title>
-
-    <para>
-        When debugging certain commands or even when just editing packages,
-        <filename>devshell</filename> can be a useful tool.
-        When you invoke <filename>devshell</filename>, all tasks up to and
-        including
-        <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
-        are run for the specified target.
-        Then, a new terminal is opened and you are placed in
-        <filename>${</filename><ulink 
url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
-        the source directory.
-        In the new terminal, all the OpenEmbedded build-related environment variables are
-        still defined so you can use commands such as <filename>configure</filename> and
-        <filename>make</filename>.
-        The commands execute just as if the OpenEmbedded build system were executing them.
-        Consequently, working this way can be helpful when debugging a build or preparing
-        software to be used with the OpenEmbedded build system.
-    </para>
-
-    <para>
-        Following is an example that uses <filename>devshell</filename> on a target named
-        <filename>matchbox-desktop</filename>:
-        <literallayout class='monospaced'>
-     $ bitbake matchbox-desktop -c devshell
-        </literallayout>
-    </para>
-
-    <para>
-        This command spawns a terminal with a shell prompt within the OpenEmbedded build environment.
-        The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
-        variable controls what type of shell is opened.
-    </para>
-
-    <para>
-        For spawned terminals, the following occurs:
-        <itemizedlist>
-            <listitem><para>The <filename>PATH</filename> variable includes the
-                cross-toolchain.</para></listitem>
-            <listitem><para>The <filename>pkgconfig</filename> variables find the correct
-                <filename>.pc</filename> files.</para></listitem>
-                <listitem><para>The <filename>configure</filename> command finds the
-                Yocto Project site files as well as any other necessary files.</para></listitem>
-        </itemizedlist>
-    </para>
-
-    <para>
-        Within this environment, you can run configure or compile
-        commands as if they were being run by
-        the OpenEmbedded build system itself.
-        As noted earlier, the working directory also automatically changes to the
-        Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
-    </para>
-
-    <para>
-        To manually run a specific task using <filename>devshell</filename>,
-        run the corresponding <filename>run.*</filename> script in
-        the
-        <filename>${</filename><ulink 
url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp</filename>
-        directory (e.g.,
-        <filename>run.do_configure.</filename><replaceable>pid</replaceable>).
-        If a task's script does not exist, which would be the case if the task was
-        skipped by way of the sstate cache, you can create the task by first running
-        it outside of the <filename>devshell</filename>:
-        <literallayout class='monospaced'>
-     $ bitbake -c <replaceable>task</replaceable>
-        </literallayout>
-        <note><title>Notes</title>
-            <itemizedlist>
-                <listitem><para>Execution of a task's <filename>run.*</filename>
-                    script and BitBake's execution of a task are identical.
-                    In other words, running the script re-runs the task
-                    just as it would be run using the
-                    <filename>bitbake -c</filename> command.
-                    </para></listitem>
-                <listitem><para>Any <filename>run.*</filename> file that does not
-                    have a <filename>.pid</filename> extension is a
-                    symbolic link (symlink) to the most recent version of that
-                    file.
-                    </para></listitem>
-            </itemizedlist>
-        </note>
-    </para>
-
-    <para>
-        Remember, that the <filename>devshell</filename> is a mechanism that allows
-        you to get into the BitBake task execution environment.
-        And as such, all commands must be called just as BitBake would call them.
-        That means you need to provide the appropriate options for
-        cross-compilation and so forth as applicable.
-    </para>
-
-    <para>
-        When you are finished using <filename>devshell</filename>, exit the shell
-        or close the terminal window.
-    </para>
-
-    <note><title>Notes</title>
-        <itemizedlist>
-            <listitem><para>
-                It is worth remembering that when using <filename>devshell</filename>
-                you need to use the full compiler name such as 
<filename>arm-poky-linux-gnueabi-gcc</filename>
-                instead of just using <filename>gcc</filename>.
-                The same applies to other applications such as <filename>binutils</filename>,
-                <filename>libtool</filename> and so forth.
-                BitBake sets up environment variables such as <filename>CC</filename>
-                to assist applications, such as <filename>make</filename> to find the correct tools.
-                </para></listitem>
-            <listitem><para>
-                It is also worth noting that <filename>devshell</filename> still works over
-                X11 forwarding and similar situations.
-                </para></listitem>
-        </itemizedlist>
-    </note>
-</section>
-
-<section id="platdev-appdev-devpyshell">
-    <title>Using a Development Python Shell</title>
-
-    <para>
-        Similar to working within a development shell as described in
-        the previous section, you can also spawn and work within an
-        interactive Python development shell.
-        When debugging certain commands or even when just editing packages,
-        <filename>devpyshell</filename> can be a useful tool.
-        When you invoke <filename>devpyshell</filename>, all tasks up to and
-        including
-        <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
-        are run for the specified target.
-        Then a new terminal is opened.
-        Additionally, key Python objects and code are available in the same
-        way they are to BitBake tasks, in particular, the data store 'd'.
-        So, commands such as the following are useful when exploring the data
-        store and running functions:
-        <literallayout class='monospaced'>
-     pydevshell> d.getVar("STAGING_DIR", True)
-     '/media/build1/poky/build/tmp/sysroots'
-     pydevshell> d.getVar("STAGING_DIR", False)
-     '${TMPDIR}/sysroots'
-     pydevshell> d.setVar("FOO", "bar")
-     pydevshell> d.getVar("FOO", True)
-     'bar'
-     pydevshell> d.delVar("FOO")
-     pydevshell> d.getVar("FOO", True)
-     pydevshell> bb.build.exec_func("do_unpack", d)
-     pydevshell>
-        </literallayout>
-        The commands execute just as if the OpenEmbedded build system were executing them.
-        Consequently, working this way can be helpful when debugging a build or preparing
-        software to be used with the OpenEmbedded build system.
-    </para>
-
-    <para>
-        Following is an example that uses <filename>devpyshell</filename> on a target named
-        <filename>matchbox-desktop</filename>:
-        <literallayout class='monospaced'>
-     $ bitbake matchbox-desktop -c devpyshell
-        </literallayout>
-    </para>
-
-    <para>
-        This command spawns a terminal and places you in an interactive
-        Python interpreter within the OpenEmbedded build environment.
-        The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
-        variable controls what type of shell is opened.
-    </para>
-
-    <para>
-        When you are finished using <filename>devpyshell</filename>, you
-        can exit the shell either by using Ctrl+d or closing the terminal
-        window.
-    </para>
-</section>
-
 </chapter>