From 8f9934b438a145d9d84beec0153c431996697507 Mon Sep 17 00:00:00 2001 From: Sebastien Douheret Date: Wed, 20 Sep 2017 10:24:51 +0200 Subject: Initial commit Signed-off-by: Sebastien Douheret --- docs/part-1/5_debug-first-app.md | 202 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 docs/part-1/5_debug-first-app.md (limited to 'docs/part-1/5_debug-first-app.md') diff --git a/docs/part-1/5_debug-first-app.md b/docs/part-1/5_debug-first-app.md new file mode 100644 index 0000000..f9f0a6e --- /dev/null +++ b/docs/part-1/5_debug-first-app.md @@ -0,0 +1,202 @@ +# Debug your first AGL application + +Debug is based on gdb and you need to use `xds-gdb` as a wrapper on gdb to cross-debug your application. +This tool allows you to debug an application built with an xds-server without the need to install gdb or any cross tool. +Two debugging models are supported: + +1. native debugging + +1. XDS remote debugging requiring an XDS server and allowing cross debug your + application. + + By default XDS remote debug is used and you need to define `XDS_NATIVE_GDB` +variable to use native gdb debug mode instead. + +> **SEE ALSO**: [xds-server](https://github.com/iotbzh/xds-server), a web server +used to remotely cross build applications. +> **SEE ALSO**: [xds-exec](https://github.com/iotbzh/xds-exec), +wrappers on `exec` command that allows to cross build your application through `xds-server`. + +## Configuration + + `xds-gdb` configuration is defined by variables (see listed below). + These variables may be set using : + +- environment variables (inherited), +- or a config file set with `XDS_CONFIG` environment variable, for example: + `XDS_CONFIG=/tmp/my_xds_gdb_config.env xds-gdb` +- or by setting variables within a gdb ini file (see details below), +- or a "user" config file located in following directory (first found is taken): + 1. $(CURRENT_DIRECTORY)/.xds-gdb.env + 1. $(CURRENT_DIRECTORY)/../xds-gdb.env + 1. $(CURRENT_DIRECTORY)/target/xds-gdb.env + 1. $(HOME)/.config/xds/xds-gdb.env + +### Configuration Variables + + `XDS_CONFIG` + Config file defining `XDS_xxx` configuration variables. Variables of this file + will overwrite inherited environment variables. Variables definition may be + prefixed or not by "export" keyword. + Here is an example of + +```bash +# for example: +# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application +cat > $MY_PROJECT_DIR/xds-gen3.conf << EOF +export XDS_SERVER_URL=http://docker:8000 +export XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject +export XDS_SDK_ID=poky-agl_aarch64_4.0.1 +EOF +``` + +`XDS_LOGLEVEL` + +Set logging level (supported levels: panic, fatal, error, warn, info, debug) + +`XDS_LOGFILE` + +Set logging file, default `/tmp/xds-gdb.log`. + +`XDS_NATIVE_GDB` + +Use native gdb mode instead of remote XDS server mode. + +`XDS_PROJECT_ID` *(mandatory with XDS server mode)* + +Project ID you want to build + +`XDS_RPATH` + +Relative path into project + +`XDS_SDK_ID` *(mandatory with XDS server mode)* + +Cross Sdk ID to use to build project + +`XDS_SERVER_URL` *(mandatory with XDS server mode)* + +Remote XDS server url + +### Configuration variables set within gdb init command file + +Above `XDS_xxx` variables may also be defined within gdb init command file +(see --command or -x option of genuine Gdb). +You must respect the following syntax: commented line including `:XDS-ENV:` tag + +Example of gdb init file where we define project and sdk ID: + +```bash + # :XDS-ENV: XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject + # :XDS-ENV: XDS_SDK_ID=poky-agl_aarch64_4.0.1 +``` + +## Using xds-gdb from command line + +### XDS remote debugging mode + +First the project you want to debug must be declared on an xds-server and this +project may also has been built using this xds-server (see [xds-server](https://github.com/iotbzh/xds-server) for more details). + +So to debug it you need to know the xds-server url (eg. ), +you also need the project and sdk unique id. You can find these IDs in project +page of XDS dashboard or you can get them from command line using the `--list` +option. +This option lists all existing projects ID: + +```bash +XDS_SERVER_URL=http://docker:8000 xds-gdb --list +``` + +Now to refer your project, just set `XDS_PROJECT_ID` and `XDS_SDK_ID` variables. + +You are now ready to use `xds-gdb` to for example cross debug your project. +Here is an example to build and debug a project based on CMakefile and +[AGL app-templates](https://git.automotivelinux.org/apps/app-templates/): + +```bash +# Go into your project directory (for example helloworld-native-application) +cd ~/xds-workspace +git clone https://github.com/iotbzh/helloworld-native-application.git +cd helloworld-service + +# Declare your project on xds-server +# + +# Define XDS config +cat <./xds-config.env +XDS_SERVER_URL=http://docker:8000 +XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject +XDS_SDK_ID=poky-agl_aarch64_4.0.1 +EOF + +# Tell to xds-exec and xds-gdb which is your config file +export XDS_CONFIG=../xds-gen3.conf + +# Create a new build directory +mkdir build && cd build + +# Start remote cross build +xds-exec -- cmake -DRSYNC_TARGET=root@myTarget .. +xds-exec -- make +xds-exec -- make remote-target-populate + +# Start debugging +xds-gdb -x target/gdb-on-root@myTarget.ini +``` + + +> **Note** : [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) project is an AGL +project based on [app-templates](https://git.automotivelinux.org/apps/app-templates/) +(included as a git submodule). This CMake templating, used to develop application +with the AGL Application Framework, will automatically generate makefile rules +(eg. `remote-target-populate`) or scripts (eg. `build/target/xxx` scripts). + +For more info about app-template, please refer to [this documentation](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/sdk-devkit/docs/part-2/2_4-Use-app-templates.html). + + +### Native debugging + +To enable native debugging mode, you need to define `XDS_NATIVE_GDB` variable. + +## Using xds-gdb within an IDE + +### Netbeans + +__Netbeans 8.x :__ + +- Open menu **Tools** -> **Options** + - Open **C/C++** tab, in **Build Tools** sub-tab, click on **Add** button: + + ![Add new tool panel](./pictures/nb_newtool.png) + + - Then, you should set **Make Command** and **Debugger Command** to point to xds tools: + + ![Add new tool panel](./pictures/nb_xds_options.png) + + - Finally click on **OK** button. + +- Edit project properties (using menu **File** -> **Project Properties**) to update Debug settings: + + - Be sure that "Gen3 board" configuration is selected + + - Select **Run** category, and set: + - Run Command: `target/start-on-root@renesas-gen3.sh` + (_script name may depend of RSYNC_TARGET variable you set in pre-build command_) + - Run Directory: `build_gen3` + + - Select **Debug** category, and set: + - Debug command: `/bin/true` + - Working Directory: _empty field_ + - Gdb Init File: `target/gdb-on-root@renesas-gen3.ini` + (_script name may depend of RSYNC_TARGET variable you set in pre-build command_) + + ![Select Model panel](./pictures/nb_project_debug-1.png) + + - Click on **Apply** and then **OK** button to save settings + +You can now start debugging your application with menu **Debug** -> **Debug Project** (or **CTRL+F5** shortcut) + +### Others IDE + +*Coming soon...* -- cgit 1.2.3-korg