ade.md

date = "2018-10-17"
weight = 100
toc = true

title = "Apertis Development Environment"

aliases = [
    "/old-developer/latest/appdev-ade.html",
    "/old-developer/v2019/appdev-ade.html",
    "/old-developer/v2020/appdev-ade.html",
    "/old-developer/v2021pre/appdev-ade.html",
    "/old-developer/v2022dev0/appdev-ade.html",
    "/old-wiki/SDK"
]

Apertis provides tools to aid with the development of applications using the Canterbury application framework, which help with the building of applications targeting a hardware platform; the installation of development versions of the application to the target device and debugging of the application.

These tools are pre-installed in the Apertis SDK. The SDK images shipped by Apertis are meant to be run in VirtualBox. They provide a common, reproducible environment to build both platform packages and application-bundles for Apertis. The tool provides general manual pages so you can get command information by using man ade on the SDK.

Sample applications

The Apertis SDK provides sample applications in the user home folder. Each application aims to demonstrate how to create a bundle addressing a minimal use case.

• helloworld-app: A basic sample application which can be used as the basic skeleton for more complex application
• helloworld-simple-agent: An agent-only application which does not provide any graphical program
• helloworld-agentapp: An agent application which interacts with a graphical program
• helloworld-https-client: A basic HTTP(S) client application
• helloworld-persistapp: An application to deal with persistent data
• helloworld-prefsapp: An application to deal with preferences
• notification-example: An example for using Notifications API
• hard-keys-example: An example for using hardware keys
• cpp-library-example: An example for using external library with C++
• helloworld-webapp: A basic Web Runtime application

{{% notice info %}} The sample applications are also available from the Apertis gitlab. {{% /notice %}}

To demonstrate how to use ade, helloworld-app is going to be used through this document.

Building and running an application bundle with ade on the SDK

To install and test on the SDK, ade provides the --native option.

$ cd /home/user/sample-applications/helloworld-app
$ ade configure --native
$ ade build --native
$ ade export
$ ade install --native
$ ade run --native

If you want to build the application in debug mode, you should use ade configure --native --debug. When the build is done, ade export will create a bundle file. For the helloworld-app example, the command will generate the org.apertis.HelloWorldApp-0.1.0.bundle file under the current path.

The final step for installation is to run ade install --native. Then, if it is done successfully, you can run the application by executing ade run --native.

Building and debugging app bundles with ade

The following steps can be used to cross-compile an example "Hello World" agent, deploy it onto the target device and debug it remotely using gdb using the Apertis helper tool called ade:

Debugging on a target device with ADE

Installation of a sysroot

To run/debug an application bundle on a target device, the first step is to download a sysroot. You can manage sysroots on the SDK with the ade sysroot command. See man ade-sysroot for more details about sysroot-related options.

ade sysroot list is used to check which sysroots are already installed on the SDK. If there's no installed sysroot image, the result would be like the following message.

$ ade sysroot list
No sysroot installed in directory /opt/sysroot/.

ade sysroot latest provides the version and downloadable URL of the sysroot image.

$ ade sysroot latest
* No distribution specified, defaulting to host distribution
* No release version specified, defaulting to host release version
* No architecture specified, defaulting to 'armhf'
* Checking latest version available for apertis - 17.06 (armhf)
* Retrieved latest version: apertis 17.06 - 20170530.0 (armhf)
* Download URL: https://images.apertis.org/sysroot/17.06/sysroot-apertis-17.06-armhf-development_20170530.0.tar.gz

The ade sysroot install command will do everything needed to install the latest sysroot version on your SDK, from downloading to installing without any manual intervention. This will default to installing a sysroot for armhf, using the distribution and release of the current SDK, specify using the command line arguments if this is not what is required (see ade sysroot install --help for more information):

$ ade sysroot install
* No distribution specified, defaulting to host distribution
* No release version specified, defaulting to host release version
* No architecture specified, defaulting to 'armhf'
* Installing version apertis 17.06 - 20170530.0 (armhf)
sysroot.tar.gz |==================================================| 100%

When the installation command has completed its job, the installed status can be checked with ade sysroot installed.

$ ade sysroot installed
* No distribution specified, defaulting to host distribution
* No release version specified, defaulting to host release version
* No architecture specified, defaulting to 'armhf'
* Retrieved current version: apertis 17.06 - 20170530.0 (armhf)

Setting up for a target device

For debugging on a target device, the target should accept remote connections via SSH and allow a specific port for remote gdb connection.

Preparing SSH key-pair on the SDK

SSH key is required to allow connecting from SDK to the target without requesting password. The following commands will generate a SSH RSA key-pair (using the legacy PEM format) and copy the generated public key to the target. In the example, it assumes that the address of the target device is 192.168.0.100. Accept the default settings so as not to require any password to access the target board.