Clickable 7 Migration

This guide describes the changes that come with Clickable 7 and how to migrate a project from Clickable 6. The suggestions described here can be applied automatically using the clickable-migration tool.

Clean Building

Clickable 6 was cleaning the build directory before each build by default. If you want to keep that behaviour for your project, add to your project config:

"always_clean": true

This behaviour can also be enabled temporarily by setting the environment variable CLICKABLE_ALWAYS_CLEAN=ON or passing --clean to a build command. Example: clickable build --clean

This means the clean-build command has been removed, as it is not needed anymore. This also means that the keyword dirty and the environment variable CLICKABLE_DIRTY are no longer needed nor supported.

Command Line Interface

The command line interface has seen a complete overhaul, eliminating the glitches we saw with the old one and enabling a lot of improvements. To get an overview run clickable --help.

Bash Completion

Clickable 7 supports bash completion through argcomplete. Run the setup and confirm to enable bash completion clickable setup completion.

If you use another shell, check argcomplete docs on whether it is supported and how to enable it.

Sub-Commands

Clickable 7 introduces proper sub-commands providing specific parameters and help messages. Example: clickable create --help.

Chaining Commands

In Clickable 6 you could chain commands like clickable build install launch logs. On one hand this was practical, on the other it caused a lot of issues with different commands. This is not possible anymore with Clickable 7. But don’t be afraid! The chain command got your back. Example: clickable chain build install launch logs

If no command is provided to chain it will run the default chain build install launch, which can even be configured through the default field. And finally a pure clickable is equivalent to clickable chain. So not much changed after all.

Libraries

Libraries are now cleaned and built by the same commands as the app itself. Run clickable build --libs to build libraries, clickable clean --libs to clean them and clickable test --libs for running unit tests.

Project Configuration File

The clickable.json has a successor: clickable.yaml. The schema did not change, just the format. YAML allows to write better human-readable and cleaner config files.

If you just want to keep your config file as is, you can do so, because YAML is a superset of JSON. It is recommended to rename the file to clickable.yaml. But even if you keep the file name clickable.json, Clickable will find it after looking for a clickable.yaml.

Builders

Rust

In Clickable 6 the Rust builder would install files such as the manifest or assets. In order to be more flexible and better aligned with the other builds, this behaviour was removed from the builder and added as install_root_data field in the Rust app template. For existing Rust apps adding that field might be necessary as well.

The Rust builder now configures the target directory to the build directory configured with Clickable in order to make the clean command work correctly for Rust apps.

The Rust builder now runs cargo install instead of cargo build. It also supports build_args in your project config now.

Pure and Cordova

In Clickable 6 pure and cordova builders would silently override architecture and framework fields in the app manifest. This behaviour was removed. For existing apps relying on the old behaviour one might need to set those fields correctly or let Clickable override it by setting the fields to @CLICK_ARCH@ or @CLICK_FRAMEWORK@ accordingly.

Some time in the past, the pure builder app template contained a CMake configuration that would configure the manifest architecture field to amd64 when it actually should be all. If that is the case for your app, just remove the command that sets the variable CLICK_ARCH.

Custom Build Commands

In contrast to previous versions, Clickable 7 executes prebuild and postbuild commands within the build container, making it independent of tools installed on host side.

Clickable 7 lets you specify a list of commands for prebuild, build, postmake and postbuild besides the possibility of specifying a single string.

Removal of Deprecated Things

Clickable 6 still accepted some deprecated keywords, which are rejected by Clickable 7.

Architecture

Instead of setting arch in your project config you should specify the architecture you want to build for via command line. Example: clickable build --arch arm64

In case your app is restricted to one specific architecture for some reason, you can still set restrict_arch. Example:

"restrict_arch": "arm64"

If the environment used with container mode only supports compiling for one specific architecture, you should set the environment variable CLICKABLE_ARCH.

Build Templates

Clickable 6.12.2 changed the naming of build templates to builders in order to avoid confusion with app templates. A builder is rather a recipe for building than a template anyways. Clickable 7 now rejects the keyword template. You can use builder as a drop-in replacement.

Python Builder

Use the precompiled builder if your Python-based app contains architecture specific files or the pure template otherwise.

Dependencies

Clickable can install build dependencies via apt. Some of them are build tools you need on your host during the build, such as ninja or libtool. We call these host dependencies. Others are libraries used by your app and need to be installed for the target architecture. We call these target dependencies. Clickable needs to distinguish them as they need to be installed for different architectures.

Clickable 6 still accepted host dependencies through the deprecated keyword dependencies_build. Clickable 7 only accepts host dependencies through dependencies_host. The keyword for target dependencies remains dependencies_target.

Click Build Command

The click packaging is done by the build command. Clickable 6 still accepted the deprecated click-build command, which would only print a deprecation message. This ancient command has been removed completely in Clickable 7.