// Copyright (C) 2021 The Qt Company Ltd.
// Copyright (C) 2019 Luxoft Sweden AB
// Copyright (C) 2018 Pelagicore AG
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!

\page installation.html
\title Installation
\brief Discusses Qt Application Manager installation considerations, such as; support, prerequisites, code coverage data and system setup.
\ingroup qtappman
\ingroup qtappman-highlights
\section1 Supported Platforms

The application manager is tested regularly on multiple platforms.

The following platforms are only supported for \b{development and testing} purposes. In addition these
platforms only allow the application manager to work in
\l{Single-Process vs. Multi-Process Mode}{single-process mode}:
\list
\li Windows
\li macOS
\li Android (the application manager cannot be deployed directly, but only as part of an Android
    APK package containing the System UI)
\endlist

These platforms can be used for \b{development and production} and will allow you to use the full
feature set of the application manager:
\list
\li Linux desktop and embedded in \l{Single-Process vs. Multi-Process Mode}
    {single-process and multi-process mode}
    \note In multi-process mode, only the \b Intel, \b AMD (open source), and \b VMWare graphics
          drivers are supported due to the varying stability levels in Wayland drivers. While other
          drivers may work, they require either special QtWayland versions or specific firmware
          blobs for the GPU driver.
\endlist

\section1 Prerequisites

To build the application manager with all its features, the following components are required:

\list
    \li \b Qt 6.5.0 or higher.
    \li \b openssl \e{- Linux only and only if you need the installer functionality}.
        Qt needs to be built with openssl support. The required minimum version is defined by Qt.
    \li \b libyaml 1.6 or higher.
    \li \b libarchive 3.0 or higher \e{- if you need the installer functionality}.
\endlist

On Debian-based systems, this command installs the three required packages:
\badcode
apt-get install libyaml-dev libarchive-dev libssl-dev
\endcode

\note On platforms without \c pkg-config (for example, Windows or macOS) as well as on platforms
that lack one of the prerequisites, the bundled versions of these libraries from the \c src/3rdparty
folder are automatically used instead. Make sure you are aware of the licensing implications,
since these bundled 3rdparty libs will be linked in as static libraries.

\warning This option is not meant for production, but for development and testing environments only.

\section1 Multi-process vs. Single-process

By default, the application manager always tries to build in multi-process mode, but falls back
to single-process mode, if certain multi-process mode dependencies are not available, such as:

\list
\li You are building for \b Linux.
\li The \c QtWayland module is available.
\li The \c QtDBus module is available.
\endlist

You can force the build mode via the respective \c --force-multi-process and
\c --force-single-process command line options, as described below.

\target build
\section1 Build

The application manager uses \c CMake for its build system. The basic installation steps are:

\code
mkdir <builddir>
  && cd <builddir>
  && cmake <srcdir> <options>
  && cmake --build .
  && cmake --install .
\endcode
or
\code
mkdir <builddir>
  && cd <builddir>
  && <qtbase>/bin/qt-configure-module <srcdir> <options>
  && cmake --build .
  && cmake --install .
\endcode

There are various options that can be given to \c CMake to tailor the build to suit your needs.

With Qt's new CMake based build system, there are three ways to set configure options for Qt
modules:

\list 1
  \li You can call \c cmake from a shell and specify the options as \c -DINPUT_<option>=<value>
      directly on the CMake command line
  \li You can also use the \c cmake-gui or Qt Creator's built-in configuration UI to change options
      after the first CMake run
  \li Again on the command line, there is Qt's convenience CMake wrapper \c qt-configure-module,
      which lets you specify the options as normal command line options: \c --<option>=<value>
\endlist

\table
\header
  \li Option
  \li Description
\row
  \li \c{libarchive}
  \li Set to \c system to force a build against the system libarchive, or \c qt to not build against
      the system libarchive, even if one was detected.
\row
  \li \c{libyaml}
  \li Set to \c system to force a build against the system libyaml, or \c qt to not build against the
      system libyaml, even if one was detected.
\row
  \li \c{force-single-process}
  \li Force a single-process build, even if Qt's Wayland \c compositor module is available.
      \br The corresponding cmake input is \c{-DINPUT_force_mode=single}.
