Overview

Click Frameworks are "contracts" between the platform (OS) and apps. These were introduced by the Click packaging tool in Ubuntu Touch / Ubuntu for phones images to ensure apps shipped from the application store were compatible with installed devices. While it was introduced along the first Ubuntu for phone images for Unity 8 / QML / Qt apps, Click is not specific to these technologies and is applicable to other images / stacks.

There might be multiple frameworks on a single image. Framework xyz is present when /usr/share/click/frameworks/xyz.framework exists, however this should be tested with click_framework_has_framework (see LP #1271633 to track this requirement).

Available frameworks

This table is subject to change and lists existing, deprecated and planned frameworks.

Ubuntu for phones frameworks

Base name and base version

The 'base name' of the framework is here to permit click to support a wider range of underlying software than Ubuntu for phones in future; consider for example apps delivered for Xubuntu. Frameworks with different base names are not comparable, so the phone stack should never change its base name.

The 'base version' of the framework is determined by the release of Ubuntu that the framework first targeted.

Some examples:

How are frameworks defined

This depends of the release and of the type of framework:

• for 13.10 we had a single framework which was too broadly defined as "any QML module or C library directly depended upon by the ubuntu-sdk-libs package"
• for C/C++ apps, the framework will be derived from a list of included C/C++ APIs; actual location is TBD
• for QML apps, the frameworks will be derived from a list of versioned QML APIs; actual location is TBD
• for HTML/Cordova apps, the definition is TBD

Qt 5.0 / 5.2 ABI change and qreal ABI breakage

Ubuntu for phones 13.10 provided only framework ubuntu-sdk-13.10 which included all of Qt 5.0.

Ubuntu for phones 14.04 will provide new 14.04-* frameworks based on a subset of Qt 5.2 (not all APIs will be blessed), but it will also still provide the 13.10 framework thanks to a mostly compatible Qt runtime. Note however that in rare cases of apps using APIs with the qreal type, there might be an ABI breakage requiring the switch to the 14.04 framework. (This is due to an upstream ABI change in the qreal type which was changed from float to double; we don't expect similar breakage in future Qt releases.)

App developer FAQ

Which base version of the framework should I target?

The only stable framework defined so far was the 13.10 one, but it wasn't widely deployed and will soon be superseded. The 14.04 frameworks are imminent and we expect all devices to move to Ubuntu for phones 14.04 immediately after release. So you should target the 14.04-*-devN frameworks for now and move to the 14.04-* frameworks as soon as these are stable (probably around 14.04 beta 1, see TrustyTahr/ReleaseSchedule).

Once Ubuntu 14.04 is released, we expect most app developers to keep targeting 14.04-* frameworks as to ensure maximum compatibility between devices.

In terms of per-release frameworks, you should use the ones that your app requires; for instance, if your app is entirely written in QML, it only needs the ubuntu-sdk-14.04-qml framework.

The rule of thumb is to use the oldest supported framework which satisfies your app's requirements. At the moment this might imply using an older SDK than the latest, but we'd like to allow targeting older frameworks from latest SDK in the future.

How long are frameworks supported?

As long as possible, ideally forever. The 14.04 framework ought to be supported in later releases for some years.

May I use multiple frameworks flavors?

You may depend on multiple frameworks from the same base version; for instance, if your app requires QML and C libraries, you should depend on the ubuntu-sdk-14.04-qml and ubuntu-sdk-14.04-papi frameworks.

How do I target frameworks from multiple base versions?

Right now this requires uploading multiple apps under different names, but we're discussing ways to make this easier for app developers:

• either you'd bundle multiple versions of your app, one for each target framework
• or we'd allow declaration of a range of supported frameworks, and your app would use the highest available one at runtime

How will security policy be applied when targeting frameworks from multiple base versions?

If supporting multiple base versions is supported in a single click package, security policy shall be applied using the highest security policy version available on the device that is supported by the click package. This works because the highest policy version is considered safe on that release since that version will reflect the most up to date AppArmor userspace, AppArmor kernel code, trusted helpers, etc for that device.¹

Eg, suppose a click app declares that it is compatible with 13.10 and 14.04 frameworks:

• a 14.04 device with only the 14.04 framework installed can install the app and click-apparmor will apply 14.04 policy
• a 14.04 device with the 13.10 framework also installed can install the app and click-apparmor will apply the 14.04 policy
• a 13.10 device with only the 13.10 framework installed can install the app and click-apparmor will apply 13.10 policy

Now, suppose a click app declares it is compatible with 13.10 only:

• a 14.04 device with only the 14.04 framework installed cannot install the app
• a 14.04 device with the 13.10 framework also installed can install the app and click-apparmor will apply 13.10 policy
• a 13.10 device with only the 13.10 framework installed can install the app and click-apparmor will apply 13.10 policy

Devices shall not be allowed to have a system release version older than a base framework version. Eg, a 13.10 device with the 14.04 framework installed is not permitted.

¹ this does not necessarily hold true if a future version of the security implementation drops a security feature

Open questions

List and definition of 14.04 frameworks

The actual list and definition fo the 14.04 frameworks is in progress; need to finalize this ASAP.

In particular, do we allow deping on QML + Platform API frameworks? Do we introduce some meta 14.04 framework which depends on all the other 14.04-* ones?

We need to be able to tell which frameworks to use for a QML app with a C/C++ extension and for a C/C++ apps using QML (might be -qml in both cases.)

Proposed list of QML/Qt APIs

• jdstrand> I'd prefer QtWebkit be left off the list. Upstream Qt is abandoning it and Oxide will replace it.

Build environment and runtime ABI

Need to clarify requirements for build environment; how do we deliver a 14.04 build environment on non-14.04 hosts, how it's kept up-to-date, how do we update it (PPA + release pocket is the current plan), SRU verifications for ABI changes etc.

Go support

This is blocked on defining how Go apps would be built; embedding the stdlib in the Click app only requires using the same base version of the framework, while having shared library dependencies suggests either introducing a Go flavored framework or using the C/C++ libs one.

QtCreator and security policy

QtCreator should be adjust to use the click-apparmor query API so that it doesn't have to worry about which security policy should go with a specific framework.

Add your own