summaryrefslogtreecommitdiffstats
path: root/docs/part-1/client-part.md
blob: b92cc0cc11b9fc5c211aff2b42c8f436fc5a15e2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
# Client Part

The client part of the X(cross) Development System (XDS) is
a set of XDS client tools that must run on your development host.

The tools that comprise the client part are: `xds-agent`, `xds-cli`, and `xds-gdb`.
Of the three, only `xds-agent`, whose source code can be found
[here](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-agent.git)
in Gerrit is required.

<!-- section-note -->
**NOTE:**

The binary version is also available as standard Linux packages
or as a portable Windows archive (i.e. Zip).
<!-- end-section-note -->

You should establish the following chain:

- XDS Client: (i.e. `xds-cli` or XDS Dashboard).
- XDS Agent: (`xds-agent`) running on your development host.
- XDS Server:  (`xds-server`) running on a remote server and/or in a container.

HTTP and Websocket protocols establish exchanges between these three tools.

You can change the default URL/port shown in the following illustration by using
configuration files.

![XDS blocks chain](./pictures/xds-block-chain.png)

<!-- section-note -->
**NOTE:**
Installation of the XDS client tools `xds-cli` and `xds-gdb` is
optional:

- [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).
- [xds-gdb](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-gdb.git) : requested for debugging application.
<!-- end-section-note -->

## Install Packages for Debian

Use the following commands to install packages for the client part
on Debian-based systems:

```bash
# Set DISTRO (e.g. xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04, xUbuntu_18.04, Debian_8.0, Debian_9.0)
export DISTRO="xUbuntu_18.04"

# Set AGL_RELEASE (AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master)
export AGL_RELEASE="AGL_Master"

wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/Release.key | sudo apt-key add -
sudo bash -c "cat >> /etc/apt/sources.list.d/AGL.list <<EOF
deb http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/ ./
EOF"

sudo apt-get update
sudo apt-get install agl-xds-agent
sudo apt-get install agl-xds-cli
sudo apt-get install agl-xds-gdb
```

## Install Packages for OpenSUSE

Use the following commands to install packages for the client part
on OpenSUSE-based systems:

```bash
# Set DISTRO (openSUSE_Leap_42.3, openSUSE_Leap_15.0, openSUSE_Tumbleweed)
export DISTRO="openSUSE_Leap_15.0"

# Set AGL_RELEASE (AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master)
export AGL_RELEASE="AGL_Master"

sudo zypper ar http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/isv:LinuxAutomotive:${AGL_RELEASE}.repo

sudo zypper ref
sudo zypper install agl-xds-agent
sudo zypper install agl-xds-cli
sudo zypper install agl-xds-gdb
```

## Install Packages for Other Platforms (e.g. Windows / MacOS)

- Follow these steps to install `xds-agent`:

  1. Download the latest released tarball from the GitHub [Releases Page](https://github.com/iotbzh/xds-agent/releases).

  1. Unzip the tarball anywhere into your local drive (e.g. `/opt/AGL/xds` or `C:\AGL\xds`).

  1. Add binary to PATH:

      - MacOs: create the .bash_profile `nano .bash_profile` and add `export PATH="/opt/AGL/xds/xds-agent:$PATH`
      - Windows: change the system path using the control panel or system settings.
        Alternatively, you can `setx path "C:\AGK\xds\xds-agent;%path%"`

- If you want to install optional tools, repeat the previous steps for each tool:
  - `xds-cli`, which is used for command-line and IDE integration.
  Downloaded from the ([released tarball link](https://github.com/iotbzh/xds-cli/releases)).
  - `xds-gdb`, used for debugging applications.
  Downloaded from the ([released tarball link](https://github.com/iotbzh/xds-gdb/releases)).

## Start xds-agent

As noted earlier, the `xds-agent` client tool must run on your local
development host when you use XDS.
Depending on your development host, use the following commands:

- For a Linux-based development host, a user systemd service is provided
  (i.e. `xds-agent.service`).

  To start this service automatically when your host boots, enable
  the service using the following command:

  ```bash
  # Enable xds-agent service at boot
  systemctl --user enable xds-agent.service
  ```

  To start the XDS-agent service and display its log, use these
  commands:

  ```bash
  # Manually start xds-agent service
  systemctl --user start xds-agent.service

  # Get status and log of xds-agent service
  systemctl --user status xds-agent.service
  ```

- For a MacOS-based host, use the following command to
  manually start `xds-agent`:

  ```batch
  /opt/AGL/bin/xds-agent
  ```

- For a Windows-based host, use the following command to
  manually start `xds-agent`:

  ```batch
  C:\AGL\xds\xds-agent\xds-agent.exe
  ```