Usage

Getting Started

At this point it is assumed that you have completed the installation process

To find out all supported command line arguments run clickable --help.

You can get started with using Clickable with an existing Ubuntu Touch app. You can use Clickable with apps generated from the old Ubuntu Touch SDK IDE or you can start fresh by running clickable create which is outlined in more detail on the previous getting started page.

To run the default set of commands, simply run clickable in the root directory of your app’s code. Clickable will attempt to auto detect which builder is able to build your app.

Note: The first time you run clickable in your app directory, it will download a new Docker container which is about 1GB in size - so plan your time and data transfer environment accordingly. This will only happen the first time you build your app for a specific architecture and when you run clickable update-images.

Running the default commands will:

  1. Build the app

  2. Build the click package (can be found in the build directory)

  3. Uninstall the app from your phone

  4. Install the newly built app on your phone

  5. Kill the app on the phone (if already running)

  6. Launch the app on your phone

By default the device is accessed using ADB, see below if you want to use SSH)

Note: ensure your device is in developer mode for the app to be installed when using ADB or enable ssh when using SSH.

Configuration

One can specify the path to a project config file with --config. If not specified, Clickable will look for an optional configuration file called clickable.yaml and then clickable.json in the current and all parent directories. If there is none, Clickable will ask if it should attempt to detect the type of app and choose a fitting builder with default configuration.

Device Access

Host Device

For Clickable running directly on a Ubuntu Touch system, the target device can be set to host (default_target or --target host).

Device Detection

For commands accessing a target device, Clickable will try to detect whether the device is connected via SSH or ADB and the device architecture (arm64, amd64 or armhf). It will only check for SSH, if an IP address or hostname was specified via --ssh or in the Clickable Configuration. It will check SSH before ADB, unless ADB was configured as default_target.

Device detection does not consider host as a target. Setting the (default) target to host disables the device detection.

Connecting to a device over SSH

By default the device is connected to via ADB. If you want to access a device over SSH you need to either specify the device IP address or hostname on the command line (ex: clickable logs --ssh 192.168.1.10 ) or you can use the CLICKABLE_SSH env var. Make sure to enable ssh on your device for this to work.

Multiple connected ADB devices

By default Clickable assumes that there is only one device connected to your computer via ADB. If you have multiple devices attached to your computer you can specify which device to install/launch/etc on by using the flag --serial-number or -s for short. You can get the serial number by running clickable devices.

App Manifest

The architecture and framework fields in the manifest.json need to be set according to the architecture the app is build for (--arch) and the minimum framework version it requires, e.g. depending on the QT Version (qt_version).

To let Clickable automatically set those fields, leave them empty or set them to $ENV{ARCH} and $ENV{CLICK_FRAMEWORK} respectively. The apparmor policy needs to match the framework. To let Clickable fill it, leave it empty or set it to $ENV{APPARMOR_POLICY}.

If you need to distinguish different frameworks for the same app version, you may append your version with either $ENV{CLICK_FRAMEWORK_BASE} or $ENV{CLICK_FRAMEWORK} to let Clickable fill it, e.g. 1.0.0-$ENV{CLICK_FRAMEWORK_BASE} may result in 1.0.0-24.04-1.x.

Note: The app templates provided by Clickable make use of CMake’s configure() to set the fields in the manifest.json.

Advanced Usage

Running Clickable in an LXD container

It is possible to run clickable in a container itself, using lxd. This is not using --container-mode, but allowing clickable to create docker containers as normal, but inside the existing lxd container. This may fail with a permissions error when mounting /proc:

docker: Error response from daemon: OCI runtime create failed: container_linux.go:349: starting container process caused "process_linux.go:449: container init caused \"rootfs_linux.go:58: mounting \\\"proc\\\" to rootfs \\\"/var/lib/docker/vfs/dir/bffeb203fe06662876a521b1bea3b74e4d5c6ea3535352215c199c75836aa925\\\" at \\\"/proc\\\" caused \\\"permission denied\\\"\"": unknown.

If this error occurs then lxd needs to be configured to allow nested containers <https://stackoverflow.com/questions/46645910/docker-rootfs-linux-go-permission-denied-when-mounting-proc> on the host:

lxc stop your-container-name lxc config set your-container-name security.nesting true lxc start your-container-name