clickable.json Format

Example:

{
    "template": "cmake",
    "scripts": {
        "test": "make test"
    },
    "dependencies_target": [
        "libpoppler-qt5-dev"
    ]
}

Placeholders & Environment Variables

The following placeholders can be used in the clickable.json. They are also provided as environment variables during build. When passing --debug to Clickable, DEBUG_BUILD=1 is set as an environment variable additionally.

Placeholder Output
$ARCH_TRIPLET Target architecture triplet (arm-linux-gnueabihf, x86_64-linux-gnu or all)
$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 ($INSTALL_DIR/lib for architecture independent apps)
$CLICK_QML2_IMPORT_PATH $INSTALL_DIR/lib/$ARCH_TRIPLET ($INSTALL_DIR/qml for architecture independent apps, which is not in QML2_IMPORT_PATH at runtime)
$CLICK_PATH $INSTALL_DIR/lib/$ARCH_TRIPLET/bin ($INSTALL_DIR for architecture independent apps)
$<lib>_LIB_INSTALL_DIR Value of install_dir from <lib> (see libraries)

Parameters accepting placeholders: root_dir, build_dir, src_dir, install_dir, gopath, cargo_home, scripts, build, build_args, make_args, postmake, postbuild, prebuild. This is an ordered list. Parameters that are used as placeholders themselfs accept only predecessors. Ex: $ROOT can be used in src_dir, but not vice-versa.

Example:

{
    "template": "cmake",
    "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"

arch

Optional, the default is armhf. You may also specify this as a cli arg (ex: --arch="armhf")

template

Optional, see build template for the full list of options. If left blank the template will be auto detected.

prebuild

Optional, a custom command to run before a build.

build

Optional, a custom command to run instead of the default build. If using the custom template this is required.

postbuild

Optional, a custom command to execute after build and before click build.

postmake

Optional, a custom command to execute after make (during build).

launch

Optional, a custom command to launch the app.

build_dir

Optional, a custom build directory. Defaults to $ROOT/build/

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

install_lib

Optional, additional libraries that should be installed with the app. The destination directory is $CLICK_LD_LIBRARY_PATH. Ex:

"install_lib": [
    "/usr/lib/$ARCH_TRIPLET/libasound.so*"
]

Can be specified as a string or a list of strings. Supports wildcards as this actually calls cp -r <from> <to> in a bash.

install_qml

Optional, additional QML files or directories that should be installed with the app. The destination directory is $CLICK_QML2_IMPORT_PATH. Ex:

"install_qml": [
    "/usr/lib/$ARCH_TRIPLET/qt5/qml/QtGraphicalEffects"
]

Can be specified as a string or a list of strings. Supports wildcards as this actually calls cp -r <from> <to> in a bash.

install_bin

Optional, additional executables that should be installed with the app. The destination directory is $CLICK_PATH. Ex:

"install_bin": [
    "/usr/bin/htop"
]

Can be specified as a string or a list of strings. Supports wildcards as this actually calls cp -r <from> <to> in a bash.

kill

Optional, a custom process name to kill (useful for killing the running app, then relaunching it). If left blank the process name will be assumed.

scripts

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

{
    "test": "make test",
    "echo": "echo Hello World"
}

default

Optional, a list of space separated sub-commands to run when no sub-commands are specified. Defaults to clean build install launch.

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

dependencies_build

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

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

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

dependencies_target

Optional, a list of dependencies that will be installed in the build container. These will be assumed to be dependency:arch, unless an architecture specifier is already appended. In desktop mode dependencies_target is handled just like dependencies_build.

Add dependencies here that your app depends on.

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

dependencies_ppa

Optional, a list of PPAs, that will be enabled in the build container. This is only supported for docker mode. Ex:

"dependencies_ppa": [
    "ppa:bhdouglass/clickable"
]

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

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.

ignore

Optional, a list of files to ignore when building a pure template Example:

"ignore": [
    ".clickable",
    ".git",
    ".gitignore",
    ".gitmodules"
]

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

gopath

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

cargo_home

Optional, the Cargo home path on the host machine that is used for caching. Defaults to ~/.clickable/cargo.

build_args

Optional, arguments to pass to qmake or cmake. When using --debug, CONFIG+=debug is additionally appended for qmake and -DCMAKE_BUILD_TYPE=Debug for cmake and cordova builds. Ex: CONFIG+=ubuntu

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

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.

make_jobs

Optional, the number of jobs to use when running make, equivalent to make’s -j option. If left blank this defaults to -j, allowing make to execute many recipes simultaneously.

dirty

Optional, whether or not do a dirty build, avoiding to clean the build directory before building. You may also specify this as a cli arg (--dirty). The default is false.

root_dir

Optional, specify a different root directory for the project. For example, if you clickable.json file is in platforms/ubuntu_touch and you want to include code from root of your project you can set root_dir: "../..".

test

Optional, specify a different test command to run when running clickable test. The default is qmltestrunner.

libraries

Optional, libraries to be build in the docker container by calling clickable build-libs. It’s a dictionary of dictionaries basically looking like the clickable.json itself. Example:

"libraries": {
    "opencv": {
        "template": "cmake",
        "make_jobs": "4",
        "build_args": [
            "-DCMAKE_BUILD_TYPE=Release",
            "-DBUILD_LIST=core,imgproc,highgui,imgcodecs",
            "-DBUILD_SHARED_LIBS=OFF"
        ]
        "prebuild": "git submodule update --init --recursive"
    }
}

The keywords install_dir, prebuild, build, postbuild, postmake, make_jobs, make_args, build_args, docker_image, dependencies_build, dependencies_target and dependencies_ppa, can be used for a library the same way as described above for the app. The libraries are compiled for the same architecture as specified for the app itself.

Consider defining a custom build directory for the app itself (Ex: build/app). Otherwise cleaning the app cleans the library, too.

In addition to the 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 to build the library with name lib1.

template

Required, but only cmake, qmake and custom are allowed.

src_dir

Optional, library source directory. Must be relative to the project root. It defaults to $ROOT/libs/$NAME

build_dir

Optional, library build directory. Must be relative to the project root. It defaults to $ROOT/build/$NAME/$ARCH_TRIPLET. 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_build 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