From c4cabee5bacd0412ee29853a7f4d51b39b90089a Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <srifenbark@gmail.com>
Date: Tue, 23 Apr 2019 15:06:30 -0700
Subject: XDS install and create app: New files and content.

Change-Id: I8021d3096e546bb0bb77a272dd5bcb0ea4dbf209
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
---
 docs/part-1/client-part.md | 143 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)
 create mode 100644 docs/part-1/client-part.md

(limited to 'docs/part-1/client-part.md')

diff --git a/docs/part-1/client-part.md b/docs/part-1/client-part.md
new file mode 100644
index 0000000..b92cc0c
--- /dev/null
+++ b/docs/part-1/client-part.md
@@ -0,0 +1,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
+  ```
-- 
cgit 1.2.3-korg