diff options
author | Adrian Freihofer <adrian.freihofer@gmail.com> | 2024-02-21 20:59:21 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2024-02-24 16:13:29 +0000 |
commit | 1a2cf4c538c1c83c50e3ea5bd0be24803d71f253 (patch) | |
tree | a1f706f8e162d628ffc903c5e61379fc30836bc2 /documentation | |
parent | 736ba6823d57ac36a00d7754563617af4284f6e3 (diff) | |
download | poky-1a2cf4c538c1c83c50e3ea5bd0be24803d71f253.tar.gz |
sdk-manual: extensible.rst: cover devtool ide-sdk
Cover the new devtool ide plugin in the extensible sdk section.
Many thanks to Enguerrand de Ribaucourt for his re-view and
contributions.
(From yocto-docs rev: d318cc41e0600ca8e18bc6789cac414ae0226a07)
Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/sdk-manual/extensible.rst | 283 |
1 files changed, 282 insertions, 1 deletions
diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst index 355c6cb0e4..05dd527469 100644 --- a/documentation/sdk-manual/extensible.rst +++ b/documentation/sdk-manual/extensible.rst | |||
@@ -63,6 +63,8 @@ their own pros and cons: | |||
63 | need to provide a well-functioning binary artefact cache over the network | 63 | need to provide a well-functioning binary artefact cache over the network |
64 | for developers with underpowered laptops. | 64 | for developers with underpowered laptops. |
65 | 65 | ||
66 | .. _setting_up_ext_sdk_in_build: | ||
67 | |||
66 | Setting up the Extensible SDK environment directly in a Yocto build | 68 | Setting up the Extensible SDK environment directly in a Yocto build |
67 | ------------------------------------------------------------------- | 69 | ------------------------------------------------------------------- |
68 | 70 | ||
@@ -168,6 +170,8 @@ architecture. The example assumes the SDK installer is located in | |||
168 | that case, set up the proper permissions in the directory and run the | 170 | that case, set up the proper permissions in the directory and run the |
169 | installer again. | 171 | installer again. |
170 | 172 | ||
173 | .. _running_the_ext_sdk_env: | ||
174 | |||
171 | Running the Extensible SDK Environment Setup Script | 175 | Running the Extensible SDK Environment Setup Script |
172 | =================================================== | 176 | =================================================== |
173 | 177 | ||
@@ -205,6 +209,8 @@ use the SDK (e.g. ``PATH``, :term:`CC`, :term:`LD`, and so forth). If you want | |||
205 | to see all the environment variables the script exports, examine the | 209 | to see all the environment variables the script exports, examine the |
206 | installation file itself. | 210 | installation file itself. |
207 | 211 | ||
212 | .. _using_devtool: | ||
213 | |||
208 | Using ``devtool`` in Your SDK Workflow | 214 | Using ``devtool`` in Your SDK Workflow |
209 | ====================================== | 215 | ====================================== |
210 | 216 | ||
@@ -230,13 +236,15 @@ all the commands. | |||
230 | See the ":doc:`/ref-manual/devtool-reference`" | 236 | See the ":doc:`/ref-manual/devtool-reference`" |
231 | section in the Yocto Project Reference Manual. | 237 | section in the Yocto Project Reference Manual. |
232 | 238 | ||
233 | Three ``devtool`` subcommands provide entry-points into development: | 239 | ``devtool`` subcommands provide entry-points into development: |
234 | 240 | ||
235 | - *devtool add*: Assists in adding new software to be built. | 241 | - *devtool add*: Assists in adding new software to be built. |
236 | 242 | ||
237 | - *devtool modify*: Sets up an environment to enable you to modify | 243 | - *devtool modify*: Sets up an environment to enable you to modify |
238 | the source of an existing component. | 244 | the source of an existing component. |
239 | 245 | ||
246 | - *devtool ide-sdk*: Generates a configuration for an IDE. | ||
247 | |||
240 | - *devtool upgrade*: Updates an existing recipe so that you can | 248 | - *devtool upgrade*: Updates an existing recipe so that you can |
241 | build it for an updated set of source files. | 249 | build it for an updated set of source files. |
242 | 250 | ||
@@ -614,6 +622,279 @@ command: | |||
614 | decide you do not want to proceed with your work. If you do use this | 622 | decide you do not want to proceed with your work. If you do use this |
615 | command, realize that the source tree is preserved. | 623 | command, realize that the source tree is preserved. |
616 | 624 | ||
625 | ``devtool ide-sdk`` configures IDEs for the extensible SDK | ||
626 | ---------------------------------------------------------- | ||
627 | |||
628 | ``devtool ide-sdk`` automatically configures IDEs to use the extensible SDK. | ||
629 | To make sure that all parts of the extensible SDK required by the generated | ||
630 | IDE configuration are available, ``devtool ide-sdk`` uses BitBake in the | ||
631 | background to bootstrap the extensible SDK. | ||
632 | |||
633 | The extensible SDK supports two different development modes. | ||
634 | ``devtool ide-sdk`` supports both of them: | ||
635 | |||
636 | #. *Modified mode*: | ||
637 | |||
638 | By default ``devtool ide-sdk`` generates IDE configurations for recipes in | ||
639 | workspaces created by ``devtool modify`` or ``devtool add`` as described in | ||
640 | :ref:`using_devtool`. This mode creates IDE configurations with support for | ||
641 | advanced features, such as deploying the binaries to the remote target | ||
642 | device and performing remote debugging sessions. The generated IDE | ||
643 | configurations use the per recipe sysroots as Bitbake does internally. | ||
644 | |||
645 | In order to use the tool, a few settings are needed. As a starting example, | ||
646 | the following lines of code can be added to the ``local.conf`` file:: | ||
647 | |||
648 | # Build the companion debug file system | ||
649 | IMAGE_GEN_DEBUGFS = "1" | ||
650 | # Optimize build time: with devtool ide-sdk the dbg tar is not needed | ||
651 | IMAGE_FSTYPES_DEBUGFS = "" | ||
652 | # Without copying the binaries into roofs-dbg, GDB does not find all source files. | ||
653 | IMAGE_CLASSES += "image-combined-dbg" | ||
654 | |||
655 | # SSH is mandatory, no password simplifies the usage | ||
656 | EXTRA_IMAGE_FEATURES += "\ | ||
657 | ssh-server-openssh \ | ||
658 | debug-tweaks \ | ||
659 | " | ||
660 | |||
661 | # Remote debugging needs gdbserver on the target device | ||
662 | IMAGE_INSTALL:append = " gdbserver" | ||
663 | |||
664 | # Add the recipes which should be modified to the image | ||
665 | # Otherwise some dependencies might be missing. | ||
666 | IMAGE_INSTALL:append = " my-recipe" | ||
667 | |||
668 | Assuming the BitBake environment is set up correctly and a workspace has | ||
669 | been created for the recipe using ``devtool modify my-recipe``, the | ||
670 | following command can create the SDK and the configuration for VSCode in | ||
671 | the recipe workspace:: | ||
672 | |||
673 | $ devtool ide-sdk my-recipe core-image-minimal --target root@192.168.7.2 | ||
674 | |||
675 | The command requires an image recipe (``core-image-minimal`` for this example) | ||
676 | that is used to create the SDK. This firmware image should also be installed | ||
677 | on the target device. It is possible to pass multiple package recipes. | ||
678 | ``devtool ide-sdk`` tries to create an IDE configuration for all package | ||
679 | recipes. | ||
680 | |||
681 | What this command does exactly depends on the recipe, more precisely on the | ||
682 | build tool used by the recipe. The basic idea is to configure the IDE so | ||
683 | that it calls the build tool exactly as ``bitbake`` does. | ||
684 | |||
685 | For example, a CMake preset is created for a recipe that inherits | ||
686 | :ref:`ref-classes-cmake`. In the case of VSCode, CMake presets are supported | ||
687 | by the CMake Tools plugin. This is an example of how the build | ||
688 | configuration used by ``bitbake`` is exported to an IDE configuration that | ||
689 | gives exactly the same build results. | ||
690 | |||
691 | Support for remote debugging with seamless integration into the IDE is | ||
692 | important for a cross-SDK. ``devtool ide-sdk`` automatically generates the | ||
693 | necessary helper scripts for deploying the compiled artifacts to the target | ||
694 | device as well as the necessary configuration for the debugger and the IDE. | ||
695 | |||
696 | .. note:: | ||
697 | |||
698 | To ensure that the debug symbols on the build machine match the binaries | ||
699 | running on the target device, it is essential that the image built by | ||
700 | ``devtool ide-sdk`` is running on the target device. | ||
701 | |||
702 | ``devtool ide-sdk`` aims to support multiple programming languages and | ||
703 | multiple IDEs natively. "Natively" means that the IDE is configured to call | ||
704 | the build tool (e.g. CMake or Meson) directly. This has several advantages. | ||
705 | First of all, it is much faster than ``devtool build``, but it also allows | ||
706 | to use the very good integration of tools like CMake or GDB in VSCode and | ||
707 | other IDEs. However, supporting many programming languages and multiple | ||
708 | IDEs is quite an elaborate and constantly evolving thing. Support for IDEs | ||
709 | is therefore implemented as plugins. Plugins can also be provided by | ||
710 | optional layers. | ||
711 | |||
712 | The default IDE is VSCode. Some hints about using VSCode: | ||
713 | |||
714 | - To work on the source code of a recipe an instance of VSCode is started in | ||
715 | the recipe's workspace. Example:: | ||
716 | |||
717 | code build/workspace/sources/my-recipe | ||
718 | |||
719 | - To work with CMake press ``Ctrl + Shift + p``, type ``cmake``. This will | ||
720 | show some possible commands like selecting a CMake preset, compiling or | ||
721 | running CTest. | ||
722 | |||
723 | For recipes inheriting :ref:`ref-classes-cmake-qemu` rather than | ||
724 | :ref:`ref-classes-cmake`, executing cross-compiled unit tests on the host | ||
725 | can be supported transparently with QEMU user-mode. | ||
726 | |||
727 | - To work with Meson press ``Ctrl + Shift + p``, type ``meson``. This will | ||
728 | show some possible commands like compiling or executing the unit tests. | ||
729 | |||
730 | A note on running cross-compiled unit tests on the host: Meson enables | ||
731 | support for QEMU user-mode by default. It is expected that the execution | ||
732 | of the unit tests from the IDE will work easily without any additional | ||
733 | steps, provided that the code is suitable for execution on the host | ||
734 | machine. | ||
735 | |||
736 | - For the deployment to the target device, just press ``Ctrl + Shift + p``, | ||
737 | type ``task``. Select ``install && deploy-target``. | ||
738 | |||
739 | - For remote debugging, switch to the debugging view by pressing the "play" | ||
740 | button with the ``bug icon`` on the left side. This will provide a green | ||
741 | play button with a drop-down list where a debug configuration can be | ||
742 | selected. After selecting one of the generated configurations, press the | ||
743 | "play" button. | ||
744 | |||
745 | Starting a remote debugging session automatically initiates the deployment | ||
746 | to the target device. If this is not desired, the | ||
747 | ``"dependsOn": ["install && deploy-target...]`` parameter of the tasks | ||
748 | with ``"label": "gdbserver start...`` can be removed from the | ||
749 | ``tasks.json`` file. | ||
750 | |||
751 | VSCode supports GDB with many different setups and configurations for many | ||
752 | different use cases. However, most of these setups have some limitations | ||
753 | when it comes to cross-development, support only a few target | ||
754 | architectures or require a high performance target device. Therefore | ||
755 | ``devtool ide-sdk`` supports the classic, generic setup with GDB on the | ||
756 | development host and gdbserver on the target device. | ||
757 | |||
758 | Roughly summarized, this means: | ||
759 | |||
760 | - The binaries are copied via SSH to the remote target device by a script | ||
761 | referred by ``tasks.json``. | ||
762 | |||
763 | - gdbserver is started on the remote target device via SSH by a script | ||
764 | referred by ``tasks.json``. | ||
765 | |||
766 | Changing the parameters that are passed to the debugging executable | ||
767 | requires modifying the generated script. The script is located at | ||
768 | ``oe-scripts/gdbserver_*``. Defining the parameters in the ``args`` | ||
769 | field in the ``launch.json`` file does not work. | ||
770 | |||
771 | - VSCode connects to gdbserver as documented in | ||
772 | `Remote debugging or debugging with a local debugger server | ||
773 | <https://code.visualstudio.com/docs/cpp/launch-json-reference#_remote-debugging-or-debugging-with-a-local-debugger-server>`__. | ||
774 | |||
775 | Additionally ``--ide=none`` is supported. With the ``none`` IDE parameter, | ||
776 | some generic configuration files like ``gdbinit`` files and some helper | ||
777 | scripts starting gdbserver remotely on the target device as well as the GDB | ||
778 | client on the host are generated. | ||
779 | |||
780 | Here is a usage example for the ``cmake-example`` recipe from the | ||
781 | ``meta-selftest`` layer which inherits :ref:`ref-classes-cmake-qemu`: | ||
782 | |||
783 | .. code-block:: sh | ||
784 | |||
785 | # Create the SDK | ||
786 | devtool modify cmake-example | ||
787 | devtool ide-sdk cmake-example core-image-minimal -c --debug-build-config --ide=none | ||
788 | |||
789 | # Install the firmware on a target device or start QEMU | ||
790 | runqemu | ||
791 | |||
792 | # From exploring the workspace of cmake-example | ||
793 | cd build/workspace/sources/cmake-example | ||
794 | |||
795 | # Find cmake-native and save the path into a variable | ||
796 | # Note: using just cmake instead of $CMAKE_NATIVE would work in many cases | ||
797 | CMAKE_NATIVE="$(jq -r '.configurePresets[0] | "\(.cmakeExecutable)"' CMakeUserPresets.json)" | ||
798 | |||
799 | # List available CMake presets | ||
800 | "$CMAKE_NATIVE" --list-presets | ||
801 | Available configure presets: | ||
802 | |||
803 | "cmake-example-cortexa57" - cmake-example: cortexa57 | ||
804 | |||
805 | # Re-compile the already compiled sources | ||
806 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 | ||
807 | ninja: no work to do. | ||
808 | # Do a clean re-build | ||
809 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target clean | ||
810 | [1/1] Cleaning all built files... | ||
811 | Cleaning... 8 files. | ||
812 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target all | ||
813 | [7/7] Linking CXX executable cmake-example | ||
814 | |||
815 | # Run the cross-compiled unit tests with QEMU user-mode | ||
816 | "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target test | ||
817 | [0/1] Running tests... | ||
818 | Test project .../build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 | ||
819 | Start 1: test-cmake-example | ||
820 | 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec | ||
821 | |||
822 | 100% tests passed, 0 tests failed out of 1 | ||
823 | |||
824 | Total Test time (real) = 0.03 sec | ||
825 | |||
826 | # Using CTest directly is possible as well | ||
827 | CTEST_NATIVE="$(dirname "$CMAKE_NATIVE")/ctest" | ||
828 | |||
829 | # List available CMake presets | ||
830 | "$CTEST_NATIVE" --list-presets | ||
831 | Available test presets: | ||
832 | |||
833 | "cmake-example-cortexa57" - cmake-example: cortexa57 | ||
834 | |||
835 | # Run the cross-compiled unit tests with QEMU user-mode | ||
836 | "$CTEST_NATIVE" --preset "cmake-example-cortexa57" | ||
837 | Test project ...build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 | ||
838 | Start 1: test-cmake-example | ||
839 | 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec | ||
840 | |||
841 | 100% tests passed, 0 tests failed out of 1 | ||
842 | |||
843 | Total Test time (real) = 0.03 sec | ||
844 | |||
845 | # Deploying the new build to the target device (default is QEUM at 192.168.7.2) | ||
846 | oe-scripts/install_and_deploy_cmake-example-cortexa57 | ||
847 | |||
848 | # Start a remote debugging session with gdbserver on the target and GDB on the host | ||
849 | oe-scripts/gdbserver_1234_usr-bin-cmake-example_m | ||
850 | oe-scripts/gdb_1234_usr-bin-cmake-example | ||
851 | break main | ||
852 | run | ||
853 | step | ||
854 | stepi | ||
855 | continue | ||
856 | quit | ||
857 | |||
858 | # Stop gdbserver on the target device | ||
859 | oe-scripts/gdbserver_1234_usr-bin-cmake-example_m stop | ||
860 | |||
861 | #. *Shared sysroots mode* | ||
862 | |||
863 | For some recipes and use cases a per-recipe sysroot based SDK is not | ||
864 | suitable. Optionally ``devtool ide-sdk`` configures the IDE to use the | ||
865 | toolchain provided by the extensible SDK as described in | ||
866 | :ref:`running_the_ext_sdk_env`. ``devtool ide-sdk --mode=shared`` is | ||
867 | basically a wrapper for the setup of the extensible SDK as described in | ||
868 | :ref:`setting_up_ext_sdk_in_build`. The IDE gets a configuration to use the | ||
869 | shared sysroots. | ||
870 | |||
871 | Creating a SDK with shared sysroots that contains all the dependencies needed | ||
872 | to work with ``my-recipe`` is possible with the following example command:: | ||
873 | |||
874 | $ devtool ide-sdk --mode=shared my-recipe | ||
875 | |||
876 | For VSCode the cross-toolchain is exposed as a CMake kit. CMake kits are | ||
877 | defined in ``~/.local/share/CMakeTools/cmake-tools-kits.json``. | ||
878 | The following example shows how the cross-toolchain can be selected in | ||
879 | VSCode. First of all we need a folder containing a CMake project. | ||
880 | For this example, let's create a CMake project and start VSCode:: | ||
881 | |||
882 | mkdir kit-test | ||
883 | echo "project(foo VERSION 1.0)" > kit-test/CMakeLists.txt | ||
884 | code kit-test | ||
885 | |||
886 | If there is a CMake project in the workspace, cross-compilation is supported: | ||
887 | |||
888 | - Press ``Ctrl + Shift + P``, type ``CMake: Scan for Kits`` | ||
889 | - Press ``Ctrl + Shift + P``, type ``CMake: Select a Kit`` | ||
890 | |||
891 | Finally most of the features provided by CMake and the IDE should be available. | ||
892 | |||
893 | Other IDEs than VSCode are supported as well. However, | ||
894 | ``devtool ide-sdk --mode=shared --ide=none my-recipe`` is currently | ||
895 | just a simple wrapper for the setup of the extensible SDK, as described in | ||
896 | :ref:`setting_up_ext_sdk_in_build`. | ||
897 | |||
617 | Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software | 898 | Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software |
618 | ------------------------------------------------------------------------------------------------------- | 899 | ------------------------------------------------------------------------------------------------------- |
619 | 900 | ||