diff options
| author |   Scott Rifenbark <srifenbark@gmail.com> | 2019-04-23 15:06:30 -0700 |
|---|---|---|
| committer | Scott Rifenbark <srifenbark@gmail.com> | 2019-04-23 15:06:30 -0700 |
| commit | c4cabee5bacd0412ee29853a7f4d51b39b90089a (patch) | |
| tree | 045678743323293b0f6292693889bd0398fe515e /docs/part-1 | |
| parent | 268d0f7fc3b5ef9ec4c2882c9defcd7815495603 (diff) | |
XDS install and create app: New files and content.
Change-Id: I8021d3096e546bb0bb77a272dd5bcb0ea4dbf209
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Diffstat (limited to 'docs/part-1')
22 files changed, 1373 insertions, 1001 deletions
diff --git a/docs/part-1/0_Abstract.md b/docs/part-1/0_Abstract.md deleted file mode 100644 index c85b0f3..0000000 --- a/docs/part-1/0_Abstract.md +++ /dev/null @@ -1,42 +0,0 @@ -# Getting Started for Users - -## Abstract - -X(cross) Development System (XDS) is set of tools that provide a multi-platform -for cross development with near-zero installation. - -This documentation is available : - -- online: [http://docs.automotivelinux.org/docs/en/master/devguides/#xcross-development-system-user's-guide](../../../#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 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: - -- 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 -- MacOS - -The following 3 main configurations are supported: - -- standalone (or local) config -- On-Premise (local network) -- SaaS (Cloud based) - -{:: style="width:98%;"} diff --git a/docs/part-1/1-1_install-xds-server-docker.md b/docs/part-1/1-1_install-xds-server-docker.md deleted file mode 100644 index 3589774..0000000 --- a/docs/part-1/1-1_install-xds-server-docker.md +++ /dev/null @@ -1,201 +0,0 @@ -# Installation based on Docker container - -## Docker container prerequisites - -Docker is installed on the host machine, please refer to [Docker documentation](https://docs.docker.com/engine/installation/) for more details. - -<!-- section-warning --> ->**Warning:** -> ->Your user must be part of docker group. You can use following command to check it : ->```bash ->groups | grep docker ->``` -> ->If not, please refer to [docker post install instructions](https://docs.docker.com/install/linux/linux-postinstall/). -> ->Here are a short recap of commands you must execute : -> ->```bash ->sudo groupadd docker ->sudo usermod -aG docker $USER -># Log out and log back in so that your group membership is re-evaluated -> -># You may also need to start docker service manually ->sudo service docker start -># or ->sudo systemctl start docker ->``` -> -<!-- end-section-warning --> - -## 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 -``` - -You should get `docker.automotivelinux.org/agl/worker-xds:X.Y` image - -```bash -# List image that we just load -docker images "docker.automotivelinux.org/agl/worker-xds*" - -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 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 (-id option value should be changed when you get port conflict error) -bash ./xds-docker-create-container.sh -id 0 - -# 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:10809->10809/tcp, 0.0.0.0:2222->22/tcp agl-xds-HOSTNAME-0-USERNAME -``` - -This container exposes following ports: - -| Port number | Description | -|-------------|---------------------------------------------| -| 8000 | `xds-server`: serve XDS webapp and REST API | -| 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 | - -### Optional settings - -**`--volume`** - -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 -``` - -**`--id`** - -You can change docker used port with `-id` option - -```bash -# Create new XDS worker container with a different port number -ID=3 -bash ./xds-docker-create-container.sh -id ${ID} - -# Check that new container is running (in example below id has been set to 3) -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:2225->22/tcp, 0.0.0.0:8003->8000/tcp, 0.0.0.0:10892->10809/tcp agl-xds-3 -``` - -<!-- section-warning --> ->**Warning:** -> Changing container id will impact the port number used to connect to xds-server. -> So you may need to adjust xds-agent config in order to match the right port number. -> ->In above example, with `id` set to 3, the export port number will be `8003` and >consequently ->you must define xds-server `url` in `xds-agent` configuration as follow: -> ->```json ->{ -> ... -> "xdsServers": [ -> { -> "url": "http://localhost:8003" -> } -> ], -> ... ->} ->``` -> ->See also [xds-agent configuration](../part-2/2_xds-agent/2_config.html) chapter for >more details. -<!-- end-section-warning --> - -### Manually setup docker user id - -<!-- section-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. -<!-- end-section-note --> - -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 user 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 -``` - -`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) - -<!-- section-note --> -Please refer to [xds-server configuration](../part-2/1_xds-server/2_config.html) chapter for additional info about xds-server settings. -<!-- end-section-note --> diff --git a/docs/part-1/1-2_install-xds-server-vm.md b/docs/part-1/1-2_install-xds-server-vm.md deleted file mode 100644 index 3bf2f61..0000000 --- a/docs/part-1/1-2_install-xds-server-vm.md +++ /dev/null @@ -1,83 +0,0 @@ -# Installation based on Virtual Machine appliance - -## Virtual Machine appliance prerequisites - -> VirtualBox is installed on the host machine - -please refer to [VirtualBox documentation](https://www.virtualbox.org/wiki/Downloads) for more details. - -## Get the appliance - -Load the pre-build AGL SDK appliance image including `xds-server`: - -```bash -wget http://iot.bzh/download/public/XDS/appliance/xds-vm-debian9_latest.ova -``` - -## Clean old appliance - -You must have one and one xds appliance only. - -So, first remove the oldest xds appliance if needed. - -```bash -# Get the virtual machine name -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 -``` - -## Create and start a new appliance - -Used provided script to create a new appliance or you can use VirtualBox GUI: - -```bash -# Import image into VirtualBox -VBoxManage import ./xds-vm-debian9_latest.ova - -# Check import result -VDS_VMNAME=$(VBoxManage list vms | grep xds-vm-debian | cut -d "\"" -f2) -echo ${VDS_VMNAME} -``` - -Add share folder to appliance, **mandatory** to use **path-mapping sharing type for projects**: - -```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 -``` - -Start appliance - -```bash -# Start XDS appliance -[ -n ${VDS_VMNAME} ] && VBoxManage startvm ${VDS_VMNAME} -``` - -## Appliance settings - -This image exposes following network ports (NAT mode): - -- 8000 : `xds-server` to serve XDS basic web page -- 2222 : ssh - -## Check if xds-server is running - -`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 basic web page that gives you some instructions: - -```bash -# if container/appliance 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.html) diff --git a/docs/part-1/1-3_install-xds-server-native.md b/docs/part-1/1-3_install-xds-server-native.md deleted file mode 100644 index 4a52b55..0000000 --- a/docs/part-1/1-3_install-xds-server-native.md +++ /dev/null @@ -1,86 +0,0 @@ -# Native installation - -You can chose to install xds-server 'natively' instead of within a docker -container but note that only Linux host OSes are supported and tested for native -installation ! - -You also need to install `python3` to allow `xds-server` to manage AGL sdks. - -## 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} -export DISTRO="xUbuntu_16.04" - -# AGL_RELEASE can be set to {AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master} -export AGL_RELEASE="AGL_Master" - -wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/Release.key | sudo apt-key add - -sudo bash -c "cat >> /etc/apt/sources.list.d/AGL.list <<EOF -deb http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/ ./ -EOF" - -sudo apt-get update -sudo apt-get install agl-xds-server - -# Install python3 -sudo apt-get install python3 -``` - -## Install packages for openSUSE distro type - -```bash -# DISTRO can be set to {openSUSE_Leap_42.3, openSUSE_Leap_15.0, openSUSE_Tumbleweed} -export DISTRO="openSUSE_Leap_15.0" - -# AGL_RELEASE can be set to {AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master} -export AGL_RELEASE="AGL_Master" - -sudo zypper ar http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/isv:LinuxAutomotive:${AGL_RELEASE}.repo - -sudo zypper ref -sudo zypper install agl-xds-server - -# Install python3 -sudo zypper install python3 -``` - -## Configure xds-server - -<!-- section-note --> -**Optional step**: skip this chapter if you plan to use default settings -<!-- end-section-note --> - -Please refer to [Configuration chapter of xds-server](../part-2/1_xds-server/2_config.html) -documentation for more details about JSON configuration file. - -## Start/Stop xds-server - -`xds-server` can be managed as a systemd service with the following commands: - -```bash -# Status XDS server: -systemctl --user status xds-server.service - -# Stop XDS server -systemctl --user stop xds-server.service - -# Start XDS server -systemctl --user start xds-server.service - -# Get XDS server logs -systemctl --user --unit=xds-server.service --output=cat -``` - -To check if xds-server is correctly install and running, you can access the web -interface, using a web browser : - -```bash -xdg-open http://localhost:8000 -``` - -or get the current version using the following curl command: - -```bash -curl http://localhost:8000/api/v1/version -``` diff --git a/docs/part-1/1_install-xds-server.md b/docs/part-1/1_install-xds-server.md deleted file mode 100644 index 5b9f776..0000000 --- a/docs/part-1/1_install-xds-server.md +++ /dev/null @@ -1,18 +0,0 @@ -# Installing XDS server - -Depending of your configuration, this step is necessary or not. - -In other words **you are a developer and plan to use/connect to an existing `xds-server`** -running on your local network (On-Premise config) or in the Cloud (SaaS config), -**you don't need to install the server part and you can skip this step**. - -For others (standalone config or administrators that want to install an -On-Premise solution) xds-server must be installed. - -Several installation types are supported: - -| Install type | Supported OS | Section to refer | -|--------------|--------------|------------------| -| Container | Linux or MacOS | [see Installation based on Docker container](./1-1_install-xds-server-docker.html) | -| Virtual Machine | Linux, MacOS or Windows | [see Installation based on VirtualBox appliance](./1-2_install-xds-server-vm.html) | -| Native | Linux | [see Native installation](./1-3_install-xds-server-native.html) | diff --git a/docs/part-1/2_install-client.md b/docs/part-1/2_install-client.md deleted file mode 100644 index 44906c0..0000000 --- a/docs/part-1/2_install-client.md +++ /dev/null @@ -1,113 +0,0 @@ -# Installing XDS client tools - -[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: - -- 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: - -- [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. - -## 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 } -export DISTRO="xUbuntu_16.04" - -# AGL_RELEASE can be set to {AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master} -export AGL_RELEASE="AGL_Master" - -wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/Release.key | sudo apt-key add - -sudo bash -c "cat >> /etc/apt/sources.list.d/AGL.list <<EOF -deb http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/ ./ -EOF" - -sudo apt-get update -sudo apt-get install agl-xds-agent -sudo apt-get install agl-xds-cli -sudo apt-get install agl-xds-gdb -``` - -## Install packages for openSUSE distro type - -```bash -# DISTRO can be set to {openSUSE_Leap_42.3, openSUSE_Leap_15.0, openSUSE_Tumbleweed} -export DISTRO="openSUSE_Leap_15.0" - -# AGL_RELEASE can be set to {AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master} -export AGL_RELEASE="AGL_Master" - -sudo zypper ar http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/isv:LinuxAutomotive:${AGL_RELEASE}.repo - -sudo zypper ref -sudo zypper install agl-xds-agent -sudo zypper install agl-xds-cli -sudo zypper install agl-xds-gdb -``` - -## Install for other platforms (Windows / MacOS) - -- Install `xds-agent`: - - 1. Download the latest released tarball from github [releases page](https://github.com/iotbzh/xds-agent/releases). - - 1. Then unzip the tarball any where into your local disk (for example: `/opt/AGL/xds` or `C:\AGL\xds`). - - 1. Add binary to PATH: - - - MacOs: create the .bash_profile `nano .bash_profile` and add `export PATH="/opt/AGL/xds/xds-agent:$PATH` - - Windows: change the system path via control panel or system settings or - `setx path "C:\AGK\xds\xds-agent;%path%"` - -- repeat the previous steps to install other tools depending of your needs: - - `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 - -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, `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 - -# Get status and log of xds-agent service -systemctl --user status xds-agent.service -``` - -On **MacOS** (or Linux), you can start-it manually using following commands: - -```batch -/opt/AGL/bin/xds-agent -``` - -On **Windows**, you can start-it manually using following commands: - -```batch -C:\AGL\xds\xds-agent\xds-agent.exe -``` diff --git a/docs/part-1/4-1_build-first-app-setup.md b/docs/part-1/4-1_build-first-app-setup.md deleted file mode 100644 index 9224a77..0000000 --- a/docs/part-1/4-1_build-first-app-setup.md +++ /dev/null @@ -1,40 +0,0 @@ -# Setup - -## Sources Sharing Methods - -### What are possible ways to share source trees ? - -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`. - -There are two possible methods to share sources between your host and the XDS server: - -* Cloud sync: implies your local directory will be sent to and replicated on the server. This method lets you clone project anywhere on your local disk, -* Path mapping: apply when the xds-server is running locally. This method uses a volume shared between your host and the server, typically `$HOME/xds-workspace` directory. - It is much more efficient as there is no replication onto the server ; but you must clone project under the shared directory (`$HOME/xds-workspace` is a good choice - because it is shared by default. To create more shared volumes, See --volume option of [container creation script](./1-1_install-xds-server-docker.html#create-and-start-a-new-container) ) - -### Which one should I choose ? - -It depends on your [deployment setup](./0_Abstract.html) (Standalone, On-Premise or SaaS). - -* Standalone : use local path mapping. It makes no sense to use cloud sync as it would add pointless overhead. -* On-Premise : use Clound Sync. -* SaaS : use Cloud Sync. This is the only way to achieve source sharing in this deployment setup. - -<!-- section-note --> -**Note:** : [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) project is an AGL -project based on [cmake-apps-module](https://git.automotivelinux.org/src/cmake-apps-module/) (refer to install cmake module [instructions](../../cmakeafbtemplates/dev_guide/installing-cmake.html)). This CMake templating, used to develop application -with the AGL Application Framework, will automatically generate makefile rules -(eg. `remote-target-populate`) or scripts (eg. `build/target/xxx` scripts). - -For more info about app-template, please refer to [this documentation](../../../#using-the-cmake-applications-module). - -<!-- end-section-note --> - -## Clone project - -```bash -cd $HOME/xds-workspace -git clone --recursive https://github.com/iotbzh/helloworld-native-application.git -``` diff --git a/docs/part-1/4-2_build-first-app-cmd.md b/docs/part-1/4-2_build-first-app-cmd.md deleted file mode 100644 index c878d08..0000000 --- a/docs/part-1/4-2_build-first-app-cmd.md +++ /dev/null @@ -1,121 +0,0 @@ -# Build using command line tool - -## Declare project - -Use XDS command line tool named [xds-cli](../part-2/3_xds-cli/0_abstract.html) 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) - -## Build from command line - -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 `xds-cli` tool and `projects list` command (short: `prj ls`): - -```bash -xds-cli prj ls -ID Label LocalPath -f9904f70-d441-11e7-8c59-3c970e49ad9b Project_helloworld-service /home/seb/xds-workspace/helloworld-service -4021617e-ced0-11e7-acd2-3c970e49ad9b Project_helloworld-native-application /home/seb/xds-workspace/helloworld-native-application -``` - -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. - -<!-- section-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 -<!-- end-section-note --> - -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: - -```bash -# First, grab your target IP address, or it's DNS name -export TARGET_ADDRESS=<target_adress> - -# Go into your project directory and create a build directory -cd $MY_PROJECT_DIR -mkdir build - -# Generate build system using cmake -# RSYNC_* variables must be set to allow deployment/populate widgets on target (see app-template doc for more info) -xds-cli exec --id=4021617e --sdkid=c226821b -- "export RSYNC_TARGET=root@${TARGET_ADDRESS} ; export RSYNC_PREFIX=/opt ; cd build && cmake .." - -# Build the project -xds-cli exec --id=4021617e --sdkid=c226821b -- "cd build && make widget" -``` - -<!-- section-note --> -**Note:** If you use `&&`, `||` or `;` statement in the executed command line, -you need to double quote the command, for example `"cd build && make`. -<!-- end-section-note --> - -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. - -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: - -```bash -# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application -cd $MY_PROJECT_DIR - -# Edit and potentially adapt xds-project.conf file that has been created -# automatically on project declaration using XDS Dashboard -cat xds-project.conf - # XDS project settings - export XDS_AGENT_URL=localhost:8800 - export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b - export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03 - -# Create build directory and invoke cmake and then build project -xds-cli exec --config=./xds-project.conf -- "mkdir -p build && cd build && cmake .." -cd build && xds-cli exec --config=../xds-project.conf -- "make all" - -# Or equivalent by first sourcing conf file (avoid to set --config option) -source xds-project.conf -xds-cli exec "mkdir -p build && cd build && cmake .." -cd build && xds-cli exec "make all" -``` - -<!-- section-note --> -**Note:** all parameters after a double dash (--) are considered as the command -to execute. -<!-- end-section-note --> diff --git a/docs/part-1/4-3_build-first-app-dashboard.md b/docs/part-1/4-3_build-first-app-dashboard.md deleted file mode 100644 index 076be94..0000000 --- a/docs/part-1/4-3_build-first-app-dashboard.md +++ /dev/null @@ -1,53 +0,0 @@ -# Build using XDS Dashboard - -## Declare project - -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` - -Open the right sidebar and select `Projects` entry to open project page and then -create/declare a new project by with the plus icon: - -{:: style="margin:auto; display:flex"} - -<!-- pagebreak --> - -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`. - -<!-- section-note --> -**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](./1-1_install-xds-server-docker.html) ), -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. -<!-- end-section-note --> - -## Build from XDS dashboard - -<!-- section-note --> -**Note:** _helloworld-native-application_ requires few configuration items to be able to walkthrough the whole process. -To pass some environment variables, use the `Settings` window in the `Build` tab. The `Env variables` field allows to pass a list of environment variables (semi-colon separated) that will be set on the server prior to any build action. -For the _helloworld-native-application_ you have to pass something like `RSYNC_TARGET=root@mytarget;RSYNC_PREFIX=/opt` (please replace `mytarget` by a valid target IP address or DNS name entry). -<!-- end-section-note --> - -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%; max-width:600px; margin:auto; display:flex"} diff --git a/docs/part-1/4-4_build-first-app-ide.md b/docs/part-1/4-4_build-first-app-ide.md deleted file mode 100644 index a3fa5a8..0000000 --- a/docs/part-1/4-4_build-first-app-ide.md +++ /dev/null @@ -1,194 +0,0 @@ -# Build using a source code editor / IDE - -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 -# create file at root directory of your project -# for example: -# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application -cat > $MY_PROJECT_DIR/xds-project.conf << EOF - 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 -``` - -## NetBeans - -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 -**Run -> Set Project Configuration**. - -__Netbeans 8.x :__ - -- Open menu **Tools** -> **Options** - - Open **C/C++** tab, in **Build Tools** sub-tab, click on **Add** button: - - {:: style="width:90%; max-width:700px; margin:auto; display:flex"} - - - Then, you should set **Make Command** and **Debugger Command** to point to xds tools: - - {:: style="width:90%; max-width:700px; margin:auto; display:flex"} - - - Finally click on **OK** button. - -- Now create we first declare project into NetBeans and create first a native - configuration. To do that, open menu **File** -> **New Project** - -- Select **C/C++ Project with Existing Sources** ; - Click on **Next** button - -- Specify your project directory and set **Select Configuration Mode** to - **Custom**. Keep **Tool Collection** to **Default GNU** in order to create a - *native configuration* based on native GNU GCC. Finally click on **Next** button. - - {:: style="width:90%; max-width:700px; margin:auto; display:flex"} - -- Just update **Run in Folder** field and add `build_native` suffix so that - resulting build files will be located into `build_native` sub-directory. - Keep all others settings to default value and click on **Next** button. - - {:: style="width:90%; max-width:700px; margin:auto; display:flex"} - -- Click several times on **Next button** (always keep default settings) and - click on **Finish** button to complete creation of native configuration. - -- Now we will create a **cross configuration** based on XDS tools. - Edit project properties (using menu **File** -> **Project Properties**) to add a new configuration that will use XDS to cross-compile your application for example for a Renesas Gen3 board. - - - in **Build** category, click on **Manage Configurations** button and then **New** button to add a new configuration named for example "Gen3 board" - - {:: style="width:90%; max-width:700px; margin:auto; display:flex"} - - - Click on **Set Active** button - - - Select **Pre-Build** sub-category, and set: - - Working Directory: `build_gen3` - - 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-cli exec -c ../xds-project.conf -- make remote-target-populate` - - Clean Command: `xds-cli exec -c ../xds-project.conf -- make clean` - - {:: style="width:90%; max-width:700px; margin:auto; display:flex"} - - - Select **Run** sub-category, and set: - - Run Command: `target/start-on-root@renesas-gen3.sh` - - Run Directory: `build-gen3` - - {:: style="width:90%; max-width:700px; margin:auto; display:flex"} - - - Click on **OK** button to save settings - -By changing configuration from **Default** to **Gen3 board**, you can now simply -compile your helloworld application natively (**Default** configuration) or -cross-compile your application through XDS for the Renesas Gen3 board -(**Gen3 board** configuration). - -## Visual Studio Code - -Open your project in VS Code - -```bash -cd $MY_PROJECT_DIR -code . & -``` - -Add new tasks : press `Ctrl+Shift+P` and select the `Tasks: Configure Task` -command and you will see a list of task runner templates. - -And define your own tasks, here is an example to build -[helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) -AGL helloworld application based on cmake template. - -```json -{ - "version": "2.0.0", - "type": "shell", - "presentation": { - "reveal": "always" - }, - "tasks": [ - { - "label": "clean", - "type": "shell", - "command": "/bin/rm -rf ${workspaceFolder}/build/* && mkdir -p build && echo Cleanup done.", - "problemMatcher": [] - }, - { - "label": "pre-build", - "type": "shell", - "group": "build", - "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ../", - "problemMatcher": [ - "$gcc" - ] - }, - { - "label": "build", - "type": "shell", - "group": "build", - "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- make widget", - "problemMatcher": [ - "$gcc" - ] - }, - { - "label": "populate", - "type": "shell", - "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- make widget-target-install", - "problemMatcher": [] - } - ] -} -``` - -To run a task : press `Ctrl+Shift+P`, select the `Tasks: Run task` and then -select for example `pre-build` to trigger pre-build task. - -> **Note:** -> -> You can also add your own keybindings to trig above tasks, for example: -> -> ```json -> // Build -> { -> "key": "alt+f9", -> "command": "workbench.action.tasks.runTask", -> "args": "clean" -> }, -> { -> "key": "alt+f10", -> "command": "workbench.action.tasks.runTask", -> "args": "pre-build" -> }, -> { -> "key": "alt+f11", -> "command": "workbench.action.tasks.runTask", -> "args": "build" -> }, -> { -> "key": "alt+f12", -> "command": "workbench.action.tasks.runTask", -> "args": "populate" -> }, -> ``` -> -> More details about VSC keybindings [here](https://code.visualstudio.com/docs/editor/tasks#_binding-keyboard-shortcuts-to-tasks) -> -> More details about VSC tasks [here](https://code.visualstudio.com/docs/editor/tasks) - -## Qt Creator - -Please refer to [agl-hello-qml](https://github.com/radiosound-com/agl-hello-qml#clone--build-project) project. -Thanks to Dennis for providing this useful example. - -## Others IDE - -*Coming soon...* diff --git a/docs/part-1/4_build-first-app.md b/docs/part-1/4_build-first-app.md deleted file mode 100644 index 637a6ab..0000000 --- a/docs/part-1/4_build-first-app.md +++ /dev/null @@ -1,21 +0,0 @@ -# Create your first AGL application - -## Prerequisites - -- `xds-server` is running locally in a docker container or is accessible on your - network (see previous chapter: [Installing XDS server](./1_install-xds-server.html)) -- `xds-agent` is running locally on your machine - (see previous chapter: [Installing XDS client tools](./2_install-client.html) ) -- one or more SDK have been installed (see previous chapter: [Installing AGL SDKs](./3_install-sdks.html)) -- 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. - ---- - -Links to subchapters : - -- [Setup](./4-1_build-first-app-setup.html) -- [Build using command line tool](./4-2_build-first-app-cmd.html) -- [Build using XDS Dashboard](./4-3_build-first-app-dashboard.html) -- [Build using a source code editor / IDE](./4-4_build-first-app-ide.html) diff --git a/docs/part-1/client-part.md b/docs/part-1/client-part.md new file mode 100644 index 0000000..b92cc0c --- /dev/null +++ b/docs/part-1/client-part.md @@ -0,0 +1,143 @@ +# Client Part + +The client part of the X(cross) Development System (XDS) is +a set of XDS client tools that must run on your development host. + +The tools that comprise the client part are: `xds-agent`, `xds-cli`, and `xds-gdb`. +Of the three, only `xds-agent`, whose source code can be found +[here](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-agent.git) +in Gerrit is required. + +<!-- section-note --> +**NOTE:** + +The binary version is also available as standard Linux packages +or as a portable Windows archive (i.e. Zip). +<!-- end-section-note --> + +You should establish the following chain: + +- XDS Client: (i.e. `xds-cli` or XDS Dashboard). +- XDS Agent: (`xds-agent`) running on your development host. +- XDS Server: (`xds-server`) running on a remote server and/or in a container. + +HTTP and Websocket protocols establish exchanges between these three tools. + +You can change the default URL/port shown in the following illustration by using +configuration files. + + + +<!-- section-note --> +**NOTE:** +Installation of the XDS client tools `xds-cli` and `xds-gdb` is +optional: + +- [xds-cli](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-cli.git) : command line tool to used to interact with XDS (also used by IDE integration). +- [xds-gdb](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-gdb.git) : requested for debugging application. +<!-- end-section-note --> + +## Install Packages for Debian + +Use the following commands to install packages for the client part +on Debian-based systems: + +```bash +# Set DISTRO (e.g. xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04, xUbuntu_18.04, Debian_8.0, Debian_9.0) +export DISTRO="xUbuntu_18.04" + +# Set AGL_RELEASE (AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master) +export AGL_RELEASE="AGL_Master" + +wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/Release.key | sudo apt-key add - +sudo bash -c "cat >> /etc/apt/sources.list.d/AGL.list <<EOF +deb http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/ ./ +EOF" + +sudo apt-get update +sudo apt-get install agl-xds-agent +sudo apt-get install agl-xds-cli +sudo apt-get install agl-xds-gdb +``` + +## Install Packages for OpenSUSE + +Use the following commands to install packages for the client part +on OpenSUSE-based systems: + +```bash +# Set DISTRO (openSUSE_Leap_42.3, openSUSE_Leap_15.0, openSUSE_Tumbleweed) +export DISTRO="openSUSE_Leap_15.0" + +# Set AGL_RELEASE (AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master) +export AGL_RELEASE="AGL_Master" + +sudo zypper ar http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/isv:LinuxAutomotive:${AGL_RELEASE}.repo + +sudo zypper ref +sudo zypper install agl-xds-agent +sudo zypper install agl-xds-cli +sudo zypper install agl-xds-gdb +``` + +## Install Packages for Other Platforms (e.g. Windows / MacOS) + +- Follow these steps to install `xds-agent`: + + 1. Download the latest released tarball from the GitHub [Releases Page](https://github.com/iotbzh/xds-agent/releases). + + 1. Unzip the tarball anywhere into your local drive (e.g. `/opt/AGL/xds` or `C:\AGL\xds`). + + 1. Add binary to PATH: + + - MacOs: create the .bash_profile `nano .bash_profile` and add `export PATH="/opt/AGL/xds/xds-agent:$PATH` + - Windows: change the system path using the control panel or system settings. + Alternatively, you can `setx path "C:\AGK\xds\xds-agent;%path%"` + +- If you want to install optional tools, repeat the previous steps for each tool: + - `xds-cli`, which is used for command-line and IDE integration. + Downloaded from the ([released tarball link](https://github.com/iotbzh/xds-cli/releases)). + - `xds-gdb`, used for debugging applications. + Downloaded from the ([released tarball link](https://github.com/iotbzh/xds-gdb/releases)). + +## Start xds-agent + +As noted earlier, the `xds-agent` client tool must run on your local +development host when you use XDS. +Depending on your development host, use the following commands: + +- For a Linux-based development host, a user systemd service is provided + (i.e. `xds-agent.service`). + + To start this service automatically when your host boots, enable + the service using the following command: + + ```bash + # Enable xds-agent service at boot + systemctl --user enable xds-agent.service + ``` + + To start the XDS-agent service and display its log, use these + commands: + + ```bash + # Manually start xds-agent service + systemctl --user start xds-agent.service + + # Get status and log of xds-agent service + systemctl --user status xds-agent.service + ``` + +- For a MacOS-based host, use the following command to + manually start `xds-agent`: + + ```batch + /opt/AGL/bin/xds-agent + ``` + +- For a Windows-based host, use the following command to + manually start `xds-agent`: + + ```batch + C:\AGL\xds\xds-agent\xds-agent.exe + ``` diff --git a/docs/part-1/create-app-build-cmd-line.md b/docs/part-1/create-app-build-cmd-line.md new file mode 100644 index 0000000..5d81625 --- /dev/null +++ b/docs/part-1/create-app-build-cmd-line.md @@ -0,0 +1,171 @@ +# Build Using the Command Line + +One option for building your application using XDS is to use +the command line (i.e. `xds-cli`). +Building the application consists of declaring your project, identifying +some key ID values, and then using the command line to build it. + +<!-- section-note --> +**NOTE:** + +XDS tools, including `xds-cli`, are installed by default in +the `/opt/AGL/bin` directory. +During installation, this directory is automatically added to your +`PATH` variable. +If, for some reason, the tool is not in your `PATH` directory, +you can manually add it using the `export PATH=${PATH}:/opt/AGL/bin` +command. +<!-- end-section-note --> + + +## Declare Project + +Use the `projects add` command to declare your project: + +```bash +xds-cli prj add --label="Project_helloworld-native-application" --type=pm --path=/home/seb/xds-workspace/helloworld-native-application --server-path=/home/devel/xds-workspace/helloworld-native-application +``` + +When you declare the project, XDS creates the `xds-project.conf` +configuration file if one does not already exist. +You should examine this configuration file before you build the +project to be sure all configurations are correct for your project. + +<!-- section-note --> +**NOTE:** + +If the Server Part (i.e. `xds-agent`) is not running on the default +port, you can use the `--url=http://localhost:<port>` option with the +`xds-cli prj add` command to specify the port. +Just substitute the actual port for `<port>` with the option. +<!-- end-section-note --> + +## Determine the ID of Your Project + +After declaring your project, you need to determine the +unique ID of your project. + +From the command line, use the `prj ls` command, which is an abbreviation +for the `projects list` command: + +```bash +xds-cli prj ls +ID Label LocalPath +f9904f70-d441-11e7-8c59-3c970e49ad9b Project_helloworld-service /home/seb/xds-workspace/helloworld-service +4021617e-ced0-11e7-acd2-3c970e49ad9b Project_helloworld-native-application /home/seb/xds-workspace/helloworld-native-application +``` + +Once you have the ID of the project, you can use the `--id` option +or the `XDS_PROJECT_ID` environment variable to refer to your project. + +<!-- section-note --> +**NOTE:** + +When using the project ID from the command line, you can use the "short" +notation by providing a non-ambiguous portion of the ID. +For example, to refer to the `Project_helloworld-native-application` project +shown in the previous example, you can use `-id 40` rather than +`--id 40 instead of --id 4021617e-ced0-11e7-acd2-3c970e49ad9b`. +<!-- end-section-note --> + +## Determine the ID of Your SDK + +You also need to determine the ID of the SDK you want to use to cross-build +your application. + +To list installed SDKs, use the following command: + +```bash +xds-cli sdks ls +List of installed SDKs: + ID NAME + 7aa19224-b769-3463-98b1-4c029d721766 aarch64 (3.99.1+snapshot) + 41a1efc4-8443-3fb0-afe5-8313e0c96efd corei7-64 (3.99.2+snapshot) + c226821b-b5c0-386d-94fe-19f807946d03 aarch64 (3.99.3) +``` + +SDK IDs are returned by architecture and version. +Be sure to identify the SDK you need. + +## Build the Application + +You can now use XDS to cross-build your project. +Following is an example that builds a project that is based on CMake: + +```bash +# First, export the target IP address, or it's DNS name +export TARGET_ADDRESS=<target_adress> + +# Go into your project directory and create a build directory +cd $MY_PROJECT_DIR +mkdir build +``` + +Before using the command line to build the project, you should be +sure the project's configuration file is correct. +Examine the `xds-project.conf` configuration file and edit it +as needed. + +Generate the build system using CMake: + +``` +# You must set RSYNC_* variables so that you deploy and populate widgets on the target +xds-cli exec --id=4021617e --sdkid=c226821b -- "export RSYNC_TARGET=root@${TARGET_ADDRESS} ; export RSYNC_PREFIX=/opt ; cd build && cmake .." +``` + +Now you can build the project: + +``` +xds-cli exec --id=4021617e --sdkid=c226821b -- "cd build && make widget" +``` + +<!-- section-note --> +**NOTE:** + +If you use `&&`, `||` or `;` statements in the executed command line, +you need to double quote the command (e.g. `"cd build && make"`). +<!-- end-section-note --> + +To avoid having to set the project ID, SDK ID, and URL for each +command line, you can define these settings as environment variables +using an environment file. +Use the `--config` option or source file before executing +the `xds-cli` command. + +To specify your configuration file with the command line, +use the `--config` option. +For example, the equivalent of the previous build command but +with a specified configuration file is as follows: + +```bash +# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application +cd $MY_PROJECT_DIR + +# Edit and potentially adapt xds-project.conf file that has been created +# automatically on project declaration using XDS Dashboard +cat xds-project.conf + # XDS project settings + export XDS_AGENT_URL=localhost:8800 + export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b + export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03 + +# Create build directory and invoke cmake and then build project +xds-cli exec --config=./xds-project.conf -- "mkdir -p build && cd build && cmake .." +cd build && xds-cli exec --config=../xds-project.conf -- "make all" +``` + +Alternatively, you could first source the configuration file to avoid using the +`--config` option as follows: + +``` +source xds-project.conf +xds-cli exec "mkdir -p build && cd build && cmake .." +cd build && xds-cli exec "make all" +``` + +<!-- section-note --> +**NOTE:** + +All parameters after a double dash (`--`) are considered as the command +to execute. +<!-- end-section-note --> diff --git a/docs/part-1/create-app-build-dashboard.md b/docs/part-1/create-app-build-dashboard.md new file mode 100644 index 0000000..d5d2dbb --- /dev/null +++ b/docs/part-1/create-app-build-dashboard.md @@ -0,0 +1,93 @@ +# Build Using the XDS Dashboard + +One option for building your application using XDS is to use +the XDS Dashboard. +Building the application consists of using the dashboard +to declare your project and then initiate the build. + +## Declare Project + +Follow these steps to declare the project: + +1. Open a Web Browser and connect to to the XDS Dashboard. + + The URL you use depends of your configuration (e.g. `http://localhost:8800`). + +2. Open the right sidebar and select the `Projects` entry to open the + project page. + Once the page is open, declare a new project by clicking on the + "plus" icon next to "Add Project": + + {:: style="margin:auto; display:flex"} + + When you declare the project, XDS creates the `xds-project.conf` + configuration file if one does not already exist. + You should examine this configuration file before you build the + project to be sure all configurations are correct for your project. + + The configuration file can be very useful when you plan to use + XDS client tools such as `xds-cli` or `xds-gdb`. + + <!-- pagebreak --> + +3. Set `Sharing Type` appropriately depending on your Client Part + configuration: + + {:: style="width:90%; max-width:560px; margin:auto; display:flex"} + + <!-- section-note --> + **NOTES:** + + - When `Path mapping` type is selected, you must clone your project into + `$HOME/xds-workspace` directory, which is named **Local Path** in the modal window. + + - If XDS server is running in the XDS docker container + the **Server Path** must be set to `/home/devel/xds-workspace/<xxx>` + where `<xxx>` is your project directory name. + See the "[Installation based on Docker container](server-part.html#docker-container))" + section for more information. + + - If you select `Cloud Sync`, you can clone your project wherever you want on + your local disk. + <!-- end-section-note --> + +## Build the Application + +Building the application requires opening the build page's "build entry" in the +left navigational pane, selecting both the project and the SDK, and +then initiating the build. + +<!-- section-note --> +**NOTE:** + +To use the `helloworld-native-application` example, you need to provide +some configuration items. +Specifically, you must pass values for both the +`RSYNC_TARGET` and `RSYNC_PREFIX` environment variables. +To pass these variables, use the `Settings` window in the `Build` tab. +You can use the `Env variables` field to pass a list of environment variables +that are set on the server prior to the build occurring. +You must separate individual variables using the semi-colon character: + +``` +RSYNC_TARGET=root@<mytarget>;RSYNC_PREFIX=/opt +``` + +When you pass these variables, substitute `<mytarget>` with the valid +target IP address or DNS name entry. +<!-- end-section-note --> + +Follow these steps to build the application: + +1. Open the build page build entry in the left-hand navigation pane: + + {:: style="display:inline; padding:0;"}, + +2. Select your **Project**. + +3. Seclect the **Cross SDK** you want to use. + +4. Click the **Clean / Pre-Build / Build / Populate** buttons to execute + the build action you want. + + {:: style="width:90%; max-width:600px; margin:auto; display:flex"} diff --git a/docs/part-1/create-app-build-ide.md b/docs/part-1/create-app-build-ide.md new file mode 100644 index 0000000..cbf39f6 --- /dev/null +++ b/docs/part-1/create-app-build-ide.md @@ -0,0 +1,244 @@ +# Build using an IDE + +One option for building your application using XDS is to use +an Integrated Development Environment +([IDE](https://en.wikipedia.org/wiki/Integrated_development_environment)). +Many IDEs exist (e.g. [NetBeans](https://netbeans.org/), +[Visual Studio Code](https://code.visualstudio.com/), +[Qt Creator](https://www.qt.io/), +[Eclipse](https://www.eclipse.org/), and so forth). + +This section first develops an XDS configuration file +(i.e. `xds-project.conf`) and then provides two +examples, NetBeans and Visual Studio, that do the following. + +- NetBeans: Creates two separate build configurations + for a project, which makes it easy to switch back and forth + between types of builds. + +- Visual Studio: Creates tasks that allow you to build an example + based on CMake templates. + +## XDS Configuration File + +This section shows how to create an XDS configuration file +(i.e. `xds-project.conf`) or how to re-use an existing file. +For example, the following commands set up the configuration +file for an `aarch64` SDK to cross-build the +application for a Renesas Gen3 board. + +```bash +# create file at root directory of your project +# for example: +# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application +cat > $MY_PROJECT_DIR/xds-project.conf << EOF + 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 +``` + +## NetBeans + +This section creates two configurations: one to compile the +project natively using native GNU gcc, and one to cross-compile +the project using XDS. + +Having two configurations allows you to easily switch between them +using NetBean's **Run -> Set Project Configuration** menu. + +### Native Configuration + +Follow these steps to create the native configuration: + +1. Open the **Tools** -> **Options** menu. + +2. Open the **C/C++** tab. + +3. Click on the **Add** button in the **Build Tools** sub-tab: + + {:: style="width:90%; max-width:700px; margin:auto; display:flex"} + +4. Fill the **Make Command** and **Debugger Command** fields to point to the XDS tools: + + {:: style="width:90%; max-width:700px; margin:auto; display:flex"} + +5. Click **OK**. + +6. Select the **File** -> **New Project** menu item to declare the + project and create a native configuration. + +7. Select **C/C++ Project with Existing Sources** and click on **Next**. + +8. Specify your project directory and set **Select Configuration Mode** to + "Custom". + Be sure to keep **Tool Collection** set to "Default GNU" in order to create a + *native configuration*, which is based on the native GNU GCC. + +9. Click **Next**. + + {:: style="width:90%; max-width:700px; margin:auto; display:flex"} + +10. Update the **Run in Folder** field to add the `build_native` suffix. + Doing so results in the build files being located in the + `build_native` sub-directory. + Be sure to keep the defaults for all other settings and then click **Next**. + + {:: style="width:90%; max-width:700px; margin:auto; display:flex"} + +11. Click through **Next** several times while always keeping the + default settings until the **Finish** button appears. + +12. Click **Finish** to complete the creation of the native configuration. + +### Cross-Compilation Configuration + +Follow these steps to create the configuration for cross-compilation +based on the XDS tools: + +1. Edit project properties (using menu **File** -> **Project Properties**) + to add a new configuration that will use XDS to cross-compile + your application for example for a Renesas Gen3 board. + +2. in the **Build** category, click on **Manage Configurations** button + and then **New** button to add a new configuration named for example + "Gen3 board". + + {:: style="width:90%; max-width:700px; margin:auto; display:flex"} + +3. Click the **Set Active** button. + +4. Select the **Pre-Build** sub-category, and set the following: + + - Working Directory: `build_gen3` + - Command Line: `xds-cli exec -c ../xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ..` + - Pre-build First: `ticked`<br/><br/> + +5. Select the **Make** sub-category, and set the following: + + - Working Directory: `build_gen3` + - Build Command: `xds-cli exec -c ../xds-project.conf -- make remote-target-populate` + - Clean Command: `xds-cli exec -c ../xds-project.conf -- make clean`<br/><br/> + + {:: style="width:90%; max-width:700px; margin:auto; display:flex"} + +6. Select the **Run** sub-category, and set the following: + + - Run Command: `target/start-on-root@renesas-gen3.sh` + - Run Directory: `build-gen3`<br/><br/> + + {:: style="width:90%; max-width:700px; margin:auto; display:flex"} + +7. Click **OK** to save settings. + +By changing the configuration from **Default** to **Gen3 board**, you can +compile your helloworld application natively, which is the default configuration. +Or, you can cross-compile your application using XDS for the Renesas Gen3 board, +which is the Gen3 board configuration. + +## Visual Studio Code + +This section presents a Visual Studio example that creates tasks +that allow you to build an example that is based on CMake templates. + +Follow these steps: + +1. Start Visual Studio Code and open your project using the + following commands: + + ```bash + cd $MY_PROJECT_DIR + code . & + ``` + +2. Add new tasks by entering the `Ctrl+Shift+P` key combination and selecting + the `Tasks: Configure Task` command. + A list of task runner templates appears. + +3. Define your own tasks. + Following is an example that builds the + [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) + that is based on CMake templates. + + ```json + { + "version": "2.0.0", + "type": "shell", + "presentation": { + "reveal": "always" + }, + "tasks": [ + { + "label": "clean", + "type": "shell", + "command": "/bin/rm -rf ${workspaceFolder}/build/* && mkdir -p build && echo Cleanup done.", + "problemMatcher": [] + }, + { + "label": "pre-build", + "type": "shell", + "group": "build", + "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ../", + "problemMatcher": [ + "$gcc" + ] + }, + { + "label": "build", + "type": "shell", + "group": "build", + "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- make widget", + "problemMatcher": [ + "$gcc" + ] + }, + { + "label": "populate", + "type": "shell", + "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- make widget-target-install", + "problemMatcher": [] + } + ] + } + ``` + +4. Run a task by entering the `Ctrl+Shift+P` key combination and + selecting `Tasks: Run task` and then selecting the specific task. + For example, select `pre-build` to trigger pre-build task. + +5. Optionally add keybindings that trigger tasks. + Following is an example: + + ```json + // Build + { + "key": "alt+f9", + "command": "workbench.action.tasks.runTask", + "args": "clean" + }, + { + "key": "alt+f10", + "command": "workbench.action.tasks.runTask", + "args": "pre-build" + }, + { + "key": "alt+f11", + "command": "workbench.action.tasks.runTask", + "args": "build" + }, + { + "key": "alt+f12", + "command": "workbench.action.tasks.runTask", + "args": "populate" + }, + ``` + + <!-- section-note --> + **NOTES:** + + - You can find more details about Visual Source Code keybindings + [here](https://code.visualstudio.com/docs/editor/tasks#_binding-keyboard-shortcuts-to-tasks). + + - You can find more details about Visual Source Code tasks + [here](https://code.visualstudio.com/docs/editor/tasks). + <!-- end-section-note --> diff --git a/docs/part-1/create-app-get-source-files.md b/docs/part-1/create-app-get-source-files.md new file mode 100644 index 0000000..7fca382 --- /dev/null +++ b/docs/part-1/create-app-get-source-files.md @@ -0,0 +1,81 @@ +# Get the Source Files + +XDS needs to be able to share your application source files. +This section describes the options you have for sharing your +files with the server running XDS. + +## Source Sharing Methods + +For this example, you will use the _helloworld-native-application_ +project. +You must clone this project's repository into a directory that +`xds-server` can access. + +Two methods exist: + +- If you Client Part is configured for SaaS (i.e. Cloud Sync), the local + directory into which you clone your application project is sent to + and replicated on the server running XDS. + This implies that you can use any local directory for your cloned + application repository. + +- If you `xds-server` is running locally, you can use path mapping. + Path mapping uses a volume shared between your development host and the server + that is running XDS. + The directory shared is `$HOME/xds-workspace`. + + <!-- section-note --> + **NOTE:** + + The path mapping method of sharing files is more efficient than + replicating the project on the XDS server. + However, you must clone the project under a directory that can be shared. + The most convenient directory is the default shared directory, which is + `$HOME/xds-workspace`. + + You could create additional shared volumes. + To create more shared volumes, See the + "[Create and Start a New Container](server-part.html#create-and-start-a-new-container)" + section. + +## Which File Sharing Method Should I Choose? + +The file sharing method you choose depends on the +Client Part configuration (i.e. Standalone, On-Premise or SaaS). + +- Standalone uses local path mapping. With this configuration, it + makes no sense to use SaaS (Cloud Sync) as it adds unnecessary overhead. + +- On-Premise uses Cloud Sync. + +- SaaS also uses Cloud Sync. With this configuration, replicating the + application project files on the XDS server is the only way to achieve + file sharing. + +<!-- section-note --> +**NOTE:** + +The +[helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) +project is an AGL project that is based on CMake +(i.e. [cmake-apps-module](https://git.automotivelinux.org/src/cmake-apps-module/)). +For information on installing and using the CMake templates, see the +"[Installing the CMake Templates](../../../../devguides/reference/cmakeafbtemplates/dev_guide/installing-cmake.html)" +section. +CMake templates, when used to develop applications +with the AGL Application Framework, automatically generate Makefile rules +(e.g. `remote-target-populate`) or scripts (e.g. `build/target/xxx` scripts). +<!-- end-section-note --> + +## Clone project + +Now that you know where you are going to put your application files, +you can clone the repository. +In the following example, the local repository is cloned to the +default shared directory assuming path mapping, which is for +a Client Part Standalone configuration. + +```bash +cd $HOME/xds-workspace +git clone --recursive https://github.com/iotbzh/helloworld-native-application.git +``` diff --git a/docs/part-1/create-app-overview.md b/docs/part-1/create-app-overview.md new file mode 100644 index 0000000..58569c6 --- /dev/null +++ b/docs/part-1/create-app-overview.md @@ -0,0 +1,27 @@ +# Overview # + +The application development workflow using XDS begins with +making sure you have met all the +[requirements](create-app-requirements.html) needed to +use the tool. + +Once requirements are met, you have some options for +[getting the application source files](create-app-get-source-files.html) +together. +These options depend on where the XDS Server part is +running and which Client Part configuration you are using +(i.e. Standalone, On-Premise, or SaaS). + +You can build the application several ways: + +- Use the XDS UI + [Command Line](create-app-build-cmd-line.html) +- Use the XDS UI + [Dashboard](create-app-build-dashboard.html) +- Use a third-party Interactive Development Environment + ([IDE](create-app-build-ide)) application + (e.g. NetBeans, Visual Studio, and so forth). + +The following figure overviews the XDS application development process: + +{:: style="margin:auto; display:flex"} diff --git a/docs/part-1/create-app-requirements.md b/docs/part-1/create-app-requirements.md new file mode 100644 index 0000000..75952be --- /dev/null +++ b/docs/part-1/create-app-requirements.md @@ -0,0 +1,27 @@ +# Requirements + +Before you can build your application using XDS, you need to be +sure you have satisfied the requirements described in this section. + +- The Client Part (i.e.`xds-agent`) is running locally on your machine. + For information about `xds-agent` and how to install it, see the + "[Client Part](client-part.html)" section. + +- The Server Part (i.e. `xds-server`) is running locally in a docker container + or is accessible on your network + For information about `xds-server` and how to install it, see the + "[Server Part](server-part)" section. + +- one or more Software Development Kits (SDKs) are installed. + For information on installing an SDK, see the + "[AGL SDKs](install-sdk.html)" or + "[Download or Build Your SDK Installer](../../../../getting_started/reference/getting-started/app-workflow-sdk.html)" + sections. + +- Your XDS configuration is correct. + You can test this connection between the `xds-agent` and `xds-server` + by opening the XDS Dashboard in a Web Browser and confirming + no error messages. + See the + "[Check if xds-server is Running](server-part.html#check-if-xds-server-is-running)" + section. diff --git a/docs/part-1/3_install-sdks.md b/docs/part-1/install-sdk.md index 094e547..18e41f1 100644 --- a/docs/part-1/3_install-sdks.md +++ b/docs/part-1/install-sdk.md @@ -1,16 +1,46 @@ -# Installing AGL SDKs +# 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. +To build your AGL services or AGL applications using XDS, +you must install a Software Development Kit (SDK) that +matches your target/board. -A SDK is a package that includes all tools you need to cross-build and cross-debug your service/application. +An SDK is a package that includes all the tools you need +to cross-build and cross-debug your service or application. +You install an SDK by running the SDK Installer. -You can generate AGL SDK for the board you want to use or you can download -a pre-packaged AGL SDK. +You can build an AGL SDK Installer for your board or you can download +a pre-built installer. -## Install a new SDK from command line +This section describes how you can download a pre-built SDK +Installer using either the command line or the XDS Dashboard. +For information on how to build an SDK Installer, see the +"[Download or Build Your SDK Installer](../../../../getting_started/reference/getting-started/app-workflow-sdk.html)" +section. -Used `sdks` command of `xds-cli` tool to managed SDKs. +<!-- section-note --> +**NOTES:** +- In order to use the command line or the XDS Dashboard + to download an SDK Installer, you must + have the XDS UI set up in your toolchain (i.e. 'xds-cli'). + If you did not install 'xds-cli', see the + "[Client Part](client-part.html)" section for instruction on how + to install XDS UI. + +- See the + "[xds-server](../part-2/1_xds-server/0_abstract.html)" chapter + for more information on SDK management. +<!-- end-section-note --> + +## Command Line Operations + +This section describes how to download and install an SDK, +abort an installation, install an SDK from a local directory, +and view all installed SDKs. + +### Download and Install an SDK Using the Command Line + +Use the following commands to choose and install a pre-built SDK +Installer: ```bash # List all available SDKs @@ -27,7 +57,7 @@ a0ae663d poky-agl-corei7-64-3.99.1+snapshot Installed 3. 8c2f2841 AGL-release-dab-4.0.2-dragonboard-410c Not Installed 4.0.2 aarch64 ... -# Install a SDK (downloaded + install) +# Download and Install an SDK xds-cli sdks install d65fe750 Installation of 'AGL-release-eel-latest-qemux86-64' SDK successfully started. @@ -58,15 +88,37 @@ Each time you wish to use the SDK in a new shell session, you need to source the $ . /xdt/sdk/poky-agl/4.99.5/corei7-64/environment-setup-corei7-64-agl-linux SDK ID d65fe750-d3a7-38f5-83d8-3d3806054f8d successfully installed. +``` + +### Abort an Installation that is in Progress +If for some reason you need to abort an ongoing installation, you can +use the `sdks abort` command: -# Abort an installation that is in progress +```bash xds-cli sdks abort -id d65fe750 +``` + +### Install an SDK Using a Local SDK Package or File -# Install a SDK (using a local SDK package/file) +If you have an SDK Installer that is already local to your system, +you can use the command line to install it from your local directory: + +```bash xds-cli sdks install --file $HOME/xds-workspace/sdks/poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-corei7-64-toolchain-4.99.5.sh +``` + +<!-- section-note --> +**NOTE:** +Installation based on a local SDK Installer is only supported when the +SDK Installer is in the `$HOME/xds-workspace/sdks` directory. +<!-- end-section-note --> -# List installed SDKs +### List Installed SDKs + +To list the installed SDKs, use the following command: + +```bash xds-cli sdks ls List of installed SDKs: @@ -75,30 +127,31 @@ e45ac787 AGL-corei7-64-4.99.5+snapshot Installed 4.99.5 d65fe750 AGL-release-eel-latest-qemux86-64 Installed 4.99.3 corei7-64 ``` -<!-- section-note --> -Installation based on a local SDK package is only supported when SDK file package -is located in `$HOME/xds-workspace/sdks` directory -<!-- end-section-note --> +## Install an SDK Using the XDS Dashboard -## Install a new SDK from XDS Dashboard +Follow these steps to locate, download, and install an SDK +using the XDS Dashboard: -Open XDS-Dashboard in web-browser and select `SDKs` entry in left side menu. +1. Open the XDS Dashboard in a Web Browser and select + `SDKs` in left-hand menu. -Then switch to `SDKs MANAGEMENT` view : +2. Switch to `SDKs MANAGEMENT` view. + Following is an example: -{:: style="margin:auto; display:flex"} + {:: 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. +3. Use filter boxes to find the SDK you want to install. -SDK download and installation process may take several minutes and output of installation script (output of -`add` script mentioned in above chapter). +4. Click on the "plus" icon in the "Actions" column to + start the installation. -{:: style="margin:auto; display:flex"} + The SDK Installer downloads and the installation process begins. + In can take several minutes for the installation to complete. + Following is an example of the output: -Note that you can abort installation by clicking on `CANCEL` button. + {:: style="margin:auto; display:flex"} -## More info +## Aborting an SDK Installation -Please refer to [xds-server](../part-2/1_xds-server/0_abstract.html) chapter for more details -about SDKs management. +If for some reason you need to abort an ongoing SDK installation, +you can do so by clicking the `CANCEL` button. diff --git a/docs/part-1/pictures/create-app-workflow.png b/docs/part-1/pictures/create-app-workflow.png Binary files differnew file mode 100755 index 0000000..36562cf --- /dev/null +++ b/docs/part-1/pictures/create-app-workflow.png diff --git a/docs/part-1/server-part.md b/docs/part-1/server-part.md new file mode 100644 index 0000000..afa27c7 --- /dev/null +++ b/docs/part-1/server-part.md @@ -0,0 +1,449 @@ +# Server Part + +Depending on your situation, you must either install the +XDS server part or you can skip installation: + +- If you are a developer and plan to connect to and use an existing `xds-server` + that is running on your local network (On-Premise) or is available from + the Cloud (SaaS), you do not need to install the server part. +- If you are configured for Standalone or you are an administrator + that wants to install an On-Premise solution, you must install + the server part. + +This section describes three types of server part installations: + +| Install type | Supported OS | Section to refer | +|--------------|--------------|------------------| +| Container | Linux or MacOS | [Docker Container](#docker-container) | +| Virtual Machine | Linux, MacOS or Windows | [VirtualBox Appliance](#virtualbox-appliance) | +| Native | Linux | [Native](#native) | + +## Docker Container + +This section describes how to install the server part (`xds-server`) +into a +[Docker Container](https://www.docker.com/resources/what-container) +on a Linux-based system or a MacOS system. + +### Prerequisites + +The system on which you are installing the server part +must meet both the following prerequisites: + +- You must have Docker installed on the host machine. + For information on installing Docker, see the + [Docker documentation](https://docs.docker.com/engine/installation/). + +- Aside from having Docker installed, users must be part of a + docker + [group](https://www.linux.com/learn/intro-to-linux/2017/12/how-manage-users-groups-linux). + Enter the following command to display the system's groups and + then search for and list the Docker groups: + + ```bash + groups | grep docker + ``` + + If the users that plan on using the container are not part of the + Docker group or the group does not exist, you must take steps. + See the [docker post install instructions](https://docs.docker.com/install/linux/linux-postinstall/) + for details on creating a Docker group and adding users. + + Following is a summary of the key commands: + + ```bash + sudo groupadd docker + sudo usermod -aG docker $USER + # Log out and re-login so the system can re-evaluate the group membership + # You might also need to start docker service manually + + sudo service docker start + # or + sudo systemctl start docker + ``` + +### Get the Container + +Use the following command to load the pre-built AGL +SDK Docker image, which includes `xds-server`: + +```bash +wget -O - http://iot.bzh/download/public/XDS/docker/docker_agl_worker-xds-latest.tar.xz | docker load +``` + +The following command lists and displays information about the image: + +```bash +docker images "docker.automotivelinux.org/agl/worker-xds*" + +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 + +Running the following script creates a new Docker image and starts 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 (change the -id option value if you get a port conflict error) +bash ./xds-docker-create-container.sh -id 0 + +# Be sure the 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:10809->10809/tcp, 0.0.0.0:2222->22/tcp agl-xds-HOSTNAME-0-USERNAME +``` + +In the previous example, the container exposes following ports: + +| Port number | Description | +|-------------|---------------------------------------------| +| 8000 | `xds-server`: serve XDS webapp and REST API | +| 2222 | ssh | + +This container also creates the following volumes, which are 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 | + +#### Optional Settings + +When you create the container, you can use optional settings. +This section shows minimal settings to configure the container. +For more detailed `xds-server` configuration information including settings, see the +"[xds-server configuration](../part-2/1_xds-server/2_config.html)" section. + +- **`--volume`** + + Adds a new shared directory using the `--volume` option (e.g. + used with Path-Mapping folder types): + + ```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 + ``` + +- **`--id`** + + Changes the port used by Docker: + + ```bash + # Create new XDS worker container with a different port number + ID=3 + bash ./xds-docker-create-container.sh -id ${ID} + + # Check that new container is running (in example below id has been set to 3) + 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:2225->22/tcp, 0.0.0.0:8003->8000/tcp, 0.0.0.0:10892->10809/tcp agl-xds-3 + ``` + + <!-- section-note --> + **WARNING:** + Changing the container id impacts the port number used to connect to `xds-server`. + Consequently, you might need to adjust the `xds-agent` configuration in order + to match the correct port number. + + In the previous example where the container id is set to "3", the export + port number is `8003`. + In this case, you must define "url" in the `xds-server` configuration as follows: + + ```json + { + ... + "xdsServers": [ + { + "url": "http://localhost:8003" + } + ], + ... + } + ``` + + For more information, see the + [xds-agent configuration](../part-2/2_xds-agent/2_config.html) section. + <!-- end-section-note --> + +#### Manually Setup the Docker User ID + +If you are using 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 names inside Docker are `devel` and `1664`, +respectively. + +<!-- section-note --> +**NOTE:** + +If you used the `xds-docker-create-container.sh` script to create the XDS +Docker container, the user uid/gid inside Docker has already been changed. +<!-- end-section-note --> + +Use following commands to replace ID `1664` with your user and group ID: + +```bash +# Set the Docker container name (e.g. 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" + +# Kill all processes of with the user ID `devel`. This includes the running xds-server. +docker exec ${CONTAINER_NAME} bash -c "/bin/loginctl kill-user devel" + +# Change user and group IDs inside Docker to match your user and group IDs. +docker exec ${CONTAINER_NAME} bash -c "usermod -u $(id -u) devel" +docker exec ${CONTAINER_NAME} bash -c "groupmod -g $(id -g) devel" + +# Update file ownerships. +docker exec ${CONTAINER_NAME} bash -c "chown -R devel:devel /home/devel /tmp/xds*" + +# Restart the devel autologin service. +docker exec ${CONTAINER_NAME} bash -c "systemctl restart autologin" + +# Restart xds-server as a service. The ssh port 2222 might depend on your container ID. +ssh -p 2222 devel@localhost -- "systemctl --user restart xds-server" +``` + +### Check if xds-server is Running (open XDS webapp) + +When the container starts up, `xds-server` automatically starts as a +user service. + +If the container is running on your localhost, you can access a basic web +application to check on `xds-server`: + +```bash +xdg-open http://localhost:8000 +``` + +From a shell prompt, you can check status, stop, and start `xds-server` +using the 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 +``` + +`xds-server` should be up and running. +You can now install AGL SDKs. +See the +"[AGL SDKs](install-sdks.html)" section for more information. + +## VirtualBox Appliance + +This section describes how to install the server part (`xds-server`) +into a guest Virtual Machine (VM) supported by +[VirtualBox](https://en.wikipedia.org/wiki/VirtualBox). +VirtualBox allows the creation and management of guest virtual +machines that run versions and derivations on many types of systems +(e.g. Linux, Window, MacOS, and so forth). + +### Prerequisites + +The system on which you are installing the server part must have +VirtualBox installed. +For information on how to install VirtualBox, see the +[VirtualBox documentation](https://www.virtualbox.org/wiki/Downloads). + +### Get the Appliance + +Use the following command to load the pre-built AGL SDK +appliance image, which includes `xds-server`: + +```bash +wget http://iot.bzh/download/public/XDS/appliance/xds-vm-debian9_latest.ova +``` + +### Clean the Old Appliance + +Only one appliance can exist on the machine. +Consequently, you must remove any existing XDS appliance. +Use the following commands: + +```bash +# Get the virtual machine name +VDS_VMNAME=$(VBoxManage list vms | grep xds-vm-debian | cut -d "\"" -f2) +echo ${VDS_VMNAME} + +# Remove the old XDS appliance +[ -n ${VDS_VMNAME} ] && VBoxManage controlvm ${VDS_VMNAME} poweroff +[ -n ${VDS_VMNAME} ] && VBoxManage unregistervm ${VDS_VMNAME} --delete +``` + +### Create and Start a New Appliance + +You can create a new appliance by using a provided script or by +using the VirtualBox GUI: + +```bash +# Import image into VirtualBox +VBoxManage import ./xds-vm-debian9_latest.ova + +# Check import result +VDS_VMNAME=$(VBoxManage list vms | grep xds-vm-debian | cut -d "\"" -f2) +echo ${VDS_VMNAME} +``` + +Add a share folder to the appliance. +You must use "path-mapping sharing type for projects": + +```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 +``` + +Use the following command to start the appliance: + +```bash +# Start XDS appliance +[ -n ${VDS_VMNAME} ] && VBoxManage startvm ${VDS_VMNAME} +``` + +### Appliance Settings + +The image exposes the following network ports, which are NAT mode: + +- 8000 : `xds-server` to serve XDS basic web page +- 2222 : ssh + +### Check if xds-server is Running + +When the container in the virtual machine starts up, the `xds-server` automatically starts. + +To check if `xds-server` is correctly installed and running, you can access the +XDS basic web page and refer to the instructions: + +```bash +# If the container/appliance is running on your local host +# (else replace localhost with the name or the ip of the machine running the container) +xdg-open http://localhost:8000 +``` + +`xds-server` should be up and running. +You can now install AGL SDKs. +See the +"[AGL SDKs](install-sdks.html)" section for more information. + + +## Native + +This section describes how to install the server part (`xds-server`) 'natively' +on a Linux-based system. + +<!-- section-note --> +**NOTE:** +Hosts running a Linux distribution are the only hosts that support native +installation of the server part. +<!-- end-section-note --> + +### Prerequisites + +The system on which you are installing the server part must have +`python3` installed, which allows `xds-server` to manage AGL SDKs. + +#### Installing Packages for Debian + +Use the following commands to install packages for +`xds-server` on Debian-based systems: + +```bash +# Set 'DISTRO' (e.g. xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04, Debian_8.0, Debian_9.0) +export DISTRO="xUbuntu_16.04" + +# Set AGL_RELEASE (e.g. AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master) +export AGL_RELEASE="AGL_Master" + +wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/Release.key | sudo apt-key add - +sudo bash -c "cat >> /etc/apt/sources.list.d/AGL.list <<EOF +deb http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/ ./ +EOF" + +sudo apt-get update +sudo apt-get install agl-xds-server + +# Install python3 +sudo apt-get install python3 +``` + +#### Install Packages for OpenSUSE + +Use the following commands to install packages for +`xds-server` on OpenSUSE-based systems: + +```bash +# Set DISTRO (openSUSE_Leap_42.3, openSUSE_Leap_15.0, openSUSE_Tumbleweed) +export DISTRO="openSUSE_Leap_15.0" + +# Set AGL_RELEASE (AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master) +export AGL_RELEASE="AGL_Master" + +sudo zypper ar http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/isv:LinuxAutomotive:${AGL_RELEASE}.repo + +sudo zypper ref +sudo zypper install agl-xds-server + +# Install python3 +sudo zypper install python3 +``` + +#### Configure the xds-server + +Configuring the `xds-server` occurs through a JSON configuration file +named `server-config.json`. +All fields in the JSON configuration file are optional. +Consequently, you can skip this configuration step if you want to use +the default settings in the JSON file. + +If you want to customize or alter the default configuration, see the +"[Configuration chapter of xds-server](../part-2/1_xds-server/2_config.html)" +section for details on the JSON configuration file. + +#### Start and Stop xds-server + +You can manage `xds-server` as a +[systemd](https://en.wikipedia.org/wiki/Systemd) service by using +the following commands: + +```bash +# Status XDS server: +systemctl --user status xds-server.service + +# Stop XDS server +systemctl --user stop xds-server.service + +# Start XDS server +systemctl --user start xds-server.service + +# Get XDS server logs +systemctl --user --unit=xds-server.service --output=cat +``` + +To check if `xds-server` is correctly installed and running, you can access +the XDS web interface through your browser: + +```bash +xdg-open http://localhost:8000 +``` + +Alternatively, you can use the following `curl` command: + +```bash +curl http://localhost:8000/api/v1/version +``` + diff --git a/docs/part-1/xds-overview.md b/docs/part-1/xds-overview.md new file mode 100644 index 0000000..0b1ce83 --- /dev/null +++ b/docs/part-1/xds-overview.md @@ -0,0 +1,56 @@ +# Overview + +X(cross) Development System (XDS) is set of tools that provides +multi-platform cross development with +[near-zero](https://en.wikipedia.org/wiki/Zero_Install) +installation. + +This guide is available in two forms: the online version and a PDF +version: + +- Online: [http://docs.automotivelinux.org/docs/en/master/devguides/#xcross-development-system-user's-guide](../../../#xcross-development-system-user's-guide) + +- PDF: [http://iot.bzh/download/public/XDS/docs/XDS_UsersGuide.pdf](http://iot.bzh/download/public/XDS/docs/XDS_UsersGuide.pdf) + +XDS has two goals: + +1. Provide a multi-platform, cross development +tool with near-zero installation. + +2. Keep application source files local to the user's machine, which + makes XDS compatible with existing IT policies + (e.g. corporate backup or SCM), and lets users continue to work + using their favorite editors all while keeping performance during + editing and browsing activities. + +The following illustration shows XDS as two functional blocks: +the client part and the server part. + +The client part consists of several tools some essential and some +required. +The client part must have `xds-agent` and can optionally have `xds-cli` +and `xds-gdb`. +The client part runs on the user's machine (Development Host). + +The server part (`xds-server`) can run anywhere in a container, +which includes a standalone machine, a server machine connected +through a local network, or a server machine connected through the Cloud. + +{:: style="width:98%;"} + +<!-- pagebreak --> + +The client part is portable and can run on the following platforms: + +- Linux +- Windows +- MacOS + +The following figure shows the three supported configurations for the client part: + +- standalone (i.e. local) +- On-Premise, which uses a local network +- [Software as a Service](https://en.wikipedia.org/wiki/Software_as_a_service) + (SaaS), which is Cloud-based + +{:: style="width:98%;"} |
