summaryrefslogtreecommitdiffstats
path: root/docs/part-2/3_xds-exec.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/part-2/3_xds-exec.md')
-rw-r--r--docs/part-2/3_xds-exec.md296
1 files changed, 296 insertions, 0 deletions
diff --git a/docs/part-2/3_xds-exec.md b/docs/part-2/3_xds-exec.md
new file mode 100644
index 0000000..7899ba9
--- /dev/null
+++ b/docs/part-2/3_xds-exec.md
@@ -0,0 +1,296 @@
+# xds-exec: wrapper on exec for XDS
+
+`xds-exec` is a wrapper on exec linux command for X(cross) Development System.
+
+As well as `xds-exec` is a wrapper on exec command and can be use to execute any
+command on a remote `xds-server`.
+
+This tool can be used in lieu of "standard" `exec` command to execute any
+command on a remote `xds-server`. For example you can trig your project build by
+executing : `xds-exec --config conf.env -- make build`
+
+> **SEE ALSO**:
+> - [xds-agent](https://github.com/iotbzh/xds-agent), an agent that should run
+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
+
+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.
+
+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`.
+
+Then create your project you XDS dashboard.
+
+### Installing xds-exec
+
+#### 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-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
+
+List of existing projects:
+ CKI7R47-UWNDQC3_myProject
+ CKI7R47-UWNDQC3_test2
+ CKI7R47-UWNDQC3_test3
+```
+
+Now to refer your project, just use --id option or use `XDS_PROJECT_ID`
+environment variable.
+
+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:
+
+```bash
+# Add xds-exec in the PATH
+export PATH=${PATH}:/opt/AGL/agl-xds-exec
+
+# Go into your project directory
+cd $MY_PROJECT_DIR
+
+# Create a build directory
+xds-exec --id=CKI7R47-UWNDQC3_myProject --sdkid=poky-agl_aarch64_4.0.1 --url=http://localhost:8000 -- mkdir build
+
+# 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 ..
+
+# Build the project
+xds-exec --id=CKI7R47-UWNDQC3_myProject --sdkid=poky-agl_aarch64_4.0.1 --url=http://localhost:8000 -- cd build && make all
+```
+
+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.
+
+For example, the equivalence of above command is:
+
+```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
+```
+
+### Using xds-exec within an IDE
+
+#### 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...*
+
+
+## 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
+ cd $GOPATH/src/github.com/iotbzh
+ git clone https://github.com/iotbzh/xds-exec.git
+ cd xds-exec
+ make
+```
+
+## Debug
+
+Visual Studio Code launcher settings can be found into `.vscode/launch.json`.
+
+>**Tricks:** To debug both `xds-exec` (client part) and `xds-server` (server part),
+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
+|-- github.com
+ |-- iotbzh
+ |-- 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
+```