diff options
| -rw-r--r-- | docs/part-1/5_debug-first-app.md | 8 | ||||
| -rw-r--r-- | docs/part-2/1_xds-server.md | 3 | ||||
| -rw-r--r-- | docs/part-2/2_xds-agent.md | 62 | ||||
| -rw-r--r-- | docs/part-2/3_xds-exec.md | 256 | ||||
| -rw-r--r-- | docs/part-2/4_xds-gdb.md | 128 |
5 files changed, 65 insertions, 392 deletions
diff --git a/docs/part-1/5_debug-first-app.md b/docs/part-1/5_debug-first-app.md index f9f0a6e..38f2b67 100644 --- a/docs/part-1/5_debug-first-app.md +++ b/docs/part-1/5_debug-first-app.md @@ -64,7 +64,7 @@ Use native gdb mode instead of remote XDS server mode. `XDS_PROJECT_ID` *(mandatory with XDS server mode)* -Project ID you want to build +Project ID you want to build `XDS_RPATH` @@ -168,11 +168,11 @@ __Netbeans 8.x :__ - Open menu **Tools** -> **Options** - Open **C/C++** tab, in **Build Tools** sub-tab, click on **Add** button: -  + {style width:90%;} - Then, you should set **Make Command** and **Debugger Command** to point to xds tools: -  + {style width:90%;} - Finally click on **OK** button. @@ -191,7 +191,7 @@ __Netbeans 8.x :__ - Gdb Init File: `target/gdb-on-root@renesas-gen3.ini` (_script name may depend of RSYNC_TARGET variable you set in pre-build command_) -  + {style width:90%;} - Click on **Apply** and then **OK** button to save settings diff --git a/docs/part-2/1_xds-server.md b/docs/part-2/1_xds-server.md index d4ae63c..d7f511a 100644 --- a/docs/part-2/1_xds-server.md +++ b/docs/part-2/1_xds-server.md @@ -193,8 +193,7 @@ See also `xds-agent` [README file](https://github.com/iotbzh/xds-agent) for more ### Dependencies -- Install and setup [Go](https://golang.org/doc/install) version 1.7 or -higher to compile this tool. +- Install and setup [Go](https://golang.org/doc/install) version 1.7 or higher to compile this tool. - Install [npm](https://www.npmjs.com/) - Install [gulp](http://gulpjs.com/) diff --git a/docs/part-2/2_xds-agent.md b/docs/part-2/2_xds-agent.md index eac157a..fa58c35 100644 --- a/docs/part-2/2_xds-agent.md +++ b/docs/part-2/2_xds-agent.md @@ -9,68 +9,6 @@ machine or container (where `xds-server` is running). > **SEE ALSO**: [xds-server](https://github.com/iotbzh/xds-server), a web server used to remotely cross build applications. -## How to install xds-agent - -### Install package for debian distro type - -```bash -export DISTRO="Debian_8.0" -wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/app-Development/${DISTRO}/Release.key | sudo apt-key add - -sudo bash -c "cat >> /etc/apt/sources.list.d/AGL.list<<EOF -deb http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/app-Development/${DISTRO}/ ./ -EOF -" -sudo apt-get update -sudo apt-get install agl-xds-agent -``` - -The value 'DISTRO' can be set to {Debian_8.0, Debian_9.0, xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04} - -Update the package - -```bash -sudo apt-get update -sudo apt-get upgrade agl-xds-agent -``` - -The files are install here: - -```bash -/opt/AGL/agl-xds-agent -``` - -### Install package for rpm distro type - -#### openSUSE - -```bash -export DISTRO="openSUSE_Leap_42.2" -sudo zypper ar http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/app-Development/${DISTRO}/isv:LinuxAutomotive:app-Development.repo -sudo zypper ref -sudo zypper install agl-xds-agent -``` - -The value 'DISTRO' can be set to {openSUSE_Leap_42.2, openSUSE_Leap_42.3, openSUSE_Tumbleweed} - -Update the package - -```bash -sudo zypper ref -sudo zypper install --force agl-xds-agent -``` - -The files are install here: - -```bash -/opt/AGL/agl-xds-agent -``` - -## How to install on other platform - -Download released tarballs from github [releases page](https://github.com/iotbzh/xds-agent/releases). - -Then unzip this tarball any where into your local disk (for example: /opt/AGL/xds or C:\AGL\xds). - ## Configuration xds-agent configuration is driven by a JSON config file (named `agent-config.json`). diff --git a/docs/part-2/3_xds-exec.md b/docs/part-2/3_xds-exec.md index 7899ba9..7487947 100644 --- a/docs/part-2/3_xds-exec.md +++ b/docs/part-2/3_xds-exec.md @@ -15,253 +15,70 @@ on your local host in order to use XDS. > - [xds-server](https://github.com/iotbzh/xds-server), a web server used to remotely cross build applications. -## Getting Started +## Configuration -You must have a running `xds-server` (locally or on the Cloud), see -[README of xds-server](https://github.com/iotbzh/xds-server/blob/master/README.md) -for more details. +`xds-exec` configuration is defined either by environment variables or by +setting command line options (see listed below). -Connect your favorite Web browser to the XDS dashboard (default url -http://localhost:8000) and follow instructions to start local `xds-agent` on -your local host. Please refer to instructions provided by XDS dashboard or see -`README of xds-agent`. +Configuration through environment variables may also be defined in a file that +will be sourced on `xds-exec` start-up. Use `--config|-c` option or set +`XDS_CONFIG` environment variable to specify the config filename. -Then create your project you XDS dashboard. +<!-- note --> +>**Note:** all parameters after a double dash (--) are considered as the command +to execute on xds-server. +<!-- endnote --> -### Installing xds-exec +### Configuration Options/Variables -#### Install package for debian distro type +`--id` option or `XDS_PROJECT_ID` env variable **(mandatory)** -```bash -export DISTRO="Debian_8.0" -wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/app-Development/${DISTRO}/Release.key | sudo apt-key add - -sudo bash -c "cat >> /etc/apt/sources.list.d/AGL.list <<EOF -deb http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/app-Development/${DISTRO}/ ./ -EOF -" -sudo apt-get update -sudo apt-get install agl-xds-exec -``` - -The value 'DISTRO' can be set to {Debian_8.0, Debian_9.0, xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04} - -Update the package - -```bash -sudo apt-get update -sudo apt-get upgrade agl-xds-exec -``` - -The files are install here: - -```bash -/opt/AGL/agl-xds-exec -``` - -#### Install package for rpm distro type - -##### openSUSE - -```bash -export DISTRO="openSUSE_Leap_42.2" -sudo zypper ar http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/app-Development/${DISTRO}/isv:LinuxAutomotive:app-Development.repo -sudo zypper ref -sudo zypper install agl-xds-exec -``` - -The value 'DISTRO' can be set to {openSUSE_Leap_42.2, openSUSE_Leap_42.3, openSUSE_Tumbleweed} - -Update the package - -```bash -sudo zypper ref -sudo zypper install --force agl-xds-exec -``` - -The files are install here: - -```bash -/opt/AGL/agl-xds-exec -``` - -### Using xds-exec from command line - -You need to determine which is the unique id of your project. You can find -this ID in project page of XDS dashboard or you can get it from command line -using the `--list` option. This option lists all existing projects ID: - -```bash -./bin/xds-exec --list +Project ID you want to build -List of existing projects: - CKI7R47-UWNDQC3_myProject - CKI7R47-UWNDQC3_test2 - CKI7R47-UWNDQC3_test3 -``` +`--config|-c` option or `XDS_CONFIG` env variable -Now to refer your project, just use --id option or use `XDS_PROJECT_ID` -environment variable. +Env config file to source on startup -You are now ready to use XDS to for example cross build your project. -Here is an example to build a project based on CMakefile: +`--log|-l` option or `XDS_LOGLEVEL` env variable -```bash -# Add xds-exec in the PATH -export PATH=${PATH}:/opt/AGL/agl-xds-exec +Logging level, supported levels are: -# Go into your project directory -cd $MY_PROJECT_DIR +* panic, +* fatal, +* error, +* warn, +* info, +* debug -# Create a build directory -xds-exec --id=CKI7R47-UWNDQC3_myProject --sdkid=poky-agl_aarch64_4.0.1 --url=http://localhost:8000 -- mkdir build +Default level is "error". -# Generate build system using cmake -xds-exec --id=CKI7R47-UWNDQC3_myProject --sdkid=poky-agl_aarch64_4.0.1 --url=http://localhost:8000 -- cd build && cmake .. +`--rpath` option or `XDS_PATH` env variable -# Build the project -xds-exec --id=CKI7R47-UWNDQC3_myProject --sdkid=poky-agl_aarch64_4.0.1 --url=http://localhost:8000 -- cd build && make all -``` +Relative path into project -To avoid to set project id, xds server url, ... at each command line, you can -define these settings as environment variable within an env file and just set -`--config` option or source file before executing xds-exec. +`sdkid` option or `XDS_SDK_ID` env variable **(mandatory)** -For example, the equivalence of above command is: +Cross Sdk ID to use to build project -```bash -cat > config.env << EOF - export XDS_SERVER_URL=localhost:8000 - export XDS_PROJECT_ID=CKI7R47-UWNDQC3_myProject - export XDS_SDK_ID=poky-agl_aarch64_4.0.1 -EOF - -xds-exec --config config.env -- mkdir build - -# Or sourcing env file -source config.env -xds-exec -- cd build && cmake .. -xds-exec -- cd build && make all -``` +`timestamp|-ts` option or `XDS_TIMESTAMP` env variable -### Using xds-exec within an IDE +Prefix output with timestamp -#### Visual Studio Code - -Open your project in VSC - -```bash -cd $MY_PROJECT_DIR -code . & -``` -Add new tasks : press `Ctrl+Shift+P` and select the `Tasks: Configure Task Runner` command and you will see a list of task runner templates. - -And define your own tasks, here is an example to build [unicens2-binding](https://github.com/iotbzh/unicens2-binding) AGL binding based on cmake (_options value of args array must be updated regarding your settings_): - -```json -{ - "version": "0.1.0", - "linux": { - "command": "/opt/AGL/agl-xds-exec/xds-exec" - }, - "isShellCommand": true, - "args": [ - "-url", "localhost:8010", - "-id", "W2EAQBA-HQI75XA_unicens2-binding", - "-sdkid", "poky-agl_aarch64_4.0.1", - "--" - ], - "showOutput": "always", - "tasks": [{ - "taskName": "clean", - "suppressTaskName": true, - "args": [ - "rm -rf build/* && echo Cleanup done." - ] - }, - { - "taskName": "pre-build", - "isBuildCommand": true, - "suppressTaskName": true, - "args": [ - "mkdir -p build && cd build && cmake -DRSYNC_TARGET=root@192.168.168.11 -DRSYNC_PREFIX=./opt" - ] - }, - { - "taskName": "build", - "isBuildCommand": true, - "suppressTaskName": true, - "args": [ - "cd build && make widget" - ], - "problemMatcher": { - "owner": "cpp", - "fileLocation": ["absolute"], - "pattern": { - "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$", - "file": 1, - "line": 2, - "column": 3, - "severity": 4, - "message": 5 - } - } - }, - { - "taskName": "populate", - "suppressTaskName": true, - "args" : [ - "cd build && make widget-target-install" - ] - } - ] -} -``` - -> **NOTE** You can also add your own keybindings to trig above tasks, for example: -> ```json -> // Build -> { -> "key": "alt+f9", -> "command": "workbench.action.tasks.runTask", -> "args": "clean" -> }, -> { -> "key": "alt+f10", -> "command": "workbench.action.tasks.runTask", -> "args": "pre-build" -> }, -> { -> "key": "alt+f11", -> "command": "workbench.action.tasks.runTask", -> "args": "build" -> }, -> { -> "key": "alt+f12", -> "command": "workbench.action.tasks.runTask", -> "args": "populate" -> }, -> ``` -> -> More details about VSC keybindings [here](https://code.visualstudio.com/docs/editor/tasks#_binding-keyboard-shortcuts-to-tasks) -> -> More details about VSC tasks [here](https://code.visualstudio.com/docs/editor/tasks) - -#### Qt Creator -Please refer to [agl-hello-qml](https://github.com/radiosound-com/agl-hello-qml#clone--build-project) project. -Thanks to Dennis for providing this useful example. - -#### Others IDE -*Coming soon...* +`url` option or `XDS_SERVER_URL` env variable +Remote XDS server url (default: "localhost:8000") ## How to build ### Prerequisites + You must install and setup [Go](https://golang.org/doc/install) version 1.7 or higher to compile this tool. ### Building + Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Makefile: + ```bash export GOPATH=$(realpath ~/workspace_go) mkdir -p $GOPATH/src/github.com/iotbzh @@ -280,6 +97,7 @@ it may be useful use the same local sources. So you should replace `xds-server` in `vendor` directory by a symlink. So clone first `xds-server` sources next to `xds-exec` directory. You should have the following tree: + ``` > tree -L 3 src src @@ -288,8 +106,10 @@ src |-- xds-exec |-- xds-server ``` + Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor directory : + ```bash cd src/github.com/iotbzh/xds-exec make vendor/debug diff --git a/docs/part-2/4_xds-gdb.md b/docs/part-2/4_xds-gdb.md index 5fe0ab9..9905eee 100644 --- a/docs/part-2/4_xds-gdb.md +++ b/docs/part-2/4_xds-gdb.md @@ -12,33 +12,19 @@ Two debugging models are supported: 1. XDS remote debugging requiring an XDS server and allowing cross debug your application. - By default XDS remote debug is used and you need to define `XDS_NATIVE_GDB` variable to use native gdb debug mode instead. > **SEE ALSO**: [xds-server](https://github.com/iotbzh/xds-server), a web server -used to remotely cross build applications. +used to remotely cross build applications. > **SEE ALSO**: [xds-exec](https://github.com/iotbzh/xds-exec), wrappers on `exec` command that allows to cross build your application through `xds-server`. -## Getting Started - -## Installing xds-gdb - -Download latest `xds-gdb` release on [https://github.com/iotbzh/xds-gdb/releases](https://github.com/iotbzh/xds-gdb/releases). - -Extract the tarball anywhere you want, for example: - -```bash -mkdir -p ~/opt/bin -unzip -j $DOWNLOAD_DIR/xds-gdb_linux-amd64-v1.0.0.zip xds-gdb/xds-gdb ~/opt/bin -``` - ## Configuration - `xds-gdb` configuration is defined by variables (see listed below). + `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` @@ -51,11 +37,11 @@ unzip -j $DOWNLOAD_DIR/xds-gdb_linux-amd64-v1.0.0.zip xds-gdb/xds-gdb ~/opt/bin ### Configuration Variables - `XDS_CONFIG` : + `XDS_CONFIG` : Config file defining `XDS_xxx` configuration variables. Variables of this file will overwrite inherited environment variables. Variables definition may be - prefixed or not by "export" keyword. - Here is an example of + prefixed or not by "export" keyword. + Here is an example of config file ```bash cat $HOME/myProject/xds-gdb.env @@ -65,25 +51,32 @@ export XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject export XDS_SDK_ID=poky-agl_aarch64_4.0.1 ``` -`XDS_LOGLEVEL` : +`XDS_LOGLEVEL` + Set logging level (supported levels: panic, fatal, error, warn, info, debug) -`XDS_LOGFILE` : +`XDS_LOGFILE` + Set logging file, default `/tmp/xds-gdb.log`. -`XDS_NATIVE_GDB` : +`XDS_NATIVE_GDB` + Use native gdb mode instead of remote XDS server mode. -`XDS_PROJECT_ID` : *(mandatory with XDS server mode)* -Project ID you want to build - -`XDS_RPATH` : +`XDS_PROJECT_ID` *(mandatory with XDS server mode)* + +Project ID you want to build + +`XDS_RPATH` + Relative path into project -`XDS_SDK_ID` : *(mandatory with XDS server mode)* +`XDS_SDK_ID` *(mandatory with XDS server mode)* + Cross Sdk ID to use to build project -`XDS_SERVER_URL` : *(mandatory with XDS server mode)* +`XDS_SERVER_URL` *(mandatory with XDS server mode)* + Remote XDS server url ### Configuration variables set within gdb init command file @@ -99,83 +92,6 @@ Example of gdb init file where we define project and sdk ID: # :XDS-ENV: XDS_SDK_ID=poky-agl_aarch64_4.0.1 ``` -## Using xds-gdb from command line - -### XDS remote debugging mode - -First the project you want to debug must be declared on an xds-server and this -project may also has been built using this xds-server (see [xds-server](https://github.com/iotbzh/xds-server) for more details). - -So to debug it you need to know the xds-server url (eg. <http://xds-docker:8000>), -you also need the project and sdk unique id. You can find these IDs in project -page of XDS dashboard or you can get them from command line using the `--list` -option. -This option lists all existing projects ID: - -```bash -XDS_SERVER_URL=http://xds-docker:8000 xds-gdb --list -``` - -Now to refer your project, just set `XDS_PROJECT_ID` and `XDS_SDK_ID` variables. - -You are now ready to use `xds-gdb` to for example cross debug your project. -Here is an example to build and debug a project based on CMakefile and -[AGL app-templates](https://git.automotivelinux.org/apps/app-templates/): - -```bash -# Go into your project directory (for example helloworld-service) -git clone https://github.com/iotbzh/helloworld-service.git -cd helloworld-service - -# Declare your project on xds-server -# <for now, you can only do this step using xds HTML dashboard (see xds-server doc)> - -# Define XDS config -cat <<EOF >./xds-config.env -XDS_SERVER_URL=http://xds-docker:8000 -XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject -XDS_SDK_ID=poky-agl_aarch64_4.0.1 -EOF - -# Tell to xds-exec and xds-gdb which is your config file -export XDS_CONFIG=../xds-config.env - -# Create a new build directory -mkdir build && cd build - -# Start remote cross build -xds-exec -- cmake .. -xds-exec -- make -xds-exec -- make remote-target-populate - -# Start debugging -xds-gdb -x target/gdb-on-root@myTarget.ini -``` - -> **Notes** : [Helloworld-service project](https://github.com/iotbzh/helloworld-service) -is an AGL project based on app-templates that can be build and debug using XDS. - -### Native debugging - -To enable native debugging mode, you need to define `XDS_NATIVE_GDB` variable. - -## Using xds-gdb within an IDE - -### Netbeans - -__Netbeans 8.x :__ -Open menu Tools -> Options -Then open C/C++ tab, in "Build Tools" sub-tab, click on "Add" button: - - -Then, you should set *Debugger Command* to point to xds-gdb - - - -### Others IDE - -*Coming soon...* - ## How to build xds-gdb from scratch ### Prerequisites |