1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Using a Development Shell
4*************************
5
6When debugging certain commands or even when just editing packages,
7``devshell`` can be a useful tool. When you invoke ``devshell``, all
8tasks up to and including
9:ref:`ref-tasks-patch` are run for the
10specified target. Then, a new terminal is opened and you are placed in
11``${``\ :term:`S`\ ``}``, the source
12directory. In the new terminal, all the OpenEmbedded build-related
13environment variables are still defined so you can use commands such as
14``configure`` and ``make``. The commands execute just as if the
15OpenEmbedded build system were executing them. Consequently, working
16this way can be helpful when debugging a build or preparing software to
17be used with the OpenEmbedded build system.
18
19Here is an example that uses ``devshell`` on a target named
20``matchbox-desktop``::
21
22  $ bitbake matchbox-desktop -c devshell
23
24This command spawns a terminal with a shell prompt within the
25OpenEmbedded build environment. The
26:term:`OE_TERMINAL` variable
27controls what type of shell is opened.
28
29For spawned terminals, the following occurs:
30
31-  The ``PATH`` variable includes the cross-toolchain.
32
33-  The ``pkgconfig`` variables find the correct ``.pc`` files.
34
35-  The ``configure`` command finds the Yocto Project site files as well
36   as any other necessary files.
37
38Within this environment, you can run configure or compile commands as if
39they were being run by the OpenEmbedded build system itself. As noted
40earlier, the working directory also automatically changes to the Source
41Directory (:term:`S`).
42
43To manually run a specific task using ``devshell``, run the
44corresponding ``run.*`` script in the
45``${``\ :term:`WORKDIR`\ ``}/temp``
46directory (e.g., ``run.do_configure.``\ `pid`). If a task's script does
47not exist, which would be the case if the task was skipped by way of the
48sstate cache, you can create the task by first running it outside of the
49``devshell``::
50
51   $ bitbake -c task
52
53.. note::
54
55   -  Execution of a task's ``run.*`` script and BitBake's execution of
56      a task are identical. In other words, running the script re-runs
57      the task just as it would be run using the ``bitbake -c`` command.
58
59   -  Any ``run.*`` file that does not have a ``.pid`` extension is a
60      symbolic link (symlink) to the most recent version of that file.
61
62Remember, that the ``devshell`` is a mechanism that allows you to get
63into the BitBake task execution environment. And as such, all commands
64must be called just as BitBake would call them. That means you need to
65provide the appropriate options for cross-compilation and so forth as
66applicable.
67
68When you are finished using ``devshell``, exit the shell or close the
69terminal window.
70
71.. note::
72
73   -  It is worth remembering that when using ``devshell`` you need to
74      use the full compiler name such as ``arm-poky-linux-gnueabi-gcc``
75      instead of just using ``gcc``. The same applies to other
76      applications such as ``binutils``, ``libtool`` and so forth.
77      BitBake sets up environment variables such as :term:`CC` to assist
78      applications, such as ``make`` to find the correct tools.
79
80   -  It is also worth noting that ``devshell`` still works over X11
81      forwarding and similar situations.
82
83