README.md

   1 # xds-gdb: wrapper on gdb for XDS
   2
   3 `xds-gdb` is a wrapper on gdb debugger for X(cross) Development System.
   4
   5 This tool allows you to debug an application built with an xds-server without the
   6 need to install gdb or any cross tool.
   7
   8 Two debugging models are supported:
   9
  10 1. XDS remote debugging requiring an XDS server and allowing cross debug your
  11   application.
  12 1. native debugging
  13
  14  By default XDS remote debug is used and you need to define `XDS_NATIVE_GDB`
  15 variable to use native gdb debug mode instead.
  16
  17 > **SEE ALSO**: [xds-server](https://github.com/iotbzh/xds-server), a web server
  18 used to remotely cross build applications.
  19 > **SEE ALSO**: [xds-exec](https://github.com/iotbzh/xds-exec),
  20 wrappers on `exec` command that allows to cross build your application through `xds-server`.
  21
  22 ## Getting Started
  23
  24 ## Installing xds-gdb
  25
  26 Download latest `xds-gdb` release on [https://github.com/iotbzh/xds-gdb/releases](https://github.com/iotbzh/xds-gdb/releases).
  27
  28 Extract the tarball anywhere you want, for example:
  29
  30 ```bash
  31 mkdir -p ~/opt/bin
  32 unzip -j $DOWNLOAD_DIR/xds-gdb_linux-amd64-v1.0.0.zip xds-gdb/xds-gdb ~/opt/bin
  33 ```
  34
  35 ## Configuration
  36
  37  `xds-gdb` configuration is defined by variables (see listed below).
  38  These variables may be set using :
  39
  40 - environment variables (inherited),
  41 - or a config file set with `XDS_CONFIG` environment variable, for example:
  42   `XDS_CONFIG=/tmp/my_xds_gdb_config.env xds-gdb`
  43 - or by setting variables within a gdb ini file (see details below),
  44 - or a "user" config file located in following directory (first found is taken):
  45   1. $(CURRENT_DIRECTORY)/.xds-gdb.env
  46   1. $(CURRENT_DIRECTORY)/../xds-gdb.env
  47   1. $(CURRENT_DIRECTORY)/target/xds-gdb.env
  48   1. $(HOME)/.config/xds/xds-gdb.env
  49
  50 ### Configuration Variables
  51
  52  `XDS_CONFIG` :
  53  Config file defining `XDS_xxx` configuration variables. Variables of this file
  54  will overwrite inherited environment variables. Variables definition may be
  55  prefixed or not by "export" keyword.
  56  Here is an example of
  57
  58 ```bash
  59 cat $HOME/myProject/xds-gdb.env
  60
  61 export XDS_SERVER_URL=http://xds-docker:8000
  62 export XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject
  63 export XDS_SDK_ID=poky-agl_aarch64_3.99.1+snapshot
  64 ```
  65
  66 `XDS_LOGLEVEL` :
  67 Set logging level (supported levels: panic, fatal, error, warn, info, debug)
  68
  69 `XDS_LOGFILE` :
  70 Set logging file, default `/tmp/xds-gdb.log`.
  71
  72 `XDS_NATIVE_GDB` :
  73 Use native gdb mode instead of remote XDS server mode.
  74
  75 `XDS_PROJECT_ID` : *(mandatory with XDS server mode)*
  76 Project ID you want to build
  77
  78 `XDS_RPATH` :
  79 Relative path into project
  80
  81 `XDS_SDK_ID` : *(mandatory with XDS server mode)*
  82 Cross Sdk ID to use to build project
  83
  84 `XDS_SERVER_URL` :  *(mandatory with XDS server mode)*
  85 Remote XDS server url
  86
  87 ### Configuration variables set within gdb init command file
  88
  89 Above `XDS_xxx` variables may also be defined within gdb init command file
  90 (see --command or -x option of genuine Gdb).
  91 You must respect the following syntax: commented line including `:XDS-ENV:` tag
  92
  93 Example of gdb init file where we define project and sdk ID:
  94
  95 ```bash
  96      # :XDS-ENV: XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject
  97      # :XDS-ENV: XDS_SDK_ID=poky-agl_aarch64_3.99.1+snapshot
  98 ```
  99
 100 ## Using xds-gdb from command line
 101
 102 ### XDS remote debugging mode
 103
 104 First the project you want to debug must be declared on an xds-server and this
 105 project may also has been built using this xds-server (see [xds-server](https://github.com/iotbzh/xds-server) for more details).
 106
 107 So to debug it you need to know the xds-server url (eg. <http://xds-docker:8000>),
 108 you also need the project and sdk unique id. You can find these IDs in project
 109 page of XDS dashboard or you can get them from command line using the `--list`
 110 option.
 111 This option lists all existing projects ID:
 112
 113 ```bash
 114 XDS_SERVER_URL=http://xds-docker:8000 xds-gdb --list
 115 ```
 116
 117 Now to refer your project, just set `XDS_PROJECT_ID` and `XDS_SDK_ID` variables.
 118
 119 You are now ready to use `xds-gdb` to for example cross debug your project.
 120 Here is an example to build and debug a project based on CMakefile and
 121 [AGL app-templates](https://git.automotivelinux.org/apps/app-templates/):
 122
 123 ```bash
 124 # Go into your project directory (for example helloworld-service)
 125 git clone https://github.com/iotbzh/helloworld-service.git
 126 cd helloworld-service
 127
 128 # Declare your project on xds-server
 129 # <for now, you can only do this step using xds HTML dashboard (see xds-server doc)>
 130
 131 # Define XDS config
 132 cat <<EOF >./xds-config.env
 133 XDS_SERVER_URL=http://xds-docker:8000
 134 XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject
 135 XDS_SDK_ID=poky-agl_aarch64_3.99.1+snapshot
 136 EOF
 137
 138 # Tell to xds-exec and xds-gdb which is your config file
 139 export XDS_CONFIG=../xds-config.env
 140
 141 # Create a new build directory
 142 mkdir build && cd build
 143
 144 # Start remote cross build
 145 xds-exec -- cmake ..
 146 xds-exec -- make
 147 xds-exec -- make remote-target-populate
 148
 149 # Start debugging
 150 xds-gdb -x target/gdb-on-root@myTarget.ini
 151 ```
 152
 153 > **Notes** : [Helloworld-service project](https://github.com/iotbzh/helloworld-service)
 154 is an AGL project based on app-templates that can be build and debug using XDS.
 155
 156 ### Native debugging
 157
 158 To enable native debugging mode, you need to define `XDS_NATIVE_GDB` variable.
 159
 160 ## Using xds-gdb within an IDE
 161
 162 ### Netbeans
 163
 164 __Netbeans 8.x :__
 165 Open menu Tools -> Options
 166 Then open C/C++ tab, in "Build Tools" sub-tab, click on "Add" button:
 167 ![Add new tool panel](./docs/images/nb_newtool.jpg)
 168
 169 Then, you should set *Debugger Command* to point to xds-gdb
 170
 171 ![Add new tool panel](./docs/images/nb_xds_options.jpg)
 172
 173 ### Others IDE
 174
 175 *Coming soon...*
 176
 177 ## How to build xds-gdb from scratch
 178
 179 ### Prerequisites
 180
 181  You must install and setup [Go](https://golang.org/doc/install) version 1.7 or
 182  higher to compile this tool.
 183
 184 ### Building
 185
 186 Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Makefile:
 187
 188 ```bash
 189  export GOPATH=$(realpath ~/workspace_go)
 190  mkdir -p $GOPATH/src/github.com/iotbzh
 191  cd $GOPATH/src/github.com/iotbzh
 192  git clone https://github.com/iotbzh/xds-gdb.git
 193  cd xds-gdb
 194  make
 195 ```
 196
 197 ## Debug
 198
 199 Visual Studio Code launcher settings can be found into `.vscode/launch.json`.