diff options
Diffstat (limited to 'documentation/dev-manual/development-shell.rst')
-rw-r--r-- | documentation/dev-manual/development-shell.rst | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/documentation/dev-manual/development-shell.rst b/documentation/dev-manual/development-shell.rst new file mode 100644 index 0000000000..be26bcffc7 --- /dev/null +++ b/documentation/dev-manual/development-shell.rst | |||
@@ -0,0 +1,82 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | Using a Development Shell | ||
4 | ************************* | ||
5 | |||
6 | When debugging certain commands or even when just editing packages, | ||
7 | ``devshell`` can be a useful tool. When you invoke ``devshell``, all | ||
8 | tasks up to and including | ||
9 | :ref:`ref-tasks-patch` are run for the | ||
10 | specified target. Then, a new terminal is opened and you are placed in | ||
11 | ``${``\ :term:`S`\ ``}``, the source | ||
12 | directory. In the new terminal, all the OpenEmbedded build-related | ||
13 | environment variables are still defined so you can use commands such as | ||
14 | ``configure`` and ``make``. The commands execute just as if the | ||
15 | OpenEmbedded build system were executing them. Consequently, working | ||
16 | this way can be helpful when debugging a build or preparing software to | ||
17 | be used with the OpenEmbedded build system. | ||
18 | |||
19 | Here is an example that uses ``devshell`` on a target named | ||
20 | ``matchbox-desktop``:: | ||
21 | |||
22 | $ bitbake matchbox-desktop -c devshell | ||
23 | |||
24 | This command spawns a terminal with a shell prompt within the | ||
25 | OpenEmbedded build environment. The | ||
26 | :term:`OE_TERMINAL` variable | ||
27 | controls what type of shell is opened. | ||
28 | |||
29 | For 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 | |||
38 | Within this environment, you can run configure or compile commands as if | ||
39 | they were being run by the OpenEmbedded build system itself. As noted | ||
40 | earlier, the working directory also automatically changes to the Source | ||
41 | Directory (:term:`S`). | ||
42 | |||
43 | To manually run a specific task using ``devshell``, run the | ||
44 | corresponding ``run.*`` script in the | ||
45 | ``${``\ :term:`WORKDIR`\ ``}/temp`` | ||
46 | directory (e.g., ``run.do_configure.``\ `pid`). If a task's script does | ||
47 | not exist, which would be the case if the task was skipped by way of the | ||
48 | sstate 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 | |||
62 | Remember, that the ``devshell`` is a mechanism that allows you to get | ||
63 | into the BitBake task execution environment. And as such, all commands | ||
64 | must be called just as BitBake would call them. That means you need to | ||
65 | provide the appropriate options for cross-compilation and so forth as | ||
66 | applicable. | ||
67 | |||
68 | When you are finished using ``devshell``, exit the shell or close the | ||
69 | terminal 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 | |||