diff options
Diffstat (limited to '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')
5 files changed, 348 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.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). |