diff options
Diffstat (limited to 'docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals ')
38 files changed, 1406 insertions, 0 deletions
diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.0_Abstract/3.4.4.0_Abstract.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.0_Abstract/3.4.4.0_Abstract.md new file mode 100644 index 0000000..b0c50a9 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.0_Abstract/3.4.4.0_Abstract.md @@ -0,0 +1,8 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# XDS internals (advanced documentation) + +## Abstract + +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. diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.1_Prerequisites/3.4.4.1_Prerequisites.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.1_Prerequisites/3.4.4.1_Prerequisites.md new file mode 100644 index 0000000..f505a39 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.1_Prerequisites/3.4.4.1_Prerequisites.md @@ -0,0 +1,63 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# Prerequisites + +XDS is written in Go and currently only build on Linux host has been validated. + +So 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` and `python3` tools. + +**Ubuntu:** + +```bash +# Install various tools +sudo apt-get install git make npm curl git zip unzip wget + +# 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 python3 +sudo apt-get install python3 +``` + +**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 python3 +sudo zypper install python3 +``` + +> Don't forget to open new user session after installing these packages. + +**All Linux distro:** + +```bash +# Install nodejs LTS version (only mandatory for xds-server and xds-agent) +sudo npm install --global n +sudo n lts +``` + +Angular developers that's plan to modify XDS Dashboard webapp (part of +`xds-agent` repo) may also need angular cli tool named `ng` : + +```bash +# Install angular cli tool (ng) +sudo npm install --global n @angular/cli +``` diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.0_ Abstract.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.0_ Abstract.md new file mode 100644 index 0000000..ab6c8c4 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.0_ Abstract.md @@ -0,0 +1,44 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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 : + +- [Build from scratch](./1_build.html) +- [Configuration](./2_config.html) +- [How to run](./3_how-to-run.html) +- [Debugging](./4_debug.html) +- [Tests](./5_test.html) diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.1_Build.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.1_Build.md new file mode 100644 index 0000000..11c18b3 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.1_Build.md @@ -0,0 +1,84 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --># 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 + +Clone sources under `$ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds/xds-server` +in order respect directory hierarchy that match Go package import logic (see +[How to Write Go Code](https://golang.org/doc/code.html) for more details). + +Then use delivered Makefile : + +```bash +# Declare ROOTDIR, can be any location (for example xds-build) +ROOTDIR=$HOME/xds-build + +# Create directory hierarchy that match Go package import logic +mkdir -p $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds +cd $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds + +# Clone sources +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 + +# Build xds-server +# (note that GOPATH will correctly be set by Makefile) +cd xds-server +make all +``` + +Generate xds-server package / tarball + +```bash +make package-all +``` + +And to install `xds-server` (by default in `/opt/AGL/xds/server`): + +```bash +make install +``` + +<!-- section-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. +<!-- end-section-warning --> + +<!-- section-note --> +**Note:** + +Used `DESTDIR` to specify another install directory + +```bash +make install DESTDIR=$HOME/opt/xds-server +``` + +<!-- end-section-note --> + +### 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/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.2_Config.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.2_Config.md new file mode 100644 index 0000000..ba97d1f --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.2_Config.md @@ -0,0 +1,91 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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 +- **sdkDbUpdate** : define how SDK database(s) is(are) updated, supported values are: + `disable`, `startup` (default: `startup`) +- **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", + "sdkDbUpdate": "startup", + "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`. + +<!-- section-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` +<!-- end-section-note --> + +## 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. + +<!-- section-note --> +**Note:** + +- `CloudSync` (AKA syncthing) synchronization type can also be disabled when `"syncthing"` key is not defined in JSON configuration file. + +<!-- end-section-note --> diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.3_how-to-run.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.3_how-to-run.md new file mode 100644 index 0000000..38bfbc3 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.3_how-to-run.md @@ -0,0 +1,199 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> +# 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 +been integrated into AGL SDK docker container. + +>**Note:** For more info about AGL SDK docker container, please refer to +[AGL SDK Quick Setup](../../../../../getting_started/reference/getting-started/docker-container-setup.html) + +## Start xds-server + +There are several way to install xds-server and start-up depend of installation type: + +| Installation type | Supported<br> host OS | Start-up | Install instructions | +|-------------------|-------------------------|---------------------------------------------------|----------------------| +| Docker container | Linux or MacOS | Automatic based on systemd user service | [see Installation based on Docker container](../../part-1/server-part.html#docker-container) | +| Virtual Machine | Linux, MacOS or Windows | Automatic based on systemd user service | [see Installation based on VirtualBox appliance](../../part-1/server-part.html#virtualbox-appliance) | +| Native | Linux | Automatic based on systemd user service or manual | [see Native installation](../../part-1/server-part.html#native) | +| Native | MacOS or Windows | Manually | [see Native installation](../../part-1/server-part.html#native) | + +### Automatic start-up based on systemd user service + +XDS server is started as a user service by Systemd. + +```bash +/usr/lib/systemd/user/xds-server.service +``` + +Use well-known systemd commands to control `xds-server.service` service. + +```bash +# Enter in docker container or VM +# (optional, depending on installation type) +ssh -p 2222 devel@localhost + +# Status XDS server: +systemctl --user status xds-server + +# Restart XDS server +systemctl --user restart xds-server +``` + +If needed you can change default setting by defining specific environment +variables file + +```bash +ssh -t -p 2222 devel@localhost vim /etc/default/xds-server +``` + +For example to control log level, just set LOG_LEVEL env variable. + +knowing that supported *level* are: + +- panic +- fatal +- error +- warn +- info +- debug + +```bash +docker exec ${CONTAINER_NAME} bash -c "echo 'LOG_LEVEL=debug' >> /etc/default/xds-server" +ssh -p 2222 devel@localhost -- "systemctl --user restart xds-server" +``` + +### Manual start-up + +On **Linux or MacOS**, simply execute `xds-server` executable: + +```bash +/opt/AGL/bin/xds-server +``` + +On **Windows**, simply execute `xds-server` executable: + +```batch +C:\AGL\bin\xds-server.exe +``` + +<!-- section-note --> +**Note:** + +Invoke `xds-server --help` to get more details about possible options that allow +for example to change logging level or select another configuration file. + +<!-- end-section-note --> + +## XDS server REST API and Web application + +`xds-server` exposes a REST API and serves a basic web-application. + +REST API based url is `http://localhost:8000/api/v1/` when XDS server is +running on your host (localhost) and basic web-application is available at +`http://localhost:8000`. + +Just replace `localhost` by the host name or ip when `xds-server` is running +on another host. + +```bash +# Get version using REST API +curl http://localhost:8000/api/v1/version + +# Open browser and local xds-server web-application +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/0_abstract.html) for more details. + +## SDK cross-toolchain Management + +### Setup to add support of a new SDK family + +<!-- section-note --> +**Optional step**: read this chapter only if you plan to add a new SDK family. +<!-- end-section-note --> + +`xds-server` dynamically detects supported SDKs by scanning sub-directories of +`sdkScriptsDir` directory (see [Configuration chapter](2_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 +of a specific family. + +These scripts are: + +- `add`: used to add/install a new SDK +- `db-dump`: returned the list of available and installed SDKs (JSON format) +- `db-update`: update SDKs database +- `get-family-config`: returned SDK family configuration structure (JSON format) +- `get-sdk-info`: extract SDK info (JSON format) from a SDK file/tarball +- `remove`: used to remove an existing SDK + +For example, here 2 SDKs family (`agl` and `zephyr`) are defined: + +```bash +# > tree ./sdks/ +./sdks/ +├── agl +│ ├── add +│ ├── db-dump +│ ├── db-update +│ ├── get-family-config +│ ├── get-sdk-info +│ └── remove +├── README.md +└── zephyr + ├── add + ├── db-dump + ├── db-update + ├── get-family-config + ├── get-sdk-info + └── remove +``` + +On startup `xds-server` will call in order: + +- `sdks/*/get-family-config` to get configuration of each SDK family. +- `sdks/*/db-update` to update database (only when `SdkDbUpdate` is set to ̀`startup`, + see [Configuration chapter](2_config.html) for more details) +- `sdks/*/db-dump` scripts to get the initial list of available and installed SDKs. + +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 + +Please refer to [Installing AGL SDKs](../../part-1/install-sdk.html) chapter. + +### Un-install a SDK from command line + +Used `sdks` command of `xds-cli` tool to managed SDKs. + +```bash +# List installed SDKs +xds-cli sdks ls +List of installed SDKs: + ID NAME STATUS VERSION ARCH + c39e5998 poky-agl_aarch64_4.0.1 Installed 4.0.1 aarch64 + d610bfbf poky-agl-aarch64.current_on_iotbzh_download-3.99.1+snapshot Installed 3.99.1+snapshot aarch64.current_on_iotbzh_download + a0ae663d poky-agl-corei7-64-3.99.1+snapshot Installed 3.99.1+snapshot corei7-64 + 87f0400b AGL-release-dab-3.99.3-m3ulcb-nogfx Installed 3.99.3 aarch64 + 352c0584 poky-agl-corei7-64-3.99.2+snapshot Installed 3.99.2+snapshot corei7-64 + d65fe750 AGL-release-eel-latest-qemux86-64 Installed 4.99.5 corei7-64 + +# Un-install a SDK +xds-cli sdks uninstall d65fe750 +SDK ID d65fe750-d3a7-38f5-83d8-3d3806054f8d successfully deleted. +``` + +### 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. diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.4_Debug.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.4_Debug.md new file mode 100644 index 0000000..ceb3e5b --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.4_Debug.md @@ -0,0 +1,47 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> +# 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 # readme +| ++-- 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 +``` + +## Debug server part (Go code) + +Install first [Visual Studio Code](https://code.visualstudio.com/) and +[Go plugin](https://marketplace.visualstudio.com/items?itemName=lukehoban.Go) +(`ext install lukehoban.Go`) + +Visual Studio Code launcher settings can be found into `.vscode/launch.json`. + +Please follow instructions of xds-agent [debugging chapter](../2_xds-agent/4_debug.html#debug-xds-agent-go-code), +knowing that you execute these same instructions in `xds-server` repo, in other words +by replacing *xds-agent* references by *xds-server*. diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.5_Test.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.5_Test.md new file mode 100644 index 0000000..2376d43 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.5_Test.md @@ -0,0 +1,43 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> +# XDS Server Test + +## XDS Server test architecture + +The test part is written in go and source code is available in test directory. + +```bash +| ++-- test/ # where xds-server test source files +| ++-- test/main_test.go # main entry point of xds-server test +| ++-- test/fixtures # fixtures for running test +``` + +The test execution will locally launch xds-server and access the api through REST and test results, events, ... + +## Dependencies + +* sshd + +Make sure sshd is in your user PATH. + +## Launch test + +Use the following command to launch test in xds-server root directory: + +```bash +make test +``` + +Launch only one test, for example launch TestSdks: + +```bash +make test name=TestSdks +``` + +Increase test verbosity: + +```bash +make test VERBOSE=1 +``` diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.0_Abstract.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.0_Abstract.md new file mode 100644 index 0000000..21126ec --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.0_Abstract.md @@ -0,0 +1,21 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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 : + +- [Build from scratch](./1_build.html) +- [Configuration](./2_config.html) +- [Start-up](./3_start.html) +- [Debugging](./4_debug.html) diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.1_Build.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.1_Build.md new file mode 100644 index 0000000..6447244 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.1_Build.md @@ -0,0 +1,92 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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 sources under `$ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds/xds-agent` +in order respect directory hierarchy that match Go package import logic (see +[How to Write Go Code](https://golang.org/doc/code.html) for more details). + +Then use delivered Makefile : + +```bash +# Declare ROOTDIR, can be any location (for example xds-build) +ROOTDIR=$HOME/xds-build + +# Create directory hierarchy that match Go package import logic +mkdir -p $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds +cd $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds + +# Clone sources +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 + +# Build xds-agent +# (note that GOPATH will correctly be set by Makefile) +cd xds-agent +make all +``` + +Generate xds-agent packages / tarballs for Linux, MacOS, Windows + +```bash +make package-all +``` + +And to install `xds-agent` (by default in `/opt/AGL/xds/agent`): + +```bash +make install +``` + +<!-- section-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-agent natively. +<!-- end-section-warning --> + +<!-- section-note --> +**Note:** + +Used `DESTDIR` to specify another install directory + +```bash +make install DESTDIR=$HOME/opt/xds-agent +``` + +<!-- end-section-note --> + +### 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/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.2_Config.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.2_Config.md new file mode 100644 index 0000000..2eac51a --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.2_Config.md @@ -0,0 +1,49 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.3_Start_Up.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.3_Start_Up.md new file mode 100644 index 0000000..5c83875 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.3_Start_Up.md @@ -0,0 +1,54 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# Start-up + +## Start-up based on systemd user service + +For **Linux** distro, XDS agent can be started as a user service by Systemd. + +```bash +/usr/lib/systemd/user/xds-agent.service +``` + +Use well-known systemd commands to control `xds-agent.service` service. + +```bash +# Status XDS agent: +systemctl --user status xds-agent + +# Start XDS agent +systemctl --user start xds-agent + +# Stop XDS agent +systemctl --user stop xds-agent +``` + +Default settings are defined in `/etc/default/xds-agent` file but these +settings you can overwritten by `$HOME/.xds/agent/agent-config.json` file, +see [Configuration chapter](./2_config.html) for more details. + +## Manual start-up + +On **Linux or MacOS**, simply execute `xds-agent` executable: + +```bash +/opt/AGL/bin/xds-agent +``` + +On **Windows**, simply execute `xds-agent` executable (root path may change +depending where you installed/unzipped xds-agent tarball): + +```batch +C:\AGL\bin\xds-agent.exe +``` + +<!-- section-note --> +**Note:** + +If need be, you can increase log level by setting option +`--log <level>`, supported *level* are: panic, fatal, error, warn, info, debug. + +Invoke `xds-agent --help` to get more details about possible options that allow +for example to change logging level or select a specific configuration file. + +<!-- end-section-note --> diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.4_Debug.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.4_Debug.md new file mode 100644 index 0000000..7842741 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.3_xds-agent/3.4.4.3.4_Debug.md @@ -0,0 +1,132 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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 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 xds-agent (Go code) + +Install first [Visual Studio Code](https://code.visualstudio.com/) and +[Go plugin](https://marketplace.visualstudio.com/items?itemName=lukehoban.Go) +(`ext install lukehoban.Go`) + +Visual Studio Code launcher settings can be found into `.vscode/launch.json`. +The important think is to correctly set `GOPATH` in launch.json in order to +build xds-agent and debug it within Visual Studio Code. + +Here is an example of launch.json: + +```json +{ + "version": "0.2.0", + "configurations": [{ + "name": "XDS-Agent", + "type": "go", + "request": "launch", + "mode": "debug", + "remotePath": "", + "port": 2345, + "host": "127.0.0.1", + "program": "${workspaceRoot}", + "env": { + "GOPATH": "${workspaceRoot}/../../../../../..:${env:GOPATH}", + }, + "args": ["-log", "debug", "-c", "__agent-config_local_dev.json"], + "showLog": false + } + ] +} +``` + +And `__agent-config_local_dev.json` file content is as follow : + +```json +{ + "webAppDir": "./webapp/dist", + "logsDir": "${HOME}/tmp/xds-agent/logs", + "xdsServers": [ + { + "url": "http://localhost:8000" + } + ], + "syncthing": { + "binDir": "./bin", + "home": "${HOME}/tmp/xds_local_dev/syncthing-config", + "gui-address": "http://localhost:8386", + } +} +``` + +### Tricks to debug both xds-agent and xds-server + +To debug both `xds-agent` and `xds-server` or common code `xds-common`, it may +be useful use the same local sources. + +A trick to do that is to replace `xds-server` + `xds-common` in `vendor` +directory by a symlink that points to local sources. + +So clone first `xds-server` + `xds-common` sources next to `xds-agent` directory. + +You should have the following tree: + +```bash +tree -L 5 src/ +src/ +`-- gerrit.automotivelinux.org + `-- gerrit + `-- src + `-- xds + |-- xds-agent + |-- xds-common + `-- xds-server +``` + +Then invoke `vendor/debug` Makefile rule to create symbolic links inside vendor +directory : + +```bash +cd src/gerrit.automotivelinux.org/gerrit/src/xds/xds-agent +make vendor/debug +``` + +## Debug dashboard part (Typescript / angular code) + +Start `xds-agent` either from command line or in debug mode (see previous +chapter) and in another terminal start a watcher daemon so that type typescript +sources of webapp / dashboard are automatically "transpiled" using following +command : + +```bash +cd webapp +npm run watch +``` + +Then open the XDS Dashboard page ([http://localhost:8800](http://localhost:8800)) +and open the developer tool of web browser (for example `Ctrl+Shift+I` in Chrome). diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.0_Abstract.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.0_Abstract.md new file mode 100644 index 0000000..dad78f8 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.0_Abstract.md @@ -0,0 +1,17 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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 : + +- [Build from scratch](./1_build.html) +- [Configuration](./2_config.html) +- [Start-up](./3_commands.html) +- [Debugging](./4_debug.html) diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.1_Build.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.1_Build.md new file mode 100644 index 0000000..3935054 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.1_Build.md @@ -0,0 +1,41 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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 sources under `$ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds/xds-cli` +in order respect directory hierarchy that match Go package import logic (see +[How to Write Go Code](https://golang.org/doc/code.html) for more details). + +Then use delivered Makefile : + +```bash +# Declare ROOTDIR, can be any location (for example xds-build) +ROOTDIR=$HOME/xds-build + +# Create directory hierarchy that match Go package import logic +mkdir -p $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds +cd $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds + +# Clone sources +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 + +# Build xds-cli +# (note that GOPATH will correctly be set by Makefile) +cd xds-cli +make all +``` + +Generate xds-cli package / tarball + +```bash +make package-all +``` diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.2_Config.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.2_Config.md new file mode 100644 index 0000000..4696d24 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.2_Config.md @@ -0,0 +1,59 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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 + +<!-- section-note --> +**Note:** + +All parameters after a double dash (--) are considered as the command +to execute on xds-server. +<!-- end-section-note --> + +## 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/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.3_Commands.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.3_Commands.md new file mode 100644 index 0000000..4feb8a2 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.3_Commands.md @@ -0,0 +1,123 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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 +``` + +<!-- section-note --> +**Note:** + +Refer to the +"[AGL SDKs](../../part-1/install-sdk.html)" +topic for details about SDK installation. + +<!-- end-section-note --> + +## 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/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.4_Debug.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.4_Debug.md new file mode 100644 index 0000000..311efaf --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.4_xds-cli/3.4.4.4.4_Debug.md @@ -0,0 +1,42 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# Debugging + +## XDS cli architecture + +This tool is written in *Go*. + +```bash +| ++-- bin/ # where xds-cli binary will be built +| ++-- cmd-XXX.go # GO sources of each sub-commands +| ++-- conf.d/ # Linux configuration and startup files (systemd user service) +| ++-- glide.yaml # Go package dependency file +| ++-- LICENSE # XDS cli license +| ++-- main.go # main entry point (Go) +| ++-- Makefile # makefile including +| ++-- README.md # readme +| ++-- scripts/ # hold various scripts used for installation +| ++-- vendor/ # temporary directory to hold Go dependencies packages +``` + +## Debug + +Install first [Visual Studio Code](https://code.visualstudio.com/) and +[Go plugin](https://marketplace.visualstudio.com/items?itemName=lukehoban.Go) +(`ext install lukehoban.Go`) + +Visual Studio Code launcher settings can be found into `.vscode/launch.json`. + +Please follow instructions of xds-agent [debugging chapter](../2_xds-agent/4_debug.html#debug-xds-agent-go-code), +knowing that you execute these same instructions in `xds-cli` repo, in other words +by replacing *xds-agent* references by *xds-cli*. diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.0_Abstract.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.0_Abstract.md new file mode 100644 index 0000000..6f8aa16 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.0_Abstract.md @@ -0,0 +1,26 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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 : + +- [Build from scratch](./1_build.html) +- [Configuration](./2_config.html) +- [Debugging](./3_debug.html) diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.1_Build.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.1_Build.md new file mode 100644 index 0000000..4ea9a9e --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.1_Build.md @@ -0,0 +1,41 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# 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 sources under `$ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds/xds-gdb` +in order respect directory hierarchy that match Go package import logic (see +[How to Write Go Code](https://golang.org/doc/code.html) for more details). + +Then use delivered Makefile : + +```bash +# Declare ROOTDIR, can be any location (for example xds-build) +ROOTDIR=$HOME/xds-build + +# Create directory hierarchy that match Go package import logic +mkdir -p $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds +cd $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds + +# Clone sources +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 + +# Build xds-gdb +# (note that GOPATH will correctly be set by Makefile) +cd xds-gdb +make all +``` + +Generate xds-gdb package / tarball + +```bash +make package-all +``` diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.2_Config.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.2_Config.md new file mode 100644 index 0000000..6108c7b --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.2_Config.md @@ -0,0 +1,88 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# Configuration + +`xds-gdb` configuration is defined by variables (see listed below). + +These variables may be set using: + +- environment variables (inherited), +- or a config file set with `XDS_CONFIG` environment variable, for example: + `XDS_CONFIG=/tmp/my_xds_gdb_config.env xds-gdb` +- or by setting variables within a gdb ini file (see details below), +- or a "user" config file located in following directory (first found is taken): + 1. $(CURRENT_DIRECTORY)/.xds-gdb.env + 1. $(CURRENT_DIRECTORY)/../xds-gdb.env + 1. $(CURRENT_DIRECTORY)/target/xds-gdb.env + 1. $(HOME)/.config/xds/xds-gdb.env + +## Configuration Variables + +`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 config file: + +```bash +cat $HOME/myProject/xds-gdb.env + +export XDS_AGENT_URL=http://localhost:8800 +export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b +export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03 +``` + +`XDS_LOGLEVEL` + +Set logging level + +Supported levels: + +- panic +- fatal +- error +- warn +- info +- debug + +`XDS_LOGFILE` + +Set logging file, default `/tmp/xds-gdb.log`. + +`XDS_NATIVE_GDB` + +Use native gdb mode instead of XDS mode. + +`XDS_PROJECT_ID` *(mandatory in XDS mode)* + +Project ID you want to build + +`XDS_RPATH` + +Relative path into project + +`XDS_SDK_ID` *(mandatory in XDS mode)* + +Cross Sdk ID to use to build project + +`XDS_AGENT_URL` + +Local XDS agent url (default `http://localhost:8800`) + +## 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). + +You must respect the following syntax: commented line including `:XDS-ENV:` tag + +Example of gdb init file where we define project and sdk ID: + +```bash + # :XDS-ENV: XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b + # :XDS-ENV: XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03 +``` diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.3_Debug.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.3_Debug.md new file mode 100644 index 0000000..e1f33dd --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.5_xds-gdb/3.4.4.5.3_Debug.md @@ -0,0 +1,42 @@ +<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml --> + +# Debugging + +## XDS gdb architecture + +This tool is written in *Go*. + +```bash +| ++-- bin/ # where xds-gdb binary will be built +| ++-- gdb-XXX.go # xds-gdb Go sources +| ++-- conf.d/ # Linux configuration and startup files (systemd user service) +| ++-- glide.yaml # Go package dependency file +| ++-- LICENSE # XDS gdb license +| ++-- main.go # main entry point (Go) +| ++-- Makefile # makefile including +| ++-- README.md # readme +| ++-- scripts/ # hold various scripts used for installation +| ++-- vendor/ # temporary directory to hold Go dependencies packages +``` + +## Debug + +Install first [Visual Studio Code](https://code.visualstudio.com/) and +[Go plugin](https://marketplace.visualstudio.com/items?itemName=lukehoban.Go) +(`ext install lukehoban.Go`) + +Visual Studio Code launcher settings can be found into `.vscode/launch.json`. + +Please follow instructions of xds-agent [debugging chapter](../2_xds-agent/4_debug.html#debug-xds-agent-go-code), +knowing that you execute these same instructions in `xds-gdb` repo, in other words +by replacing *xds-agent* references by *xds-gdb*. diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/create-app-workflow.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/create-app-workflow.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/create-app-workflow.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-1.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-1.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-1.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-2.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-2.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-2.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-3.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-3.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-3.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-4.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-4.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-4.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-5.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-5.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_new-project-5.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_newtool.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_newtool.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_newtool.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_project_debug-1.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_project_debug-1.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_project_debug-1.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_xds_options.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_xds_options.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/nb_xds_options.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-conf.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-conf.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-conf.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-icon-2.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-icon-2.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-icon-2.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-icon-3.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-icon-3.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-icon-3.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-prj-1.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-prj-1.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-prj-1.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-prj-2.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-prj-2.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-prj-2.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-sdks-install.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-sdks-install.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-sdks-install.png diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-sdks-mgt.png b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-sdks-mgt.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /pictures/xds-dashboard-sdks-mgt.png |