gerrit.automotivelinux Code Review - AGL/documentation.git/blob

   1 # Client Part
   2
   3 The client part of the X(cross) Development System (XDS) is
   4 a set of XDS client tools that must run on your development host.
   5
   6 The tools that comprise the client part are: `xds-agent`, `xds-cli`, and `xds-gdb`.
   7 Of the three, only `xds-agent`, whose source code can be found
   8 [here](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-agent.git)
   9 in Gerrit is required.
  10
  11 <!-- section-note -->
  12 **NOTE:**
  13
  14 The binary version is also available as standard Linux packages
  15 or as a portable Windows archive (i.e. Zip).
  16 <!-- end-section-note -->
  17
  18 You should establish the following chain:
  19
  20 - XDS Client: (i.e. `xds-cli` or XDS Dashboard).
  21 - XDS Agent: (`xds-agent`) running on your development host.
  22 - XDS Server:  (`xds-server`) running on a remote server and/or in a container.
  23
  24 HTTP and Websocket protocols establish exchanges between these three tools.
  25
  26 You can change the default URL/port shown in the following illustration by using
  27 configuration files.
  28
  29 ![XDS blocks chain](./pictures/xds-block-chain.png)
  30
  31 <!-- section-note -->
  32 **NOTE:**
  33 Installation of the XDS client tools `xds-cli` and `xds-gdb` is
  34 optional:
  35
  36 - [xds-cli](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-cli.git) : command line tool to used to interact with XDS (also used by IDE integration).
  37 - [xds-gdb](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-gdb.git) : requested for debugging application.
  38 <!-- end-section-note -->
  39
  40 ## Install Packages for Debian
  41
  42 Use the following commands to install packages for the client part
  43 on Debian-based systems:
  44
  45 ```bash
  46 # Set DISTRO (e.g. xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04, xUbuntu_18.04, Debian_8.0, Debian_9.0)
  47 export DISTRO="xUbuntu_18.04"
  48
  49 # Set AGL_RELEASE (AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master)
  50 export AGL_RELEASE="AGL_Master"
  51
  52 wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/Release.key | sudo apt-key add -
  53 sudo bash -c "cat >> /etc/apt/sources.list.d/AGL.list <<EOF
  54 deb http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/ ./
  55 EOF"
  56
  57 sudo apt-get update
  58 sudo apt-get install agl-xds-agent
  59 sudo apt-get install agl-xds-cli
  60 sudo apt-get install agl-xds-gdb
  61 ```
  62
  63 ## Install Packages for OpenSUSE
  64
  65 Use the following commands to install packages for the client part
  66 on OpenSUSE-based systems:
  67
  68 ```bash
  69 # Set DISTRO (openSUSE_Leap_42.3, openSUSE_Leap_15.0, openSUSE_Tumbleweed)
  70 export DISTRO="openSUSE_Leap_15.0"
  71
  72 # Set AGL_RELEASE (AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master)
  73 export AGL_RELEASE="AGL_Master"
  74
  75 sudo zypper ar http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/isv:LinuxAutomotive:${AGL_RELEASE}.repo
  76
  77 sudo zypper ref
  78 sudo zypper install agl-xds-agent
  79 sudo zypper install agl-xds-cli
  80 sudo zypper install agl-xds-gdb
  81 ```
  82
  83 ## Install Packages for Other Platforms (e.g. Windows / MacOS)
  84
  85 - Follow these steps to install `xds-agent`:
  86
  87   1. Download the latest released tarball from the GitHub [Releases Page](https://github.com/iotbzh/xds-agent/releases).
  88
  89   1. Unzip the tarball anywhere into your local drive (e.g. `/opt/AGL/xds` or `C:\AGL\xds`).
  90
  91   1. Add binary to PATH:
  92
  93       - MacOs: create the .bash_profile `nano .bash_profile` and add `export PATH="/opt/AGL/xds/xds-agent:$PATH`
  94       - Windows: change the system path using the control panel or system settings.
  95         Alternatively, you can `setx path "C:\AGK\xds\xds-agent;%path%"`
  96
  97 - If you want to install optional tools, repeat the previous steps for each tool:
  98   - `xds-cli`, which is used for command-line and IDE integration.
  99   Downloaded from the ([released tarball link](https://github.com/iotbzh/xds-cli/releases)).
 100   - `xds-gdb`, used for debugging applications.
 101   Downloaded from the ([released tarball link](https://github.com/iotbzh/xds-gdb/releases)).
 102
 103 ## Start xds-agent
 104
 105 As noted earlier, the `xds-agent` client tool must run on your local
 106 development host when you use XDS.
 107 Depending on your development host, use the following commands:
 108
 109 - For a Linux-based development host, a user systemd service is provided
 110   (i.e. `xds-agent.service`).
 111
 112   To start this service automatically when your host boots, enable
 113   the service using the following command:
 114
 115   ```bash
 116   # Enable xds-agent service at boot
 117   systemctl --user enable xds-agent.service
 118   ```
 119
 120   To start the XDS-agent service and display its log, use these
 121   commands:
 122
 123   ```bash
 124   # Manually start xds-agent service
 125   systemctl --user start xds-agent.service
 126
 127   # Get status and log of xds-agent service
 128   systemctl --user status xds-agent.service
 129   ```
 130
 131 - For a MacOS-based host, use the following command to
 132   manually start `xds-agent`:
 133
 134   ```batch
 135   /opt/AGL/bin/xds-agent
 136   ```
 137
 138 - For a Windows-based host, use the following command to
 139   manually start `xds-agent`:
 140
 141   ```batch
 142   C:\AGL\xds\xds-agent\xds-agent.exe
 143   ```