Update documentation to yaml config file

docs/builders.rst

@@ -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

docs/changelog.rst

@@ -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
 -----------------

docs/commands.rst

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

docs/env-vars.rst

@@ -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>`.

docs/index.rst

@@ -22,7 +22,7 @@ Using Clickable
     usage
     debugging
     commands
-    clickable-json
+    project-config
     env-vars
     app-templates
     builders

docs/migration.rst

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

docs/clickable-json.rst → docs/project-config.rst

-.. _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:
 
 ============= ======

docs/usage.rst

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