diff options
| -rwxr-xr-x | docs/part-1/debug-configuration.md | 132 |
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 100755 --- 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 |