Clickable
=========

Build and compile Ubuntu Touch apps easily from the command line. Deploy your
apps to your Ubuntu Touch device for testing or test them on any desktop Linux
distribution. Get logs for debugging and directly access a terminal on your device.

Clickable is fully Open Source and can be found on `GitLab <https://gitlab.com/clickable/clickable>`__.
Clickable is developed by `Brian Douglass <http://bhdouglass.com>`__ and
`Jonatan Hatakeyama Zeidler <https://gitlab.com/jonnius>`__ with a huge
thank you to all the `contributors <https://gitlab.com/clickable/clickable/graphs/master>`__.

.. toctree::
    :maxdepth: 1
    :name: main

    install
    getting-started
    usage
    commands
    debugging
    continuous-integration

.. toctree::
    :maxdepth: 1
    :caption: Configuration
    :name: sec-configuration

    config
    project-config
    env-vars
    app-templates
    builders

.. toctree::
    :maxdepth: 1
    :caption: Changes
    :name: sec-changes

    changelog
    migration-guides

Getting Started
---------------

:ref:`Read the getting started guide to get started developing with clickable. <getting-started>`

Issues and Feature Requests
---------------------------

If you run into any problems using clickable or have any feature requests you
can find clickable on `GitLab <https://gitlab.com/clickable/clickable/issues>`__.
Clickable logs from the last run can be found at ``~/.clickable/clickable.log``
or ``~/snap/clickable/current/.clickable/clickable.log`` for the snap package.


.. _install:

Install
=======

Install Via Pip (Recommended)
-----------------------------

* Install docker, adb, git, python3 and pipx (Ubuntu 20.04 or higher)

  * pipx: ``sudo apt install docker.io adb git python3 pipx python3-setuptools``

* Run

  * pipx: ``pipx install clickable-ut``

* Add pip scripts to your PATH: ``echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc`` and open a new terminal for the setting to take effect

* Alternatively, to install nightly builds

  * pipx: ``pipx install git+https://gitlab.com/clickable/clickable.git@dev``

To update Clickable
  * pipx: ``pipx upgrade clickable-ut``

Install Via Python Virtual Environment (Alternative)
----------------------------------------------------

* Install docker, adb, git, python3 and pip3
  (in Ubuntu: ``sudo apt install docker.io adb git python3 python3-pip python3-setuptools python3-venv``)
* Run:

.. code-block:: bash
   :linenos:

   # Create a virtual environment called .venv
   python3 -m venv .venv --system-site-packages
   # Activate the virtual env
   source ./.venv/bin/activate
   # Install clickable
   pip install clickable-ut --upgrade
   # Create clickable app
   clickable create --dir ./

Install as Snap
---------------
* Make sure you have `snapd installed <https://snapcraft.io/docs/installing-snapd>`__.
* Run:

.. code-block:: bash
   :linenos:

   # Install clickable and docker
   sudo snap install clickable
   sudo snap install docker
   # Add connections
   sudo snap connect clickable:ssh-keys
   sudo snap connect clickable:etc-gitconfig

Install Via PPA (Ubuntu)
------------------------

* Add the `PPA <https://launchpad.net/~bhdouglass/+archive/ubuntu/clickable>`__ to your system: ``sudo add-apt-repository ppa:bhdouglass/clickable``
* Update your package list: ``sudo apt-get update``
* Install clickable: ``sudo apt-get install clickable``

Install Via AUR (Arch Linux)
----------------------------

* Using your favorite AUR helper, install the `clickable-git package <https://aur.archlinux.org/packages/clickable-git/>`__
* Example: ``pacaur -S clickable-git``

Install NixOS
-------------

* Using one of the following options to install the clickable package 
* nix-shell: ``nix-shell -p clickable``
* or add the following code to your configuration:

.. code-block:: nix
   :linenos:

   environment.systemPackages = [
     pkgs.clickable
   ];

After install
-------------

* Let Clickable setup docker (asking for root permissions) and bash completion: ``clickable setup``
* Log out or restart to apply changes if requested


.. _getting-started:

Getting Started
===============

* Run ``clickable create`` to get started with a new app.
* Choose from the list of :ref:`app templates <app-templates>`.
* Provide all the needed information about your new app.
* When the app has finished generating, enter the newly created directory containing your app.
* Run ``clickable`` to compile your app and install it on your phone.

For more information on Clickable basics, check out the `UBports Clickable video <https://youtu.be/O4vSweahsHs?si=_EMcQGtQNmfJewBR>`__.

Getting Logs
------------

To get logs from your app simply run ``clickable logs``. This will give you output
from C++ (``QDebug() << "message"``) or from QML (``console.log("message")``)
in addition to any errors or warnings.

Running on the Desktop
----------------------

Running the app on the desktop just requires you to run ``clickable desktop``.
This is not as complete as running the app on your phone, but it can help
speed up development.

Accessing Your Device
---------------------

If you need to access a terminal on your Ubuntu Touch device you can use
``clickable shell`` to open up a terminal to your device from your computer.
This is a replacement for the old ``phablet-shell`` command.

Ubuntu Touch SDK Api Docs
-------------------------

For more information about the Ubuntu Touch QML or HTML SDK check out the
`docs over at UBports <https://api-docs.ubports.com>`__.

Run Automatic Review
--------------------

Apps submitted to the OpenStore will undergo automatic review, to test your
app before submitting it, run ``clickable review`` after you've compiled a click.
This runs the ``click-review`` command against your click within the clickable
container (no need to install it on your computer).

.. _publishing:

Handling Dependencies
---------------------
For more information about compiling, using and deploying app dependencies, check out the
`docs over at UBports <https://docs.ubports.com/en/latest/appdev/guides/dependencies.html>`__.

Publishing to the OpenStore
---------------------------

If this is your first time publishing to the OpenStore, you need to
`signup for an account <https://open-store.io/login>`__. You can signup with
your GitHub, GitLab, or Ubuntu account.

