diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2016-09-22 15:55:29 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2016-09-28 15:02:33 +0100 |
commit | bbc7a646ecbcbc5ab97a59a43df736e0f5edb3e0 (patch) | |
tree | 8fd475094b3bb2757946efae264132b008c4d676 | |
parent | 9f2cf76e091ed66f36e88ce0718c8336730f6c38 (diff) | |
download | openembedded-core-contrib-bbc7a646ecbcbc5ab97a59a43df736e0f5edb3e0.tar.gz |
ref-manual, dev-manual: Add information on devpyshell
Fixes [YOCTO #9166]
In the dev-manual, I added a new section titled "Using a
Development Python Shell." This section is similar to the
section that talks about using devshell. The section is
tied to a reference section on the do_devpyshell task.
In the ref-manual, I entered a new task reference for the
do_devpyshell task. It is brief and references into the
new section in the dev-manual.
(From yocto-docs rev: 637128809e298c3d5e660f6da2366f8e9e307218)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/dev-manual/dev-manual-model.xml | 139 | ||||
-rw-r--r-- | documentation/ref-manual/ref-tasks.xml | 16 |
2 files changed, 155 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index c5c672baae..6f359c2986 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -1593,4 +1593,143 @@ </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 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>. + 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> + 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>devpyshell</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>devpyshell</filename> is a mechanism that allows + you to get into the BitBake task execution environment + through an interactive Python interpreter. + 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>devpyshell</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>devpyshell</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>devpyshell</filename> still works over + X11 forwarding and similar situations. + </para></listitem> + </itemizedlist> + </note> +</section> + </chapter> diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml index 0ad3632538..f05d0f8eb7 100644 --- a/documentation/ref-manual/ref-tasks.xml +++ b/documentation/ref-manual/ref-tasks.xml @@ -684,6 +684,22 @@ </para> </section> + <section id='ref-tasks-devpyshell'> + <title><filename>do_devpyshell</filename></title> + + <para> + Starts a shell in which an interactive Python interpreter allows + you to interact with the BitBake build environment. + From within this shell, you can directly examine and set + bits from the data store and execute functions as if within + the BitBake environment. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devpyshell'>Using a Development Python Shell</ulink>" + section in the Yocto Project Development Manual for more + information about using <filename>devpyshell</filename>. + </para> + </section> + <section id='ref-tasks-devshell'> <title><filename>do_devshell</filename></title> |