xds-gdb: wrapper on gdb for XDS

xds-gdb is a wrapper on gdb debugger for X(cross) Development System.

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

  2. XDS remote debugging requiring an XDS agent/server setup. That allows you to easily cross debug your application.

By default XDS debug model is used and you need to define XDS_NATIVE_GDB variable to use native gdb debug mode instead.

SEE ALSO: xds-agent, a local agent used to interface xds-server. SEE ALSO: xds-server, a REST API server used to remotely cross build applications. SEE ALSO: xds-cli, XDS command line tool.


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
    2. $(CURRENT_DIRECTORY)/../xds-gdb.env
    3. $(CURRENT_DIRECTORY)/target/xds-gdb.env
    4. $(HOME)/.config/xds/xds-gdb.env

Configuration Variables


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 config file:

cat $HOME/myProject/xds-gdb.env

export XDS_AGENT_URL=http://localhost:8800
export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b
export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03


Set logging level

Supported levels:

  • panic
  • fatal
  • error
  • warn
  • info
  • debug


Set logging file, default /tmp/xds-gdb.log.


Use native gdb mode instead of XDS mode.

XDS_PROJECT_ID (mandatory in XDS mode)

Project ID you want to build


Relative path into project

XDS_SDK_ID (mandatory in XDS mode)

Cross Sdk ID to use to build project


Local XDS agent url (default http://localhost:8800)

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:

     # :XDS-ENV: XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b
     # :XDS-ENV: XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03

How to build xds-gdb from scratch


Install Go and some other tools. Refer to Prerequisites chapter for more details.


Clone this repo into your $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds and use delivered Makefile:

 export GOPATH=$(realpath ~/workspace_go)
 mkdir -p $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds
 cd $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds
 git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-gdb
 # or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-gdb
 cd xds-gdb


Visual Studio Code launcher settings can be found into .vscode/launch.json.