summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-model.xml139
1 files changed, 139 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 @@
1593 </note> 1593 </note>
1594</section> 1594</section>
1595 1595
1596<section id="platdev-appdev-devpyshell">
1597 <title>Using a Development Python Shell</title>
1598
1599 <para>
1600 Similar to working within a development shell as described in
1601 the previous section, you can also spawn and work within an
1602 interactive Python development shell.
1603 When debugging certain commands or even when just editing packages,
1604 <filename>devpyshell</filename> can be a useful tool.
1605 When you invoke <filename>devpyshell</filename>, all tasks up to and
1606 including
1607 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1608 are run for the specified target.
1609 Then, a new terminal is opened and you are placed in
1610 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
1611 the source directory.
1612 In the new terminal, all the OpenEmbedded build-related environment variables are
1613 still defined so you can use commands such as <filename>configure</filename> and
1614 <filename>make</filename>.
1615 Additionally, key Python objects and code are available in the same
1616 way they are to BitBake tasks, in particular, the data store 'd'.
1617 So, commands such as the following are useful when exploring the data
1618 store and running functions:
1619 <literallayout class='monospaced'>
1620 pydevshell> d.getVar("STAGING_DIR", True)
1621 '/media/build1/poky/build/tmp/sysroots'
1622 pydevshell> d.getVar("STAGING_DIR", False)
1623 '${TMPDIR}/sysroots'
1624 pydevshell> d.setVar("FOO", "bar")
1625 pydevshell> d.getVar("FOO", True)
1626 'bar'
1627 pydevshell> d.delVar("FOO")
1628 pydevshell> d.getVar("FOO", True)
1629 pydevshell> bb.build.exec_func("do_unpack", d)
1630 pydevshell>
1631 </literallayout>
1632 The commands execute just as if the OpenEmbedded build system were executing them.
1633 Consequently, working this way can be helpful when debugging a build or preparing
1634 software to be used with the OpenEmbedded build system.
1635 </para>
1636
1637 <para>
1638 Following is an example that uses <filename>devpyshell</filename> on a target named
1639 <filename>matchbox-desktop</filename>:
1640 <literallayout class='monospaced'>
1641 $ bitbake matchbox-desktop -c devpyshell
1642 </literallayout>
1643 </para>
1644
1645 <para>
1646 This command spawns a terminal and places you in an interactive
1647 Python interpreter within the OpenEmbedded build environment.
1648 The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
1649 variable controls what type of shell is opened.
1650 </para>
1651
1652 <para>
1653 For spawned terminals, the following occurs:
1654 <itemizedlist>
1655 <listitem><para>The <filename>PATH</filename> variable includes the
1656 cross-toolchain.</para></listitem>
1657 <listitem><para>The <filename>pkgconfig</filename> variables find the correct
1658 <filename>.pc</filename> files.</para></listitem>
1659 <listitem><para>The <filename>configure</filename> command finds the
1660 Yocto Project site files as well as any other necessary files.</para></listitem>
1661 </itemizedlist>
1662 </para>
1663
1664 <para>
1665 Within this environment, you can run configure or compile
1666 commands as if they were being run by
1667 the OpenEmbedded build system itself.
1668 As noted earlier, the working directory also automatically changes to the
1669 Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
1670 </para>
1671
1672 <para>
1673 To manually run a specific task using <filename>devpyshell</filename>,
1674 run the corresponding <filename>run.*</filename> script in
1675 the
1676 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp</filename>
1677 directory (e.g.,
1678 <filename>run.do_configure.</filename><replaceable>pid</replaceable>).
1679 If a task's script does not exist, which would be the case if the task was
1680 skipped by way of the sstate cache, you can create the task by first running
1681 it outside of the <filename>devshell</filename>:
1682 <literallayout class='monospaced'>
1683 $ bitbake -c <replaceable>task</replaceable>
1684 </literallayout>
1685 <note><title>Notes</title>
1686 <itemizedlist>
1687 <listitem><para>Execution of a task's <filename>run.*</filename>
1688 script and BitBake's execution of a task are identical.
1689 In other words, running the script re-runs the task
1690 just as it would be run using the
1691 <filename>bitbake -c</filename> command.
1692 </para></listitem>
1693 <listitem><para>Any <filename>run.*</filename> file that does not
1694 have a <filename>.pid</filename> extension is a
1695 symbolic link (symlink) to the most recent version of that
1696 file.
1697 </para></listitem>
1698 </itemizedlist>
1699 </note>
1700 </para>
1701
1702 <para>
1703 Remember, that the <filename>devpyshell</filename> is a mechanism that allows
1704 you to get into the BitBake task execution environment
1705 through an interactive Python interpreter.
1706 And as such, all commands must be called just as BitBake would call them.
1707 That means you need to provide the appropriate options for
1708 cross-compilation and so forth as applicable.
1709 </para>
1710
1711 <para>
1712 When you are finished using <filename>devpyshell</filename>, exit the shell
1713 or close the terminal window.
1714 </para>
1715
1716 <note><title>Notes</title>
1717 <itemizedlist>
1718 <listitem><para>
1719 It is worth remembering that when using <filename>devpyshell</filename>
1720 you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename>
1721 instead of just using <filename>gcc</filename>.
1722 The same applies to other applications such as <filename>binutils</filename>,
1723 <filename>libtool</filename> and so forth.
1724 BitBake sets up environment variables such as <filename>CC</filename>
1725 to assist applications, such as <filename>make</filename> to find the correct tools.
1726 </para></listitem>
1727 <listitem><para>
1728 It is also worth noting that <filename>devpyshell</filename> still works over
1729 X11 forwarding and similar situations.
1730 </para></listitem>
1731 </itemizedlist>
1732 </note>
1733</section>
1734
1596</chapter> 1735</chapter>