README.md

   1 xds-gdb: wrapper on gdb for XDS
   2 =================================
   3
   4 `xds-gdb` is a wrapper on gdb debugger for X(cross) Development System.
   5
   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.
   9
  10 Two debugging models are supported:
  11   1. XDS remote debugging requiring an XDS server and allowing cross debug your
  12   application.
  13   2. native debugging
  14
  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.
  17
  18 > **SEE ALSO**: [xds-server](https://github.com/iotbzh/xds-server), a web server
  19 used to remotely cross build applications.
  20
  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`.
  23
  24 ## Getting Started
  25
  26 ## Installing xds-gdb
  27 Download latest `xds-gdb` release on [https://github.com/iotbzh/xds-gdb/releases](https://github.com/iotbzh/xds-gdb/releases).
  28
  29 Extract the tarball anywhere you want, for example:
  30 ```
  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  `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
  47
  48 ### Configuration Variables:
  49
  50  `XDS_CONFIG` :
  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
  54 ```
  55 cat $HOME/myProject/xds-gdb.env
  56
  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
  60 ```
  61
  62 `XDS_LOGLEVEL` :
  63 Set logging level (supported levels: panic, fatal, error, warn, info, debug)
  64
  65 `XDS_LOGFILE` :
  66 Set logging file, default `/tmp/xds-gdb.log`.
  67
  68 `XDS_NATIVE_GDB` :
  69 Use native gdb mode instead of remote XDS server mode.
  70
  71 `XDS_PROJECT_ID` : *(mandatory with XDS server mode)*
  72 Project ID you want to build
  73
  74 `XDS_RPATH` :
  75 Relative path into project
  76
  77 `XDS_SDK_ID` : *(mandatory with XDS server mode)*
  78 Cross Sdk ID to use to build project
  79
  80 `XDS_SERVER_URL` :  *(mandatory with XDS server mode)*
  81 Remote XDS server url
  82
  83
  84 ### Configuration variables set within gdb init command file
  85
  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
  89
  90 Example of gdb init file where we define project and sdk ID:
  91 ```
  92      # :XDS-ENV: XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject
  93      # :XDS-ENV: XDS_SDK_ID=poky-agl_aarch64_3.99.1+snapshot
  94 ```
  95
  96 ## Using xds-gdb from command line
  97
  98 ### XDS remote debugging mode
  99
 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).
 102
 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:
 107 ```bash
 108 XDS_SERVER_URL=http://xds-docker:8000 xds-gdb --list
 109 ```
 110
 111 Now to refer your project, just set `XDS_PROJECT_ID` and `XDS_SDK_ID` variables.
 112
 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/):
 116
 117 ```bash
 118 # Go into your project directory (for example helloworld-service)
 119 git clone https://github.com/iotbzh/helloworld-service.git
 120 cd helloworld-service
 121
 122 # Declare your project on xds-server
 123 # <for now, you can only do this step using xds HTML dashboard (see xds-server doc)>
 124
 125 # Define XDS config
 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
 130 EOF
 131
 132 # Tell to xds-exec and xds-gdb which is your config file
 133 export XDS_CONFIG=../xds-config.env
 134
 135 # Create a new build directory
 136 mkdir build && cd build
 137
 138 # Start remote cross build
 139 xds-exec -- cmake ..
 140 xds-exec -- make
 141 xds-exec -- make remote-target-populate
 142
 143 # Start debugging
 144 xds-gdb -x target/gdb-on-root@myTarget.ini
 145 ```
 146
 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.
 149
 150 ### Native debugging
 151
 152 To enable native debugging mode, you need to define `XDS_NATIVE_GDB` variable.
 153
 154
 155 ## Using xds-gdb within an IDE
 156
 157 ### Netbeans
 158
 159 **Netbeans 8.x :**
 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)
 163
 164 Then, you should set *Debugger Command* to point to xds-gdb
 165
 166 ![Add new tool panel](/docs/images/nb_xds_options.jpeg)
 167
 168 ### Others IDE
 169 *Coming soon...*
 170
 171
 172 ## How to build xds-gdb from scratch
 173
 174 ### Prerequisites
 175  You must install and setup [Go](https://golang.org/doc/install) version 1.7 or
 176  higher to compile this tool.
 177
 178 ### Building
 179 Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Makefile:
 180 ```bash
 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
 185  cd xds-gdb
 186  make
 187 ```
 188
 189 ## Debug
 190
 191 Visual Studio Code launcher settings can be found into `.vscode/launch.json`.