If your app is new to the OpenStore you must first create your app by entering
the name from your manifest.json and the app's title
on the `OpenStore's submission page <https://open-store.io/submit>`__.

If your app already exists you can use the ``clickable publish`` command to
upload your compiled click file to the OpenStore. In order to publish to the
OpenStore you need to grab your
`api key from the OpenStore <https://open-store.io/manage>`__. After you have
your api key you need to let Clickable know about it. You can either pass it
as an argument every time: ``clickable publish --apikey XYZ`` Or you can set it
as an environment variable: ``export OPENSTORE_API_KEY=XYZ`` (you can add this
to your ``~/.bashrc`` to keep it set).


.. _usage:

Usage
=====

Getting Started
---------------

At this point it is assumed that you have completed the :ref:`installation
process <install>`

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 :ref:`getting started <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
:ref:`builder <builders>` 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 <http://docs.ubports.com/en/latest/userguide/advanceduse/adb.html?highlight=mode#enable-developer-mode>`__
for the app to be installed when using ADB or `enable ssh <http://docs.ubports.com/en/latest/userguide/advanceduse/ssh.html>`__
when using SSH.

Configuration
-------------
One can specify the path to a :ref:`project config file <project-config>`
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
:ref:`builder <builders>` with default configuration.

Device Access
-------------

Host Device
^^^^^^^^^^^

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

.. _device-detection:

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
:ref:`Clickable Configuration <ipv4>`. It will check SSH before ADB, unless
ADB was configured as :ref:`default_target <default_target>`.

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

.. _ssh:

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 <http://docs.ubports.com/en/latest/userguide/advanceduse/ssh.html>`__
on your device for this to work.

