From bbc7a646ecbcbc5ab97a59a43df736e0f5edb3e0 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 22 Sep 2016 15:55:29 -0700 Subject: [PATCH] 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 Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-model.xml | 139 ++++++++++++++++++ documentation/ref-manual/ref-tasks.xml | 16 ++ 2 files changed, 155 insertions(+) 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 @@ +
+ Using a Development Python Shell + + + 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, + devpyshell can be a useful tool. + When you invoke devpyshell, all tasks up to and + including + do_patch + are run for the specified target. + Then, a new terminal is opened and you are placed in + ${S}, + the source directory. + In the new terminal, all the OpenEmbedded build-related environment variables are + still defined so you can use commands such as configure and + make. + 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: + + 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> + + 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. + + + + Following is an example that uses devpyshell on a target named + matchbox-desktop: + + $ bitbake matchbox-desktop -c devpyshell + + + + + This command spawns a terminal and places you in an interactive + Python interpreter within the OpenEmbedded build environment. + The OE_TERMINAL + variable controls what type of shell is opened. + + + + For spawned terminals, the following occurs: + + The PATH variable includes the + cross-toolchain. + The pkgconfig variables find the correct + .pc files. + The configure command finds the + Yocto Project site files as well as any other necessary files. + + + + + 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 (S). + + + + To manually run a specific task using devpyshell, + run the corresponding run.* script in + the + ${WORKDIR}/temp + directory (e.g., + run.do_configure.pid). + 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 devshell: + + $ bitbake -c task + + Notes + + Execution of a task's run.* + 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 + bitbake -c command. + + Any run.* file that does not + have a .pid extension is a + symbolic link (symlink) to the most recent version of that + file. + + + + + + + Remember, that the devpyshell 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. + + + + When you are finished using devpyshell, exit the shell + or close the terminal window. + + + Notes + + + It is worth remembering that when using devpyshell + you need to use the full compiler name such as arm-poky-linux-gnueabi-gcc + instead of just using gcc. + The same applies to other applications such as binutils, + libtool and so forth. + BitBake sets up environment variables such as CC + to assist applications, such as make to find the correct tools. + + + It is also worth noting that devpyshell still works over + X11 forwarding and similar situations. + + + +
+ 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 @@ +
+ <filename>do_devpyshell</filename> + + + 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 + "Using a Development Python Shell" + section in the Yocto Project Development Manual for more + information about using devpyshell. + +
+
<filename>do_devshell</filename>