Commit f428a905 authored by Jonatan Hatakeyama Zeidler's avatar Jonatan Hatakeyama Zeidler
Browse files

Update documentation to yaml config file

parent 041dec60
Pipeline #328511722 failed with stage
in 14 minutes and 1 second
......@@ -45,7 +45,7 @@ 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 <clickable-json-restrict_arch>` in the clickable.json file
:ref:`restrict_arch <project-config-restrict_arch>` in the project config file
can be useful with this builder.
python
......
......@@ -313,8 +313,8 @@ Changes in v6.1.0
- Added support for multimedia in desktop mode
- Make app data, config and cache persistent in desktop mode by mounting phablet home folder to ~/.clickable/home
- Added arm64 support and docker images (does not yet work for apps built with qmake)
- :ref:`Added placeholders and env vars to commands and scripts run via clickable <clickable-json-placeholders>`
- :ref:`Added option to install libs/qml/binaries from the docker image into the click package <clickable-json-install_lib>`
- :ref:`Added placeholders and env vars to commands and scripts run via clickable <project-config-placeholders>`
- :ref:`Added option to install libs/qml/binaries from the docker image into the click package <project-config-install_lib>`
- Switched to a clickable specific Cargo home for Rust apps
- Click packages are now deleted from the device after installing
- Fixed ``dependencies_build`` not being allowed as a string
......@@ -425,7 +425,7 @@ Changes in v5.12.1
Changes in v5.12.0
------------------
- clickable.json supports :ref:`placeholders <clickable-json-placeholders>` now
- clickable.json supports :ref:`placeholders <project-config-placeholders>` now
- Add new ``src_dir`` configuration option
- Make build-libs respect ``root_dir``, too
- Fix build-libs for architecture all
......@@ -462,14 +462,14 @@ Changes in v5.8.1
Changes in v5.8.0
-----------------
- New configuration option for automatically including ppas in the build environment: :ref:`dependencies_ppa <clickable-json-dependencies-ppa>`.
- Changed :ref:`libraries <clickable-json-libraries>` format from a list to a dictionary (the old format is still supported for now)
- New configuration option for automatically including ppas in the build environment: :ref:`dependencies_ppa <project-config-dependencies-ppa>`.
- Changed :ref:`libraries <project-config-libraries>` format from a list to a dictionary (the old format is still supported for now)
- The default ``cargo_home`` is now set to ``~/.cargo``
Changes in v5.7.0
-----------------
- Introduced two new dependency options to separate `build <clickable-json-dependencies_build>` and `target <clickable-json-dependencies_target>` dependencies
- Introduced two new dependency options to separate `build <project-config-dependencies_build>` and `target <project-config-dependencies_target>` dependencies
Changes in v5.6.1
-----------------
......@@ -525,7 +525,7 @@ Changes in v5.3.1
Changes in v5.3.0
-----------------
- :ref:`Added options for compiling libraries <clickable-json-libraries>`
- :ref:`Added options for compiling libraries <project-config-libraries>`
Changes in v5.2.0
-----------------
......
......@@ -13,7 +13,7 @@ A pure ``clickable`` call is equivalent to ``clickable chain``.
-------------------
Chains multiple commands that can be specified. The default chain can be configured via the
:ref:`default <clickable-json-default>` field. The default chain itself defaults to
:ref:`default <project-config-default>` field. The default chain itself defaults to
``build install launch``.
A clean build can be enforced by running ``clickable chain --clean``.
......@@ -125,7 +125,7 @@ to ``@CLICK_FRAMEWORK@`` to have Clickable replace them with the appropriate val
``clickable build --libs``
--------------------------
Builds libraries specified in the clickable.json.
Builds libraries specified in the project config.
``clickable build --output=/path/to/some/diretory``
---------------------------------------------------
......@@ -145,8 +145,8 @@ to review your click without installing click-review on your computer.
------------------
Run your test suite in with a virtual screen. By default this runs qmltestrunner,
but you can specify a custom command by setting the :ref:`test <clickable-json-test>`
property in your clickable.json.
but you can specify a custom command by setting the :ref:`test <project-config-test>`
property in your project config.
``clickable install``
---------------------
......
......@@ -3,11 +3,11 @@
Environment Variables
=====================
Environment variables will override values in the clickable.json and can be
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 <clickable-json-placeholders>` set by
Clickable, there are :ref:`environment variables <project-config-placeholders>` set by
Clickable to be used during build.
``CLICKABLE_ARCH``
......@@ -18,57 +18,57 @@ Restricts build commands (``build``, ``build-libs``, ``desktop``) to the specifi
``CLICKABLE_QT_VERSION``
------------------------
Overrides the clickable.json's :ref:`qt_version <clickable-json-qt_version>`.
Overrides the project config's :ref:`qt_version <project-config-qt_version>`.
``CLICKABLE_FRAMEWORK``
-----------------------
Overrides the clickable.json's :ref:`builder <clickable-json-framework>`.
Overrides the project config's :ref:`builder <project-config-framework>`.
``CLICKABLE_BUILDER``
---------------------
Overrides the clickable.json's :ref:`builder <clickable-json-builder>`.
Overrides the project config's :ref:`builder <project-config-builder>`.
``CLICKABLE_BUILD_DIR``
-----------------------
Overrides the clickable.json's :ref:`dir <clickable-json-build_dir>`.
Overrides the project config's :ref:`dir <project-config-build_dir>`.
``CLICKABLE_DEFAULT``
---------------------
Overrides the clickable.json's :ref:`default <clickable-json-default>`.
Overrides the project config's :ref:`default <project-config-default>`.
``CLICKABLE_MAKE_JOBS``
-----------------------
Overrides the clickable.json's :ref:`make_jobs <clickable-json-make-jobs>`.
Overrides the project config's :ref:`make_jobs <project-config-make-jobs>`.
``GOPATH``
----------
Overrides the clickable.json's :ref:`gopath <clickable-json-gopath>`.
Overrides the project config's :ref:`gopath <project-config-gopath>`.
``CARGO_HOME``
--------------
Overrides the clickable.json's :ref:`cargo_home <clickable-json-cargo_home>`.
Overrides the project config's :ref:`cargo_home <project-config-cargo_home>`.
``CLICKABLE_DOCKER_IMAGE``
--------------------------
Overrides the clickable.json's :ref:`docker_image <clickable-json-docker-image>`.
Overrides the project config's :ref:`docker_image <project-config-docker-image>`.
``CLICKABLE_BUILD_ARGS``
------------------------
Overrides the clickable.json's :ref:`build_args <clickable-json-build-args>`.
Overrides the project config's :ref:`build_args <project-config-build-args>`.
``CLICKABLE_MAKE_ARGS``
------------------------
Overrides the clickable.json's :ref:`make_args <clickable-json-make-args>`.
Overrides the project config's :ref:`make_args <project-config-make-args>`.
``OPENSTORE_API_KEY``
---------------------
......@@ -108,7 +108,7 @@ Same as :ref:`--no-nvidia <nvidia>`.
``CLICKABLE_ALWAYS_CLEAN``
--------------------------
Overrides the clickable.json's :ref:`always_clean <clickable-json-always-clean>`.
Overrides the project config's :ref:`always_clean <project-config-always-clean>`.
``CLICKABLE_NON_INTERACTIVE``
-----------------------------
......@@ -123,7 +123,7 @@ Same as ``--debug``
``CLICKABLE_TEST``
------------------
Overrides the clickable.json's :ref:`test <clickable-json-test>`.
Overrides the project config's :ref:`test <project-config-test>`.
``CLICKABLE_DARK_MODE``
-----------------------
......@@ -137,4 +137,4 @@ 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 <clickable-json-env_vars>`.
Overrides env vars in :ref:`test <project-config-env_vars>`.
......@@ -22,7 +22,7 @@ Using Clickable
usage
debugging
commands
clickable-json
project-config
env-vars
app-templates
builders
......
......@@ -13,7 +13,7 @@ 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
``clickable.json``:
project config:
.. code-block:: javascript
......@@ -74,6 +74,17 @@ 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
--------
......@@ -121,7 +132,7 @@ Clickable 7.
Architecture
^^^^^^^^^^^^
Instead of setting ``arch`` in your ``clickable.json`` you should specify the
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``
......
.. _clickable-json:
.. _project-config:
clickable.json Format
Project Config Format
=====================
Example:
......@@ -17,7 +17,7 @@ Example:
]
}
.. _clickable-json-placeholders:
.. _project-config-placeholders:
Placeholders & Environment Variables
------------------------------------
......@@ -25,7 +25,7 @@ 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 <clickable-json-env_vars>`.
For custom environment variables see :ref:`env_vars <project-config-env_vars>`.
The following table lists all available placeholders.
......@@ -44,7 +44,7 @@ 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 <clickable-json-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_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``)
======================= ======
......@@ -76,7 +76,7 @@ clickable_minimum_required
Optional, a minimum Clickable version number required to build the project.
Ex: ``"6"`` or ``"5.4.0"``
.. _clickable-json-qt_version:
.. _project-config-qt_version:
qt_version
----------
......@@ -85,7 +85,7 @@ Qt version consisting of major and minor version. This value is used to
determine the framework automatically. Defaults to ``5.12``.
Ex: ``5.9``
.. _clickable-json-framework:
.. _project-config-framework:
framework
---------
......@@ -95,7 +95,7 @@ choose the correct docker image and set the ``framework`` field in the manifest
accordingly, if desired.
Ex: ``ubuntu-sdk-16.04.4``
.. _clickable-json-restrict_arch:
.. _project-config-restrict_arch:
restrict_arch
-------------
......@@ -105,7 +105,7 @@ This prevents the app from being build for other architectures and may also prev
To specify the architecture for building use the cli argument instead (ex: ``--arch arm64``).
.. _clickable-json-builder:
.. _project-config-builder:
builder
-------
......@@ -142,7 +142,7 @@ Optional, a custom command to execute from the root dir, after build, but before
Can be specified as a string or a list of strings.
.. _clickable-json-env_vars:
.. _project-config-env_vars:
env_vars
--------
......@@ -166,7 +166,7 @@ Optional, arguments to pass to qmake or cmake. When using ``--debug``,
Can be specified as a string or a list of strings.
.. _clickable-json-make-args:
.. _project-config-make-args:
make_args
---------
......@@ -177,7 +177,7 @@ conflicts, the number of make jobs should not be specified here, but using
Can be specified as a string or a list of strings.
.. _clickable-json-make-jobs:
.. _project-config-make-jobs:
make_jobs
---------
......@@ -190,7 +190,7 @@ launch
Optional, a custom command to launch the app, used by ``clickable launch``.
.. _clickable-json-build_dir:
.. _project-config-build_dir:
build_dir
---------
......@@ -210,7 +210,7 @@ install_dir
Optional, a custom install directory (used to gather data that goes into the click package).
Defaults to ``${BUILD_DIR}/install``
.. _clickable-json-install_lib:
.. _project-config-install_lib:
install_lib
-----------
......@@ -323,7 +323,7 @@ Optional, an object detailing custom commands to run. For example:
That enables the use of ``clickable script fetch`` and ``clickable script echo``.
.. _clickable-json-default:
.. _project-config-default:
default
-------
......@@ -334,7 +334,7 @@ The ``--clean`` cli argument prepends ``clean`` to that list.
Can be specified as a string or a list of strings.
.. _clickable-json-always-clean:
.. _project-config-always-clean:
always_clean
------------
......@@ -344,7 +344,7 @@ disabling the build cache. Affects the ``chain``, ``build`` and ``desktop`` comm
Does not affect libraries.
The default is ``false``.
.. _clickable-json-dependencies_host:
.. _project-config-dependencies_host:
dependencies_host
-----------------
......@@ -355,7 +355,7 @@ Add tools here that are part of your build tool chain.
Can be specified as a string or a list of strings.
.. _clickable-json-dependencies_target:
.. _project-config-dependencies_target:
dependencies_target
-------------------
......@@ -369,7 +369,7 @@ Add dependencies here that your app depends on.
Can be specified as a string or a list of strings.
.. _clickable-json-dependencies-ppa:
.. _project-config-dependencies-ppa:
dependencies_ppa
----------------
......@@ -384,7 +384,7 @@ Optional, a list of PPAs, that will be enabled in the build container. Ex:
Can be specified as a string or a list of strings.
.. _clickable-json-docker-image:
.. _project-config-docker-image:
image_setup
-----------
......@@ -416,7 +416,7 @@ 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 <clickable-json-env_vars>` instead).
:ref:`env_vars <project-config-env_vars>` instead).
docker_image
------------
......@@ -442,14 +442,14 @@ Example:
Can be specified as a string or a list of strings.
.. _clickable-json-gopath:
.. _project-config-gopath:
gopath
------
Optional, the gopath on the host machine. If left blank, the ``GOPATH`` env var will be used.
.. _clickable-json-cargo_home:
.. _project-config-cargo_home:
cargo_home
----------
......@@ -458,18 +458,18 @@ 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``.
.. _clickable-json-build-args:
.. _project-config-build-args:
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
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.json``.
``clickable -c platforms/ubuntu_touch/clickable.yaml``.
.. _clickable-json-test:
.. _project-config-test:
test
----
......@@ -477,12 +477,12 @@ test
Optional, specify a test command to be executed when running ``clickable test``.
The default is ``qmltestrunner``.
.. _clickable-json-libraries:
.. _project-config-libraries:
libraries
---------
Optional, dependencies to be build by running ``clickable build-libs``.
It's a dictionary of dictionaries similar to the clickable.json itself. Example:
It's a dictionary of dictionaries similar to the project config itself. Example:
.. code-block:: javascript
......@@ -504,7 +504,7 @@ The keywords ``test``, ``install_dir``, ``prebuild``, ``build``, ``postbuild``,
``dependencies_host``, ``dependencies_target`` and ``dependencies_ppa``,
can be used for a library the same way as described above for the app.
In addition to the :ref:`placeholders <clickable-json-placeholders>` described above,
In addition to the :ref:`placeholders <project-config-placeholders>` described above,
the following placeholders are available:
============= ======
......
......@@ -43,10 +43,11 @@ when using ssh.
Configuration
-------------
It is recommend to specify a configuration file in the
:ref:`clickable.json format <clickable-json>` with ``--config``. If not
specified, clickable will look for an optional configuration file called
``clickable.json`` in the current directory. If there is none Clickable will
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 directory.
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.
......@@ -77,7 +78,7 @@ 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 <clickable-json-qt_version>`).
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
``@CLICK_ARCH@`` and ``@CLICK_FRAMEWORK@`` respectively.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment