diff options
Diffstat (limited to 'docs/part-2')
24 files changed, 801 insertions, 777 deletions
diff --git a/docs/part-2/0_Abstract.md b/docs/part-2/0_Abstract.md index aa7ddc4..45f5f40 100644 --- a/docs/part-2/0_Abstract.md +++ b/docs/part-2/0_Abstract.md @@ -4,48 +4,3 @@ This 2nd part is the "technical" documentation of all XDS pieces/tools that allows for example to fine tune XDS configuration or rebuild all XDS tools from scratch. - -## Prerequisites - -To build xds binaries you need to install first [Go](https://golang.org/doc/install) version 1.8.1 or higher and some other tools. To build `xds-server` and `xds-agent` -you also need to install in addition `nodejs`. - -**Ubuntu:** - -```bash -# Install various tools -sudo apt-get install git make npm curl git zip unzip - -# Install Go -source /etc/os-release -wget -O- "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x52B59B1571A79DBC054901C0F6BC817356A3D45E" | sudo apt-key add - -sudo bash -c "cat >> /etc/apt/sources.list.d/golang.list <<EOF -deb http://ppa.launchpad.net/longsleep/golang-backports/ubuntu ${VERSION_CODENAME} main -EOF" -sudo apt-get update -sudo apt-get install golang-go - -# Install nodejs LTS version and angular-cli (only mandatory for xds-server and xds-agent) -sudo npm install --global n @angular/cli -sudo n lts -``` - -**openSUSE:** - -```bash -# Install various tools -sudo zypper install git make npm curl zip unzip - -# Install Go -# ( the value 'DISTRO' can be set to {openSUSE_Leap_42.2, openSUSE_Leap_42.3, openSUSE_Tumbleweed} ) -source /etc/os-release; export DISTRO="openSUSE_Leap_$VERSION" -sudo zypper ar http://download.opensuse.org/repositories/devel:/languages:/go/${DISTRO}/devel:languages:go.repo -sudo zypper --gpg-auto-import-keys ref -sudo zypper install go1.9 - -# Install nodejs LTS version and angular-cli (only mandatory for xds-server and xds-agent) -sudo npm install --global n @angular/cli -sudo n lts -``` - -Don't forget to open new user session after installing these packages. diff --git a/docs/part-2/1_Prerequisites.md b/docs/part-2/1_Prerequisites.md new file mode 100644 index 0000000..fcaa031 --- /dev/null +++ b/docs/part-2/1_Prerequisites.md @@ -0,0 +1,44 @@ +# Prerequisites + +To build xds binaries you need to install first [Go](https://golang.org/doc/install) version 1.8.1 or higher and some other tools. To build `xds-server` and `xds-agent` +you also need to install in addition `nodejs`. + +**Ubuntu:** + +```bash +# Install various tools +sudo apt-get install git make npm curl git zip unzip + +# Install Go +source /etc/os-release +wget -O- "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x52B59B1571A79DBC054901C0F6BC817356A3D45E" | sudo apt-key add - +sudo bash -c "cat >> /etc/apt/sources.list.d/golang.list <<EOF +deb http://ppa.launchpad.net/longsleep/golang-backports/ubuntu ${VERSION_CODENAME} main +EOF" +sudo apt-get update +sudo apt-get install golang-go + +# Install nodejs LTS version and angular-cli (only mandatory for xds-server and xds-agent) +sudo npm install --global n @angular/cli +sudo n lts +``` + +**openSUSE:** + +```bash +# Install various tools +sudo zypper install git make npm curl zip unzip + +# Install Go +# ( the value 'DISTRO' can be set to {openSUSE_Leap_42.2, openSUSE_Leap_42.3, openSUSE_Tumbleweed} ) +source /etc/os-release; export DISTRO="openSUSE_Leap_$VERSION" +sudo zypper ar http://download.opensuse.org/repositories/devel:/languages:/go/${DISTRO}/devel:languages:go.repo +sudo zypper --gpg-auto-import-keys ref +sudo zypper install go1.9 + +# Install nodejs LTS version and angular-cli (only mandatory for xds-server and xds-agent) +sudo npm install --global n @angular/cli +sudo n lts +``` + +Don't forget to open new user session after installing these packages. diff --git a/docs/part-2/1_xds-server/0_abstract.md b/docs/part-2/1_xds-server/0_abstract.md new file mode 100644 index 0000000..07dd057 --- /dev/null +++ b/docs/part-2/1_xds-server/0_abstract.md @@ -0,0 +1,41 @@ +# XDS - X(cross) Development System Server + +`xds-server` is a web server that allows user to remotely cross build applications. + +- The first goal is to provide a multi-platform cross development tool with near-zero installation. +- The second goal is to keep application sources locally (on user's machine). + - Make it compatible with existing IT policies (e.g. corporate backup or SCM). + - Let user to continue to work as usual. + - Use his favorite editor. + - keep performance while editing/browsing sources. + - Avoids manual operation + +This powerful and portable webserver (written in [Go](https://golang.org)) +exposes a REST interface over HTTP. + +`xds-server` uses [Syncthing](https://syncthing.net/) tool to synchronize +projects files from user machine to build server machine or container. + +`xds-server` is commonly running on a build server (within a container or not) +and [xds-agent](../2_xds-agent/0_abstract.html) must run on the developer/user machine in order +to setup the following connection chain: + +```schema + developer/user machine | build server or container + ---------------------------|----------------------------- + xds-cli <---> xds-agent <-|-> xds-server +``` + +**SEE ALSO**: [xds-cli](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-cli.git), +a command-line tool that allows you to send commands to `xds-agent / xds-server` +and for example build your application from command-line or from your favorite +IDE (such as Netbeans or Visual Studio Code) through `xds-agent <=> xds-server`. + +--- + +Links to subchapters : + +- [Configuration](./1_config.html) +- [How to run](./2_how-to-run.html) +- [Build from scratch](./3_build.html) +- [Debugging](./4_debug.html) diff --git a/docs/part-2/1_xds-server/1_config.md b/docs/part-2/1_xds-server/1_config.md new file mode 100644 index 0000000..594bdf2 --- /dev/null +++ b/docs/part-2/1_xds-server/1_config.md @@ -0,0 +1,86 @@ +# Configuration + +`xds-server` configuration is driven by a JSON config file (`server-config.json`). + +Here is the logic to determine which `server-config.json` file will be used: + +1. from command line option: `--config myConfig.json` +1. `$HOME/.xds/server/server-config.json` file +1. `/etc/xds/server/server-config.json` file +1. `<xds-server executable dir>/server-config.json` file + +Supported fields in configuration file are: + +- **httpPort** : HTTP port of client webapp/REST API +- **webAppDir** : location of client web application (default: webapp/dist) +- **shareRootDir** : root directory where projects will be copied +- **logsDir** : directory to store logs (eg. syncthing output) +- **sdkScriptsDir** : directory where scripts, used to managed SDKs, are installed +- **syncthing.binDir** : syncthing binaries directory (default: executable directory) +- **syncthing.home"** : syncthing home directory (usually .../syncthing-config) +- **syncthing.gui-address** : syncthing gui url (default <http://localhost:8385>) +- **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated) + +All fields are optional and example below corresponds to the default values. + +```json +{ + "httpPort": 8000, + "webAppDir": "webapp/dist", + "shareRootDir": "${HOME}/.xds/server/projects", + "logsDir": "/tmp/logs", + "sdkScriptsDir": "${EXEPATH}/scripts/sdks", + "syncthing": { + "binDir": "./bin", + "home": "${HOME}/.xds/server/syncthing-config", + "gui-address": "http://localhost:8385", + "gui-apikey": "123456789", + } +} +``` + +>**Notes:** +> +>Environment variables are supported by using `${MY_VAR}` syntax. +> + +When `xds-server` is started as a systemd service, default environment variables +are set into `/etc/default/xds-server` file. + +`xds-server` configuration is also driven by a JSON config file (`server-config.json`), +and default JSON config is `/etc/xds/server/server-config.json`. + +<!-- note --> +**Note:** +You can use your own JSON config by settings `APP_CONFIG` variable of +`/etc/default/xds-server` file to your file, for example `/home/MYUSER/.xds/server/server-config.json` +<!-- endnote --> + +## Disable syncthing + +`CloudSync` synchronization type based on `syncthing` tool can be disabled by +simply removing (or renaming) `"syncthing"` key in configuration file. +Here is a JSON configuration file example where syncthing key as been renamed: + +```json +{ + "httpPort": 8000, + "webAppDir": "webapp/dist", + "shareRootDir": "${HOME}/.xds/server/projects", + "logsDir": "/tmp/logs", + "sdkScriptsDir": "${EXEPATH}/scripts/sdks", + "syncthing_DISABLE": { + "binDir": "./bin", + "home": "${HOME}/.xds/server/syncthing-config", + } +} +``` + +On benefit to do that is to increase XDS-Server startup time. + +<!-- note --> +**Note:** + +- `CloudSync` (AKA syncthing) synchronization type can also be disabled when `"syncthing"` key is not defined in JSON configuration file. + +<!-- endnote --> diff --git a/docs/part-2/1_xds-server.md b/docs/part-2/1_xds-server/2_how-to-run.md index a45a8f0..36bc9a6 100644 --- a/docs/part-2/1_xds-server.md +++ b/docs/part-2/1_xds-server/2_how-to-run.md @@ -1,37 +1,4 @@ -# XDS - X(cross) Development System Server - -`xds-server` is a web server that allows user to remotely cross build applications. - -- The first goal is to provide a multi-platform cross development tool with near-zero installation. -- The second goal is to keep application sources locally (on user's machine). - - Make it compatible with existing IT policies (e.g. corporate backup or SCM). - - Let user to continue to work as usual. - - Use his favorite editor. - - keep performance while editing/browsing sources. - - Avoids manual operation - -This powerful and portable webserver (written in [Go](https://golang.org)) -exposes a REST interface over HTTP. - -`xds-server` uses [Syncthing](https://syncthing.net/) tool to synchronize -projects files from user machine to build server machine or container. - -`xds-server` is commonly running on a build server (within a container or not) -and [xds-agent](2_xds-agent.html) must run on the developer/user machine in order -to setup the following connection chain: - -```schema - developer/user machine | build server or container - ---------------------------|----------------------------- - xds-cli <---> xds-agent <-|-> xds-server -``` - -**SEE ALSO**: [xds-cli](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-cli.git), -a command-line tool that allows you to send commands to `xds-agent / xds-server` -and for example build your application from command-line or from your favorite -IDE (such as Netbeans or Visual Studio Code) through `xds-agent <=> xds-server`. - -## How to run +# How to run `xds-server` has been designed to easily compile and debug [AGL](https://www.automotivelinux.org/) applications. That's why `xds-server` has @@ -40,12 +7,12 @@ been integrated into AGL SDK docker container. >**Note:** For more info about AGL SDK docker container, please refer to [AGL SDK Quick Setup](http://docs.automotivelinux.org/docs/getting_started/en/dev/reference/setup-sdk-environment.html) -### Start xds-server within the container +## Start xds-server within the container -See [Installation based on Docker container](../part-1/2_install-xds-server.html#installation-based-on-docker-container) +See [Installation based on Docker container](../../part-1/2-1_install-xds-server-docker.html) chapter. -### Manually Start XDS server +## Manually Start XDS server XDS server is started as a service by Systemd. @@ -82,16 +49,16 @@ docker exec ${CONTAINER_NAME} bash -c "echo 'LOG_LEVEL=debug' >> /etc/default/xd ssh -p 2222 devel@localhost -- "systemctl --user restart xds-server" ``` -### SDK cross-toolchain Management +## SDK cross-toolchain Management -#### Setup to add support of a new SDK family +### Setup to add support of a new SDK family <!-- note --> **Optional step**: read this chapter only if you plan to add a new SDK family. <!-- endnote --> `xds-server` dynamically detects supported SDKs by scanning sub-directories of -`sdkScriptsDir` directory (see [Configuration chapter](#configuration)). +`sdkScriptsDir` directory (see [Configuration chapter](1_config.html)). Each sub-directory (usually name is the same as the SDK family) of `sdkScriptsDir` must contain a set of scripts that will be called by `xds-server` to managed SDKs @@ -136,7 +103,7 @@ On startup `xds-server` will call in order: Please refer to `sdks/README.md` for more information about scripts definition and to understand how to add support of a new SDK family. -#### Install a new SDK from command line +### Install a new SDK from command line Used `sdks` command of `xds-cli` tool to managed SDKs. @@ -201,7 +168,7 @@ Installation based on a local SDK package is only supported when SDK file packag is located in `$HOME/xds-workspace/sdks` directory <!-- endnote --> -#### Install a new SDK from XDS Dashboard +### Install a new SDK from XDS Dashboard Open XDS-Dashboard in web-browser and select `SDKs` entry in left side menu. @@ -218,7 +185,7 @@ SDK download and installation process may take several minutes and output of ins Note that you can abort installation by clicking on `CANCEL` button. -#### Un-install a SDK from command line +### Un-install a SDK from command line Used `sdks` command of `xds-cli` tool to managed SDKs. @@ -239,14 +206,14 @@ xds-cli sdks uninstall d65fe750 SDK ID d65fe750-d3a7-38f5-83d8-3d3806054f8d successfully deleted. ``` -#### Un-install a SDK from XDS Dashboard +### Un-install a SDK from XDS Dashboard Open XDS-Dashboard in web-browser and select `SDKs` entry in left side menu. If needed, switch to `BASIC SDKS VIEW` view and click on trash icon located in the top-right corner of SDK card. -### XDS server REST API and Web application +## XDS server REST API and Web application `xds-server` exposes a REST API and serves a basic web-application. @@ -268,201 +235,4 @@ xdg-open http://localhost:8000 Then follow instructions provided on this page to install and start `xds-agent` that must run locally on your machine. -See also [xds-agent documentation](2_xds-agent.html) for more details. - -## Build xds-server from scratch - -### Dependencies - -Install [Go](https://golang.org/doc/install), [npm](https://www.npmjs.com/), -[nodejs](https://nodejs.org/en/) and some other tools. -Refer to [Prerequisites chapter](./0_Abstract.html#prerequisites) for more details. - -### Building - -#### Native build - -Create a GOPATH variable(must be a full path): - -```bash -export GOPATH=$(realpath ~/workspace_go) -``` - -Clone this repo into your `$GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds` and use delivered Makefile: - -```bash -export GOPATH=${GOPATH}:${ROOTDIR} - -mkdir -p $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds -cd $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds -git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-server -# or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-server -cd xds-server -make all -``` - -And to install `xds-server` (by default in `/opt/AGL/xds/server`): - -```bash -make install -``` - -<!-- warning --> -**Warning:** - -Makefile install rule and default values in configuration file are set -to fit the docker setup. - -So you may need to adapt some settings when you want to install xds-server natively. -<!-- endwarning --> - -<!-- note --> -**Note:** - -Used `DESTDIR` to specify another install directory - -```bash -make install DESTDIR=$HOME/opt/xds-server -``` - -<!-- endnote --> - -#### XDS docker image - -As an alternative to a pre-build image, you can rebuild the container from scratch. - -`xds-server` has been integrated as a flavour of AGL SDK docker image. - -So to rebuild docker image just execute following commands: - -```bash -# Clone docker-worker-generator git repo -git clone https://git.automotivelinux.org/AGL/docker-worker-generator -# Start build that will create a docker image -cd docker-worker-generator -make build FLAVOUR=xds -``` - -### Configuration - -`xds-server` configuration is driven by a JSON config file (`server-config.json`). - -Here is the logic to determine which `server-config.json` file will be used: - -1. from command line option: `--config myConfig.json` -1. `$HOME/.xds/server/server-config.json` file -1. `/etc/xds/server/server-config.json` file -1. `<xds-server executable dir>/server-config.json` file - -Supported fields in configuration file are: - -- **httpPort** : HTTP port of client webapp/REST API -- **webAppDir** : location of client web application (default: webapp/dist) -- **shareRootDir** : root directory where projects will be copied -- **logsDir** : directory to store logs (eg. syncthing output) -- **sdkScriptsDir** : directory where scripts, used to managed SDKs, are installed -- **syncthing.binDir** : syncthing binaries directory (default: executable directory) -- **syncthing.home"** : syncthing home directory (usually .../syncthing-config) -- **syncthing.gui-address** : syncthing gui url (default <http://localhost:8385>) -- **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated) - -All fields are optional and example below corresponds to the default values. - -```json -{ - "httpPort": 8000, - "webAppDir": "webapp/dist", - "shareRootDir": "${HOME}/.xds/server/projects", - "logsDir": "/tmp/logs", - "sdkScriptsDir": "${EXEPATH}/scripts/sdks", - "syncthing": { - "binDir": "./bin", - "home": "${HOME}/.xds/server/syncthing-config", - "gui-address": "http://localhost:8385", - "gui-apikey": "123456789", - } -} -``` - ->**Notes:** -> ->Environment variables are supported by using `${MY_VAR}` syntax. -> - -When `xds-server` is started as a systemd service, default environment variables -are set into `/etc/default/xds-server` file. - -`xds-server` configuration is also driven by a JSON config file (`server-config.json`), -and default JSON config is `/etc/xds/server/server-config.json`. - -<!-- note --> -**Note:** -You can use your own JSON config by settings `APP_CONFIG` variable of -`/etc/default/xds-server` file to your file, for example `/home/MYUSER/.xds/server/server-config.json` -<!-- endnote --> - -#### Disable syncthing - -`CloudSync` synchronization type based on `syncthing` tool can be disabled by -simply removing (or renaming) `"syncthing"` key in configuration file. -Here is a JSON configuration file example where syncthing key as been renamed: - -```json -{ - "httpPort": 8000, - "webAppDir": "webapp/dist", - "shareRootDir": "${HOME}/.xds/server/projects", - "logsDir": "/tmp/logs", - "sdkScriptsDir": "${EXEPATH}/scripts/sdks", - "syncthing_DISABLE": { - "binDir": "./bin", - "home": "${HOME}/.xds/server/syncthing-config", - } -} -``` - -On benefit to do that is to increase XDS-Server startup time. - -<!-- note --> -**Note:** - -- `CloudSync` (AKA syncthing) synchronzation type can also be disabled when `"syncthing"` key is not defined in JSON configuration file. - -<!-- endnote --> - -## Debugging - -### XDS server architecture - -The server part is written in *Go* and web app (basic HTML) in *Angular4*. - -```bash -| -+-- bin/ # where xds-server binary file will be built -| -+-- conf.d/ # Linux configuration and startup files (systemd user service) -| -+-- glide.yaml # Go package dependency file -| -+-- lib/ # sources of server part (Go) -| -+-- LICENSE # XDS server license -| -+-- main.go # main entry point of of Web server (Go) -| -+-- Makefile # makefile including -| -+-- README.md # -| -+-- scripts/ # hold various scripts used for installation or startup -| -+-- test/ # XDS test suite -| -+-- tools/ # temporary directory to hold development tools (like glide) -| -+-- vendor/ # temporary directory to hold Go dependencies packages -| -+-- webapp/ # source client basic web application -``` - -Visual Studio Code launcher settings can be found into `.vscode/launch.json`. +See also [xds-agent documentation](../2_xds-agent/0_abstract.html) for more details. diff --git a/docs/part-2/1_xds-server/3_build.md b/docs/part-2/1_xds-server/3_build.md new file mode 100644 index 0000000..8be3b33 --- /dev/null +++ b/docs/part-2/1_xds-server/3_build.md @@ -0,0 +1,73 @@ +# Build xds-server from scratch + +## Dependencies + +Install [Go](https://golang.org/doc/install), [npm](https://www.npmjs.com/), +[nodejs](https://nodejs.org/en/) and some other tools. + +Refer to [Prerequisites chapter](../1_Prerequisites.html) for more details. + +## Building + +### Native build + +Create a GOPATH variable(must be a full path): + +```bash +export GOPATH=$(realpath ~/workspace_go) +``` + +Clone this repo into your `$GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds` and use delivered Makefile: + +```bash +export GOPATH=${GOPATH}:${ROOTDIR} + +mkdir -p $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds +cd $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds +git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-server +# or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-server +cd xds-server +make all +``` + +And to install `xds-server` (by default in `/opt/AGL/xds/server`): + +```bash +make install +``` + +<!-- warning --> +**Warning:** + +Makefile install rule and default values in configuration file are set +to fit the docker setup. + +So you may need to adapt some settings when you want to install xds-server natively. +<!-- endwarning --> + +<!-- note --> +**Note:** + +Used `DESTDIR` to specify another install directory + +```bash +make install DESTDIR=$HOME/opt/xds-server +``` + +<!-- endnote --> + +### XDS docker image + +As an alternative to a pre-build image, you can rebuild the container from scratch. + +`xds-server` has been integrated as a flavour of AGL SDK docker image. + +So to rebuild docker image just execute following commands: + +```bash +# Clone docker-worker-generator git repo +git clone https://git.automotivelinux.org/AGL/docker-worker-generator +# Start build that will create a docker image +cd docker-worker-generator +make build FLAVOUR=xds +``` diff --git a/docs/part-2/1_xds-server/4_debug.md b/docs/part-2/1_xds-server/4_debug.md new file mode 100644 index 0000000..2b36697 --- /dev/null +++ b/docs/part-2/1_xds-server/4_debug.md @@ -0,0 +1,36 @@ +# Debugging + +## XDS server architecture + +The server part is written in *Go* and web app (basic HTML) in *Angular4*. + +```bash +| ++-- bin/ # where xds-server binary file will be built +| ++-- conf.d/ # Linux configuration and startup files (systemd user service) +| ++-- glide.yaml # Go package dependency file +| ++-- lib/ # sources of server part (Go) +| ++-- LICENSE # XDS server license +| ++-- main.go # main entry point of of Web server (Go) +| ++-- Makefile # makefile including +| ++-- README.md # +| ++-- scripts/ # hold various scripts used for installation or startup +| ++-- test/ # XDS test suite +| ++-- tools/ # temporary directory to hold development tools (like glide) +| ++-- vendor/ # temporary directory to hold Go dependencies packages +| ++-- webapp/ # source client basic web application +``` + +Visual Studio Code launcher settings can be found into `.vscode/launch.json`. diff --git a/docs/part-2/2_xds-agent.md b/docs/part-2/2_xds-agent.md deleted file mode 100644 index 1429715..0000000 --- a/docs/part-2/2_xds-agent.md +++ /dev/null @@ -1,201 +0,0 @@ -# XDS - X(cross) Development System Agent - -XDS-agent is a client that should run on your local / user development machine when you use XDS. - -This agent takes care, among others, of starting [Syncthing](https://syncthing.net/) -tool to synchronize your project files from your local host to XDS build server -machine or container (where `xds-server` is running). - -> **SEE ALSO**: [xds-server](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-server.git), a web server -used to remotely cross build applications. - -## Configuration - -xds-agent configuration is driven by a JSON config file. - -The tarball mentioned in previous section includes this file with default settings. - -Here is the logic to determine which conf file will be used: - -1. from command line option: `--config myConfig.json` -1. `$HOME/.xds/agent/agent-config.json` file -1. `/etc/xds/agent/agent-config.json` file - -Supported fields in configuration file are (all fields are optional and example -below corresponds to the default values): - -- **httpPort** : http port of agent REST interface -- **webAppDir** : location of client webapp / dashboard (default: webapp/dist) -- **logsDir** : directory to store logs (eg. syncthing output) -- **xdsServers** : an array of xds-server object - - **xdsServers.url**: url of xds-server to connect to -- **syncthing**: a object defining syncthing settings - - **syncthing.binDir** : syncthing binaries directory (default: executable directory) - - **syncthing.home"** : syncthing home directory (usually .../syncthing-config) - - **syncthing.gui-address** : syncthing gui url (default <http://localhost:8386>) - - **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated) - -```json -{ - "httpPort": "8800", - "webAppDir": "./www", - "logsDir": "${HOME}/.xds/agent/logs", - "xdsServers": [ - { - "url": "http://localhost:8000" - } - ], - "syncthing": { - "home": "${HOME}/.xds/agent/syncthing-config", - "gui-address": "http://localhost:8386", - "gui-apikey": "1234abcezam" - } -} -``` - ->**Note:** -> ->environment variables are supported by using `${MY_VAR}` syntax. - -## Start-up - -Simply to start `xds-agent` executable - -```bash -./xds-agent & -``` - ->**Note:** -> ->If need be, you can increase log level by setting option -`--log <level>`, supported *level* are: panic, fatal, error, warn, info, debug. - -You can now use XDS dashboard and check that connection with `xds-agent` is up. - -## Build xds-agent from scratch - -### Dependencies - -Install [Go](https://golang.org/doc/install), [npm](https://www.npmjs.com/), -[nodejs](https://nodejs.org/en/) and some other tools. -Refer to [Prerequisites chapter](./0_Abstract.html#prerequisites) for more details. - -### Building - -Clone this repo into your `$GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds` and use delivered Makefile: - -```bash - mkdir -p $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds - cd $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds - git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-agent - # or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-agent - cd xds-agent - make all -``` - -And to install xds-agent (by default in `/usr/local/bin`): - -```bash -make install -``` - ->**Note:** -> ->Used `DESTDIR` to specify another install directory ->```bash ->make install DESTDIR=$HOME/opt/xds-agent ->``` - -#### Cross build - -For example on a Linux machine to cross-build for Windows, just follow these steps. - -The first time you need to install all the windows-amd64 standard packages on -your system with - -```bash -# List all supported OS / ARCH -go tool dist list - -# Install all standard packages for another OS/ARCH (eg. windows amd64) -GOOS=windows GOARCH=amd64 go install -v -a std -``` - -Then compile and package xds-agent using provided makefile - -```bash -export GOOS=windows -export GOARCH=amd64 -make all -make package -``` - -## Debugging - -### XDS agent architecture - -The agent part is written in *Go* and the webapp / dashboard is in *typescript + Angular4*. - -```bash -| -+-- bin/ where xds-server binary file will be built -| -+-- conf.d Linux configuration and startup files (systemd user service) -| -+-- glide.yaml Go package dependency file -| -+-- lib/ sources of server part (Go) -| -+-- main.go main entry point of of Web server (Go) -| -+-- Makefile makefile including -| -+-- README.md this readme -| -+-- scripts/ hold various scripts used for installation or startup -| -+-- tools/ temporary directory to hold development tools (like glide) -| -+-- vendor/ temporary directory to hold Go dependencies packages -| -+-- webapp/ source client basic webapp / dashboard -``` - -### Debug - -Visual Studio Code launcher settings can be found into `.vscode/launch.json`. - ->**Tricks:** -> ->To debug both `xds-agent` and `xds-server` or common code ->`xds-common`, it may be useful use the same local sources. -> ->So you should replace `xds-server` + `xds-common` in `vendor` directory by a symlink. -> ->So clone first `xds-server` + `xds-common` sources next to `xds-agent` directory. - -You should have the following tree: - -```bash -tree -L 5 --charset=ascii src/ -src/ -`-- gerrit.automotivelinux.org - `-- gerrit - `-- src - `-- xds - |-- backup.sh - |-- xds-agent - |-- xds-cli - |-- xds-common - |-- xds-docs - |-- xds-gdb - `-- xds-server -``` - -Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor -directory : - -```bash -cd src/gerrit.automotivelinux.org/gerrit/src/xds/xds-agent -make vendor/debug -``` diff --git a/docs/part-2/2_xds-agent/0_abstract.md b/docs/part-2/2_xds-agent/0_abstract.md new file mode 100644 index 0000000..d73bdb9 --- /dev/null +++ b/docs/part-2/2_xds-agent/0_abstract.md @@ -0,0 +1,19 @@ +# XDS - X(cross) Development System Agent + +XDS-agent is a client that should run on your local / user development machine when you use XDS. + +This agent takes care, among others, of starting [Syncthing](https://syncthing.net/) +tool to synchronize your project files from your local host to XDS build server +machine or container (where `xds-server` is running). + +> **SEE ALSO**: [xds-server](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-server.git), a web server +used to remotely cross build applications. + +--- + +Links to subchapters : + +- [Configuration](./1_config.html) +- [Start-up](./2_start.html) +- [Build from scratch](./3_build.html) +- [Debugging](./4_debug.html) diff --git a/docs/part-2/2_xds-agent/1_config.md b/docs/part-2/2_xds-agent/1_config.md new file mode 100644 index 0000000..9e912cb --- /dev/null +++ b/docs/part-2/2_xds-agent/1_config.md @@ -0,0 +1,47 @@ +# Configuration + +xds-agent configuration is driven by a JSON config file. + +The tarball mentioned in previous section includes this file with default settings. + +Here is the logic to determine which conf file will be used: + +1. from command line option: `--config myConfig.json` +1. `$HOME/.xds/agent/agent-config.json` file +1. `/etc/xds/agent/agent-config.json` file + +Supported fields in configuration file are (all fields are optional and example +below corresponds to the default values): + +- **httpPort** : http port of agent REST interface +- **webAppDir** : location of client webapp / dashboard (default: webapp/dist) +- **logsDir** : directory to store logs (eg. syncthing output) +- **xdsServers** : an array of xds-server object + - **xdsServers.url**: url of xds-server to connect to +- **syncthing**: a object defining syncthing settings + - **syncthing.binDir** : syncthing binaries directory (default: executable directory) + - **syncthing.home"** : syncthing home directory (usually .../syncthing-config) + - **syncthing.gui-address** : syncthing gui url (default <http://localhost:8386>) + - **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated) + +```json +{ + "httpPort": "8800", + "webAppDir": "./www", + "logsDir": "${HOME}/.xds/agent/logs", + "xdsServers": [ + { + "url": "http://localhost:8000" + } + ], + "syncthing": { + "home": "${HOME}/.xds/agent/syncthing-config", + "gui-address": "http://localhost:8386", + "gui-apikey": "1234abcezam" + } +} +``` + +>**Note:** +> +>environment variables are supported by using `${MY_VAR}` syntax. diff --git a/docs/part-2/2_xds-agent/2_start.md b/docs/part-2/2_xds-agent/2_start.md new file mode 100644 index 0000000..8ff0b1d --- /dev/null +++ b/docs/part-2/2_xds-agent/2_start.md @@ -0,0 +1,14 @@ +# Start-up + +Simply to start `xds-agent` executable + +```bash +./xds-agent & +``` + +>**Note:** +> +>If need be, you can increase log level by setting option +`--log <level>`, supported *level* are: panic, fatal, error, warn, info, debug. + +You can now use XDS dashboard and check that connection with `xds-agent` is up. diff --git a/docs/part-2/2_xds-agent/3_build.md b/docs/part-2/2_xds-agent/3_build.md new file mode 100644 index 0000000..ce1407d --- /dev/null +++ b/docs/part-2/2_xds-agent/3_build.md @@ -0,0 +1,58 @@ +# Build xds-agent from scratch + +## Dependencies + +Install [Go](https://golang.org/doc/install), [npm](https://www.npmjs.com/), +[nodejs](https://nodejs.org/en/) and some other tools. + +Refer to [Prerequisites chapter](../1_Prerequisites.html) for more details. + +## Building + +Clone this repo into your `$GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds` and use delivered Makefile: + +```bash + mkdir -p $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds + cd $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds + git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-agent + # or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-agent + cd xds-agent + make all +``` + +And to install xds-agent (by default in `/usr/local/bin`): + +```bash +make install +``` + +>**Note:** +> +>Used `DESTDIR` to specify another install directory +>```bash +>make install DESTDIR=$HOME/opt/xds-agent +>``` + +### Cross build + +For example on a Linux machine to cross-build for Windows, just follow these steps. + +The first time you need to install all the windows-amd64 standard packages on +your system with + +```bash +# List all supported OS / ARCH +go tool dist list + +# Install all standard packages for another OS/ARCH (eg. windows amd64) +GOOS=windows GOARCH=amd64 go install -v -a std +``` + +Then compile and package xds-agent using provided makefile + +```bash +export GOOS=windows +export GOARCH=amd64 +make all +make package +``` diff --git a/docs/part-2/2_xds-agent/4_debug.md b/docs/part-2/2_xds-agent/4_debug.md new file mode 100644 index 0000000..9490c4b --- /dev/null +++ b/docs/part-2/2_xds-agent/4_debug.md @@ -0,0 +1,69 @@ +# Debugging + +## XDS agent architecture + +The agent part is written in *Go* and the webapp / dashboard is in *typescript + Angular4*. + +```bash +| ++-- bin/ where xds-server binary file will be built +| ++-- conf.d Linux configuration and startup files (systemd user service) +| ++-- glide.yaml Go package dependency file +| ++-- lib/ sources of server part (Go) +| ++-- main.go main entry point of of Web server (Go) +| ++-- Makefile makefile including +| ++-- README.md this readme +| ++-- scripts/ hold various scripts used for installation or startup +| ++-- tools/ temporary directory to hold development tools (like glide) +| ++-- vendor/ temporary directory to hold Go dependencies packages +| ++-- webapp/ source client basic webapp / dashboard +``` + +## Debug + +Visual Studio Code launcher settings can be found into `.vscode/launch.json`. + +>**Tricks:** +> +>To debug both `xds-agent` and `xds-server` or common code +>`xds-common`, it may be useful use the same local sources. +> +>So you should replace `xds-server` + `xds-common` in `vendor` directory by a symlink. +> +>So clone first `xds-server` + `xds-common` sources next to `xds-agent` directory. + +You should have the following tree: + +```bash +tree -L 5 --charset=ascii src/ +src/ +`-- gerrit.automotivelinux.org + `-- gerrit + `-- src + `-- xds + |-- backup.sh + |-- xds-agent + |-- xds-cli + |-- xds-common + |-- xds-docs + |-- xds-gdb + `-- xds-server +``` + +Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor +directory : + +```bash +cd src/gerrit.automotivelinux.org/gerrit/src/xds/xds-agent +make vendor/debug +``` diff --git a/docs/part-2/3_xds-cli.md b/docs/part-2/3_xds-cli.md deleted file mode 100644 index ade25f8..0000000 --- a/docs/part-2/3_xds-cli.md +++ /dev/null @@ -1,233 +0,0 @@ -# xds-cli: command-line tool for XDS - -`xds-cli` is a command-line tool for X(cross) Development System. - -## Configuration - -`xds-cli` configuration is defined either by environment variables or by -setting command line options. - -Configuration through environment variables may also be defined in a file that -will be sourced by `xds-cli` on start-up. - -Use `--config|-c` option or set `XDS_CONFIG` environment variable to specify the config file to use. - -So configuration is driven either by environment variables or by command line -options or using a config file knowing that the following priority order is used: - -1. use option value (for example use project ID set by `--id` option), -1. else use variable `XDS_xxx` (for example `XDS_PROJECT_ID` variable) when a - config file is specified with `--config|-c` option, -1. else use `XDS_xxx` (for example `XDS_PROJECT_ID`) environment variable - -<!-- note --> -**Note:** - -All parameters after a double dash (--) are considered as the command -to execute on xds-server. -<!-- endnote --> - -### Global Options / Configuration variables - -Following is the list of global options across all sub-commands. - -__`--config|-c` option or `XDS_CONFIG` env variable__ - -Env config file to source on startup - -__`--log|-l` option or `XDS_LOGLEVEL` env variable__ - -Logging level, supported levels are: - -- panic -- fatal -- error -- warn -- info -- debug - -Default level is "error". - -**`--rpath` option or `XDS_PATH` env variable** - -Relative path into project - -**`timestamp|-ts` option or `XDS_TIMESTAMP` env variable** - -Prefix output with timestamp - -**`url` option or `XDS_AGENT_URL` env variable** - -Local XDS agent url (default: "localhost:8800") - -## Commands - -### projects - -`projects` (short `prj`) command should be used to managed XDS projects. - -This command supports following sub-commands: - -```bash -add, a Add a new project -get Get a property of a project -list, ls List existing projects -remove, rm Remove an existing project -sync Force synchronization of project sources -``` - -Here are some usage examples: - -```bash -# Create/declare a new project -xds-cli prj add --label "ABeautifulName" --type pm -p /home/seb/xds-workspace/myProject -sp /home/devel/xds-workspace/myProject - -# List projects -xds-cli prj ls - -# Delete an existing project -xds-cli prj rm 8e49 -``` - -### sdks - -`sdks` (alias `sdk`) command should be used to managed cross SDKs. - -This command supports following sub-commands: - -```bash -add, a Add a new SDK -get Get a property of a SDK -list, ls List installed SDKs -remove, rm Remove an existing SDK -``` - -Here are some usage examples: - -```bash -# List existing SDKs -xds-cli sdks ls - -# Get SDK info -xds-cli sdks get c64d -``` - -### exec - -`exec` command should be used to exec command through XDS system. - -For example you can use this command to build your project in XDS system. - -This command supports following sub-commands: - -`exec` command options are: - -**`--id` option or `XDS_PROJECT_ID` env variable (**mandatory option**)** - -project ID you want to build - -**`--rpath` (short `-p`) or `XDS_RPATH` env variable** - -relative path into project - -**`--sdkid` (alias `--sdk`) or `XDS_SDK_ID` env variable (**mandatory option**)** - -Cross Sdk ID to use to build project. - -Here are some usage examples: - -```bash -cd $MY_PROJECT_DIR -mkdir build - -# Generate build system using cmake -xds-cli exec --id=4021 --sdkid=c226 -- "cd build && cmake .." - -# Build the project -xds-cli exec --id=4021 --sdkid=c226 -- "cd build && make all" -``` - -In case of `xds-agent` is not running on default url:port (that is `localhost:8800`) - -You can specify the url using `--url` option : - -```bash -xds-cli --url=http://localhost:8800 exec --id=4021 --sdkid=c226 -- "cd build && make all" -``` - -### misc - -`misc` command allows to execute miscellaneous sub-commands such as: - -```bash -version, v Get version of XDS agent and XDS server -status, sts Get XDS configuration status (including XDS server connection) -``` - -Here are some usage examples: - -```bash -xds-cli misc version --verbose - -xds-cli misc sts -``` - -## How to build - -### Dependencies - -Install [Go](https://golang.org/doc/install) and some other tools. -Refer to [Prerequisites chapter](./0_Abstract.html#prerequisites) for more details. - -### Building - -Clone this repo into your `$GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds` and use delivered Makefile: - -```bash - export GOPATH=$(realpath ~/workspace_go) - mkdir -p $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds - cd $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds - git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-cli - # or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-cli - cd xds-cli - make -``` - -## Debug - -Visual Studio Code launcher settings can be found into `.vscode/launch.json`. - ->**Tricks:** -> ->To debug both `xds-cli` and `xds-agent` (REST API part) or common -code `xds-common`, it may be useful use the same local sources. -> ->So you should replace `xds-agent` + `xds-common` in `vendor` directory by a symlink. -> ->So clone first `xds-agent` + `xds-common` sources next to `xds-cli` directory. - -You should have the following tree: - -```bash -tree -L 5 --charset=ascii src/ -src/ -`-- gerrit.automotivelinux.org - `-- gerrit - `-- src - `-- xds - |-- backup.sh - |-- xds-agent - |-- xds-cli - |-- xds-common - |-- xds-docs - |-- xds-gdb - `-- xds-server -``` - -Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor -directory : - -```bash -cd src/gerrit.automotivelinux.org/gerrit/src/xds/xds-cli -make vendor/debug -``` diff --git a/docs/part-2/3_xds-cli/0_abstract.md b/docs/part-2/3_xds-cli/0_abstract.md new file mode 100644 index 0000000..df7db6c --- /dev/null +++ b/docs/part-2/3_xds-cli/0_abstract.md @@ -0,0 +1,15 @@ +# xds-cli: command-line tool for XDS + +`xds-cli` is a command-line tool for X(cross) Development System. + +This tool can be used in addition to `XDS Dashboard` to control XDS from command +line. + +--- + +Links to subchapters : + +- [Configuration](./1_config.html) +- [Start-up](./2_commands.html) +- [Build from scratch](./3_build.html) +- [Debugging](./4_debug.html) diff --git a/docs/part-2/3_xds-cli/1_config.md b/docs/part-2/3_xds-cli/1_config.md new file mode 100644 index 0000000..6dc7993 --- /dev/null +++ b/docs/part-2/3_xds-cli/1_config.md @@ -0,0 +1,57 @@ +# Configuration + +`xds-cli` configuration is defined either by environment variables or by +setting command line options. + +Configuration through environment variables may also be defined in a file that +will be sourced by `xds-cli` on start-up. + +Use `--config|-c` option or set `XDS_CONFIG` environment variable to specify the config file to use. + +So configuration is driven either by environment variables or by command line +options or using a config file knowing that the following priority order is used: + +1. use option value (for example use project ID set by `--id` option), +1. else use variable `XDS_xxx` (for example `XDS_PROJECT_ID` variable) when a + config file is specified with `--config|-c` option, +1. else use `XDS_xxx` (for example `XDS_PROJECT_ID`) environment variable + +<!-- note --> +**Note:** + +All parameters after a double dash (--) are considered as the command +to execute on xds-server. +<!-- endnote --> + +## Global Options / Configuration variables + +Following is the list of global options across all sub-commands. + +__`--config|-c` option or `XDS_CONFIG` env variable__ + +Env config file to source on startup + +__`--log|-l` option or `XDS_LOGLEVEL` env variable__ + +Logging level, supported levels are: + +- panic +- fatal +- error +- warn +- info +- debug + +Default level is "error". + +**`--rpath` option or `XDS_PATH` env variable** + +Relative path into project + +**`timestamp|-ts` option or `XDS_TIMESTAMP` env variable** + +Prefix output with timestamp + +**`url` option or `XDS_AGENT_URL` env variable** + +Local XDS agent url (default: "localhost:8800") diff --git a/docs/part-2/3_xds-cli/2_commands.md b/docs/part-2/3_xds-cli/2_commands.md new file mode 100644 index 0000000..b5e0c0a --- /dev/null +++ b/docs/part-2/3_xds-cli/2_commands.md @@ -0,0 +1,119 @@ +# Commands + +## projects + +`projects` (short `prj`) command should be used to managed XDS projects. + +This command supports following sub-commands: + +```bash +add, a Add a new project +get Get a property of a project +list, ls List existing projects +remove, rm Remove an existing project +sync Force synchronization of project sources +``` + +Here are some usage examples: + +```bash +# Create/declare a new project +xds-cli prj add --label "myProjectName" --type pm -p /home/seb/xds-workspace/myProject -sp /home/devel/xds-workspace/myProject + +# List projects +xds-cli prj ls + +# Delete an existing project +xds-cli prj rm 8e49 +``` + +## sdks + +`sdks` (alias `sdk`) command should be used to managed cross SDKs. + +This command supports following sub-commands: + +```bash +get Get a property of a SDK +list, ls List installed SDKs +install, i Install a SDK +uninstall, rm UnInstall an existing SDK +abort, a Abort an install action +``` + +Here are some usage examples: + +```bash +# List existing SDKs +xds-cli sdks ls + +# Get SDK info +xds-cli sdks get c64d +``` + +<!-- note --> +**Note:** + +Please also refer to [Installing AGL SDKs](../../part-1/3_install-sdks.html) chapter for more details about sdks installation. + +<!-- endnote --> + +## exec + +`exec` command should be used to exec command through XDS system. + +For example you can use this command to build your project in XDS system. + +This command supports following sub-commands: + +`exec` command options are: + +**`--id` option or `XDS_PROJECT_ID` env variable (**mandatory option**)** + +project ID you want to build + +**`--rpath` (short `-p`) or `XDS_RPATH` env variable** + +relative path into project + +**`--sdkid` (alias `--sdk`) or `XDS_SDK_ID` env variable (**mandatory option**)** + +Cross Sdk ID to use to build project. + +Here are some usage examples: + +```bash +cd $MY_PROJECT_DIR +mkdir build + +# Generate build system using cmake +xds-cli exec --id=4021 --sdkid=c226 -- "cd build && cmake .." + +# Build the project +xds-cli exec --id=4021 --sdkid=c226 -- "cd build && make all" +``` + +In case of `xds-agent` is not running on default url:port (that is `localhost:8800`) + +You can specify the url using `--url` option : + +```bash +xds-cli --url=http://localhost:8800 exec --id=4021 --sdkid=c226 -- "cd build && make all" +``` + +## misc + +`misc` command allows to execute miscellaneous sub-commands such as: + +```bash +version, v Get version of XDS agent and XDS server +status, sts Get XDS configuration status (including XDS server connection) +``` + +Here are some usage examples: + +```bash +xds-cli misc version --verbose + +xds-cli misc sts +``` diff --git a/docs/part-2/3_xds-cli/3_build.md b/docs/part-2/3_xds-cli/3_build.md new file mode 100644 index 0000000..ba2d83b --- /dev/null +++ b/docs/part-2/3_xds-cli/3_build.md @@ -0,0 +1,21 @@ +# How to build + +## Dependencies + +Install [Go](https://golang.org/doc/install) and some other tools. + +Refer to [Prerequisites chapter](../1_Prerequisites.html) for more details. + +## Building + +Clone this repo into your `$GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds` and use delivered Makefile: + +```bash + export GOPATH=$(realpath ~/workspace_go) + mkdir -p $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds + cd $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds + git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-cli + # or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-cli + cd xds-cli + make +``` diff --git a/docs/part-2/3_xds-cli/4_debug.md b/docs/part-2/3_xds-cli/4_debug.md new file mode 100644 index 0000000..38628db --- /dev/null +++ b/docs/part-2/3_xds-cli/4_debug.md @@ -0,0 +1,38 @@ +# Debug + +Visual Studio Code launcher settings can be found into `.vscode/launch.json`. + +>**Tricks:** +> +>To debug both `xds-cli` and `xds-agent` (REST API part) or common +code `xds-common`, it may be useful use the same local sources. +> +>So you should replace `xds-agent` + `xds-common` in `vendor` directory by a symlink. +> +>So clone first `xds-agent` + `xds-common` sources next to `xds-cli` directory. + +You should have the following tree: + +```bash +tree -L 5 --charset=ascii src/ +src/ +`-- gerrit.automotivelinux.org + `-- gerrit + `-- src + `-- xds + |-- backup.sh + |-- xds-agent + |-- xds-cli + |-- xds-common + |-- xds-docs + |-- xds-gdb + `-- xds-server +``` + +Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor +directory : + +```bash +cd src/gerrit.automotivelinux.org/gerrit/src/xds/xds-cli +make vendor/debug +``` diff --git a/docs/part-2/4_xds-gdb/0_abstract.md b/docs/part-2/4_xds-gdb/0_abstract.md new file mode 100644 index 0000000..d282efa --- /dev/null +++ b/docs/part-2/4_xds-gdb/0_abstract.md @@ -0,0 +1,24 @@ +# xds-gdb: wrapper on gdb for XDS + +`xds-gdb` is a wrapper on gdb debugger for X(cross) Development System. + +This tool allows you to debug an application built with an xds-server without +the need to install gdb or any cross tool. + +Two debugging models are supported: + +1. native debugging + +1. XDS remote debugging requiring an XDS agent/server setup. That allows you to + easily cross debug your application. + + By default XDS debug model is used and you need to define `XDS_NATIVE_GDB` +variable to use native gdb debug mode instead. + +--- + +Links to subchapters : + +- [Configuration](./1_config.html) +- [Build from scratch](./2_build.html) +- [Debugging](./3_debug.html) diff --git a/docs/part-2/4_xds-gdb.md b/docs/part-2/4_xds-gdb/1_config.md index 96f5498..8568f18 100644 --- a/docs/part-2/4_xds-gdb.md +++ b/docs/part-2/4_xds-gdb/1_config.md @@ -1,26 +1,4 @@ -# xds-gdb: wrapper on gdb for XDS - -`xds-gdb` is a wrapper on gdb debugger for X(cross) Development System. - -This tool allows you to debug an application built with an xds-server without -the need to install gdb or any cross tool. - -Two debugging models are supported: - -1. native debugging - -1. XDS remote debugging requiring an XDS agent/server setup. That allows you to easily cross debug your application. - - By default XDS debug model is used and you need to define `XDS_NATIVE_GDB` -variable to use native gdb debug mode instead. - -> **SEE ALSO**: [xds-agent](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-agent.git), a local agent -used to interface xds-server. -> **SEE ALSO**: [xds-server](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-server.git), a REST API server -used to remotely cross build applications. -> **SEE ALSO**: [xds-cli](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-cli.git), XDS command line tool. - -## Configuration +# Configuration `xds-gdb` configuration is defined by variables (see listed below). @@ -36,7 +14,7 @@ These variables may be set using: 1. $(CURRENT_DIRECTORY)/target/xds-gdb.env 1. $(HOME)/.config/xds/xds-gdb.env -### Configuration Variables +## Configuration Variables `XDS_CONFIG` @@ -93,7 +71,7 @@ Cross Sdk ID to use to build project Local XDS agent url (default `http://localhost:8800`) -### Configuration variables set within gdb init command file +## Configuration variables set within gdb init command file Above `XDS_xxx` variables may also be defined within gdb init command file (see --command or -x option of genuine Gdb). @@ -106,28 +84,3 @@ Example of gdb init file where we define project and sdk ID: # :XDS-ENV: XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b # :XDS-ENV: XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03 ``` - -## How to build xds-gdb from scratch - -### Dependencies - -Install [Go](https://golang.org/doc/install) and some other tools. -Refer to [Prerequisites chapter](./0_Abstract.html#prerequisites) for more details. - -### Building - -Clone this repo into your `$GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds` and use delivered Makefile: - -```bash - export GOPATH=$(realpath ~/workspace_go) - mkdir -p $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds - cd $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds - git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-gdb - # or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-gdb - cd xds-gdb - make -``` - -## Debug - -Visual Studio Code launcher settings can be found into `.vscode/launch.json`. diff --git a/docs/part-2/4_xds-gdb/2_build.md b/docs/part-2/4_xds-gdb/2_build.md new file mode 100644 index 0000000..5cc0ca8 --- /dev/null +++ b/docs/part-2/4_xds-gdb/2_build.md @@ -0,0 +1,21 @@ +# How to build xds-gdb from scratch + +## Dependencies + +Install [Go](https://golang.org/doc/install) and some other tools. + +Refer to [Prerequisites chapter](../1_Prerequisites.html) for more details. + +## Building + +Clone this repo into your `$GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds` and use delivered Makefile: + +```bash + export GOPATH=$(realpath ~/workspace_go) + mkdir -p $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds + cd $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds + git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-gdb + # or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-gdb + cd xds-gdb + make +``` diff --git a/docs/part-2/4_xds-gdb/3_debug.md b/docs/part-2/4_xds-gdb/3_debug.md new file mode 100644 index 0000000..80554ec --- /dev/null +++ b/docs/part-2/4_xds-gdb/3_debug.md @@ -0,0 +1,3 @@ +# Debug + +Visual Studio Code launcher settings can be found into `.vscode/launch.json`. diff --git a/docs/part-2/5_xds-exec.md b/docs/part-2/5_xds-exec.md deleted file mode 100644 index 4a36f87..0000000 --- a/docs/part-2/5_xds-exec.md +++ /dev/null @@ -1,5 +0,0 @@ -# xds-exec: wrapper on exec for XDS - -`xds-exec` is now deprecated and has been replaced `exec` command of `xds-cli`. - -Please refer to [xds-cli documentation](3_xds-cli.html) for more details. |