summaryrefslogtreecommitdiffstats
path: root/docs/part-1/debug-configuration.md
blob: af0d7625720fa052573cf1a649db6385153c3903 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
# Configuration

Debug configuration (i.e. `xds-gdb`) is defined by variables.
You can see the variables used further down in this section.

You can set these variables using a number of methods:

- Environment variables that are inherited.

- Configuration file pointed to by the `XDS_CONFIG` environment variable
  (e.g. `XDS_CONFIG=/tmp/my_xds_gdb_config.env xds-gdb`).

- A GDB "init" command file.

- A "user" configuration file located in one of the following
  areas, which are order-dependent:

  1. $(CURRENT_DIRECTORY)/.xds-gdb.env
  1. $(CURRENT_DIRECTORY)/../xds-gdb.env
  1. $(CURRENT_DIRECTORY)/target/xds-gdb.env
  1. $(HOME)/.config/xds/xds-gdb.env

## Configuration Variables

This section describes the `XDS_*` configuration variables.
As previously mentioned, you can define these variables as
described in the previous section.

- `XDS_LOGLEVEL`

  Sets the logging level.
  Levels include "panic", "fatal", "error", "warn", "info", and "debug".

- `XDS_LOGFILE`

  Sets the logging file.
  The default is `/tmp/xds-gdb.log`.

- `XDS_NATIVE_GDB`

  Specifies to use native GDB mode rather than remote XDS mode.

- `XDS_PROJECT_ID`  *(mandatory in XDS mode)*

  The project ID you want to build.

- `XDS_RPATH`

  The relative path to the project.

- `XDS_SDK_ID`   *(mandatory in XDS mode)*

  Cross Sdk ID to use to build project

- `XDS_AGENT_URL`

  The local XDS agent URL.
  The default is `http://localhost:8800`.

## Configuration Using `XDS_CONFIG`

As mentioned, you can define configuration variables in
a file you point to with the `XDS_CONFIG` variable.
Here is an example:

```bash
XDS_CONFIG=/tmp/my_xds_gdb_config.env xds-gdb
```

Variables defined in this file overwrite any inherited
environment variables.
When you define a variable in the file, you can prefix the
assignment with the "export" string.
Doing so causes the variable to be exported to the environment.

Following is an example of a configuration file pointed
to by the `XDS_CONFIG` variable.
These commands create the `xds-gen3.conf` configuration file
in the `$MY_PROJECT_DIR` directory:

```bash
# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application
cat > $MY_PROJECT_DIR/xds-gen3.conf << EOF
export XDS_AGENT_URL=localhost:8800
export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b
export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03
EOF
```

## Configuration Using GDB Init

GDB is a versatile debugger and can be run with many options.
One such option is to execute a GDB "init" file upon startup.
You do this by using the "--command" or "-x" command-line options
and providing the name of the init file.

<!-- section-note -->
**NOTES:**

- For information on debugging with GDB, see
  "[Debugging with GDB](https://www.sourceware.org/gdb/onlinedocs/gdb.html#index-_002d_002dcommand)".

- For information on GDB init files, see
  "[Command files](https://ftp.gnu.org/old-gnu/Manuals/gdb-5.1.1/html_node/gdb_190.html)".
<!-- end-section-note -->

When you create an init file, it must conform to the following
syntax (i.e. inclusion of what are normally commenting characters
as well as use of the `:XDS-ENV:` tag).

Following is an example init file that defines the `XDS_PROJECT_ID`
and `XDS_SDK_ID` variables:

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