diff options
24 files changed, 600 insertions, 214 deletions
@@ -5,8 +5,8 @@ "keywords": "AGL, XDS, cross, Development, Iotbzh", "author": "Sebastien Douheret", "website": "http://iot.bzh", - "published": "October 2017", - "version": "0.2", + "published": "November 2017", + "version": "1.0.0-rc1", "gitbook": "3.2.2", "root": "docs", @@ -93,9 +93,9 @@ } }, { - "pattern": "<img ([^>]*)> {0,}{style {1,}([^}]*)}", + "pattern": "<img ([^>]*)> {0,}{:: {0,}style=([^}]*)}", "flags": "g", - "substitute": "<img $1 style=\"$2\">", + "substitute": "<img $1 style=$2>", "decode": true } ] diff --git a/docs/0-Doc-Revisions.md b/docs/0-Doc-Revisions.md index f36b344..c0ca786 100644 --- a/docs/0-Doc-Revisions.md +++ b/docs/0-Doc-Revisions.md @@ -1,7 +1,8 @@ Document revisions ================== -| Date | Version | Designation | Author | -|-------------|---------|--------------------------------------|-------------------------| -| Sept 2017 | 0.1 | Initial release | S. Douheret [ Iot.bzh ] | -| Oct 2017 | 0.2 | Various update to match new behavior | S. Douheret [ Iot.bzh ] | +| Date | Version | Designation | Author | +|-------------|-----------|---------------------------------------|-------------------------| +| Sept 2017 | 0.1 | Initial release | S. Douheret [ Iot.bzh ] | +| Oct 2017 | 0.2 | Various updates to match new behavior | S. Douheret [ Iot.bzh ] | +| Nov 2017 | 1.0.0-rc1 | Updates to match v1.0.0-rc1 behavior | S. Douheret [ Iot.bzh ] | diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index cdba733..cfebece 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -12,5 +12,7 @@ * [Part 2 - XDS internals](part-2/0_Abstract.md) * [xds-server](part-2/1_xds-server.md) * [xds-agent](part-2/2_xds-agent.md) - * [xds-exec](part-2/3_xds-exec.md) + * [xds-cli](part-2/3_xds-cli.md) * [xds-gdb](part-2/4_xds-gdb.md) + * [xds-exec](part-2/5_xds-exec.md) +
\ No newline at end of file diff --git a/docs/cover.jpg b/docs/cover.jpg Binary files differindex 01e492b..1100177 100644 --- a/docs/cover.jpg +++ b/docs/cover.jpg diff --git a/docs/cover_small.jpg b/docs/cover_small.jpg Binary files differindex b89f699..c7d8c26 100644 --- a/docs/cover_small.jpg +++ b/docs/cover_small.jpg diff --git a/docs/part-1/1_install-client.md b/docs/part-1/1_install-client.md index 0d463d1..a1c2a4e 100644 --- a/docs/part-1/1_install-client.md +++ b/docs/part-1/1_install-client.md @@ -2,17 +2,30 @@ [xds-agent](https://github.com/iotbzh/xds-agent) is a client tool that must run on your machine (user / developer host) to be able to use XDS. +You should establish the following chain: -Installation of other XDS client tools, such as `xds-exec` or `xds-gdb` is + +Client (eg. `xds-cli` or XDS Dashboard) and `xds-agent` is running on your machine +and `xds-server` is running on a remote server and/or in a container. +Exchanges between these 3 tools are done though HTTP and Websocket protocols +and default url/port mentioned in schema below can be change using config files. + + + +Installation of other XDS client tools, such as `xds-cli` or `xds-gdb` is optional and depends of what you want to do : -- [xds-exec](https://github.com/iotbzh/xds-exec) : command line tool to interact with XDS (also used by IDE integration). +- [xds-cli](https://github.com/iotbzh/xds-cli) : command line tool to used to interact with XDS (also used by IDE integration). - [xds-gdb](https://github.com/iotbzh/xds-gdb) : requested for debugging application. +> [xds-exec](https://github.com/iotbzh/xds-exec) is another tool used to interact +> with XDS before that `xds-cli` exists. `xds-exec` is deprecated and you should +> now use `xds-cli exec` command instead. + ## Install packages for debian distro type ```bash -# 'DISTRO' can be set to { xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04, Debian_8.0, Debian_9.0} +# 'DISTRO' can be set to { xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04, Debian_8.0, Debian_9.0 } seb@laptop ~$ export DISTRO="xUbuntu_16.04" seb@laptop ~$ wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/app-Development/${DISTRO}/Release.key | sudo apt-key add - @@ -22,7 +35,7 @@ EOF" seb@laptop ~$ sudo apt-get update seb@laptop ~$ sudo apt-get install agl-xds-agent -seb@laptop ~$ sudo apt-get install agl-xds-exec +seb@laptop ~$ sudo apt-get install agl-xds-cli seb@laptop ~$ sudo apt-get install agl-xds-gdb ``` @@ -36,7 +49,7 @@ seb@laptop ~$ sudo zypper ar http://download.opensuse.org/repositories/isv:/Lin seb@laptop ~$ sudo zypper ref seb@laptop ~$ sudo zypper install agl-xds-agent -seb@laptop ~$ sudo zypper install agl-xds-exec +seb@laptop ~$ sudo zypper install agl-xds-cli seb@laptop ~$ sudo zypper install agl-xds-gdb ``` @@ -54,7 +67,7 @@ seb@laptop ~$ sudo zypper install agl-xds-gdb `setx path "C:\AGK\xds\xds-agent;%path%"` - repeat the previous steps to install other tools depending of your needs: - - `xds-exec` : requested for command line and IDE integration. ([released tarball link](https://github.com/iotbzh/xds-exec/releases)). + - `xds-cli` : requested for command line and IDE integration. ([released tarball link](https://github.com/iotbzh/xds-cli/releases)). - `xds-gdb` : requested for debugging application. ([released tarball link](https://github.com/iotbzh/xds-gdb/releases)). ## Start xds-agent diff --git a/docs/part-1/2_install-xds-server.md b/docs/part-1/2_install-xds-server.md index 5ac244c..143e028 100644 --- a/docs/part-1/2_install-xds-server.md +++ b/docs/part-1/2_install-xds-server.md @@ -13,11 +13,11 @@ Several installation types are supported : | Install type | Supported OS | Section to refer | |--------------|--------------|------------------| -| Container | Linux or MacOS | [see Installation based on Docker container](#docker_container) | -| Virtual Machine | Linux, MacOS or Windows | [see Installation based on VirtualBox appliance](#vbox_appliance) | -| Native | Linux | [see Native installation](#native) | +| Container | Linux or MacOS | [see Installation based on Docker container](#installation-based-on-docker-container) | +| Virtual Machine | Linux, MacOS or Windows | [see Installation based on VirtualBox appliance](#installation-based-on-virtualbox-appliance) | +| Native | Linux | [see Native installation](#native-installation) | -## <a name="docker_container"></a> Installation based on Docker container +## Installation based on Docker container ### Prerequisites @@ -69,8 +69,8 @@ seb@laptop ~$ bash ./xds-docker-create-container.sh --volume /my-workspace:$HOME `xds-server` is automatically started as a service on container startup. -To check if xds-server is correctly install and running, you can access the web -interface, what we call the "Dashboard", using a web browser : +To check if xds-server is correctly install and running, you can access the basic +web page that gives you some instructions: ```bash # if container is running on your local host @@ -79,13 +79,13 @@ seb@laptop ~$ xdg-open http://localhost:8000 ``` `xds-server` is now up and running, you can now install AGL SDKs, please refer -to chapter named "Installing AGL SDKs" +to next chapter named [Installing AGL SDKs](3_install-sdks.md#installing-agl-sdks) ### Container settings This container (ID=0) exposes following ports: -- 8000 : `xds-server` to serve XDS Dashboard +- 8000 : `xds-server` to serve XDS basic web page - 69 : TFTP - 2222 : ssh @@ -99,17 +99,18 @@ inside and outside docker): | $USER_VOLUME | $USER_VOLUME | user path, see `--volume` option of `xds-docker-create-container.sh` script | <!-- note --> -Please refer to **part 2 - xds-server** documentation for additional info. +Please refer to [part 2 - xds-server](../part-2/1_xds-server.md) documentation +for additional info. <!-- endnote --> -## <a name="vbox_appliance"></a> Installation based on VirtualBox appliance +## Installation based on VirtualBox appliance _coming soon ..._ -## <a name="native"></a> Native installation +## Native installation You can chose to install xds-server 'natively' instead of within a docker -container but only Linux host OSes are supported and tested for native +container but note that only Linux host OSes are supported and tested for native installation ! ### Install packages for debian distro type @@ -142,7 +143,7 @@ seb@laptop ~$ sudo zypper install agl-xds-server ### Configure xds-server <!-- note --> ->**Optional step**: nothing to do if you keep default settings +**Optional step**: skip this chapter if you want to use keep default settings <!-- endnote --> When `xds-server` is started as a systemd service, default environment variables @@ -152,15 +153,14 @@ are set into `/etc/default/xds-server` file. and default JSON config is `/etc/xds-server/config.json`. <!-- note --> ->**Note:** you can use your own JSON config by settings `APP_CONFIG` variable of -`/etc/default/xds-server` file to your file, for example -`/home/MYUSER/.xds/server/config.json` +**Note:** you can use your own JSON config by settings `APP_CONFIG` variable of +`/etc/default/xds-server` file to your file, for example `/home/MYUSER/.xds/server/config.json` <!-- endnote --> Supported fields in JSON configuration file are : -- **httpPort** : HTTP port of client webapp / dashboard -- **webAppDir** : location of client dashboard (default: webapp/dist) +- **httpPort** : HTTP port of client webapp/REST API +- **webAppDir** : location of client web application (default: webapp/dist) - **shareRootDir** : root directory where projects will be copied - **logsDir** : directory to store logs (eg. syncthing output) - **sdkRootDir** : root directory where cross SDKs are installed @@ -208,8 +208,14 @@ seb@laptop ~$ systemctl --user --unit=xds-server.service --output=cat ``` To check if xds-server is correctly install and running, you can access the web -interface, what we call the "Dashboard", using a web browser : +interface, using a web browser : ```bash seb@laptop ~$ xdg-open http://localhost:8000 ``` + +or get the current version using the following curl command: + +```bash +seb@laptop ~$ curl http://localhost:8000/api/v1/version +``` diff --git a/docs/part-1/3_install-sdks.md b/docs/part-1/3_install-sdks.md index 9c8b245..3ea342e 100644 --- a/docs/part-1/3_install-sdks.md +++ b/docs/part-1/3_install-sdks.md @@ -37,10 +37,10 @@ devel@docker ~$ sudo /opt/AGL/xds/server/xds-utils/install-agl-sdks.sh --arch co ``` <!-- warning --> ->**Warning:** due to some limitation, you need for now to restart `xds-server` in +**Warning:** due to some limitation, you need for now to restart `xds-server` in order to make new installed SDK visible/available. -> ```bash -> seb@laptop ~$ ssh -p 2222 devel@localhost -> devel@docker ~$ systemctl --user restart xds-server.service -> ``` +```bash +seb@laptop ~$ ssh -p 2222 devel@localhost +devel@docker ~$ systemctl --user restart xds-server.service +``` <!-- endwarning --> diff --git a/docs/part-1/4_build-first-app.md b/docs/part-1/4_build-first-app.md index 45b57b7..d473d77 100644 --- a/docs/part-1/4_build-first-app.md +++ b/docs/part-1/4_build-first-app.md @@ -2,17 +2,18 @@ ## Prerequisites -- `xds-agent` is running on your machine - (see **Installing XDS client tools** previous chapter) +- `xds-agent` is running locally on your machine + (see previous chapter: [Installing XDS client tools](./1_install-client.md) ) - `xds-server` is running locally in a docker container or is accessible on your - network (see **Installing XDS server** previous chapter) -- one or more SDK have been installed (see **Installing AGL SDKs** previous chapter) -- XDS configuration is correct: in other words, all table lines are blue in - configuration page of XDS Dashboard. + network (see previous chapter: [Installing XDS server](./2_install-xds-server.md)) +- one or more SDK have been installed (see previous chapter: [Installing AGL SDKs](3_install-sdks.md)) +- XDS configuration is correct: in other words, connection is correctly + established between `xds-agent` and `xds-server` and no error message is + displayed when you open XDS Dashboard in a web browser. ## Setup -Let's use for example helloworld-native-application, so you need first to clone +Let's use _helloworld-native-application_ project as example, so you need first to clone this project into a directory that will be accessible by `xds-server`. Depending of the project sharing method: @@ -20,7 +21,7 @@ Depending of the project sharing method: - Path mapping: you must clone project into `$HOME/xds-workspace` directory. <!-- note --> -> **Note:** : [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) project is an AGL +**Note:** : [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) project is an AGL project based on [app-templates](https://git.automotivelinux.org/apps/app-templates/) (included as a git submodule). This CMake templating, used to develop application with the AGL Application Framework, will automatically generate makefile rules @@ -36,36 +37,59 @@ cd $HOME/xds-workspace git clone --recursive https://github.com/iotbzh/helloworld-native-application.git ``` -### Declare project into XDS +### Declare project using XDS Dashboard Use XDS Dashboard to declare your project. Open a browser and connect to XDS -Dashboard. URL depends of your config, for example `http://localhost:8000` +Dashboard. URL depends of your config, for example `http://localhost:8800` -Click cog icon {:: style="display:inline; padding:0;"} -to open configuration panel and then create/declare a new project by with the -plus icon -{:: style="display:inline; padding:0;"} -of `Projects` bar. +Open the right sidebar and select `Projects` entry to open project page and then +create/declare a new project by with the plus icon: -Set `Sharing Type` and paths according to your setup. +{:: style="margin:auto;"} + +<!-- pagebreak --> + +Set `Sharing Type` and paths according to your needs. {:: style="width:90%;"} -Note that XDS creates a file name `xds-project.conf` (if not already exists) -when you declare a new project using XDS Dashboard. This file may be very useful -when you will use XDS client tools such as `xds-exec` (see next chapter). +Note that XDS creates (if not already exists) a file named `xds-project.conf` +when you declare a new project. This file may be very useful when you plan to +use XDS client tools such as `xds-cli` or `xds-gdb`. <!-- note --> ->**Note:** when you select `Path mapping`, you must clone your project into -`$HOME/xds-workspace` directory (named "Local Path" in modal window) and -"Server Path" must be set to `/home/devel/xds-workspace/xxx` where xxx is your -project directory name. If you select `Cloud Sync`, you can clone your project -where you want on your local disk. +**Note:** when `Path mapping` type is selected, you must clone your project into +`$HOME/xds-workspace` directory (named **Local Path** in modal window). + +If XDS server is running in the XDS docker container (see [Installation based on Docker container](./2_install-xds-server.md#installation-based-on-docker-container) ), +the **Server Path** must be set to `/home/devel/xds-workspace/xxx` where xxx is your +project directory name. + +If you select `Cloud Sync`, you can clone your project wherever you want on +your local disk. <!-- endnote --> +### Declare project from command line + +Use XDS command line tool named [xds-cli](./part2/3_xds-cli.md) to declare your +project from command line and more precisely the `projects add` command +(short option: `prj add`). + +```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 +``` + +> **Note:** option `--url=http://localhost:1234` may be added to `xds-cli` in +> order to set url of `xds-agent` in case of agent is not running on default +> port (for example here, 1234) + +<!-- pagebreak --> + ## Build from XDS dashboard -Open the build page (icon {:: style="display:inline; padding:0;"}), then select your **Project** and the **Cross SDK** you want to use and click on +Open the build page build entry of left sidebar {:: style="display:inline; padding:0;"}, + +then select your **Project** and the **Cross SDK** you want to use and click on **Clean / Pre-Build / Build / Populate** buttons to execute various build actions. {:: style="width:90%;"} @@ -74,24 +98,40 @@ Open the build page (icon {:: style="dis You need to determine which is the unique id of your project. You can find this ID in project page of XDS dashboard or you can get it from command line -using the `--list` option. This option lists all existing projects ID: +using `xds-cli` tool and `projects list` command (short: `prj ls`): ```bash -xds-exec --list - -List of existing projects: - CKI7R47-UWNDQC3_myProject - CKI7R47-UWNDQC3_test2 - CKI7R47-UWNDQC3_test3 +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 ``` -> **Note:** XDS tools, including `xds-exec` are installed by default in `/opt/AGL/bin` -> directory and this path has been added into your PATH variable. -> If it is not the case, just add it manually using `export PATH=${PATH}:/opt/AGL/bin` command line. +XDS tools, including `xds-cli` are installed by default in `/opt/AGL/bin` +directory and this path has been added into your PATH variable. If it is not the +case, just add it manually using `export PATH=${PATH}:/opt/AGL/bin` command line. Now to refer your project, just use --id option or use `XDS_PROJECT_ID` environment variable. +<!-- note --> +**Note:** short id notation is also supported as soon as given id value is non ambiguous. +For example, to refer to Project_helloworld-native-application project listed +in above command, you can simply use --id 40 instead of --id 4021617e-ced0-11e7-acd2-3c970e49ad9b +<!-- endnote --> + +You also need to determine the ID of the cross SDK you want to use to cross build +you application. To list installed SDK, 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) +``` + You are now ready to use XDS to for example cross build your project. Here is an example to build a project based on CMakefile: @@ -101,18 +141,24 @@ cd $MY_PROJECT_DIR mkdir build # Generate build system using cmake -xds-exec --id=CKI7R47-UWNDQC3_myProject --sdkid=poky-agl_aarch64_4.0.1 --url=http://localhost:8000 -- cd build && cmake .. +xds-cli exec --id=4021617e --sdkid=c226821b -- "cd build && cmake .." # Build the project -xds-exec --id=CKI7R47-UWNDQC3_myProject --sdkid=poky-agl_aarch64_4.0.1 --url=http://localhost:8000 -- cd build && make all +xds-cli exec --id=4021617e --sdkid=c226821b -- "cd build && make all" ``` -To avoid to set project id, xds server url, ... at each command line, you can -define these settings as environment variable within an env file and just set -`--config` option or source file before executing xds-exec. +<!-- note --> +**Note:** If you use `&&`, `||` or `;` statement in the executed command line, +you need to double quote the command, for example `"cd build && make`. +<!-- endnote --> + +To avoid to set project id, sdks id, url, ... for each command line, you can +define these settings as environment variables within an env file and just set +`--config` option or source file before executing xds-cli command. -XDS creates a file name `xds-project.conf` (only if not already exists) when you -declare a new project using XDS Dashboard. Use this file with `--config` option. +Note that XDS creates a file named `xds-project.conf` (only if not already exists) +when you declare a new project using XDS Dashboard (or using `xds-cli prj add...`). +Edit this file if needed and then refer it with `--config` option. For example, the equivalence of above command is: @@ -122,30 +168,30 @@ cd $MY_PROJECT_DIR # Edit and potentially adapt xds-project.conf file that has been created # automatically on project declaration using XDS Dashboard -vi xds-project.conf +cat xds-project.conf # XDS project settings - export XDS_SERVER_URL=localhost:8000 - export XDS_PROJECT_ID=cde3b382-9d3b-11e7_helloworld-native-application - export XDS_SDK_ID=poky-agl_aarch64_4.0.1 + 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-exec --config xds-project.conf -- "mkdir -p build && cd build && cmake .." -cd build && xds-exec -- make all +xds-cli exec --config=./xds-project.conf -- "mkdir -p build && cd build && cmake .." +cd build && xds-cli exec --config=../xds-project.conf -- "make all" # Or equivalent by first sourcing conf file (avoid to set --config option) source xds-project.conf -xds-exec -- "mkdir -p build && cd build && cmake .." -cd build && xds-exec -- make all +xds-cli exec "mkdir -p build && cd build && cmake .." +cd build && xds-cli exec "make all" ``` <!-- note --> ->**Note:** all parameters after a double dash (--) are considered as the command -to execute on xds-server. +**Note:** all parameters after a double dash (--) are considered as the command +to execute. <!-- endnote --> ## Build from IDE -First create an XDS config file or reuse the previous one, for example we use +First create an XDS config file or reuse the previous one, for example we use here aarch64 SDK to cross build application for a Renesas Gen3 board. ```bash @@ -153,9 +199,9 @@ here aarch64 SDK to cross build application for a Renesas Gen3 board. # for example: # MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application cat > $MY_PROJECT_DIR/xds-project.conf << EOF - export XDS_SERVER_URL=localhost:8000 - export XDS_PROJECT_ID=cde3b382-9d3b-11e7_helloworld-native-application - export XDS_SDK_ID=poky-agl_aarch64_3.99.3 + export XDS_AGENT_URL=localhost:8800 + export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b + export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03 EOF ``` @@ -211,13 +257,13 @@ __Netbeans 8.x :__ - Select **Pre-Build** sub-category, and set: - Working Directory: `build_gen3` - - Command Line: `xds-exec -c ../xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ..` + - Command Line: `xds-cli exec -c ../xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ..` - Pre-build First: `ticked` - Select **Make** sub-category, and set: - Working Directory: `build_gen3` - - Build Command: `xds-exec -c ../xds-project.conf -- make remote-target-populate` - - Clean Command: `xds-exec -c ../xds-project.conf -- make clean` + - Build Command: `xds-cli exec -c ../xds-project.conf -- make remote-target-populate` + - Clean Command: `xds-cli exec -c ../xds-project.conf -- make clean`  @@ -266,7 +312,7 @@ AGL helloworld application based on cmake template. { "taskName": "pre-build", "group": "build", - "command": "/opt/AGL/bin/xds-exec --rpath build --config xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ../", + "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ../", "problemMatcher": [ "$gcc" ] @@ -274,14 +320,14 @@ AGL helloworld application based on cmake template. { "taskName": "build", "group": "build", - "command": "/opt/AGL/bin/xds-exec --rpath build --config xds-project.conf -- make widget", + "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- make widget", "problemMatcher": [ "$gcc" ] }, { "taskName": "populate", - "command": "/opt/AGL/bin/xds-exec --rpath build --config xds-project.conf -- make widget-target-install", + "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- make widget-target-install", "problemMatcher": [] } ] diff --git a/docs/part-1/5_debug-first-app.md b/docs/part-1/5_debug-first-app.md index 15f58b9..69f004f 100644 --- a/docs/part-1/5_debug-first-app.md +++ b/docs/part-1/5_debug-first-app.md @@ -1,22 +1,18 @@ # Debug your first AGL application -Debug is based on gdb and you need to use `xds-gdb` as a wrapper on gdb to cross-debug your application. -This tool allows you to debug an application built with an xds-server without the need to install gdb or any cross tool. +Debug is based on gdb and you need to use `xds-gdb` as a wrapper on gdb to +cross-debug your application. This tool allows you to debug an application built +with XDS without the need to install gdb or any cross tools. + Two debugging models are supported: 1. native debugging -1. XDS remote debugging requiring an XDS server and allowing cross debug your - application. +1. XDS remote debugging requiring an XDS agent/server setup and that allows you to cross debug your application. - By default XDS remote debug is used and you need to define `XDS_NATIVE_GDB` +By default XDS debug model is used and you need to define `XDS_NATIVE_GDB` variable to use native gdb debug mode instead. -> **SEE ALSO**: [xds-server](https://github.com/iotbzh/xds-server), a web server -used to remotely cross build applications. -> **SEE ALSO**: [xds-exec](https://github.com/iotbzh/xds-exec), -wrappers on `exec` command that allows to cross build your application through `xds-server`. - ## Configuration `xds-gdb` configuration is defined by variables (see listed below). @@ -44,9 +40,9 @@ wrappers on `exec` command that allows to cross build your application through ` # for example: # MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application cat > $MY_PROJECT_DIR/xds-gen3.conf << EOF -export XDS_SERVER_URL=http://docker:8000 -export XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject -export XDS_SDK_ID=poky-agl_aarch64_4.0.1 +export XDS_AGENT_URL=localhost:8800 +export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b +export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03 EOF ``` @@ -60,9 +56,9 @@ Set logging file, default `/tmp/xds-gdb.log`. `XDS_NATIVE_GDB` -Use native gdb mode instead of remote XDS server mode. +Use native gdb mode instead of remote XDS mode. -`XDS_PROJECT_ID` *(mandatory with XDS server mode)* +`XDS_PROJECT_ID` *(mandatory in XDS mode)* Project ID you want to build @@ -70,13 +66,13 @@ Project ID you want to build Relative path into project -`XDS_SDK_ID` *(mandatory with XDS server mode)* +`XDS_SDK_ID` *(mandatory in XDS mode)* Cross Sdk ID to use to build project -`XDS_SERVER_URL` *(mandatory with XDS server mode)* +`XDS_AGENT_URL` -Remote XDS server url +Local XDS agent url (default `http://localhost:8800`) ### Configuration variables set within gdb init command file @@ -87,8 +83,8 @@ You must respect the following syntax: commented line including `:XDS-ENV:` tag Example of gdb init file where we define project and sdk ID: ```bash - # :XDS-ENV: XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject - # :XDS-ENV: XDS_SDK_ID=poky-agl_aarch64_4.0.1 + # :XDS-ENV: XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b + # :XDS-ENV: XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03 ``` ## Using xds-gdb from command line @@ -96,16 +92,16 @@ Example of gdb init file where we define project and sdk ID: ### XDS remote debugging mode First the project you want to debug must be declared on an xds-server and this -project may also has been built using this xds-server (see [xds-server](https://github.com/iotbzh/xds-server) for more details). +project may also has been built using using XDS (see [Create your first AGL application](./4_build-first-app.md) for more details). -So to debug it you need to know the xds-server url (eg. <http://docker:8000>), +So to debug it you need to have the XDS agent - server chain in place and you also need the project and sdk unique id. You can find these IDs in project page of XDS dashboard or you can get them from command line using the `--list` option. This option lists all existing projects ID: ```bash -XDS_SERVER_URL=http://docker:8000 xds-gdb --list +xds-gdb --list ``` Now to refer your project, just set `XDS_PROJECT_ID` and `XDS_SDK_ID` variables. @@ -125,28 +121,28 @@ cd helloworld-service # Define XDS config cat <<EOF >./xds-config.env -XDS_SERVER_URL=http://docker:8000 +#optional if not default value: XDS_AGENT_URL=http://localhost:8800 XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject XDS_SDK_ID=poky-agl_aarch64_4.0.1 EOF -# Tell to xds-exec and xds-gdb which is your config file +# Tell to xds-cli and xds-gdb which is your config file export XDS_CONFIG=../xds-gen3.conf # Create a new build directory mkdir build && cd build # Start remote cross build -xds-exec -- cmake -DRSYNC_TARGET=root@myTarget .. -xds-exec -- make -xds-exec -- make remote-target-populate +xds-cli exec -- cmake -DRSYNC_TARGET=root@myTarget .. +xds-cli exec -- make +xds-cli exec -- make remote-target-populate # Start debugging xds-gdb -x target/gdb-on-root@myTarget.ini ``` <!-- note --> -> **Note:** : [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) project is an AGL +**Note:** : [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) project is an AGL project based on [app-templates](https://git.automotivelinux.org/apps/app-templates/) (included as a git submodule). This CMake templating, used to develop application with the AGL Application Framework, will automatically generate makefile rules diff --git a/docs/part-1/pictures/nb_new-project-4.png b/docs/part-1/pictures/nb_new-project-4.png Binary files differindex ebd330a..bcb0716 100644 --- a/docs/part-1/pictures/nb_new-project-4.png +++ b/docs/part-1/pictures/nb_new-project-4.png diff --git a/docs/part-1/pictures/nb_xds_options.png b/docs/part-1/pictures/nb_xds_options.png Binary files differindex 02bd3a9..fa82a94 100644 --- a/docs/part-1/pictures/nb_xds_options.png +++ b/docs/part-1/pictures/nb_xds_options.png diff --git a/docs/part-1/pictures/xds-block-chain.png b/docs/part-1/pictures/xds-block-chain.png Binary files differnew file mode 100644 index 0000000..0ecceb0 --- /dev/null +++ b/docs/part-1/pictures/xds-block-chain.png diff --git a/docs/part-1/pictures/xds-block-diagram.png b/docs/part-1/pictures/xds-block-diagram.png Binary files differindex cd11ad8..fae6df2 100644 --- a/docs/part-1/pictures/xds-block-diagram.png +++ b/docs/part-1/pictures/xds-block-diagram.png diff --git a/docs/part-1/pictures/xds-dashboard-icon-1.png b/docs/part-1/pictures/xds-dashboard-icon-1.png Binary files differindex 9aea05e..8fdc20f 100644 --- a/docs/part-1/pictures/xds-dashboard-icon-1.png +++ b/docs/part-1/pictures/xds-dashboard-icon-1.png diff --git a/docs/part-1/pictures/xds-dashboard-icon-2.png b/docs/part-1/pictures/xds-dashboard-icon-2.png Binary files differindex 5df47b6..e551d8c 100644 --- a/docs/part-1/pictures/xds-dashboard-icon-2.png +++ b/docs/part-1/pictures/xds-dashboard-icon-2.png diff --git a/docs/part-1/pictures/xds-dashboard-icon-3.png b/docs/part-1/pictures/xds-dashboard-icon-3.png Binary files differindex 4a642e6..7b303ed 100644 --- a/docs/part-1/pictures/xds-dashboard-icon-3.png +++ b/docs/part-1/pictures/xds-dashboard-icon-3.png diff --git a/docs/part-1/pictures/xds-dashboard-prj-1.png b/docs/part-1/pictures/xds-dashboard-prj-1.png Binary files differindex c675b90..d5b0621 100644 --- a/docs/part-1/pictures/xds-dashboard-prj-1.png +++ b/docs/part-1/pictures/xds-dashboard-prj-1.png diff --git a/docs/part-1/pictures/xds-dashboard-prj-2.png b/docs/part-1/pictures/xds-dashboard-prj-2.png Binary files differindex 821b573..9429246 100644 --- a/docs/part-1/pictures/xds-dashboard-prj-2.png +++ b/docs/part-1/pictures/xds-dashboard-prj-2.png diff --git a/docs/part-2/1_xds-server.md b/docs/part-2/1_xds-server.md index ee5df5e..e07d9d3 100644 --- a/docs/part-2/1_xds-server.md +++ b/docs/part-2/1_xds-server.md @@ -10,15 +10,25 @@ and let user to continue to work as usual (use his favorite editor, keep performance while editing/browsing sources). This powerful and portable webserver (written in [Go](https://golang.org)) -exposes a REST interface over HTTP and also provides a Web dashboard to configure projects and execute _(for now)_ only basics commands. +exposes a REST interface over HTTP. `xds-server` uses [Syncthing](https://syncthing.net/) tool to synchronize projects files from user machine to build server machine or container. -> **SEE ALSO**: [xds-exec](https://github.com/iotbzh/xds-exec), -wrappers on `exec` commands that allows you to send commands to `xds-server` +`xds-server` is commonly running on a build server (within a container or not) +and [xds-agent](2_xds-agent.md) must run on the developer/user machine in order +to setup the following connection chain: + +```schema + developer/user machine | build server or container + ---------------------------|----------------------------- + xds-cli <---> xds-agent <-|-> xds-server +``` + +**SEE ALSO**: [xds-cli](https://github.com/iotbzh/xds-cli), +a command-line tool that allows you to send commands to `xds-agent / xds-server` and for example build your application from command-line or from your favorite -IDE (such as Netbeans or Visual Studio Code) through `xds-server`. +IDE (such as Netbeans or Visual Studio Code) through `xds-agent <=> xds-server`. ## How to run @@ -75,18 +85,21 @@ seb@laptop ~$ bash ./xds-docker-create-container.sh --volume /my-workspace:$HOME This container (ID=0) exposes following ports: -- 8000 : `xds-server` to serve XDS Dashboard +- 8000 : `xds-server` to serve XDS webapp - 69 : TFTP - 2222 : ssh #### Manually setup docker user id <!-- note --> ->**Note:** if you used `xds-docker-create-container.sh` script to create XDS -> docker container, user uid/gid inside docker has already been changed by this script. +**Note:** if you used `xds-docker-create-container.sh` script to create XDS +docker container, user uid/gid inside docker has already been changed by this script. <!-- endnote --> -If you plan to **use path-mapping sharing type for your projects**, you need to have the same user id and group id inside and outside docker. By default user and group name inside docker is set `devel` (id `1664`), use following commands to replace id `1664` with your user/group id: +If you plan to **use path-mapping sharing type for your projects**, you need to +have the same user id and group id inside and outside docker. By default user +and group name inside docker is set `devel` (id `1664`), use following commands +to replace id `1664` with your user/group id: ```bash # Set docker container name to use (usually agl-xds-xxx where xxx is USERNAME@MACHINENAME-IDX-NAME) @@ -109,11 +122,12 @@ seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "systemctl start autologin" seb@laptop ~$ ssh -p 2222 devel@localhost -- "systemctl --user start xds-server" ``` -## Check if xds-server is running (open XDS Dashboard) +## Check if xds-server is running (open XDS webapp) **`xds-server` is automatically started** as a service on container startup. -If the container is running on your localhost, you can access the web interface (what we call the "Dashboard"): +If the container is running on your localhost, you can access to a basic web +application: ```bash seb@laptop ~$ xdg-open http://localhost:8000 @@ -182,39 +196,43 @@ devel@docker ~$ sudo /opt/AGL/xds/server/xds-utils/install-agl-sdks.sh --arch co ``` -### XDS Dashboard +### XDS server REST API and Web application -`xds-server` serves a web-application at [http://localhost:8000](http://localhost:8000) -when XDS server is running on your host. Just replace `localhost` by the host -name or ip when XDS server is running on another host. So you can now connect -your browser to this url and use what we call the **XDS dashboard**. +`xds-server` exposes a REST API and serves a basic web-application. + +REST API based url is `http://localhost:8000/api/v1/` when XDS server is +running on your host (localhost) and basic web-application is available at +[http://localhost:8000](http://localhost:8000). + +Just replace `localhost` by the host name or ip when `xds-server` is running +on another host. ```bash +# Get version using REST API +curl http://localhost:8000/api/v1/version + +# Open browser and local xds-server web-application xdg-open http://localhost:8000 ``` -Then follow instructions provided by this dashboard, knowing that the first time -you need to download and start `xds-agent` on your local machine. +Then follow instructions provided on this page to install and start `xds-agent` +that must run locally on your machine. -To download this tool, just click on download icon in dashboard configuration -page or download one of `xds-agent` released tarball: [https://github.com/iotbzh/xds-agent/releases](https://github.com/iotbzh/xds-agent/releases). - -See also `xds-agent` [README file](https://github.com/iotbzh/xds-agent) for more details. +See also [xds-agent documentation](2_xds-agent.md) for more details. ## Build xds-server from scratch ### Dependencies -- Install and setup [Go](https://golang.org/doc/install) version 1.7 or higher to compile this tool. +- Install and setup [Go](https://golang.org/doc/install) version 1.8.1 or higher to compile this tool. - Install [npm](https://www.npmjs.com/) -- Install [gulp](http://gulpjs.com/) - Install [nodejs](https://nodejs.org/en/) Ubuntu: ```bash sudo apt-get install golang npm curl git zip unzip - sudo npm install -g gulp-cli n + sudo npm install --global @angular/cli # Angular Command Line Interface # Install LTS version of nodejs sudo n lts ``` @@ -223,7 +241,7 @@ openSUSE: ```bash sudo zypper install go npm git curl zip unzip - sudo npm install -g gulp-cli n + sudo npm install --global @angular/cli # Angular Command Line Interface # Install LTS version of nodejs sudo n lts ``` @@ -257,17 +275,18 @@ And to install `xds-server` (by default in `/opt/AGL/xds/server`): ``` <!-- warning --> ->**Warning:** makefile install rule and default values in configuration file are set -> to fit the docker setup, so you may need to adapt some settings when you want to install -> xds-server natively. +**Warning:** makefile install rule and default values in configuration file are set +to fit the docker setup, so you may need to adapt some settings when you want to install +xds-server natively. <!-- endwarning --> <!-- note --> ->**Note:** Used `DESTDIR` to specify another install directory -> ->```bash ->make install DESTDIR=$HOME/opt/xds-server ->``` +**Note:** Used `DESTDIR` to specify another install directory + +```bash +make install DESTDIR=$HOME/opt/xds-server +``` + <!-- endnote --> #### XDS docker image @@ -298,8 +317,8 @@ Here is the logic to determine which `config.json` file will be used: Supported fields in configuration file are (all fields are optional and example below corresponds to the default values): -- **httpPort** : HTTP port of client webapp / dashboard -- **webAppDir** : location of client dashboard (default: webapp/dist) +- **httpPort** : HTTP port of client webapp/REST API +- **webAppDir** : location of client web application (default: webapp/dist) - **shareRootDir** : root directory where projects will be copied - **logsDir** : directory to store logs (eg. syncthing output) - **sdkRootDir** : root directory where cross SDKs are installed @@ -330,14 +349,15 @@ below corresponds to the default values): ### XDS server architecture -The server part is written in *Go* and web app / dashboard (client part) in -*Angular2*. +The server part is written in *Go* and web app (basic HTML) in *Angular4*. ```bash | +-- bin/ where xds-server binary file will be built | -+-- agent-config.json.in example of config.json file ++-- conf.d Linux configuration and startup files (systemd user service) +| ++-- config.json.in example of config.json file | +-- glide.yaml Go package dependency file | @@ -355,7 +375,7 @@ The server part is written in *Go* and web app / dashboard (client part) in | +-- vendor/ temporary directory to hold Go dependencies packages | -+-- webapp/ source client dashboard (Angular2 app) ++-- webapp/ source client basic web application ``` Visual Studio Code launcher settings can be found into `.vscode/launch.json`. diff --git a/docs/part-2/2_xds-agent.md b/docs/part-2/2_xds-agent.md index 0ece136..7ff271d 100644 --- a/docs/part-2/2_xds-agent.md +++ b/docs/part-2/2_xds-agent.md @@ -24,23 +24,30 @@ Supported fields in configuration file are (all fields are optional and example below corresponds to the default values): - **httpPort** : http port of agent REST interface +- **webAppDir** : location of client webapp / dashboard (default: webapp/dist) - **logsDir** : directory to store logs (eg. syncthing output) -- **xds-apikey** : xds-agent api-key to use (always set value to "1234abcezam") -- **syncthing.binDir** : syncthing binaries directory (default: executable directory) -- **syncthing.home"** : syncthing home directory (usually .../syncthing-config) -- **syncthing.gui-address** : syncthing gui url (default <http://localhost:8386>) -- **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated) +- **xdsServers** : an array of xds-server object + - **xdsServers.url**: url of xds-server to connect to +- **syncthing**: a object defining syncthing settings + - **syncthing.binDir** : syncthing binaries directory (default: executable directory) + - **syncthing.home"** : syncthing home directory (usually .../syncthing-config) + - **syncthing.gui-address** : syncthing gui url (default <http://localhost:8386>) + - **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated) ```json { - "httpPort": "8010", - "logsDir": "/tmp/logs", - "xds-apikey": "1234abcezam", + "httpPort": "8800", + "webAppDir": "./www", + "logsDir": "${HOME}/.xds/agent/logs", + "xdsServers": [ + { + "url": "http://localhost:8000" + } + ], "syncthing": { - "binDir": ".", "home": "${HOME}/.xds/agent/syncthing-config", "gui-address": "http://localhost:8386", - "gui-apikey": "1234abcezam", + "gui-apikey": "1234abcezam" } } ``` @@ -65,11 +72,33 @@ You can now use XDS dashboard and check that connection with `xds-agent` is up. ### Dependencies -Install and setup [Go](https://golang.org/doc/install) version 1.8 or -higher to compile this tool. +Install and setup [Go](https://golang.org/doc/install) version 1.8.1 or higher to compile this tool. >**Note:** for Ubuntu, you can use a PPA, see [https://github.com/golang/go/wiki/Ubuntu](https://github.com/golang/go/wiki/Ubuntu) +Install [npm](https://www.npmjs.com/), [nodejs](https://nodejs.org/en/) and +some other tools + +Ubuntu: + +```bash + sudo apt-get install golang npm curl git zip unzip + sudo npm install --global @angular/cli # Angular Command Line Interface + # Install LTS version of nodejs + sudo n lts +``` + +openSUSE: + +```bash + sudo zypper install go npm git curl zip unzip + sudo npm install --global @angular/cli # Angular Command Line Interface + # Install LTS version of nodejs + sudo n lts +``` + +Don't forget to open new user session after installing the packages. + ### Building Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Makefile: @@ -116,3 +145,62 @@ export GOARCH=amd64 make all make package ``` + +## Debugging + +### XDS agent architecture + +The agent part is written in *Go* and the webapp / dashboard is in *typescript + Angular4*. + +```bash +| ++-- bin/ where xds-server binary file will be built +| ++-- conf.d Linux configuration and startup files (systemd user service) +| ++-- glide.yaml Go package dependency file +| ++-- lib/ sources of server part (Go) +| ++-- main.go main entry point of of Web server (Go) +| ++-- Makefile makefile including +| ++-- README.md this readme +| ++-- scripts/ hold various scripts used for installation or startup +| ++-- tools/ temporary directory to hold development tools (like glide) +| ++-- vendor/ temporary directory to hold Go dependencies packages +| ++-- webapp/ source client basic webapp / dashboard +``` + +### Debug + +Visual Studio Code launcher settings can be found into `.vscode/launch.json`. + +>**Tricks:** To debug both `xds-agent` and `xds-server` or common code +`xds-common`, it may be useful use the same local sources. +So you should replace `xds-server` + `xds-common` in `vendor` directory by a symlink. +So clone first `xds-server` + `xds-common` sources next to `xds-agent` directory. +You should have the following tree: + +```bash +> tree -L 3 src +src +|-- github.com + |-- iotbzh + |-- xds-agent + |-- xds-common + |-- xds-server +``` + +Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor +directory : + +```bash +cd src/github.com/iotbzh/xds-agent +make vendor/debug +``` diff --git a/docs/part-2/3_xds-cli.md b/docs/part-2/3_xds-cli.md new file mode 100644 index 0000000..a5610c1 --- /dev/null +++ b/docs/part-2/3_xds-cli.md @@ -0,0 +1,212 @@ +# xds-cli: command-line tool for XDS + +`xds-cli` is a command-line tool for X(cross) Development System. + +## 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") + +## 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 "ABeautifulName" --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 +add, a Add a new SDK +get Get a property of a SDK +list, ls List installed SDKs +remove, rm Remove an existing SDK +``` + +Here are some usage examples: + +```bash +# List existing SDKs +xds-cli sdks ls + +# Get SDK info +xds-cli sdks get c64d +``` + +### 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 +``` + +## How to build + +### Prerequisites + + You must install and setup [Go](https://golang.org/doc/install) version 1.8.1 or + higher to compile this tool. + +### Building + +Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Makefile: + +```bash + export GOPATH=$(realpath ~/workspace_go) + mkdir -p $GOPATH/src/github.com/iotbzh + cd $GOPATH/src/github.com/iotbzh + git clone https://github.com/iotbzh/xds-cli.git + cd xds-cli + make +``` + +## 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 3 src +src +|-- github.com + |-- iotbzh + |-- xds-agent + |-- xds-cli + |-- xds-common +``` + +Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor +directory : + +```bash +cd src/github.com/iotbzh/xds-cli +make vendor/debug +``` diff --git a/docs/part-2/4_xds-gdb.md b/docs/part-2/4_xds-gdb.md index 529dc51..6e5b57d 100644 --- a/docs/part-2/4_xds-gdb.md +++ b/docs/part-2/4_xds-gdb.md @@ -9,16 +9,16 @@ Two debugging models are supported: 1. native debugging -1. XDS remote debugging requiring an XDS server and allowing cross debug your - application. +1. XDS remote debugging requiring an XDS agent/server setup. That allows you to easily cross debug your application. - By default XDS remote debug is used and you need to define `XDS_NATIVE_GDB` + By default XDS debug model is used and you need to define `XDS_NATIVE_GDB` variable to use native gdb debug mode instead. -> **SEE ALSO**: [xds-server](https://github.com/iotbzh/xds-server), a web server +> **SEE ALSO**: [xds-agent](https://github.com/iotbzh/xds-agent), a local agent +used to interface xds-server. +> **SEE ALSO**: [xds-server](https://github.com/iotbzh/xds-server), a REST API server used to remotely cross build applications. -> **SEE ALSO**: [xds-exec](https://github.com/iotbzh/xds-exec), -wrappers on `exec` command that allows to cross build your application through `xds-server`. +> **SEE ALSO**: [xds-cli](https://github.com/iotbzh/xds-cli), XDS command line tool. ## Configuration @@ -46,9 +46,9 @@ wrappers on `exec` command that allows to cross build your application through ` ```bash cat $HOME/myProject/xds-gdb.env -export XDS_SERVER_URL=http://xds-docker:8000 -export XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject -export XDS_SDK_ID=poky-agl_aarch64_4.0.1 +export XDS_AGENT_URL=http://localhost:8800 +export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b +export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03 ``` `XDS_LOGLEVEL` @@ -61,9 +61,9 @@ Set logging file, default `/tmp/xds-gdb.log`. `XDS_NATIVE_GDB` -Use native gdb mode instead of remote XDS server mode. +Use native gdb mode instead of XDS mode. -`XDS_PROJECT_ID` *(mandatory with XDS server mode)* +`XDS_PROJECT_ID` *(mandatory in XDS mode)* Project ID you want to build @@ -71,13 +71,13 @@ Project ID you want to build Relative path into project -`XDS_SDK_ID` *(mandatory with XDS server mode)* +`XDS_SDK_ID` *(mandatory in XDS mode)* Cross Sdk ID to use to build project -`XDS_SERVER_URL` *(mandatory with XDS server mode)* +`XDS_AGENT_URL` -Remote XDS server url +Local XDS agent url (default `http://localhost:8800`) ### Configuration variables set within gdb init command file @@ -88,15 +88,15 @@ You must respect the following syntax: commented line including `:XDS-ENV:` tag Example of gdb init file where we define project and sdk ID: ```bash - # :XDS-ENV: XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject - # :XDS-ENV: XDS_SDK_ID=poky-agl_aarch64_4.0.1 + # :XDS-ENV: XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b + # :XDS-ENV: XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03 ``` ## How to build xds-gdb from scratch ### Prerequisites - You must install and setup [Go](https://golang.org/doc/install) version 1.7 or + You must install and setup [Go](https://golang.org/doc/install) version 1.8.1 or higher to compile this tool. ### Building diff --git a/docs/part-2/3_xds-exec.md b/docs/part-2/5_xds-exec.md index 0c63ff3..cc31a40 100644 --- a/docs/part-2/3_xds-exec.md +++ b/docs/part-2/5_xds-exec.md @@ -22,25 +22,26 @@ 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 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 +**Note:** all parameters after a double dash (--) are considered as the command to execute on xds-server. <!-- endnote --> ### Configuration Options/Variables -`--id` option or `XDS_PROJECT_ID` env variable **(mandatory)** +__`--id` option or `XDS_PROJECT_ID` env variable **(mandatory)**__ Project ID you want to build -`--config|-c` option or `XDS_CONFIG` env variable +__`--config|-c` option or `XDS_CONFIG` env variable__ Env config file to source on startup -`--log|-l` option or `XDS_LOGLEVEL` env variable +__`--log|-l` option or `XDS_LOGLEVEL` env variable__ Logging level, supported levels are: @@ -53,27 +54,27 @@ Logging level, supported levels are: Default level is "error". -`--rpath` option or `XDS_PATH` env variable +__`--rpath` option or `XDS_PATH` env variable__ Relative path into project -`sdkid` option or `XDS_SDK_ID` env variable **(mandatory)** +__`sdkid` option or `XDS_SDK_ID` env variable **(mandatory)**__ Cross Sdk ID to use to build project -`timestamp|-ts` option or `XDS_TIMESTAMP` env variable +__`timestamp|-ts` option or `XDS_TIMESTAMP` env variable__ Prefix output with timestamp -`url` option or `XDS_SERVER_URL` env variable +__`url` option or `XDS_AGENT_URL` env variable__ -Remote XDS server url (default: "localhost:8000") +Local XDS agent url (default: "localhost:8800") ## How to build ### Prerequisites - You must install and setup [Go](https://golang.org/doc/install) version 1.7 or + You must install and setup [Go](https://golang.org/doc/install) version 1.8.1 or higher to compile this tool. ### Building @@ -93,10 +94,10 @@ Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Make Visual Studio Code launcher settings can be found into `.vscode/launch.json`. ->**Tricks:** To debug both `xds-exec` (client part) and `xds-server` (server part), -it may be useful use the same local sources. -So you should replace `xds-server` in `vendor` directory by a symlink. -So clone first `xds-server` sources next to `xds-exec` directory. +>**Tricks:** To debug both `xds-exec` 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-exec` directory. You should have the following tree: ```bash @@ -104,8 +105,9 @@ You should have the following tree: src |-- github.com |-- iotbzh + |-- xds-agent + |-- xds-common |-- xds-exec - |-- xds-server ``` Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor |
