Split markdown files to have a detailed TOC/summary.

Change-Id: I7d578335ba0d1719030bc2efc6518da17a6150dc
Signed-off-by: Sebastien Douheret <sebastien.douheret@iot.bzh>

5 files changed, 250 insertions, 0 deletions

diff --git a/docs/part-2/3_xds-cli/0_abstract.md b/docs/part-2/3_xds-cli/0_abstract.md
new file mode 100644
index 0000000..df7db6c
--- /dev/null
+++ b/docs/part-2/3_xds-cli/0_abstract.md
@@ -0,0 +1,15 @@
+# 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 :
+
+- [Configuration](./1_config.html)
+- [Start-up](./2_commands.html)
+- [Build from scratch](./3_build.html)
+- [Debugging](./4_debug.html)
diff --git a/docs/part-2/3_xds-cli/1_config.md b/docs/part-2/3_xds-cli/1_config.md
new file mode 100644
index 0000000..6dc7993
--- /dev/null
+++ b/docs/part-2/3_xds-cli/1_config.md
@@ -0,0 +1,57 @@
+# 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
+
+<!-- note -->
+**Note:**
+
+All parameters after a double dash (--) are considered as the command
+to execute on xds-server.
+<!-- endnote -->
+
+## 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/part-2/3_xds-cli/2_commands.md b/docs/part-2/3_xds-cli/2_commands.md
new file mode 100644
index 0000000..b5e0c0a
--- /dev/null
+++ b/docs/part-2/3_xds-cli/2_commands.md
@@ -0,0 +1,119 @@
+# 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
+```
+
+<!-- note -->
+**Note:**
+
+Please also refer to [Installing AGL SDKs](../../part-1/3_install-sdks.html) chapter for more details about sdks installation.
+
+<!-- endnote -->
+
+## 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/part-2/3_xds-cli/3_build.md b/docs/part-2/3_xds-cli/3_build.md
new file mode 100644
index 0000000..ba2d83b
--- /dev/null
+++ b/docs/part-2/3_xds-cli/3_build.md
@@ -0,0 +1,21 @@
+# 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 this repo into your `$GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds` and use delivered Makefile:
+
+```bash
+ export GOPATH=$(realpath ~/workspace_go)
+ mkdir -p $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds
+ cd $GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds
+ 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
+ cd xds-cli
+ make
+```
diff --git a/docs/part-2/3_xds-cli/4_debug.md b/docs/part-2/3_xds-cli/4_debug.md
new file mode 100644
index 0000000..38628db
--- /dev/null
+++ b/docs/part-2/3_xds-cli/4_debug.md
@@ -0,0 +1,38 @@
+# Debug
+
+Visual Studio Code launcher settings can be found into `.vscode/launch.json`.
+
+>**Tricks:**
+>
+>To debug both `xds-cli` and `xds-agent` (REST API part) or common
+code `xds-common`, it may be useful use the same local sources.
+>
+>So you should replace `xds-agent` + `xds-common` in `vendor` directory by a symlink.
+>
+>So clone first `xds-agent` + `xds-common` sources next to `xds-cli` directory.
+
+You should have the following tree:
+
+```bash
+tree -L 5 --charset=ascii src/
+src/
+`-- gerrit.automotivelinux.org
+    `-- gerrit
+        `-- src
+            `-- xds
+                |-- backup.sh
+                |-- xds-agent
+                |-- xds-cli
+                |-- xds-common
+                |-- xds-docs
+                |-- xds-gdb
+                `-- xds-server
+```
+
+Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor
+directory :
+
+```bash
+cd src/gerrit.automotivelinux.org/gerrit/src/xds/xds-cli
+make vendor/debug
+```