diff options
Diffstat (limited to 'documentation/dev-manual/development-shell.rst')
| -rw-r--r-- | documentation/dev-manual/development-shell.rst | 82 |
1 files changed, 0 insertions, 82 deletions
diff --git a/documentation/dev-manual/development-shell.rst b/documentation/dev-manual/development-shell.rst deleted file mode 100644 index be26bcffc7..0000000000 --- a/documentation/dev-manual/development-shell.rst +++ /dev/null | |||
| @@ -1,82 +0,0 @@ | |||
| 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 | |||
