1 xds-gdb: wrapper on gdb for XDS
2 =================================
4 `xds-gdb` is a wrapper on gdb debugger for X(cross) Development System.
6 This tool allows you to debug an application built with an xds-server
7 (see [xds-server on github](https://github.com/iotbzh/xds-server)) without the
8 need to install gdb or any cross tool.
10 Two debugging models are supported:
11 1. XDS remote debugging requiring an XDS server and allowing cross debug your
15 By default XDS remote debug is used and you need to define `XDS_NATIVE_GDB`
16 variable to use native gdb debug mode instead.
18 > **SEE ALSO**: [xds-server](https://github.com/iotbzh/xds-server), a web server
19 used to remotely cross build applications.
21 > **SEE ALSO**: [xds-exec](https://github.com/iotbzh/xds-exec),
22 wrappers on `exec` command that allows to cross build your application through `xds-server`.
27 Download latest `xds-gdb` release on [https://github.com/iotbzh/xds-gdb/releases](https://github.com/iotbzh/xds-gdb/releases).
29 Extract the tarball anywhere you want, for example:
32 unzip -j $DOWNLOAD_DIR/xds-gdb_linux-amd64-v1.0.0.zip xds-gdb/xds-gdb ~/opt/bin
36 `xds-gdb` configuration is defined by variables (see listed below).
37 These variables may be set using :
38 - environment variables (inherited),
39 - or a config file set with `XDS_CONFIG` environment variable, for example:
40 `XDS_CONFIG=/tmp/my_xds_gdb_config.env xds-gdb`
41 - or by setting variables within a gdb ini file (see details below),
42 - or a "user" config file located in following directory (first found is taken):
43 1. $(CURRENT_DIRECTORY)/.xds-gdb.env
44 2. $(CURRENT_DIRECTORY)/../xds-gdb.env
45 3. $(CURRENT_DIRECTORY)/target/xds-gdb.env
46 4. $(HOME)/.config/xds/xds-gdb.env
48 ### Configuration Variables:
51 Config file defining `XDS_xxx` configuration variables. Variables of this file
52 will overwrite inherited environment variables. Variables definition may be
53 prefixed or not by "export" keyword. Here is an example of
55 cat $HOME/myProject/xds-gdb.env
57 export XDS_SERVER_URL=http://xds-docker:8000
58 export XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject
59 export XDS_SDK_ID=poky-agl_aarch64_3.99.1+snapshot
63 Set logging level (supported levels: panic, fatal, error, warn, info, debug)
66 Set logging file, default `/tmp/xds-gdb.log`.
69 Use native gdb mode instead of remote XDS server mode.
71 `XDS_PROJECT_ID` : *(mandatory with XDS server mode)*
72 Project ID you want to build
75 Relative path into project
77 `XDS_SDK_ID` : *(mandatory with XDS server mode)*
78 Cross Sdk ID to use to build project
80 `XDS_SERVER_URL` : *(mandatory with XDS server mode)*
84 ### Configuration variables set within gdb init command file
86 Above `XDS_xxx` variables may also be defined within gdb init command file
87 (see --command or -x option of genuine Gdb).
88 You must respect the following syntax: commented line including `:XDS-ENV:` tag
90 Example of gdb init file where we define project and sdk ID:
92 # :XDS-ENV: XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject
93 # :XDS-ENV: XDS_SDK_ID=poky-agl_aarch64_3.99.1+snapshot
96 ## Using xds-gdb from command line
98 ### XDS remote debugging mode
100 First the project you want to debug must be declared on an xds-server and this
101 project may also has been built using this xds-server (see [xds-server](https://github.com/iotbzh/xds-server) for more details).
103 So to debug it you need to know the xds-server url (eg. http://xds-docker:8000),
104 you also need the project and sdk unique id. You can find these IDs in project
105 page of XDS dashboard or you can get them from command line using the `--list`
106 option. This option lists all existing projects ID:
108 XDS_SERVER_URL=http://xds-docker:8000 xds-gdb --list
111 Now to refer your project, just set `XDS_PROJECT_ID` and `XDS_SDK_ID` variables.
113 You are now ready to use `xds-gdb` to for example cross debug your project.
114 Here is an example to build and debug a project based on CMakefile and
115 [AGL app-templates](https://git.automotivelinux.org/apps/app-templates/):
118 # Go into your project directory (for example helloworld-service)
119 git clone https://github.com/iotbzh/helloworld-service.git
120 cd helloworld-service
122 # Declare your project on xds-server
123 # <for now, you can only do this step using xds HTML dashboard (see xds-server doc)>
126 cat <<EOF >./xds-config.env
127 XDS_SERVER_URL=http://xds-docker:8000
128 XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject
129 XDS_SDK_ID=poky-agl_aarch64_3.99.1+snapshot
132 # Tell to xds-exec and xds-gdb which is your config file
133 export XDS_CONFIG=../xds-config.env
135 # Create a new build directory
136 mkdir build && cd build
138 # Start remote cross build
141 xds-exec -- make remote-target-populate
144 xds-gdb -x target/gdb-on-root@myTarget.ini
147 > **Notes** : [Helloworld-service project](https://github.com/iotbzh/helloworld-service)
148 is an AGL project based on app-templates that can be build and debug using XDS.
152 To enable native debugging mode, you need to define `XDS_NATIVE_GDB` variable.
155 ## Using xds-gdb within an IDE
160 Open menu Tools -> Options
161 Then open C/C++ tab, in "Build Tools" sub-tab, click on "Add" button:
162 ![Add new tool panel](/docs/images/nb_newtool.jpeg)
164 Then, you should set *Debugger Command* to point to xds-gdb
166 ![Add new tool panel](/docs/images/nb_xds_options.jpeg)
172 ## How to build xds-gdb from scratch
175 You must install and setup [Go](https://golang.org/doc/install) version 1.7 or
176 higher to compile this tool.
179 Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Makefile:
181 export GOPATH=$(realpath ~/workspace_go)
182 mkdir -p $GOPATH/src/github.com/iotbzh
183 cd $GOPATH/src/github.com/iotbzh
184 git clone https://github.com/iotbzh/xds-gdb.git
191 Visual Studio Code launcher settings can be found into `.vscode/launch.json`.