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.

Unconfined Apps¶

The build command fails if there are review warnings or errors, because the Open Store refuses the upload of click packages in that case. Unconfined apps need to configure review warnings to be ignored:

"ignore_review_warnings": true

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.

Commands¶

Clickable 7 introduces proper 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.

Update¶

The update command has been renamed to update-images because it was often misunderstood as a command to update clickable. In fact, it does only update the clickable docker images.

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.

The Rust builder can now be used in libraries, too. The Rust builder explicitly specifies the rust channel to avoid unintended rustup calls that would fail due to missing permissions in the container.

The channel can now be configured via the field rust_channel which makes it easy to use nightly or pin the rust version as desired (e.g. 1.56.1).

Go¶

In Clickable 6 the Go builder would install files all files from the project folder unless they were listed in ignore. In order to be more flexible and better aligned with the other builds, this behaviour was removed from the builder. Installing necessary files and folders has been added as install_root_data field in the Go app template. For existing Go apps adding that field might be necessary as well.

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

The Go builder no longer renames the produced binary based on the manifest.

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.

Container Handling¶

Unlike previous versions, Clickable 7 does not skip the image setup for custom docker images. If skipping is still desired, the command line flag --skip-image-setup can be used.

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.