aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorSebastien Douheret <sebastien.douheret@iot.bzh>2017-10-18 17:35:38 +0200
committerSebastien Douheret <sebastien.douheret@iot.bzh>2017-10-18 17:35:44 +0200
commit32dcf3f8430a5e9bb913834d43738c495376ba8f (patch)
tree28e5602034a562336b92a660dd64ff0b3f7a28fd /docs
parent92b5cf7ed66c1dbec7a5d0c5f1ef5f0c35a0e5dc (diff)
Various updates to reflect current XDS state.
Signed-off-by: Sebastien Douheret <sebastien.douheret@iot.bzh>
Diffstat (limited to 'docs')
-rw-r--r--docs/part-1/1_install-client.md20
-rw-r--r--docs/part-1/2_install-xds-server.md8
-rw-r--r--docs/part-1/3_install-sdks.md9
-rw-r--r--docs/part-1/4_build-first-app.md156
-rw-r--r--docs/part-1/pictures/nb_new-project-3.pngbin58461 -> 58152 bytes
-rw-r--r--docs/part-2/1_xds-server.md34
-rw-r--r--docs/part-2/2_xds-agent.md9
-rw-r--r--docs/part-2/3_xds-exec.md2
8 files changed, 152 insertions, 86 deletions
diff --git a/docs/part-1/1_install-client.md b/docs/part-1/1_install-client.md
index 4a1d140..0d463d1 100644
--- a/docs/part-1/1_install-client.md
+++ b/docs/part-1/1_install-client.md
@@ -56,3 +56,23 @@ seb@laptop ~$ sudo zypper install agl-xds-gdb
- repeat the previous steps to install other tools depending of your needs:
- `xds-exec` : requested for command line and IDE integration. ([released tarball link](https://github.com/iotbzh/xds-exec/releases)).
- `xds-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, 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:
+
+```bash
+# Enable xds-agent service at boot
+seb@laptop ~$ systemctl --user enable xds-agent.service
+
+# Manually start xds-agent service
+seb@laptop ~$ systemctl --user start xds-agent.service
+
+# Get status and log of xds-agent service
+seb@laptop ~$ systemctl --user status xds-agent.service
+```
diff --git a/docs/part-1/2_install-xds-server.md b/docs/part-1/2_install-xds-server.md
index 7a8ff23..5ac244c 100644
--- a/docs/part-1/2_install-xds-server.md
+++ b/docs/part-1/2_install-xds-server.md
@@ -57,6 +57,14 @@ seb@laptop ~$ 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
```
+Note that you can also 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
+seb@laptop ~$ bash ./xds-docker-create-container.sh --volume /my-workspace:$HOME/my-workspace
+```
+
### Check if xds-server is running
`xds-server` is automatically started as a service on container startup.
diff --git a/docs/part-1/3_install-sdks.md b/docs/part-1/3_install-sdks.md
index 6a747ac..9c8b245 100644
--- a/docs/part-1/3_install-sdks.md
+++ b/docs/part-1/3_install-sdks.md
@@ -35,3 +35,12 @@ seb@laptop ~$ ssh -p 2222 devel@localhost
devel@docker ~$ sudo /opt/AGL/xds/server/xds-utils/install-agl-sdks.sh --arch corei7-64 --file /tmp/poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-corei7-64-toolchain-
4.0.1.sh
```
+
+<!-- warning -->
+>**Warning:** due to some limitation, you need for now to restart `xds-server` in
+order to make new installed SDK visible/available.
+> ```bash
+> seb@laptop ~$ ssh -p 2222 devel@localhost
+> devel@docker ~$ systemctl --user restart xds-server.service
+> ```
+<!-- endwarning -->
diff --git a/docs/part-1/4_build-first-app.md b/docs/part-1/4_build-first-app.md
index 880d7c8..2a1bb67 100644
--- a/docs/part-1/4_build-first-app.md
+++ b/docs/part-1/4_build-first-app.md
@@ -1,5 +1,15 @@
# Create your first AGL application
+## Prerequisites
+
+- `xds-agent` is running on your machine
+ (see **Installing XDS client tools** previous chapter)
+- `xds-server` is running locally in a docker container or is accessible on your
+ network (see **Installing XDS server** previous chapter)
+- one or more SDK have been installed (see **Installing AGL SDKs** previous chapter)
+- XDS configuration is correct: in other words, all table lines are blue in
+ configuration page of XDS Dashboard.
+
## Setup
Let's use for example helloworld-native-application, so you need first to clone
@@ -41,6 +51,10 @@ Set `Sharing Type` and paths according to your setup.
![](./pictures/xds-dashboard-prj-1.png){:: style="width:90%;"}
+Note that XDS creates a file name `xds-project.conf` (if not already exists)
+when you declare a new project using XDS Dashboard. This file may be very useful
+when you will use XDS client tools such as `xds-exec` (see next chapter).
+
<!-- note -->
>**Note:** when you select `Path mapping`, you must clone your project into
`$HOME/xds-workspace` directory (named "Local Path" in modal window) and
@@ -71,6 +85,10 @@ List of existing projects:
CKI7R47-UWNDQC3_test3
```
+> **Note:** XDS tools, including `xds-exec` are installed by default in `/opt/AGL/bin`
+> directory and this path has been added into your PATH variable.
+> If it is not the case, just add it manually using `export PATH=${PATH}:/opt/AGL/bin` command line.
+
Now to refer your project, just use --id option or use `XDS_PROJECT_ID`
environment variable.
@@ -78,14 +96,9 @@ 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
-# Add xds-exec in the PATH
-export PATH=${PATH}:/opt/AGL/bin
-
-# Go into your project directory
+# Go into your project directory and create a build directory
cd $MY_PROJECT_DIR
-
-# Create a build directory
-xds-exec --id=CKI7R47-UWNDQC3_myProject --sdkid=poky-agl_aarch64_4.0.1 --url=http://localhost:8000 -- mkdir build
+mkdir build
# Generate build system using cmake
xds-exec --id=CKI7R47-UWNDQC3_myProject --sdkid=poky-agl_aarch64_4.0.1 --url=http://localhost:8000 -- cd build && cmake ..
@@ -98,23 +111,31 @@ To avoid to set project id, xds server url, ... at each command line, you can
define these settings as environment variable within an env file and just set
`--config` option or source file before executing xds-exec.
+XDS creates a file name `xds-project.conf` (only if not already exists) when you
+declare a new project using XDS Dashboard. Use this file with `--config` option.
+
For example, the equivalence of above command is:
```bash
# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application
cd $MY_PROJECT_DIR
-cat > xds-project.conf << EOF
- export XDS_SERVER_URL=localhost:8000
- export XDS_PROJECT_ID=CKI7R47-UWNDQC3_myProject
- export XDS_SDK_ID=poky-agl_corei7-64_4.0.1
-EOF
-xds-exec --config xds-project.conf -- mkdir build
+# Edit and potentially adapt xds-project.conf file that has been created
+# automatically on project declaration using XDS Dashboard
+vi xds-project.conf
+ # XDS project settings
+ export XDS_SERVER_URL=localhost:8000
+ export XDS_PROJECT_ID=cde3b382-9d3b-11e7_helloworld-native-application
+ export XDS_SDK_ID=poky-agl_aarch64_4.0.1
+
+# Create build directory and invoke cmake and then build project
+xds-exec --config xds-project.conf -- "mkdir -p build && cd build && cmake .."
+cd build && xds-exec -- make all
-# Or sourcing env file
+# Or equivalent by first sourcing conf file (avoid to set --config option)
source xds-project.conf
-xds-exec -- mkdir -o build && cd build && cmake ..
-xds-exec -- cd build && make all
+xds-exec -- "mkdir -p build && cd build && cmake .."
+cd build && xds-exec -- make all
```
<!-- note -->
@@ -124,23 +145,27 @@ to execute on xds-server.
## Build from IDE
-First create the XDS config file that will be used later by xds-exec commands.
-For example we use here aarch64 SDK to cross build application for a Renesas
-Gen3 board.
+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-gen3.conf << EOF
+cat > $MY_PROJECT_DIR/xds-project.conf << EOF
export XDS_SERVER_URL=localhost:8000
export XDS_PROJECT_ID=cde3b382-9d3b-11e7_helloworld-native-application
- export XDS_SDK_ID=poky-agl_aarch64_4.0.1
+ export XDS_SDK_ID=poky-agl_aarch64_3.99.3
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**
@@ -154,16 +179,23 @@ __Netbeans 8.x :__
- Finally click on **OK** button.
-- Open menu **File** -> **New Project**
+- 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 the directory where you cloned your project and click on **Finish** button to keep all default settings:
+- Specify the directory where you cloned your project and click on **Finish** button to keep all default settings in order to create a *native configuration*.
![Select Model panel](./pictures/nb_new-project-1.png)
-- 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)
+<!-- warning -->
+> **Warning:** Take care to set **Tool Collection** to **Default GNU** in order
+> to create a native configuration based on native GNU GCC.
+<!-- endwarning -->
+
+- 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"
@@ -173,13 +205,13 @@ __Netbeans 8.x :__
- Select **Pre-Build** sub-category, and set:
- Working Directory: `build_gen3`
- - Command Line: `xds-exec -c ../xds-gen3.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ..`
+ - Command Line: `xds-exec -c ../xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ..`
- Pre-build First: `ticked`
- Select **Make** sub-category, and set:
- Working Directory: `build_gen3`
- - Build Command: `xds-exec -c ../xds-gen3.conf -- make remote-target-populate`
- - Clean Command: `xds-exec -c ../xds-gen3.conf -- make clean`
+ - Build Command: `xds-exec -c ../xds-project.conf -- make remote-target-populate`
+ - Clean Command: `xds-exec -c ../xds-project.conf -- make clean`
![Select Make sub-category](./pictures/nb_new-project-3.png)
@@ -193,7 +225,8 @@ __Netbeans 8.x :__
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 a Renesas Gen3 board (**Gen3 board** configuration).
+cross-compile your application through XDS for the Renesas Gen3 board
+(**Gen3 board** configuration).
### Visual Studio Code
@@ -204,65 +237,46 @@ cd $MY_PROJECT_DIR
code . &
```
-Add new tasks : press `Ctrl+Shift+P` and select the `Tasks: Configure Task Runner` command and you will see a list of task runner templates.
+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 [unicens2-binding](https://github.com/iotbzh/unicens2-binding) AGL binding based on cmake (_options value of args array must be updated regarding your settings_):
+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": "0.1.0",
- "linux": {
- "command": "/opt/AGL/bin/xds-exec"
+ "version": "2.0.0",
+ "type": "shell",
+ "presentation": {
+ "reveal": "always"
},
- "isShellCommand": true,
- "args": [
- "-url", "localhost:8000",
- "-id", "CKI7R47-UWNDQC3_myProject",
- "-sdkid", "poky-agl_aarch64_4.0.1",
- "--"
- ],
- "showOutput": "always",
- "tasks": [{
+ "tasks": [
+ {
"taskName": "clean",
- "suppressTaskName": true,
- "args": [
- "rm -rf build/* && echo Cleanup done."
- ]
+ "command": "/bin/rm -rf ${workspaceFolder}/build/* && mkdir -p build && echo Cleanup done.",
+ "problemMatcher": []
},
{
"taskName": "pre-build",
- "isBuildCommand": true,
- "suppressTaskName": true,
- "args": [
- "mkdir -p build && cd build && cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt"
+ "group": "build",
+ "command": "/opt/AGL/bin/xds-exec --rpath build --config xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ../",
+ "problemMatcher": [
+ "$gcc"
]
},
{
"taskName": "build",
- "isBuildCommand": true,
- "suppressTaskName": true,
- "args": [
- "cd build && make widget"
- ],
- "problemMatcher": {
- "owner": "cpp",
- "fileLocation": ["absolute"],
- "pattern": {
- "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
- "file": 1,
- "line": 2,
- "column": 3,
- "severity": 4,
- "message": 5
- }
- }
+ "group": "build",
+ "command": "/opt/AGL/bin/xds-exec --rpath build --config xds-project.conf -- make widget",
+ "problemMatcher": [
+ "$gcc"
+ ]
},
{
"taskName": "populate",
- "suppressTaskName": true,
- "args" : [
- "cd build && make widget-target-install"
- ]
+ "command": "/opt/AGL/bin/xds-exec --rpath build --config xds-project.conf -- make widget-target-install",
+ "problemMatcher": []
}
]
}
diff --git a/docs/part-1/pictures/nb_new-project-3.png b/docs/part-1/pictures/nb_new-project-3.png
index 051bfdd..ebd330a 100644
--- a/docs/part-1/pictures/nb_new-project-3.png
+++ b/docs/part-1/pictures/nb_new-project-3.png
Binary files differ
diff --git a/docs/part-2/1_xds-server.md b/docs/part-2/1_xds-server.md
index c4f00b3..ee5df5e 100644
--- a/docs/part-2/1_xds-server.md
+++ b/docs/part-2/1_xds-server.md
@@ -65,6 +65,14 @@ seb@laptop ~$ 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
```
+Note that you can also 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
+seb@laptop ~$ bash ./xds-docker-create-container.sh --volume /my-workspace:$HOME/my-workspace
+```
+
This container (ID=0) exposes following ports:
- 8000 : `xds-server` to serve XDS Dashboard
@@ -73,14 +81,19 @@ This container (ID=0) exposes following ports:
#### 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)
seb@laptop ~$ export CONTAINER_NAME=agl-xds-seb@laptop-0-seb
-# First stop xds-server
-seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "systemctl stop xds-server"
+# First kill all processes of devel user (including running xds-server)
+seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "/bin/loginctl kill-user devel"
# Change user and group id inside docker to match your ids
seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "usermod -u $(id -u) devel"
@@ -89,8 +102,11 @@ seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "groupmod -g $(id -g) devel"
# Update some files ownership
seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "chown -R devel:devel /home/devel /tmp/xds*"
-# Restart xds-server
-seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "systemctl start xds-server"
+# Restart devel autologin service
+seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "systemctl start autologin"
+
+# Restart xds-server as a service (ssh port 2222 may depend on your container ID)
+seb@laptop ~$ ssh -p 2222 devel@localhost -- "systemctl --user start xds-server"
```
## Check if xds-server is running (open XDS Dashboard)
@@ -110,16 +126,16 @@ If needed you can status / stop / start it manually using following commands:
seb@laptop ~$ ssh -p 2222 devel@localhost
# Status XDS server:
-devel@docker ~$ sudo systemctl status xds-server.service
+devel@docker ~$ systemctl --user status xds-server.service
# Stop XDS server
-devel@docker ~$ sudo systemctl stop xds-server.service
+devel@docker ~$ systemctl --user stop xds-server.service
# Start XDS server
-devel@docker ~$ sudo systemctl start xds-server.service
+devel@docker ~$ systemctl --user start xds-server.service
# Get XDS server logs
-devel@docker ~$ sudo journalctl --unit=xds-server.service --output=cat
+devel@docker ~$ journalctl --user --unit=xds-server.service --output=cat
```
### Manually Start XDS server
@@ -140,7 +156,7 @@ supported *level* are: panic, fatal, error, warn, info, debug.
```bash
seb@laptop ~$ ssh -p 2222 devel@localhost
devel@docker ~$ echo 'LOG_LEVEL=debug' | sudo tee --append /etc/default/xds-server > /dev/null
-devel@docker ~$ sudo systemctl restart xds-server.service
+devel@docker ~$ systemctl --user restart xds-server.service
devel@docker ~$ tail -f /tmp/xds-server/logs/xds-server.log
```
diff --git a/docs/part-2/2_xds-agent.md b/docs/part-2/2_xds-agent.md
index 55943fc..0ece136 100644
--- a/docs/part-2/2_xds-agent.md
+++ b/docs/part-2/2_xds-agent.md
@@ -11,15 +11,14 @@ used to remotely cross build applications.
## Configuration
-xds-agent configuration is driven by a JSON config file (named `agent-config.json`).
+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 `agent-config.json` file will be used:
+Here is the logic to determine which conf file will be used:
1. from command line option: `--config myConfig.json`
1. `$HOME/.xds/agent/agent-config.json` file
-1. `/etc/xds-agent/agent-config.json` file
-1. `<xds-agent executable dir>/agent-config.json` file
+1. `/etc/xds-agent/config.json` file
Supported fields in configuration file are (all fields are optional and example
below corresponds to the default values):
@@ -29,7 +28,7 @@ below corresponds to the default values):
- **xds-apikey** : xds-agent api-key to use (always set value to "1234abcezam")
- **syncthing.binDir** : syncthing binaries directory (default: executable directory)
- **syncthing.home"** : syncthing home directory (usually .../syncthing-config)
-- **syncthing.gui-address** : syncthing gui url (default http://localhost:8386)
+- **syncthing.gui-address** : syncthing gui url (default <http://localhost:8386>)
- **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated)
```json
diff --git a/docs/part-2/3_xds-exec.md b/docs/part-2/3_xds-exec.md
index 504cf01..0c63ff3 100644
--- a/docs/part-2/3_xds-exec.md
+++ b/docs/part-2/3_xds-exec.md
@@ -19,7 +19,7 @@ will be sourced on `xds-exec` start-up. Use `--config|-c` option or set
`XDS_CONFIG` environment variable to specify the config filename.
So configuration is driven either by environment variables or by command line
-options or using a config file knowning that the following priority order is used:
+options or using a config file knowing that the following priority order is used:
1. use option value (for example use project ID set by `--id` option),
1. else use variable `XDS_xxx` (for example `XDS_PROJECT_ID` variable) when a config file is specified with `--config|-c` option,