.. _multiple-devices:

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 (:ref:`qt_version <project-config-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
--------------

.. _lxd:

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``:

.. code-block:: bash

   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:

.. code-block:: bash

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


.. _commands:

Commands
========

The behavior of Clickable is controlled via commands, each with their own set of available
parameters.

.. code-block:: bash

   clickable <command> [param ...]

This documentation only lists some selected commands and parameters. Run
``clickable --help`` to see the list of all available commands and
``clickable <command> --help`` to get a command-specific help message listing its
available parameters.

Project-specific commands like ``build`` and ``install`` can be executed from the projec
root or any of its sub-directories, given there is a project config in the project root.

Running Clickable without a command is a shortcut to the default ``chain`` command (see
below). This special case allows a few universal parameters like ``--verbose`` and
``--arch``.

``chain``
---------

Chains multiple commands that can be specified. The default chain can be configured via the
:ref:`default <project-config-default>` field. If not configured, the default is
``build install launch``.

A clean build in a chain can be enforced by running ``clickable chain --clean``.

``desktop``
-----------

Compiles and runs the app on the desktop. Accepts the same arguments as the ``build`` command
plus some desktop mode specific ones.

Note: Snap and ArchLinux users might need to run ``xhost +local:clickable`` before using
desktop mode.

Run ``clickable desktop --dark-mode`` to set the dark mode preference.

Run ``clickable desktop --lang <language code>_<country code>`` (for example, `fr_FR`)
to test using a different language.

Run ``clickable desktop --gdb`` to start the app via GDB.

Run ``clickable desktop --qmllive`` on a QML only app enable QML live update when QML files are
changed.

The env var ``CLICKABLE_DESKTOP_MODE`` is set in desktop mode.

.. _commands-ide:

``ide``
-------

Will run an IDE inside the Clickable docker container, QtCreator by default.

``ci``
------

Will open a root bash inside a Clickable CI container that can be used to debug a CI job.

``run``
-------

Opens a bash inside the Clickable docker container to analyze the build environment.
This is only meant to inspect the container. Changes do not persist.

``clickable run -- <some command>`` runs an arbitrary command in the Clickable container.

``create``
----------

Generate a new app from a list of :ref:`app template options <app-templates>`.

``shell``
---------

Opens a SSH shell on a connected device either via SSH or ADB.

``clean``
---------

Cleans out the app build dir. Can be applied to libraries by appending ``--libs``.

``build``
---------

Builds the project using the specified builder, build dir, and build commands.
Then it takes the built files and compiles them into a click package (you can
find it in the build dir). Finally runs a review.

Set the manifest architecture field to ``@CLICK_ARCH@`` and the framework field
to ``@CLICK_FRAMEWORK@`` to have Clickable replace them with the appropriate values.

Set the apparmor policy to ``@APPARMOR_POLICY@`` to have Clickable replace it with
an appropriate value based on the framework.

Specify where to put the compiled click by ``--output``.

Builds libraries specified in the project config using the ``libs`` parameter.

``review``
----------

Takes the built click package and runs click-review against it. This allows you
to review your click without installing click-review on your computer.

The review runs automatically after a ``build`` command.

.. _commands-test:

``test``
--------

Run your test suite with a virtual screen. By default this runs ``qmltestrunner``,
but you can specify a custom command by setting the :ref:`test <project-config-test>`
property in your project config.

``install``
-----------

Takes a built click package from the build dir and installs it on a connected device.

``launch``
----------

Launches the app on a connected device.

``clickable launch <app name>`` launches the specified app.

``logs``
--------

Follows the app log file on a connected device.

``log``
------------------

Prints the app log file from a connected device.

``publish``
-----------

Publish your click package to the OpenStore. Check the
:ref:`Getting started doc <getting-started>` for more info.

``clickable publish "changelog message"`` publishs your click app to the OpenStore
with a message prepended to the changelog.

``update-images``
-----------------

Update the docker images used with Clickable.

``no-lock``
-----------

Turns off the display timeout for a connected device.

``writable-image``
------------------

Make your Ubuntu Touch device's rootfs writable.

``devices``
-----------

Lists the serial numbers and model names for attached devices using ADB. Useful when
multiple devices are attached and you need to know what to use for the ``-s``
argument.

``script``
----------

``clickable script <script name>`` runs a custom command specified as a script in the
project config.

Shared Parameters
-----------------

Some parameters can be used with multiple commands. This sections explains some of them.

``--arch``
^^^^^^^^^^

Specifying the target architecture allows Clickable to select to appropriate
docker image, choose the build dir path and (cross-)compile the app correctly.

Defaults to the host architecture.

.. _nvidia:

``--nvidia``
^^^^^^^^^^^^

The ``desktop`` command checks automatically if nvidia-drivers are installed and turns on nvidia
mode. If ``prime-select`` is installed, it is queried to check whether the nvidia-driver
is actually in use.
The ``--nvidia`` flag lets you manually enforce nvidia mode. The ``--no-nvidia``
flag in contrast lets you disable automatic detection.

Depending on your docker version, the docker execution will change and
you need to provide additional system requirements:

**docker < 19.03 system requirements**

* nvidia-modprobe
* nvidia-docker

On Ubuntu, install these requirements using ``apt install nvidia-modprobe nvidia-docker``.

**docker >= 19.03 system requirements**

* nvidia-container-toolkit

On Ubuntu, install these requirements using ``apt install nvidia-container-toolkit``.

To be able to install the nvidia-container-toolkit you have to perform the following commands
(as mentioned on https://www.server-world.info/en/note?os=Ubuntu_20.04&p=nvidia&f=2):

As root:

.. code-block:: bash

   curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | apt-key add -

   curl -s -L https://nvidia.github.io/nvidia-docker/ubuntu20.04/nvidia-docker.list > /etc/apt/sources.list.d/nvidia-docker.list

   apt update

   apt -y install nvidia-container-toolkit

   systemctl restart docker

Run Clickable with the ``--verbose`` flag to see the executed command for your system.

.. _container-mode:

``--container-mode``
^^^^^^^^^^^^^^^^^^^^

Runs all builds commands on the current machine and not in a container. This is
useful for running Clickable from within a container, especially in a CI.

``--verbose``
^^^^^^^^^^^^^

Have Clickable print out debug information and more detailed error messages. Also
makes tools like ``make`` or ``cargo`` more verbose.

``--ssh``
^^^^^^^^^

Specify an IP address to run a device-related command over SSH rather than the default
ADB. Note that you will first need to set up SSH public key authentication for your device by following the
`SSH setup instructions <https://docs.ubports.com/en/latest/userguide/advanceduse/ssh.html>`__.



.. _debugging-with-gdb:

Debugging
=========

Clickable does not separate build caches for different build types. Therefore make
sure to create a clean debug build, e.g. via
``clickable build --debug --clean --arch arm64``.

Desktop Mode
------------

The easiest way to do GDB Debugging via Clickable is desktop mode and can be started
by running ``clickable desktop --gdb``.

Alternatively a GDB Server can be started with ``clickable desktop --gdbserver <port>``
(just choose any port, e.g. ``3333``). Check for an option to do GDB Remote Debugging
in your IDE and connect to ``localhost:<port>``. To connect a GDB Client run
``gdb <app-binary> -ex 'target remote localhost:<port>'``.

To analyze errors in memory access run ``clickable desktop --valgrind``.

.. _on-device-debugging:

On Device
---------

Two terminals are required to do debugging on the device, one to start the ``gdbserver``
and the other one to start ``gdb``. In the first terminal run ``clickable gdbserver``
and in the second one ``clickable gdb``. This method is limited to
apps that are started via their own binary file.

For Debugging in your IDE, run ``clickable gdb --script debug.gdbinit``. This creates
a GDB script that can be configured as init script in your IDE's GDB Remote Debugging
feature. To execute the script from a gdb shell (e.g. gdb-multiarch) run
``source debug.gdbinit``.

For detailed instructions on how to use gdb check out
`gdb documentation <https://sourceware.org/gdb/current/onlinedocs/gdb/>`__.


.. _continuous-integration:

Continuous Integration
======================

Clickable CI Docker Images
--------------------------

CI docker images are available for easily using Clickable with a continuous
integration setup. They can be found on Docker hub: ``clickable/ci-20.04-armhf``,
``clickable/ci-20.04-amd64`` and ``clickable/ci-20.04-arm64``.
The images come with Clickable pre installed and already setup in container mode.

GitLab CI Tutorial
------------------

For a full guide to setting up GitLab CI with a Clickable app check out this
`blog post <https://bhdouglass.com/blog/publishing-apps-to-the-openstore-with-gitlab-ci/>`__.
This method can also be adapted for other CI solutions.

A working template of a `.gitlab-ci.yml` for building and publishing your app can be found in the `clickable app template <https://gitlab.com/clickable/ut-app-meta-template/-/blob/master/{{cookiecutter['App Name']}}/.gitlab-ci.yml>`__. If you also wish to have an automatic gitlab release to be created when pushing a tag, follow `gitlabs docs <https://docs.gitlab.com/ee/ci/yaml/#release>`__. To use the last commit message as description use this configuration `description: "$CI_COMMIT_MESSAGE"`.

.. _config:

Clickable Config Format
=======================

Optionally, a config file can be provided to configure Clickable for
all projects. The file needs to be located at ``~/.clickable/config.yaml``
or ``~/snap/clickable/current/.clickable/config.yaml`` for the snap package.

Example:

.. code-block:: javascript

    device:
      ipv4: 192.168.178.41

    build:
      skip_review: true
      default_arch: arm64

    cli:
      default_chain:
        - build
        - install
        - launch
        - logs
      scripts:
        submodules: git submodule update --init --recursive

    ide:
      image_setup:
        run:
          - apt update
          - apt install vim -y

      default: vim .

device
------

Default configurations for the target device.

.. _ipv4:

ipv4
^^^^

IP address used for connecting via SSH.

Can be overwritten on command line with ``--ssh``.

serial_number
^^^^^^^^^^^^^

Device serial number for connecting via ADB.

Can be overwritten on command line with ``--serial-number``.

.. _default_target:

default_target
^^^^^^^^^^^^^^

Target device used by default. Allowed values are ``ssh``, ``adb``, ``host``
and ``detect`` (default value).

====== =================
Value  Description
====== =================
host   Don't detect remote devices and interact with host system instead.
detect Try to detect a remote device (default behavior)
ssh    Check via SSH before checking for ADB devices (currently default behavior).
adb    Check for ADB devices before checking via SSH.
====== =================

always_detect
^^^^^^^^^^^^^

Detect the remote device and its architecture even for commands that don't require
a connection to the device (e.g. ``build``). Behaves like ``--arch detect``

skip_uninstall
^^^^^^^^^^^^^^

Skip uninstall step before installing an app.

Can be overwritten on command line with ``install --skip-uninstall``.

build
-----

Default configuration for the ``build`` command.

always_clean
^^^^^^^^^^^^

Always clean the build directory before building.

skip_review
^^^^^^^^^^^

Skip automatic review after building. Review can still be executed manually
using the ``review`` command.

default_arch
^^^^^^^^^^^^

Target architecture used by default.

Can be overwritten on command line with ``--arch``.
Allowed values are ``armhf``, ``arm64``, ``amd64`` and ``detect``.

environment
-----------

Default configuration for the environment Clickable is running in.

nvidia
^^^^^^

Set to ``"on"`` if you use the proprietary nvidia driver in order to use a special
docker image with an nvidia workaround in Desktop Mode.
Set to ``"off"`` to disable nvidia support.
Set to ``"auto"`` to let Clickable automatically detect whether an nvidia driver is in
use. This is the default behavior.

non_interactive
^^^^^^^^^^^^^^^

Do not show prompts for anything.

container_mode
^^^^^^^^^^^^^^

Run all commands withing the environment and do not use docker containers.

restrict_arch
^^^^^^^^^^^^^

Restrict the architecture the environment can build for. This is meant to be used
in conjunction with ``container_mode``.
Allowed values are ``armhf``, ``arm64``, ``amd64`` and ``host``.

cli
---

default_chain
^^^^^^^^^^^^^

Change the default chain of commands to be executed on a pure ``clickable`` or a
``clickable chain`` call.

scripts
^^^^^^^

Add scripts to be used with the ``script`` command.

ide
---

image_setup
^^^^^^^^^^^

Additional run commands and env vars for preparing the ``ide`` docker image. This
allows to install your preferred IDE.

default
^^^^^^^

Default run command for ``ide`` command. This allows to start your preferred IDE
by default.


.. _project-config:

Project Config Format
=====================

Example:

.. code-block:: yaml

    builder: cmake
    scripts:
    - fetch: git submodule update --init
    dependencies_target:
    - libpoppler-qt5-dev

.. _project-config-placeholders:

Placeholders & Environment Variables
------------------------------------

Placeholders are values provided by Clickable that can be used in some
configuration fields as ``${PLACEHOLDER}``.
All placeholders are provided as environment variables during build, additionally.
For custom environment variables see :ref:`env_vars <project-config-env_vars>`.

The following table lists all available placeholders.

======================= ======
Placeholder             Output
======================= ======
CLICK_FRAMEWORK_BASE    Target framework base (``20.04`` by default)
CLICK_FRAMEWORK         Target framework (``ubuntu-sdk-20.04`` by default)
SDK_FRAMEWORK           Depecrated, same as CLICK_FRAMEWORK
APPARMOR_POLICY         The (assumed) app armor policy, based on target framework
QT_VERSION              Qt version within target framework (``5.12`` by default)
ARCH                    Target architecture (``armhf``, ``arm64``, ``amd64`` or ``all``)
ARCH_TRIPLET            Target architecture triplet (``arm-linux-gnueabihf``, ``aarch64-linux-gnu``, ``x86_64-linux-gnu`` or ``all``)
ARCH_RUST               Rust target (``armv7-unknown-linux-gnueabihf``, ``aarch64-unknown-linux-gnu`` or ``x86_64-unknown-linux-gnu``)
NUM_PROCS               Number of build jobs recommended (``make_jobs``) and used by the CMake and QMake builders
ROOT                    Value of ``root_dir``
BUILD_DIR               Value of ``build_dir``
SRC_DIR                 Value of ``src_dir``
INSTALL_DIR             Value of ``install_dir``
CLICK_LD_LIBRARY_PATH   ``${INSTALL_DIR}/lib/${ARCH_TRIPLET}`` (will be in ``LD_LIBRARY_PATH`` at runtime) or ``${INSTALL_DIR}/lib`` for architecture independent apps
CLICK_QML2_IMPORT_PATH  ``${INSTALL_DIR}/lib/${ARCH_TRIPLET}`` (will be in ``QML2_IMPORT_PATH`` at runtime) or ``${INSTALL_DIR}/qml`` for architecture independent apps
CLICK_PATH              ``${INSTALL_DIR}/lib/${ARCH_TRIPLET}/bin`` or ``${INSTALL_DIR}`` for architecture independent apps (will be in ``PATH`` at runtime)
<lib>_LIB_BUILD_DIR     Value of ``build_dir`` from library with name ``<lib>`` (see :ref:`libraries <project-config-libraries>`), where the library name consists solely of capital letters (e.g. from lib name ``my-libC++`` this env var would be ``MY_LIBC___LIB_BUILD_DIR``)
<lib>_LIB_INSTALL_DIR   Value of ``install_dir`` from library with name ``<lib>`` (e.g. ``OPENCV_LIB_INSTALL_DIR``)
<lib>_LIB_SRC_DIR       Value of ``src_dir`` from library with name ``<lib>`` (e.g. ``OPENCV_LIB_SRC_DIR``)
======================= ======

Parameters accepting placeholders:
``root_dir``, ``build_dir``, ``src_dir``, ``install_dir``,
``app_lib_dir``, ``app_bin_dir``, ``app_qml_dir``,
``gopath``, ``cargo_home``, ``scripts``, ``build``,
``build_args``, ``make_args``, ``postmake``, ``postbuild``,
``prebuild``,
``install_lib``, ``install_qml``, ``install_bin``, ``install_root_data``,
``install_data`` and ``env_vars``.

This is an ordered list. Parameters that are used as placeholders themselves accept only predecessors.
Ex: ``${ROOT}`` can be used in ``src_dir``, but not vice-versa.

Library placeholders can be used by subsequent libraries, but not predecessors.

Example:

.. code-block:: yaml

    build_dir: ${ROOT}/build/${ARCH_TRIPLET}/myApp

clickable_minimum_required
--------------------------

Optional, a minimum Clickable version number required to build the project.
Ex: ``"6"`` or ``"5.4.0"``

.. _project-config-qt_version:

qt_version
----------

Qt version consisting of major and minor version. This value is used to
determine the framework automatically. Defaults to ``5.12``. Currently, no
other version is supported.

.. _project-config-framework:

framework
---------

The SDK framework which the app should be built for. This allows Clickable to
choose the correct docker image and set the ``framework`` field in the manifest
accordingly, if desired.
Ex: ``ubuntu-sdk-16.04.5`` or ``ubuntu-sdk-20.04``

.. _project-config-restrict_arch:

restrict_arch
-------------

Optional, specifies an exclusive architecture that this configuration is compatible with.
This prevents the app from being build for other architectures and may also prevent the desktop mode.

To specify the architecture for building use the cli argument instead (ex: ``--arch arm64``).

.. _project-config-builder:

builder
-------

Optional, see :ref:`builders <builders>` for the full list of options.

prebuild
--------

Optional, a custom command to run from the root dir, before a build.

Can be specified as a string or a list of strings.

build
-----

A custom command to run from the build dir. Required if using the ``custom``
builder, ignored otherwise.

Can be specified as a string or a list of strings.

postmake
---------

Optional, a custom command to execute from the build directory, after make (during build). Only
used for Make-based builders.

Can be specified as a string or a list of strings.

postbuild
---------

Optional, a custom command to execute from the root dir, after build, but before click packaging.

Can be specified as a string or a list of strings.

.. _project-config-env_vars:

env_vars
--------

Optional, environment variables to be set in the build container. Ex:

.. code-block:: yaml

    env_vars:
      TARGET_SYSTEM: UbuntuTouch

When passing ``--debug`` to Clickable, ``DEBUG_BUILD=1`` is set as an environment variable, additionally.

build_args
----------

Optional, arguments to pass to qmake, cargo or cmake.

When using ``--debug``, ``CONFIG+=debug`` is additionally appended for qmake and
``-DCMAKE_BUILD_TYPE=Debug`` for cmake and cordova builds. For cargo calls
``--release`` is added if not running Clickable with ``--debug``.

Ex: ``CONFIG+=ubuntu``

Can be specified as a string or a list of strings.

.. _project-config-make-args:

make_args
---------

Optional, arguments to pass to make, e.g. a target name. To avoid configuration
conflicts, the number of make jobs should not be specified here, but using
``make_jobs`` instead, so it can be overriden by the according environment variable.

Can be specified as a string or a list of strings.

.. _project-config-make-jobs:

make_jobs
---------

Optional, the number of jobs to use when running make, equivalent to make's ``-j``
option. If left blank this defaults to the number of CPU cores.

launch
------

Optional, a custom command to launch the app, used by ``clickable launch``.

.. _project-config-build_dir:

build_dir
---------

Optional, a custom build directory. Defaults to ``${ROOT}/build/${ARCH_TRIPLET}/app``.
Thanks to the architecture triplet, builds for different architectures can
exist in parallel.

src_dir
-------

Optional, a custom source directory. Defaults to ``${ROOT}``

install_dir
-----------

Optional, a custom install directory (used to gather data that goes into the click package).
Defaults to ``${BUILD_DIR}/install``

.. _project-config-install_lib:

install_lib
-----------

Optional, additional libraries that should be installed with the app and be in ``LD_LIBRARY_PATH``
at runtime.
If an entry is just a file name, then Clickable looks for it in common library locations
(as listed in ``/etc/ld.so.conf.d/*.conf``) as well as the install dirs of libraries defined in the
libraries section.
The destination directory is ``${CLICK_LD_LIBRARY_PATH}``. Ex:

.. code-block:: yaml

    install_lib:
    - libasound.so*
    - /usr/lib/${ARCH_TRIPLET}/libasound.so*

Can be specified as a string or a list of strings.
Supports wildcards.

install_qml
-----------

Optional, additional QML files or directories that should be installed with the app and be in
``QML2_IMPORT_PATH`` at runtime. The destination directory is ``${CLICK_QML2_IMPORT_PATH}``. Ex:

.. code-block:: yaml

    install_qml:
    - /usr/lib/${ARCH_TRIPLET}/qt5/qml/Qt/labs/calendar

Relative paths are prepended with the project root dir.

QML modules will be installed to the correct directory based on the name of the module.
In the above example it will be installed to ``lib/${ARCH_TRIPLET}/Qt/labs/calendar``
because the module specified in the qmldir file is ``Qt.labs.calendar``.
Can be specified as a string or a list of strings. Supports wildcards.

install_bin
-----------

Optional, additional executables that should be installed with the app and be in ``PATH`` at runtime.
If an entry is just a file name, then Clickable looks for it in ``PATH`` as well as the install
dirs of libraries defined in the libraries section.
The destination directory is ``${CLICK_PATH}``. Ex:

.. code-block:: yaml

    install_bin:
    - htop
    - /usr/bin/htop

Relative paths are prepended with the project root dir.

Can be specified as a string or a list of strings. Supports wildcards.

install_root_data
-----------------

Optional, additional files or directories that should be installed with the app and be in the app
root dir. Ex:

.. code-block:: yaml

    install_root_data:
    - packaging/manifest.json
    - packaging/myapp.desktop

Can be specified as a string or a list of strings. Supports wildcards.

install_data
------------

Optional, additional files or directories that should be installed with the app.
Needs to be specified as a dictionary with absolute source paths as keys and destinations as value. Ex:

.. code-block:: yaml

    install_data:
      icons/logo.svg: assets

Relative source paths are prepended with the project root dir and destination paths with
the install dir.

Can be specified as a string or a list of strings. Supports wildcards.
``${INSTALL_DIR}`` is added as prefix if path is not relative to the install dir.

kill
----

Optional, a custom process name to kill (used by ``clickable launch`` to kill the app before
relaunching it). If left blank the process name will be assumed.

scripts
-------

Optional, an object detailing custom commands to run. For example:

.. code-block:: yaml

    scripts:
      fetch: git submodule update --init
      echo-target: echo ${ARCH_TRIPLET}

That enables the use of ``clickable script fetch`` and ``clickable script echo-target``.

.. _project-config-default:

default
-------

Optional, sub-commands to run when with the ``chain`` command when no
sub-commands are specified. Defaults to ``build install launch``.
The ``--clean`` cli argument prepends ``clean`` to that list.

Can be specified as a string or a list of strings.

.. _project-config-always-clean:

always_clean
------------

Optional, whether or not to always clean app build directory before building,
disabling the build cache. Affects the ``chain``, ``build`` and ``desktop`` command.
Does not affect libraries.
The default is ``false``.

is_app
------

Optional, whether or not the project contains an app that can be packaged as a
click. If not, the project can still be used to build libraries.
The default is ``true``.

ignore_review_errors
--------------------

Optional, whether or not to let the build command fail if there are review errors.
The default is ``false``.

ignore_review_warnings
----------------------

Optional, whether or not to let the build command fail if there are review warnings.
The default is ``false``.

skip_review
-----------

Optional, whether or not to skip review on click builds at all. Usually
``ignore_review_warnings`` or ``ignore_review_errors`` should be preferred.
The default is ``false``.

.. _project-config-dependencies_host:

dependencies_host
-----------------

Optional, a list of dependencies that will be installed in the build container.

Add tools here that are part of your build tool chain.

Can be specified as a string or a list of strings.

.. _project-config-dependencies_target:

dependencies_target
-------------------

Optional, a list of dependencies that will be installed in the build container.
These will be assumed to be ``dependency:arch`` (where ``arch`` is the target
architecture), unless an architecture specifier
is already appended.

Add dependencies here that your app depends on.

Can be specified as a string or a list of strings.

.. _project-config-dependencies-ppa:

dependencies_ppa
----------------

Optional, a list of PPAs, that will be enabled in the build container. Ex:

.. code-block:: yaml

    dependencies_ppa:
    - ppa:bhdouglass/clickable

Can be specified as a string or a list of strings.

rust_channel
------------
Optional, rust channel that should installed in the image and used by the rust
builder.
Ex: ``nightly`` or ``1.56.0``

.. _project-config-docker-image:

image_setup
-----------
Optional, dictionary containing setup configuration for the docker image used.
The image is based on the default image provided by Clickable. Example:

.. code-block:: yaml

    image_setup:
      env:
        PATH: /opt/someprogram/bin:$PATH
      run:
      - curl -fsSL https://deb.nodesource.com/setup_current.x | bash -
      - apt-get install -y nodejs

run
^^^
Optional, a list of commands to run on image setup (each added as `RUN <cmd>` to
the corresponding Dockerfile).

These commands also run in container mode (CI).

env
^^^
Optional, a dictionary of env vars to add during image setup (each added as
`ENV <key>="<val>"` to the corresponding Dockerfile).

These are ignored in container mode (use
:ref:`env_vars <project-config-env_vars>` instead).

docker_image
------------

Optional, the name of a docker image to use. When building a custom docker image
it's recommended to use one of the Clickable images as a base. You can find them
on `Docker Hub <https://hub.docker.com/u/clickable>`__.

ignore
------

Optional, a list of files to ignore when building with ``pure`` builder
Example:

.. code-block:: yaml

    ignore:
    - .clickable
    - .git
    - .gitignore
    - .gitmodules

Can be specified as a string or a list of strings.

.. _project-config-gopath:

gopath
------

Optional, the gopath on the host machine. If left blank, the ``GOPATH`` env var will be used.

.. _project-config-cargo_home:

cargo_home
----------

Optional, the Cargo home path on the host machine that is used for caching
(namely its subdirs ``registry``, ``git`` and ``.package-cache``).
Defaults to ``~/.clickable/cargo``.

.. _project-config-build-args:

root_dir
--------

Optional, specify a different root directory for the project. For example,
if you project config file is in ``platforms/ubuntu_touch`` and you want to include
code from root of your project you can set ``root_dir: "../.."``. Alternatively you can run
clickable from the project root in that case via
``clickable -c platforms/ubuntu_touch/clickable.yaml``.

.. _project-config-test:

test
----

Optional, specify a test command to be executed when running ``clickable test``.
The default is ``qmltestrunner``.

.. _project-config-libraries:

templates
---------

Optional, add reusable objects here for reuse with yaml anchors. Mostly usefull
to share dependency lists or build args between libraries.

.. code-block:: yaml

    templates:
      lib_dep: &lib_dep
        dependencies_host:
        - nasm
        dependencies_target:
        - libasound2-dev

    libraries:
      mylib1:
        <<*: &lib_dep
        builder: cmake
      mylib2:
        <<*: &lib_dep
        builder: cmake

.. _project-config-templates:

libraries
---------
Optional, dependencies to be build by running ``clickable build --libs``.
It's a dictionary of dictionaries similar to the project config itself. Example:

.. code-block:: yaml

    libraries:
      opencv:
        builder: cmake
        make_jobs: 2
        build_args: [
          -DBUILD_LIST=core,imgproc,highgui,imgcodecs,
          -DBUILD_SHARED_LIBS=OFF
        ]
        prebuild: git submodule update --init --recursive

The keywords ``test``, ``install_dir``, ``prebuild``, ``build``, ``postbuild``,
``postmake``, ``make_jobs``, ``make_args``, ``env_vars``, ``build_args``, ``docker_image``,
``dependencies_host``, ``dependencies_target``, ``dependencies_ppa``, ``test``,
``restrict_arch``` and ``image_setup``.

can be used for a library the same way as described above for the app.

In addition to the :ref:`placeholders <project-config-placeholders>` described above,
the following placeholders are available:

============= ======
Placeholder   Output
============= ======
NAME          The library name (key name in the ``libraries`` dictionary)
============= ======

A single library can be build by specifying its name as
``clickable build --libs lib1 --arch arm64`` to build the library with name
``lib1`` for the architecture ``arm64``.
``clickable clean --libs lib1 --arch arm64`` cleans the libraries build dir.
``clickable test --libs lib1`` tests the library.

builder
^^^^^^^
Required, but only ``cmake``, ``qmake``, ``rust`` and ``custom`` are allowed.

src_dir
^^^^^^^
Optional, library source directory. Must be relative to the project root. Defaults to ``${ROOT}/libs/${NAME}``

build_dir
^^^^^^^^^
Optional, library build directory. Must be relative to the project root. Defaults to ``${ROOT}/build/${ARCH_TRIPLET}/${NAME}``.
Thanks to the architecture triplet, builds for different architectures can
exist in parallel.

Removed keywords
----------------
The following keywords are no longer supported:

- ``dependencies`` (use ``dependencies_target`` and ``dependencies_host`` instead)
- ``specificDependencies``
- ``dir`` (use ``build_dir`` instead)
- ``lxd``
- ``premake`` (use ``prebuild``, ``postmake`` or ``postbuild`` instead)
- ``ssh`` (use program option ``--ssh`` or environment variable ``CLICKABLE_SSH`` instead)
- ``chroot``
- ``sdk``
- ``package``
- ``app``
- ``dirty`` (use ``always_clean`` for the opposite case instead)
- ``arch`` (use program option ``--arch`` instead)
- ``template`` (use ``builder`` instead)
- ``dependencies_build`` (use ``dependencies_host`` instead)


.. _env-vars:

Environment Variables
=====================

Environment variables will override values in the project config and can be
overridden by command line arguments.

In contrast to the environment variables described here that configure
Clickable, there are :ref:`environment variables <project-config-placeholders>` set by
Clickable to be used during build.

``CLICKABLE_ARCH``
------------------

Restricts build commands (``build``, ``build-libs``, ``desktop``) to the specified architecture. Architecture agnostic builds (``all``) are not affected. Useful in container mode.

``CLICKABLE_QT_VERSION``
------------------------

Overrides the project config's :ref:`qt_version <project-config-qt_version>`.

``CLICKABLE_FRAMEWORK``
-----------------------

Overrides the project config's :ref:`framework <project-config-framework>`.

``CLICKABLE_BUILDER``
---------------------

Overrides the project config's :ref:`builder <project-config-builder>`.

``CLICKABLE_BUILD_DIR``
-----------------------

Overrides the project config's :ref:`dir <project-config-build_dir>`.

``CLICKABLE_DEFAULT``
---------------------

Overrides the project config's :ref:`default <project-config-default>`.

``CLICKABLE_MAKE_JOBS``
-----------------------

Overrides the project config's :ref:`make_jobs <project-config-make-jobs>`.

``GOPATH``
----------

Overrides the project config's :ref:`gopath <project-config-gopath>`.

``CARGO_HOME``
--------------

Overrides the project config's :ref:`cargo_home <project-config-cargo_home>`.

``CLICKABLE_DOCKER_IMAGE``
--------------------------

Overrides the project config's :ref:`docker_image <project-config-docker-image>`.

``CLICKABLE_SKIP_DOCKER_CHECKS``
--------------------------------

Disables check whether docker is installed and properly set up.

``CLICKABLE_DOCKER_COMMAND``
----------------------------

Replaces the docker command. This is useful on systems where both, docker and
podman, are installed and Clickable would give podman precedence.

``CLICKABLE_BUILD_ARGS``
------------------------

Overrides the project config's :ref:`build_args <project-config-build-args>`.

``CLICKABLE_MAKE_ARGS``
------------------------

Overrides the project config's :ref:`make_args <project-config-make-args>`.

``OPENSTORE_API_KEY``
---------------------

Your api key for :ref:`publishing to the OpenStore <publishing>`.

``CLICKABLE_CONTAINER_MODE``
----------------------------

Same as :ref:`--container-mode <container-mode>`.

``CLICKABLE_SERIAL_NUMBER``
---------------------------

Same as :ref:`--serial-number <multiple-devices>`.

``CLICKABLE_SSH``
-----------------

Same as :ref:`--ssh <ssh>`.

``CLICKABLE_OUTPUT``
--------------------

Override the output directory for the resulting click file

``CLICKABLE_NVIDIA``
--------------------

Same as :ref:`--nvidia <nvidia>`.

``CLICKABLE_NO_NVIDIA``
-----------------------

Same as :ref:`--no-nvidia <nvidia>`.

``CLICKABLE_ALWAYS_CLEAN``
--------------------------

Overrides the project config's :ref:`always_clean <project-config-always-clean>`.

``CLICKABLE_NON_INTERACTIVE``
-----------------------------

Same as ``--non-interactive``

``CLICKABLE_DEBUG_BUILD``
-------------------------

Same as ``--debug``

``CLICKABLE_TEST``
------------------

Overrides the project config's :ref:`test <project-config-test>`.

``CLICKABLE_DARK_MODE``
-----------------------

Same as ``--dark-mode``

``CLICKABLE_ENV_<CUSTOM>``
--------------------------

Adds custom env vars to the build container. E.g. set
``CLICKABLE_ENV_BUILD_TESTS=ON`` to have ``BUILD_TESTS=ON`` set in the build
container.

Overrides env vars in :ref:`test <project-config-env_vars>`.

``CLICKABLE_DOCKER_REGISTRY``
-----------------------------

The Docker registry used to pull images. Defaults to ``docker.io`` to pull
from `Docker Hub <https://hub.docker.com/u/clickable>`__.
To use the `GitLab container registry <https://gitlab.com/groups/clickable/-/container_registries>`__
change this to ``registry.gitlab.com/clickable``.


.. _app-templates:

App Templates
=============

Find the source code for the templates on `GitLab <https://gitlab.com/clickable/ut-app-meta-template>`__.

QML Only
--------

An app template that is setup for a purely QML app. It includes a CMake setup
to allow for easy translations.

C++
---

An app template that is setup for a QML app with a C++ plugin. It includes a CMake
setup for compiling and to allow for easy translation.

Python
------

An app template that is setup for an app using Python with QML. It includes a
CMake setup to allow for easy translation.

HTML
----

An app template that is setup for a local HTML app.

Go
--

An app template that is setup for a QML app with a Go backend.

Rust
----

An app template that is setup for a QML app with a Rust backend.

Godot (Precompiled)
-------------------

An app template that is setup to package a precompiled Godot app together with
a patched Godot and SDL 2 build.

SDL
---

An app template that is setup for an SDL app. It includes both SDL3 and SDL2
through `sdl2-compat <https://github.com/libsdl-org/sdl2-compat>`__, as well as
satellite libraries like SDL_image, SDL_ttf, SDL_mixer and SDL_net, both
versions 2 and 3.

The template provides information to assist developers wishing to port existing
apps based on SDL to Ubuntu Touch; another good information source is the
`SDL docs for Ubuntu Touch <https://github.com/libsdl-org/SDL/blob/main/docs/README-ubuntu-touch.md>`__.


.. _builders:

Builders
========
Builders have been called Build Templates in the early days of Clickable.

pure-qml-qmake
--------------

A purely qml qmake project.

qmake
-----

A project that builds using qmake (has more than just QML).

pure-qml-cmake
--------------

A purely qml cmake project

cmake
-----

A project that builds using cmake (has more than just QML)

custom
------

A custom build command will be used.

pure
----

A project that does not need to be compiled. All files in the project root will be copied into the click.

precompiled
-----------

A project that does not need to be compiled. All files in the project root will
be copied into the click. There may be precompiled binaries or libraries
included in apps build with this builder. Specifying the
:ref:`restrict_arch <project-config-restrict_arch>` in the project config file
can be useful with this builder.

qbs
---

A project that builds using QBS.

go
--

A project that uses go version 1.6.

rust
----

A project that uses rust. Debug builds can be enabled by specifying ``--debug``.

Removed Builders
----------------

The following builders are no longer supported:

- ``python`` (use ``precompiled`` or ``pure`` instead)
- ``cordova``


Migration Guides
================

.. toctree::
    :maxdepth: 1
    :name: migration-guides

    migration
    migration7


.. _migration8:

Clickable 8 Migration
=====================

This guide describes the changes that come with Clickable 8 and how to migrate a
project from Clickable 7.

For migration from Clickable 6 to 7, see :ref:`Clickable 7 Migration <migration7>`.

Default Framework
-----------------

The default framework changed from ``ubuntu-sdk-16.04.5`` to ``ubuntu-sdk-20.04``.
If your app is made for Ubuntu Touch 16.04, you need to set the framework:

.. code-block:: yaml

    framework: ubuntu-sdk-16.04.5

Command Line Interface
----------------------

Until Clickable 7, all commands would accept ``--ssh`` and ``--serial-number`` as
arguments. Starting with Clickable 8, only device commands like ``install`` or
``launch`` accept these.

If you want to opt into architecture detection for architecture-specific, but
non-device commands, like ``build``, you can pass ``--arch detect``.

For device commands, you can specify the target device with ``--target``, which
can be one of ``ssh``, ``adb``, ``host`` and ``detect`` (resolves to either
``ssh`` or ``adb``).

Project Config
--------------

There are no changes in the project configuration file format, except for the
removal of the ``cordova`` builder.

Clickable Config
----------------

Since Clickable 7, the default architecture is the host one, meant to
facilitate the Desktop Mode Use Case, e.g. a seemless
``clickable build --libs``, followed by ``clickable desktop``. For testing
on an ``armhf`` or ``arm64`` device, the user needed to specify the
architecture, e.g. ``clickable build --all --arch arm64`` followed by
``clickable chain install launch logs --arch arm64``. Thanks to architecture
detection in Clickable 8, the latter would automatically set the correct
architecture and the ``--arch`` argument can be ommitted.
For the ``build`` command, the issue remains, because it is a non-device
command.

If you do not commonly use Desktop Mode, it might be more convenient for you
to enforce architecture detection via ``always_detect`` in the ``device``
section. This comes at the cost of failing commands, when no target device is
accessible. Another solution is to set the ``default_arch`` in the ``build``
section to your device's architecture.

Thanks to architecture detection, the ``arch`` parameter in the ``device``
section became superfluous and is deprecated and ignored in Clickable 8.

You can set a ``default_target`` in the ``device`` section. This way you can
control whether SSH or ADB takes precedence or you can set the ``host`` target
if you run Clickable inside an Ubuntu Touch environment.

NodeJS Removal
--------------

With the drop of Cordova support, nodejs was removed from the docker images
as well. If your app depends on it, you need to add it to your
``dependencies_host``. In order to get an up-to-date version of nodejs,
consider adding a repo via the ``image_setup`` field, e.g.:

.. code-block:: yaml

    image_setup:
      run:
      # Install instructions taken from https://github.com/nodesource/distributions#installation-instructions
      - mkdir -p /etc/apt/keyrings
      - curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
      - echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

    dependencies_host:
    - nodejs


.. _migration7:

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 <https://crates.io/crates/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:

.. code-block:: javascript

    "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:

.. code-block:: javascript

    "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 <https://kislyuk.github.io/argcomplete/>`__
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:

.. code-block:: javascript

    "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.