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