\row
  \li \c{force-multi-process}
  \li Force a multi-process build - this will break if Qt's Wayland \c compositor module is not
      available.
      \br The corresponding cmake input is \c{-DINPUT_force_mode=multi}.
\row
  \li \c{installer}
    \target config disable installer
  \li Set to \c no to disable the installer part.
\row
  \li \c{external-dbus-interfaces}
  \li Set to \c no to completely disable the external D-Bus interfaces. The internal communication
      channel between the applications and the application manager will still be based on a
      peer-to-peer D-Bus.
\row
  \li \c{tools-only}
  \li Set to \c yes to only build tools: \l{Controller}{appman-controller} and
      \l{Packager}{appman-packager}.
\row
  \li \c{widgets-support}
  \li Set to \c yes to enable support for Qt widgets. This option can be useful to enable the use
      of some development tools using Qt widgets.
\row
  \li \c{hardware-id=<id>}
  \li If set, compiles in \c id as a hard-coded hardware-id; see \l{The Hardware ID} for more
      information.
\row
  \li \c{libbacktrace}
  \li If set to \c yes, enables building and linking against \c libbacktrace in the 3rdparty folder.
      This gives you readable backtraces for crashes on Linux, but also increases the binary size
      slightly. For debug builds, this option is enabled by default.
      Set to \c no disables building and linking against \c libbacktrace.
\row
  \li \c{stackwalker}
  \li If set to \c yes, enables building and linking against \c stackwalker in the 3rdparty folder.
      This gives you readable backtraces for crashes on Windows, but also increases the binary size
      slightly. For debug builds, this option is enabled by default.
      Set to \c no disables building and linking against \c stackwalker.
\endtable

\section2 The Hardware ID

The installer part of the application manager needs a unique device ID, if you want to deliver
application packages that are bound to a specific device unit from your app-store. The use case here
is to prevent customers from buying apps once and then sharing them with others for free.

Since the application manager doesn't know, at build time, how a potential app-store will be
configured, the application manager tries to create a unique ID based on the MAC address of the
first configured ethernet device. If the ethernet device is not configured at all, or configured
after the application manager starts, this scenario will not work.

There are three different ways to specify a hardware ID:

\list 1
\li No configure option: use the MAC address of the first ethernet device. Typically, this option
    works out of the box.

\li \c{hardware-id=yourID} hardcodes the ID to \c yourID. This option is ideal, if
    you do not use any application manager features that require this ID to be unique and if you
    cannot (or do not want to) guarantee that an ethernet device is up when the application manager
    starts.

\li \c{hardware-id=@yourFile} makes the application manager read the
    contents of \c yourFile at startup and uses its content as the ID; instead of the ethernet MAC
    address. This option is useful if your device has a unique device ID available via \c /proc or
    \c /sys and you want to use features that require such an ID.
\endlist

All executables, including the unit tests, can be found in the build folder's \c bin directory, after
compiling.


\section1 Generate Code-Coverage Data

Instead of doing a normal build, you can also create a coverage build by running
\c{cmake -DAM_COVERAGE=ON}. Since every compile step needs to be instrumented with special compiler
flags, make sure to create a new build directory, or at least clean an existing one.

Using a build like this enables you to generate HTML coverage reports with the following command
in the build directory:

\badcode
cmake --build . --target check_coverage
\endcode

The command line output provides you the URL to the generated report.


\section1 System Setup

The runtime configuration of the application manager is done through command line switches and
one or more configuration files.

Ideally, in a production setup, the basic configuration is done via two separate config files:
one for target system specific setup and one for System UI specific settings. The target system
specific one would for example have the path to installation directories and the required
logging settings; the System UI specific one would for example have the QML import path and
the paths to built-in apps.

If you have the target settings in \c /etc/target-am-config.yaml and the System UI with its
\c am-config.yaml and \c main.qml files at \c /path/to/system-ui, you can then the
application manager like so:

\badcode
cd /path/to/system-ui
appman -c /etc/target-am-config.yaml -c am-config.yaml --verbose main.qml
\endcode

\c{--verbose} gives you verbose output, which is quite helpful when first setting up the environment
and also for debugging purposes.

*/