diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/part-1/1_install-client.md | 20 | ||||
| -rw-r--r-- | docs/part-1/2_install-xds-server.md | 8 | ||||
| -rw-r--r-- | docs/part-1/3_install-sdks.md | 9 | ||||
| -rw-r--r-- | docs/part-1/4_build-first-app.md | 156 | ||||
| -rw-r--r-- | docs/part-1/pictures/nb_new-project-3.png | bin | 58461 -> 58152 bytes | |||
| -rw-r--r-- | docs/part-2/1_xds-server.md | 34 | ||||
| -rw-r--r-- | docs/part-2/2_xds-agent.md | 9 | ||||
| -rw-r--r-- | docs/part-2/3_xds-exec.md | 2 |
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. {:: 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*.  -- 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`  @@ -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 Binary files differindex 051bfdd..ebd330a 100644 --- a/docs/part-1/pictures/nb_new-project-3.png +++ b/docs/part-1/pictures/nb_new-project-3.png 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, |
