summaryrefslogtreecommitdiffstats
path: root/docs/part-1/debug-configuration.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/part-1/debug-configuration.md')
-rw-r--r--docs/part-1/debug-configuration.md132
1 files changed, 88 insertions, 44 deletions
diff --git a/docs/part-1/debug-configuration.md b/docs/part-1/debug-configuration.md
index 8743bc1..c87a72f 100644
--- a/docs/part-1/debug-configuration.md
+++ b/docs/part-1/debug-configuration.md
@@ -1,74 +1,118 @@
# Configuration
- `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
- 1. $(CURRENT_DIRECTORY)/../xds-gdb.env
- 1. $(CURRENT_DIRECTORY)/target/xds-gdb.env
- 1. $(HOME)/.config/xds/xds-gdb.env
+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
-`XDS_CONFIG` Config file defining `XDS_xxx` configuration variables.
+This section describes the `XDS_*` configuration variables.
+As previously mentioned, you can define these variables as
+described in the previous section.
-Variables of this file will overwrite inherited environment variables.
+- `XDS_LOGLEVEL`
-Variables definition may be prefixed or not by "export" keyword.
+ Sets the logging level.
+ Levels include "panic", "fatal", "error", "warn", "info", and "debug".
-Here is an example of configuration file:
+- `XDS_LOGFILE`
-```bash
-# for example:
-# 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
-```
+ 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)*
-`XDS_LOGLEVEL`
+ The project ID you want to build.
-Set logging level (supported levels: panic, fatal, error, warn, info, debug)
+- `XDS_RPATH`
-`XDS_LOGFILE`
+ The relative path to the project.
-Set logging file, default `/tmp/xds-gdb.log`.
+- `XDS_SDK_ID` *(mandatory in XDS mode)*
-`XDS_NATIVE_GDB`
+ Cross SDK ID to use to build project
-Use native gdb mode instead of remote XDS mode.
+- `XDS_AGENT_URL`
-`XDS_PROJECT_ID` *(mandatory in XDS mode)*
+ The local XDS agent URL.
+ The default is `http://localhost:8800`.
-Project ID you want to build
+## 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
+```
-`XDS_RPATH`
+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.
-Relative path into project
+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:
-`XDS_SDK_ID` *(mandatory in XDS mode)*
+```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
+```
-Cross Sdk ID to use to build project
+## Configuration Using GDB Init
-`XDS_AGENT_URL`
+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.
-Local XDS agent url (default `http://localhost:8800`)
+<!-- section-note -->
+**NOTES:**
-## Configuration variables set within gdb init command file
+- For information on debugging with GDB, see
+ "[Debugging with GDB](https://www.sourceware.org/gdb/onlinedocs/gdb.html)".
-Above `XDS_xxx` variables may also be defined within gdb init command file
-(see --command or -x option of genuine Gdb).
+- 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 -->
-You must respect the following syntax: commented line including `:XDS-ENV:` tag
+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).
-Example of gdb init file where we define project and sdk ID:
+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