aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorSebastien Douheret <sebastien.douheret@iot.bzh>2017-09-20 14:17:57 +0200
committerSebastien Douheret <sebastien.douheret@iot.bzh>2017-09-20 14:17:57 +0200
commitb919b385f5b7d3e2f41855d742c1e818ae95bd02 (patch)
tree1f7a8e28d764c98f366bb13f3ed2630b2c579067 /docs
parent539cc38be44221ba526ee3a1e07ea44ec98c72da (diff)
Update xds internals doc
Signed-off-by: Sebastien Douheret <sebastien.douheret@iot.bzh>
Diffstat (limited to 'docs')
-rw-r--r--docs/part-1/5_debug-first-app.md8
-rw-r--r--docs/part-2/1_xds-server.md3
-rw-r--r--docs/part-2/2_xds-agent.md62
-rw-r--r--docs/part-2/3_xds-exec.md256
-rw-r--r--docs/part-2/4_xds-gdb.md128
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:
- ![Add new tool panel](./pictures/nb_newtool.png)
+ ![Add new tool panel](./pictures/nb_newtool.png){style width:90%;}
- Then, you should set **Make Command** and **Debugger Command** to point to xds tools:
- ![Add new tool panel](./pictures/nb_xds_options.png)
+ ![Add new tool panel](./pictures/nb_xds_options.png){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_)
- ![Select Model panel](./pictures/nb_project_debug-1.png)
+ ![Select Model panel](./pictures/nb_project_debug-1.png){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:
-![Add new tool panel](./docs/images/nb_newtool.jpg)
-
-Then, you should set *Debugger Command* to point to xds-gdb
-
-![Add new tool panel](./docs/images/nb_xds_options.jpg)
-
-### Others IDE
-
-*Coming soon...*
-
## How to build xds-gdb from scratch
### Prerequisites