diff options
| -rw-r--r-- | docs/part-1/0_Abstract.md | 19 | ||||
| -rw-r--r-- | docs/part-1/1_install-client.md | 24 | ||||
| -rw-r--r-- | docs/part-1/2_install-xds-server.md | 160 | ||||
| -rw-r--r-- | docs/part-1/3_install-sdks.md | 11 | ||||
| -rw-r--r-- | docs/part-1/4_build-first-app.md | 39 | ||||
| -rw-r--r-- | docs/part-1/5_debug-first-app.md | 27 | ||||
| -rw-r--r-- | docs/part-2/1_xds-server.md | 200 | ||||
| -rw-r--r-- | docs/part-2/2_xds-agent.md | 26 | ||||
| -rw-r--r-- | docs/part-2/3_xds-cli.md | 56 | ||||
| -rw-r--r-- | docs/part-2/4_xds-gdb.md | 31 |
10 files changed, 316 insertions, 277 deletions
diff --git a/docs/part-1/0_Abstract.md b/docs/part-1/0_Abstract.md index 8def883..e2620e6 100644 --- a/docs/part-1/0_Abstract.md +++ b/docs/part-1/0_Abstract.md @@ -10,22 +10,29 @@ This documentation is available : - online: [http://docs.automotivelinux.org/docs/devguides/en/dev/#xcross-development-system-user's-guide](http://docs.automotivelinux.org/docs/devguides/en/dev/#xcross-development-system-user's-guide) - PDF file: [http://iot.bzh/download/public/XDS/docs/XDS_UsersGuide.pdf](http://iot.bzh/download/public/XDS/docs/XDS_UsersGuide.pdf) -The first goal of XDS is to provide a multi-platform cross development tool with -near-zero installation. +The first goal of XDS is to provide a multi-platform cross development tool with near-zero installation. + The second goal is to keep application sources locally (on user's machine) to make it compatible with existing IT policies (e.g. corporate backup or SCM), and let user to continue to work as usual (use his favorite editor, keep performance while editing/browsing sources). -The two main blocks that compose XDS are the client part (`xds-agent`) running -on the user's machine and the server part (`xds-server`) running somewhere in a container or on a server machine (on local network or cloud). +The two main blocks that compose XDS: + +- The client part (`xds-agent`) running on the user's machine and +- The server part (`xds-server`) running somewhere in a container or on a server machine (on local network or cloud). {:: style="width:98%;"} <!-- pagebreak --> -The client part (`xds-agent`) is portable and is running on Linux, Windows or -MacOS machine and the following 3 main configurations are supported: +The client part (`xds-agent`) is portable and is running on: + +- Linux +- Windows +- MacOS + +The following 3 main configurations are supported: - standalone (or local) config - On-Premise (local network) diff --git a/docs/part-1/1_install-client.md b/docs/part-1/1_install-client.md index b482dc9..255401d 100644 --- a/docs/part-1/1_install-client.md +++ b/docs/part-1/1_install-client.md @@ -2,17 +2,21 @@ [xds-agent](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-agent.git) 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: -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. +- XDS Client: (`xds-cli` or XDS Dashboard). +- XDS Agent: (`xds-agent`) running on your machine. +- XDS Server (`xds-server`) running on a remote server and/or in a container. + +Exchanges between these 3 tools are done though HTTP and Websocket protocols. + +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 : +optional and depends of what you want to do: - [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. @@ -71,14 +75,18 @@ sudo zypper install agl-xds-gdb XDS-agent is a client tool that must run on your local / user development machine when you use XDS. -For Linux distro, a user systemd service is provided, so you just need to enable -if you want to start it automatically at boot and you can also start it -immediately using following commands: +For Linux distro, a user systemd service is provided, `xds-agent.service`. + +To start it automatically at boot and you can enable it using following commands: ```bash # Enable xds-agent service at boot systemctl --user enable xds-agent.service +``` + +To start the XDS-agent service: +```bash # Manually start xds-agent service systemctl --user start xds-agent.service diff --git a/docs/part-1/2_install-xds-server.md b/docs/part-1/2_install-xds-server.md index 3609bd7..cbbca44 100644 --- a/docs/part-1/2_install-xds-server.md +++ b/docs/part-1/2_install-xds-server.md @@ -9,7 +9,7 @@ running on your local network (On-Premise config) or in the Cloud (SaaS config), For others (standalone config or administrators that want to install an On-Premise solution) xds-server must be installed. -Several installation types are supported : +Several installation types are supported: | Install type | Supported OS | Section to refer | |--------------|--------------|------------------| @@ -19,7 +19,7 @@ Several installation types are supported : ## Installation based on Docker container -### Prerequisites +### Docker container prerequisites Docker is installed on the host machine, please refer to [Docker documentation](https://docs.docker.com/engine/installation/) for more details. @@ -37,27 +37,47 @@ You should get `docker.automotivelinux.org/agl/worker-xds:X.Y` image # List image that we just load docker images "docker.automotivelinux.org/agl/worker-xds*" -docker.automotivelinux.org/agl/worker-xds 4.0 786d65b2792c 6 days ago 654MB +REPOSITORY TAG IMAGE ID CREATED SIZE +docker.automotivelinux.org/agl/worker-xds 5.0 877979e534ff 3 hours ago 106MB ``` ### Create and start a new container -Use provided script to create a new docker container and start it: +Use provided script to create a new docker image and start a new container: ```bash # Get script -wget https://raw.githubusercontent.com/iotbzh/xds-server/master/scripts/xds-docker-create-container.sh +wget -O xds-docker-create-container.sh 'https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-server.git;a=blob_plain;f=scripts/xds-docker-create-container.sh;hb=master' # Create new XDS worker container bash ./xds-docker-create-container.sh # Check that new container is running docker ps | grep worker-xds - -b985d81af40c docker.automotivelinux.org/agl/worker-xds:3.99.1 "/usr/bin/wait_for..." 6 days ago Up 4 hours 0.0.0.0:8000->8000/tcp, 0.0.0.0:69->69/udp, 0.0.0.0:10809->10809/tcp, 0.0.0.0:2222->22/tcp agl-xds-seb@laptop-0-seb +f67079db4339 docker.automotivelinux.org/agl/worker-xds:5.0 "/usr/bin/wait_for..." About a minute ago Up 34 seconds 0.0.0.0:8000->8000/tcp, 0.0.0.0:69->69/udp, 0.0.0.0:10809->10809/tcp, 0.0.0.0:2222->22/tcp agl-xds-HOSTNAME-0-USERNAME ``` -Note that you can also add a new shared directory using `--volume` option in order +This container exposes following ports: + +| Port number | Description | +|-------------|---------------------------------------------| +| 8000 | `xds-server`: serve XDS webapp and REST API | +| 69 | TFTP | +| 2222 | ssh | + +This container also creates the following volumes (shared folders between +inside and outside docker): + +| Directory on host | Directory inside docker | Comment | +|-------------------|-------------------------|---------| +| $HOME/xds-workspace | /home/devel/xds-workspace | XDS projects workspace location| +| $HOME/xds-workspace/.xdt_0 | /xdt | location to store SDKs | +| $USER_VOLUME | $USER_VOLUME | user path, see `--volume` option of `xds-docker-create-container.sh` script | + +<!-- note --> +**Note:** + +You can add a new shared directory using `--volume` option in order to use for example with Path-Mapping folder type. ```bash @@ -65,47 +85,95 @@ to use for example with Path-Mapping folder type. bash ./xds-docker-create-container.sh --volume /my-workspace:$HOME/my-workspace ``` -### Check if xds-server is running +You can change docker used port with `-id` option -`xds-server` is automatically started as a service on container startup. +```bash +# Create new XDS worker container with a different port number +bash ./xds-docker-create-container.sh -id ${ID} -To check if xds-server is correctly install and running, you can access the basic -web page that gives you some instructions: +# Check that new container is running +docker ps | grep worker-xds +f67079db4339 docker.automotivelinux.org/agl/worker-xds:5.0 "/usr/bin/wait_for..." About a minute ago Up 34 seconds 0.0.0.0:(2222+ID)->22/tcp, 0.0.0.0:(69+ID)->69/udp, 0.0.0.0:(8000+ID)->8000/tcp, 0.0.0.0:(10809+ID)->10809/tcp agl-xds-HOSTNAME-ID-USERNAME +``` + +<!-- endnote --> + +#### 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. +<!-- 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: + +```bash +# Set docker container name to use (usually agl-xds-xxx where xxx is USERNAME@MACHINENAME-IDX-NAME) +export CONTAINER_NAME=agl-xds-seb@laptop-0-seb +docker ps | grep -q ${CONTAINER_NAME} || echo "ERROR: No container name \"${CONTAINER_NAME}\" please set a valid CONTAINER_NAME before you continue" + +# First kill all processes of devel user (including running xds-server) +docker exec ${CONTAINER_NAME} bash -c "/bin/loginctl kill-user devel" + +# Change user and group id inside docker to match your ids +docker exec ${CONTAINER_NAME} bash -c "usermod -u $(id -u) devel" +docker exec ${CONTAINER_NAME} bash -c "groupmod -g $(id -g) devel" + +# Update some files ownership +docker exec ${CONTAINER_NAME} bash -c "chown -R devel:devel /home/devel /tmp/xds*" + +# Restart devel autologin service +docker exec ${CONTAINER_NAME} bash -c "systemctl restart autologin" + +# Restart xds-server as a service (ssh port 2222 may depend on your container ID) +ssh -p 2222 devel@localhost -- "systemctl --user restart xds-server" +``` + +### 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 to a basic web +application: ```bash -# if container is running on your local host -# (else replace localhost by the name or the ip of the machine running the container) xdg-open http://localhost:8000 ``` -`xds-server` is now up and running, you can now install AGL SDKs, please refer -to next chapter named [Installing AGL SDKs](3_install-sdks.md#installing-agl-sdks) +If needed you can status / stop / start it manually using following commands: -### Container settings +```bash +# Status XDS server: +ssh -p 2222 devel@localhost systemctl --user status xds-server.service -This container (ID=0) exposes following ports: +# Stop XDS server +ssh -p 2222 devel@localhost systemctl --user stop xds-server.service -- 8000 : `xds-server` to serve XDS basic web page -- 69 : TFTP -- 2222 : ssh +# Start XDS server +ssh -p 2222 devel@localhost systemctl --user start xds-server.service -This container also creates the following volumes (sharing directories between -inside and outside docker): +# Get XDS server logs +ssh -p 2222 devel@localhost journalctl --user --unit=xds-server.service --output=cat +``` -| Directory on host | Directory inside docker | Comment | -|-------------------|-------------------------|---------| -| $HOME/xds-workspace | /home/devel/xds-workspace | XDS projects workspace location| -| $HOME/xds-workspace/.xdt_0 | /xdt | location to store SDKs | -| $USER_VOLUME | $USER_VOLUME | user path, see `--volume` option of `xds-docker-create-container.sh` script | +`xds-server` is now up and running, you can now install AGL SDKs, please refer +to next chapter named [Installing AGL SDKs](3_install-sdks.html#installing-agl-sdks) <!-- note --> -Please refer to [part 2 - xds-server](../part-2/1_xds-server.md#sdk-cross-toolchain-management) documentation +Please refer to [part 2 - xds-server](../part-2/1_xds-server.html#sdk-cross-toolchain-management) documentation for additional info. <!-- endnote --> ## Installation based on Virtual Machine appliance -### Prerequisites +### Virtual Machine appliance prerequisites > VirtualBox is installed on the host machine @@ -131,6 +199,7 @@ VDS_VMNAME=$(VBoxManage list vms | grep xds-vm-debian | cut -d "\"" -f2) echo ${VDS_VMNAME} # Remove old XDS appliance +[ -n ${VDS_VMNAME} ] && VBoxManage controlvm ${VDS_VMNAME} poweroff [ -n ${VDS_VMNAME} ] && VBoxManage unregistervm ${VDS_VMNAME} --delete ``` @@ -150,6 +219,18 @@ echo ${VDS_VMNAME} [ -n ${VDS_VMNAME} ] && VBoxManage startvm ${VDS_VMNAME} ``` +**Mandatory**: + +Add share folder to appliance, to allow files sharing using pathmap method: + +```bash +# Create local share folder +mkdir -p $HOME/xds-workspace + +#Add share folder to appliance +vboxmanage sharedfolder add ${VDS_VMNAME} --name XDS-workspace --hostpath $HOME/xds-workspace +``` + ### Appliance settings This image exposes following network ports (NAT mode): @@ -171,7 +252,7 @@ xdg-open http://localhost:8000 ``` `xds-server` is now up and running, you can now install AGL SDKs, please refer -to next chapter named [Installing AGL SDKs](3_install-sdks.md#installing-agl-sdks) +to next chapter named [Installing AGL SDKs](3_install-sdks.html#installing-agl-sdks) ## Native installation @@ -212,23 +293,6 @@ sudo zypper install agl-xds-server **Optional step**: skip this chapter if you plan to use default settings <!-- endnote --> -When `xds-server` is started as a systemd service, default environment variables -are set into `/etc/default/xds-server` file. - -`xds-server` configuration is also driven by a JSON config file (`server-config.json`), -and default JSON config is `/etc/xds/server/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/server-config.json` - -- `CloudSync` (AKA syncthing) synchronzation type can also be disabled when -`"syncthing"` key is not defined in JSON configuration file. - -<!-- endnote --> - Please refer to [Configuration chapter of xds-server](../part-2/1_xds-server.html#configuration) documentation for more details about JSON configuration file. diff --git a/docs/part-1/3_install-sdks.md b/docs/part-1/3_install-sdks.md index 4755b95..67a6002 100644 --- a/docs/part-1/3_install-sdks.md +++ b/docs/part-1/3_install-sdks.md @@ -1,8 +1,9 @@ # Installing AGL SDKs To build your AGL services or AGL applications using XDS you must install a SDK -matching the target/board you want to use. A SDK is a package that includes all -tools you need to cross-build and cross-debug your service/application. +matching the target/board you want to use. + +A SDK is a package that includes all tools you need to cross-build and cross-debug your service/application. You can generate AGL SDK for the board you want to use or you can download a pre-packaged AGL SDK. @@ -75,13 +76,15 @@ is located in `$HOME/xds-workspace/sdks` directory ## Install a new SDK from XDS Dashboard Open XDS-Dashboard in web-browser and select `SDKs` entry in left side menu. + Then switch to `SDKs MANAGEMENT` view : {:: style="margin:auto; display:flex"} Use filter boxes to find the SDK you want to install and then click on plus -icon (Actions column) to start installation. SDK download and installation -process may take several minutes and output of installation script (output of +icon (Actions column) to start installation. + +SDK download and installation process may take several minutes and output of installation script (output of `add` script mentioned in above chapter). {:: style="margin:auto; display:flex"} diff --git a/docs/part-1/4_build-first-app.md b/docs/part-1/4_build-first-app.md index 997a4b9..f6810d1 100644 --- a/docs/part-1/4_build-first-app.md +++ b/docs/part-1/4_build-first-app.md @@ -15,6 +15,7 @@ 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: - Cloud sync: you can clone project anywhere on your local disk, @@ -40,7 +41,9 @@ git clone --recursive https://github.com/iotbzh/helloworld-native-application.gi ### 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:8800` +Dashboard. + +URL depends of your config, for example `http://localhost:8800` Open the right sidebar and select `Projects` entry to open project page and then create/declare a new project by with the plus icon: @@ -54,14 +57,17 @@ Set `Sharing Type` and paths according to your needs. {:: style="width:90%; max-width:560px; margin:auto; display:flex"} 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`. +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 `Path mapping` type is selected, you must clone your project into +**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) ), +If XDS server is running in the XDS docker container (see [Installation based on Docker container](./2_install-xds-server.html#installation-based-on-docker-container) ), the **Server Path** must be set to `/home/devel/xds-workspace/xxx` where xxx is your project directory name. @@ -108,20 +114,26 @@ f9904f70-d441-11e7-8c59-3c970e49ad9b Project_helloworld-service ``` 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. +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. +**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: +you application. + +To list installed SDK, use the following command: ```bash xds-cli sdks ls @@ -133,6 +145,7 @@ List of installed SDKs: ``` 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: ```bash @@ -209,7 +222,9 @@ EOF This chapter will show you how to create 2 configurations, one to compile your project natively (using native GNU gcc) and one to cross-compile your project -using XDS. You can easily switch from one to other configuration using menu +using XDS. + +You can easily switch from one to other configuration using menu **Run -> Set Project Configuration**. __Netbeans 8.x :__ @@ -334,7 +349,9 @@ AGL helloworld application based on cmake template. } ``` -> **Note:** You can also add your own keybindings to trig above tasks, for example: +> **Note:** +> +> You can also add your own keybindings to trig above tasks, for example: > > ```json > // Build diff --git a/docs/part-1/5_debug-first-app.md b/docs/part-1/5_debug-first-app.md index 2a27177..01a183e 100644 --- a/docs/part-1/5_debug-first-app.md +++ b/docs/part-1/5_debug-first-app.md @@ -1,13 +1,13 @@ # 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 XDS without the need to install gdb or any cross tools. +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 agent/server setup and that allows you to cross debug your application. By default XDS debug model is used and you need to define `XDS_NATIVE_GDB` @@ -30,11 +30,13 @@ variable to use native gdb debug mode instead. ### Configuration Variables - `XDS_CONFIG` - Config file defining `XDS_xxx` configuration variables. Variables of this file - will overwrite inherited environment variables. Variables definition may be - prefixed or not by "export" keyword. - Here is an example of configuration file +`XDS_CONFIG` Config file defining `XDS_xxx` configuration variables. + +Variables of this file will overwrite inherited environment variables. + +Variables definition may be prefixed or not by "export" keyword. + +Here is an example of configuration file: ```bash # for example: @@ -78,6 +80,7 @@ Local XDS agent url (default `http://localhost:8800`) Above `XDS_xxx` variables may also be defined within gdb init command file (see --command or -x option of genuine Gdb). + You must respect the following syntax: commented line including `:XDS-ENV:` tag Example of gdb init file where we define project and sdk ID: @@ -95,9 +98,10 @@ First the project you want to debug must be declared on an xds-server and this project may also has been built using using XDS (see [Create your first AGL application](./4_build-first-app.html) for more details). 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. +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 @@ -107,6 +111,7 @@ xds-gdb --list Now to refer your project, just set `XDS_PROJECT_ID` and `XDS_SDK_ID` variables. You are now ready to use `xds-gdb` to for example cross debug your project. + Here is an example to build and debug a project based on CMakefile and [AGL app-templates](https://git.automotivelinux.org/apps/app-templates/): diff --git a/docs/part-2/1_xds-server.md b/docs/part-2/1_xds-server.md index 2c31b1e..a45a8f0 100644 --- a/docs/part-2/1_xds-server.md +++ b/docs/part-2/1_xds-server.md @@ -40,135 +40,10 @@ been integrated into AGL SDK docker container. >**Note:** For more info about AGL SDK docker container, please refer to [AGL SDK Quick Setup](http://docs.automotivelinux.org/docs/getting_started/en/dev/reference/setup-sdk-environment.html) -### Get the container - -Load the pre-build AGL SDK docker image including `xds-server`: - -```bash -wget -O - http://iot.bzh/download/public/XDS/docker/docker_agl_worker-xds-latest.tar.xz | docker load -``` - -### List container - -You should get `docker.automotivelinux.org/agl/worker-xds:X.Y` image - -```bash -# List image that we just built -docker images | grep worker-xds - -docker.automotivelinux.org/agl/worker-xds 5.0 02616f565535 5 hours ago 640MB -``` - ### Start xds-server within the container -Use provided script to create a new docker image and start a new container: - -```bash -# Get script -wget -O xds-docker-create-container.sh 'https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-server.git;a=blob_plain;f=scripts/xds-docker-create-container.sh;hb=master' - -# Create new XDS worker container -bash ./xds-docker-create-container.sh - -# Check that new container is running -docker ps | grep worker-xds -f67079db4339 docker.automotivelinux.org/agl/worker-xds:5.0 "/usr/bin/wait_for..." About a minute ago Up 34 seconds 0.0.0.0:8000->8000/tcp, 0.0.0.0:69->69/udp, 0.0.0.0:10809->10809/tcp, 0.0.0.0:2222->22/tcp agl-xds-HOSTNAME-0-USERNAME -``` - -This container exposes following ports: - -- 8000 : `xds-server` to serve XDS webapp -- 69 : TFTP -- 2222 : ssh - -<!-- note --> -**Note:** - -You can add a new shared directory using `--volume` option in order -to use for example with Path-Mapping folder type. - -```bash -# Create new XDS worker container and share extra '$HOME/my-workspace' directory -bash ./xds-docker-create-container.sh --volume /my-workspace:$HOME/my-workspace -``` - -You can change docker used port with `-id` option - -```bash -# Create new XDS worker container with a different port number -bash ./xds-docker-create-container.sh -id ${ID} - -# Check that new container is running -docker ps | grep worker-xds -f67079db4339 docker.automotivelinux.org/agl/worker-xds:5.0 "/usr/bin/wait_for..." About a minute ago Up 34 seconds 0.0.0.0:(2222+ID)->22/tcp, 0.0.0.0:(69+ID)->69/udp, 0.0.0.0:(8000+ID)->8000/tcp, 0.0.0.0:(10809+ID)->10809/tcp agl-xds-HOSTNAME-ID-USERNAME -``` - -<!-- endnote --> - -#### 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. -<!-- 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: - -```bash -# Set docker container name to use (usually agl-xds-xxx where xxx is USERNAME@MACHINENAME-IDX-NAME) -export CONTAINER_NAME=agl-xds-seb@laptop-0-seb -docker ps | grep ${CONTAINER_NAME} || echo "ERROR: No container name \"${CONTAINER_NAME}\" please set a valid CONTAINER_NAME before you continue" - -# First kill all processes of devel user (including running xds-server) -docker exec ${CONTAINER_NAME} bash -c "/bin/loginctl kill-user devel" - -# Change user and group id inside docker to match your ids -docker exec ${CONTAINER_NAME} bash -c "usermod -u $(id -u) devel" -docker exec ${CONTAINER_NAME} bash -c "groupmod -g $(id -g) devel" - -# Update some files ownership -docker exec ${CONTAINER_NAME} bash -c "chown -R devel:devel /home/devel /tmp/xds*" - -# Restart devel autologin service -docker exec ${CONTAINER_NAME} bash -c "systemctl start autologin" - -# Restart xds-server as a service (ssh port 2222 may depend on your container ID) -ssh -p 2222 devel@localhost -- "systemctl --user start xds-server" -``` - -## 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 to a basic web -application: - -```bash -xdg-open http://localhost:8000 -``` - -If needed you can status / stop / start it manually using following commands: - -```bash -# Status XDS server: -ssh -p 2222 devel@localhost systemctl --user status xds-server.service - -# Stop XDS server -ssh -p 2222 devel@localhost systemctl --user stop xds-server.service - -# Start XDS server -ssh -p 2222 devel@localhost systemctl --user start xds-server.service - -# Get XDS server logs -ssh -p 2222 devel@localhost journalctl --user --unit=xds-server.service --output=cat -``` +See [Installation based on Docker container](../part-1/2_install-xds-server.html#installation-based-on-docker-container) +chapter. ### Manually Start XDS server @@ -188,7 +63,7 @@ If needed you can change default setting by defining specific environment variables file ```bash -ssh -p 2222 devel@localhost vim /etc/default/xds-server +ssh -t -p 2222 devel@localhost vim /etc/default/xds-server ``` For example to control log level, just set LOG_LEVEL env variable. @@ -203,10 +78,8 @@ knowing that supported *level* are: - debug ```bash -ssh -p 2222 devel@localhost -echo 'LOG_LEVEL=debug' | sudo tee --append /etc/default/xds-server > /dev/null -systemctl --user restart xds-server.service -tail -f /tmp/xds-server/logs/xds-server.log +docker exec ${CONTAINER_NAME} bash -c "echo 'LOG_LEVEL=debug' >> /etc/default/xds-server" +ssh -p 2222 devel@localhost -- "systemctl --user restart xds-server" ``` ### SDK cross-toolchain Management @@ -412,28 +285,26 @@ Refer to [Prerequisites chapter](./0_Abstract.html#prerequisites) for more detai Create a GOPATH variable(must be a full path): ```bash - export GOPATH=$(realpath ~/workspace_go) +export GOPATH=$(realpath ~/workspace_go) ``` -SEB Rework GOPATH inscrutions - Clone this repo into your `$GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds` and use delivered Makefile: ```bash export GOPATH=${GOPATH}:${ROOTDIR} - mkdir -p $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds - cd $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds - git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-server - # or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-server - cd xds-server - make all +mkdir -p $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds +cd $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds +git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-server +# or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-server +cd xds-server +make all ``` And to install `xds-server` (by default in `/opt/AGL/xds/server`): ```bash - make install +make install ``` <!-- warning --> @@ -518,6 +389,18 @@ All fields are optional and example below corresponds to the default values. >Environment variables are supported by using `${MY_VAR}` syntax. > +When `xds-server` is started as a systemd service, default environment variables +are set into `/etc/default/xds-server` file. + +`xds-server` configuration is also driven by a JSON config file (`server-config.json`), +and default JSON config is `/etc/xds/server/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/server-config.json` +<!-- endnote --> + #### Disable syncthing `CloudSync` synchronization type based on `syncthing` tool can be disabled by @@ -540,6 +423,13 @@ Here is a JSON configuration file example where syncthing key as been renamed: On benefit to do that is to increase XDS-Server startup time. +<!-- note --> +**Note:** + +- `CloudSync` (AKA syncthing) synchronzation type can also be disabled when `"syncthing"` key is not defined in JSON configuration file. + +<!-- endnote --> + ## Debugging ### XDS server architecture @@ -548,27 +438,31 @@ The server part is written in *Go* and web app (basic HTML) in *Angular4*. ```bash | -+-- bin/ where xds-server binary file will be built ++-- 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 | -+-- conf.d Linux configuration and startup files (systemd user service) ++-- lib/ # sources of server part (Go) | -+-- glide.yaml Go package dependency file ++-- LICENSE # XDS server license | -+-- lib/ sources of server part (Go) ++-- main.go # main entry point of of Web server (Go) | -+-- main.go main entry point of of Web server (Go) ++-- Makefile # makefile including | -+-- Makefile makefile including ++-- README.md # | -+-- README.md this readme ++-- scripts/ # hold various scripts used for installation or startup | -+-- scripts/ hold various scripts used for installation or startup ++-- test/ # XDS test suite | -+-- tools/ temporary directory to hold development tools (like glide) ++-- tools/ # temporary directory to hold development tools (like glide) | -+-- vendor/ temporary directory to hold Go dependencies packages ++-- vendor/ # temporary directory to hold Go dependencies packages | -+-- webapp/ source client basic web application ++-- 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 ce03ae7..1429715 100644 --- a/docs/part-2/2_xds-agent.md +++ b/docs/part-2/2_xds-agent.md @@ -12,6 +12,7 @@ used to remotely cross build applications. ## Configuration xds-agent configuration is driven by a JSON config file. + The tarball mentioned in previous section includes this file with default settings. Here is the logic to determine which conf file will be used: @@ -52,7 +53,9 @@ below corresponds to the default values): } ``` ->**Note:** environment variables are supported by using `${MY_VAR}` syntax. +>**Note:** +> +>environment variables are supported by using `${MY_VAR}` syntax. ## Start-up @@ -62,7 +65,9 @@ Simply to start `xds-agent` executable ./xds-agent & ``` ->**Note:** if need be, you can increase log level by setting option +>**Note:** +> +>If need be, you can increase log level by setting option `--log <level>`, supported *level* are: panic, fatal, error, warn, info, debug. You can now use XDS dashboard and check that connection with `xds-agent` is up. @@ -94,7 +99,9 @@ And to install xds-agent (by default in `/usr/local/bin`): make install ``` ->**Note:** Used `DESTDIR` to specify another install directory +>**Note:** +> +>Used `DESTDIR` to specify another install directory >```bash >make install DESTDIR=$HOME/opt/xds-agent >``` @@ -158,10 +165,15 @@ The agent part is written in *Go* and the webapp / dashboard is in *typescript + 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. +>**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 diff --git a/docs/part-2/3_xds-cli.md b/docs/part-2/3_xds-cli.md index a4ccca5..ade25f8 100644 --- a/docs/part-2/3_xds-cli.md +++ b/docs/part-2/3_xds-cli.md @@ -6,9 +6,11 @@ `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. +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: @@ -19,7 +21,9 @@ options or using a config file knowing that the following priority order is used 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 --> @@ -35,24 +39,24 @@ __`--log|-l` option or `XDS_LOGLEVEL` env variable__ Logging level, supported levels are: -- panic, -- fatal, -- error, -- warn, -- info, +- panic +- fatal +- error +- warn +- info - debug Default level is "error". -__`--rpath` option or `XDS_PATH` env variable__ +**`--rpath` option or `XDS_PATH` env variable** Relative path into 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_AGENT_URL` env variable__ +**`url` option or `XDS_AGENT_URL` env variable** Local XDS agent url (default: "localhost:8800") @@ -61,6 +65,7 @@ Local XDS agent url (default: "localhost:8800") ### projects `projects` (short `prj`) command should be used to managed XDS projects. + This command supports following sub-commands: ```bash @@ -87,6 +92,7 @@ xds-cli prj rm 8e49 ### sdks `sdks` (alias `sdk`) command should be used to managed cross SDKs. + This command supports following sub-commands: ```bash @@ -108,23 +114,25 @@ 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. +`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**)__ +**`--id` option or `XDS_PROJECT_ID` env variable (**mandatory option**)** project ID you want to build -__`--rpath` (short `-p`) or `XDS_RPATH` env variable__ +**`--rpath` (short `-p`) or `XDS_RPATH` env variable** relative path into project -__`--sdkid` (alias `--sdk`) or `XDS_SDK_ID` env variable (**mandatory option**)__ +**`--sdkid` (alias `--sdk`) or `XDS_SDK_ID` env variable (**mandatory option**)** -Cross Sdk ID to use to build project +Cross Sdk ID to use to build project. Here are some usage examples: @@ -140,7 +148,8 @@ 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 : + +You can specify the url using `--url` option : ```bash xds-cli --url=http://localhost:8800 exec --id=4021 --sdkid=c226 -- "cd build && make all" @@ -188,10 +197,15 @@ Clone this repo into your `$GOPATH/src/gerrit.automotivelinux.org/gerrit/src/xds 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 +>**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. +> +>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 diff --git a/docs/part-2/4_xds-gdb.md b/docs/part-2/4_xds-gdb.md index 6185ce9..96f5498 100644 --- a/docs/part-2/4_xds-gdb.md +++ b/docs/part-2/4_xds-gdb.md @@ -22,8 +22,9 @@ used to remotely cross build applications. ## Configuration - `xds-gdb` configuration is defined by variables (see listed below). - These variables may be set using : +`xds-gdb` configuration is defined by variables (see listed below). + +These variables may be set using: - environment variables (inherited), - or a config file set with `XDS_CONFIG` environment variable, for example: @@ -37,11 +38,15 @@ used to remotely cross build applications. ### Configuration Variables - `XDS_CONFIG` : - Config file defining `XDS_xxx` configuration variables. Variables of this file - will overwrite inherited environment variables. Variables definition may be - prefixed or not by "export" keyword. - Here is an example of config file +`XDS_CONFIG` + +Config file defining `XDS_xxx` configuration variables. + +Variables of this file will overwrite inherited environment variables. + +Variables definition may be prefixed or not by "export" keyword. + +Here is an example of config file: ```bash cat $HOME/myProject/xds-gdb.env @@ -53,7 +58,16 @@ export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03 `XDS_LOGLEVEL` -Set logging level (supported levels: panic, fatal, error, warn, info, debug) +Set logging level + +Supported levels: + +- panic +- fatal +- error +- warn +- info +- debug `XDS_LOGFILE` @@ -83,6 +97,7 @@ Local XDS agent url (default `http://localhost:8800`) Above `XDS_xxx` variables may also be defined within gdb init command file (see --command or -x option of genuine Gdb). + You must respect the following syntax: commented line including `:XDS-ENV:` tag Example of gdb init file where we define project and sdk ID: |