Various review edits for XDS

Took care of review comments from Sebastien
to clear up some terminlogy, update the
create-app-workflow.png image to include
declaring a project. Fixed a link to the
XDS user guide to be guppy-specific.

Included more explanation regarding
aborting an ongoing installation.

v2: squased version due to files being (re-)moved

Change-Id: I48c20d8e0b105f1e26b68b574b2c5d2b56eecb61
Signed-off-by: Scott RifenbarK <srifenbark@gmail.com>
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>

1 files changed, 171 insertions, 0 deletions

diff --git a/docs/part-1/create-app-build-cmd-line.md b/docs/part-1/create-app-build-cmd-line.md
new file mode 100644
index 0000000..5d81625
--- /dev/null
+++ b/docs/part-1/create-app-build-cmd-line.md
@@ -0,0 +1,171 @@
+# Build Using the Command Line
+
+One option for building your application using XDS is to use
+the command line (i.e. `xds-cli`).
+Building the application consists of declaring your project, identifying
+some key ID values, and then using the command line to build it.
+
+<!-- section-note -->
+**NOTE:**
+
+XDS tools, including `xds-cli`, are installed by default in
+the `/opt/AGL/bin` directory.
+During installation, this directory is automatically added to your
+`PATH` variable.
+If, for some reason, the tool is not in your `PATH` directory,
+you can manually add it using the `export PATH=${PATH}:/opt/AGL/bin`
+command.
+<!-- end-section-note -->
+
+
+## Declare Project
+
+Use the `projects add` command to declare your project:
+
+```bash
+xds-cli prj add --label="Project_helloworld-native-application" --type=pm --path=/home/seb/xds-workspace/helloworld-native-application --server-path=/home/devel/xds-workspace/helloworld-native-application
+```
+
+When you declare the project, XDS creates the `xds-project.conf`
+configuration file if one does not already exist.
+You should examine this configuration file before you build the
+project to be sure all configurations are correct for your project.
+
+<!-- section-note -->
+**NOTE:**
+
+If the Server Part (i.e. `xds-agent`) is not running on the default
+port, you can use the `--url=http://localhost:<port>` option with the
+`xds-cli prj add` command to specify the port.
+Just substitute the actual port for `<port>` with the option.
+<!-- end-section-note -->
+
+## Determine the ID of Your Project
+
+After declaring your project, you need to determine the
+unique ID of your project.
+
+From the command line, use the `prj ls` command, which is an abbreviation
+for the `projects list` command:
+
+```bash
+xds-cli prj ls
+ID                                       Label                                   LocalPath
+f9904f70-d441-11e7-8c59-3c970e49ad9b     Project_helloworld-service              /home/seb/xds-workspace/helloworld-service
+4021617e-ced0-11e7-acd2-3c970e49ad9b     Project_helloworld-native-application   /home/seb/xds-workspace/helloworld-native-application
+```
+
+Once you have the ID of the project, you can use the `--id` option
+or the `XDS_PROJECT_ID` environment variable to refer to your project.
+
+<!-- section-note -->
+**NOTE:**
+
+When using the project ID from the command line, you can use the "short"
+notation by providing a non-ambiguous portion of the ID.
+For example, to refer to the `Project_helloworld-native-application` project
+shown in the previous example, you can use `-id 40` rather than
+`--id 40 instead of --id 4021617e-ced0-11e7-acd2-3c970e49ad9b`.
+<!-- end-section-note -->
+
+## Determine the ID of Your SDK
+
+You also need to determine the ID of the SDK you want to use to cross-build
+your application.
+
+To list installed SDKs, use the following command:
+
+```bash
+xds-cli sdks ls
+List of installed SDKs:
+  ID                                    NAME
+  7aa19224-b769-3463-98b1-4c029d721766  aarch64  (3.99.1+snapshot)
+  41a1efc4-8443-3fb0-afe5-8313e0c96efd  corei7-64  (3.99.2+snapshot)
+  c226821b-b5c0-386d-94fe-19f807946d03  aarch64  (3.99.3)
+```
+
+SDK IDs are returned by architecture and version.
+Be sure to identify the SDK you need.
+
+## Build the Application
+
+You can now use XDS to cross-build your project.
+Following is an example that builds a project that is based on CMake:
+
+```bash
+# First, export the target IP address, or it's DNS name
+export TARGET_ADDRESS=<target_adress>
+
+# Go into your project directory and create a build directory
+cd $MY_PROJECT_DIR
+mkdir build
+```
+
+Before using the command line to build the project, you should be
+sure the project's configuration file is correct.
+Examine the `xds-project.conf` configuration file and edit it
+as needed.
+
+Generate the build system using CMake:
+
+```
+# You must set RSYNC_* variables so that you deploy and populate widgets on the target
+xds-cli exec --id=4021617e --sdkid=c226821b -- "export RSYNC_TARGET=root@${TARGET_ADDRESS} ; export RSYNC_PREFIX=/opt ; cd build && cmake .."
+```
+
+Now you can build the project:
+
+```
+xds-cli exec --id=4021617e --sdkid=c226821b -- "cd build && make widget"
+```
+
+<!-- section-note -->
+**NOTE:**
+
+If you use `&&`, `||` or `;` statements in the executed command line,
+you need to double quote the command (e.g. `"cd build && make"`).
+<!-- end-section-note -->
+
+To avoid having to set the project ID, SDK ID, and URL for each
+command line, you can define these settings as environment variables
+using an environment file.
+Use the `--config` option or source file before executing
+the `xds-cli` command.
+
+To specify your configuration file with the command line,
+use the `--config` option.
+For example, the equivalent of the previous build command but
+with a specified configuration file is as follows:
+
+```bash
+# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application
+cd $MY_PROJECT_DIR
+
+# Edit and potentially adapt xds-project.conf file that has been created
+# automatically on project declaration using XDS Dashboard
+cat xds-project.conf
+  # XDS project settings
+  export XDS_AGENT_URL=localhost:8800
+  export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b
+  export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03
+
+# Create build directory and invoke cmake and then build project
+xds-cli exec --config=./xds-project.conf -- "mkdir -p build && cd build && cmake .."
+cd build && xds-cli exec --config=../xds-project.conf -- "make all"
+```
+
+Alternatively, you could first source the configuration file to avoid using the
+`--config` option as follows:
+
+```
+source xds-project.conf
+xds-cli exec "mkdir -p build && cd build && cmake .."
+cd build && xds-cli exec "make all"
+```
+
+<!-- section-note -->
+**NOTE:**
+
+All parameters after a double dash (`--`) are considered as the command
+to execute.
+<!-- end-section-note -->