配置

主配置

您可以通过配置文件和命令行来配置应用程序管理器。要显示当前支持的命令行选项，请运行 appman --help。其中一些选项也可以通过命令行中带 --config-file <filename> 选项的配置文件来设置。

配置文件是一个遵循与应用程序管理器中使用的所有其他 YAML 文件相同规则的YAML 文件。

在解析 YAML 文档之前，应用程序管理器会替换与 bash 类似的语法表示的变量：${VariableName}。可以通过这种方式替换不同类型的变量

类型	描述
`${CONFIG_PWD}`	使用解析的配置文件的绝对路径进行替换。此功能使您可以将所有导入路径和文件引用相对于主要配置文件。
`${env:ENV_VAR_NAME}`	使用 `$ENV_VAR_NAME` 环境变量的值进行替换。例如，`${env:USER}` 被替换为您的 Unix 用户名。
`${stdpath:Location}`	使用用于 `Location` 的平台对应值替换相应的值标准位置。例如，`${stdpath:TempLocation}` 在 Unix 上被替换为 `/tmp`；除非您的系统管理员做了其他配置。

如果有多个地方指定了选项：要么在命令行和配置文件中，要么在多个配置文件中，则最终值基于以下规则解析

从所有可用的配置文件中解析选项，顺序与出现在命令行上的顺序相同。值被配置文件覆盖，因为它们被加载。
直接通过命令行指定的选项始终覆盖配置文件中的值。
有一个例外：期望列表值（如 -I 或 ui/importPaths ）的选项。在这种情况下，无论它们在哪里指定，所有值都合并到一个单一的最终列表中。

命令行 [`配置键`]	类型	描述
（第一个非选项） [`ui/mainQml`]	字符串	主要 QML 文件。
--help	布尔值	打印支持的选项并退出。
--version	布尔值	打印应用程序管理器的当前版本并退出。
--build-config	布尔值	以 YAML 格式打印应用程序管理器的构建配置并退出。
--config-file 或 -c	数组<字符串>	从一组文件中加载配置设置。您可以使用多个配置文件，例如，将配置清晰分割为针对设备和 UI 的部分。所有配置文件的内容均按命令行中出现的顺序合并：作为较早配置值中未出现的键保持不变；重复的键根据以下算法合并标量值覆盖早期配置值。列表连接到较早列表的内容。将映射与较早的映射按键键递归合并，依据规则 1 和 2。应用程序管理器将解析和评估所有配置文件的结果保存到缓存中。如果下次启动时使用的是确切的配置文件集，则加载此缓存。（默认：`/opt/am/config.yaml`）
--no-cache	布尔值	禁用配置文件和应用程序数据库的缓存功能：既不读取也不写入缓存。（默认：false）
--clear-cache	布尔值	尽管应用管理器应该检测配置文件和应用数据库缓存是否不同步，但您可以使用此选项强制在启动时清除缓存。旧的选项 `--clear-config-cache`、`-r` 和 `--recreate-database` 仍然受到支持，并且名称不同 - 同样也会清除两个缓存。 (默认：false)
--option 或 -o	YAML	使用此选项可以通过命令行设置或覆盖配置文件的某些部分。此选项可以指定多次，其值将像通过 `-c` 指定的配置文件内容一样进行评估。评估顺序是在配置文件之后，但在更具体的直接选项（如 `--fullscreen`，可以重写为 `-o 'ui: { fullscreen: no }'`）之前。
--instance-id [`instanceId`]	字符串	为这个应用管理器实例分配一个唯一的名称。只有当您同时运行多个实例并且需要通过 appman-controller 工具对它们进行寻址时才有用。
--database [`applications/database`]	字符串	已弃用并忽略。应用数据库将被透明地缓存 - 参见 `--clear-cache` 和 `--no-cache` 选项。
--recreate-database 或 -r	布尔值	已弃用。这些选项对于应用管理器响应应用清单文件的变化是必要的，但现在已经不再需要。为了保持向后兼容，这些选项将映射到 `--clear-cache` 选项，该选项将清除配置和应用数据库缓存。(默认：false)
--builtin-apps-manifest-dir [`applications/builtinAppsManifestDir`]	字符串	内置应用清单的基础目录；也可以指定多个目录列表。
--installation-dir [`applications/installationDir`]	字符串	包安装的基础目录。如果您想安装新包，则必须指定此选项；否则，只有内置包可用。(默认：空/禁用)
--document-dir [`applications/documentDir`]	字符串	每个包文档存储目录的基础目录。(默认：空/禁用) 请注意，如果您在此处不设置 `documentDir`，则在安装新包时不会创建每个应用的文档目录。
[`applications/installationDirMountPoint`]	字符串	如果设置，将延迟加载包数据库，直到指定的挂载点已被挂载。(默认：空/禁用)
--dbus	字符串	在指定的 D-Bus 上注册 ApplicationManager、ApplicationInstaller、NotificationManager 和 WindowManager：可以是完整的 D-Bus 总线规范字符串、`session`、`system`、`auto`（默认）或 `none`（表示完全不动）。仅在桌面或开发期间使用 `auto` 关键字。此关键字表示应用管理器尝试启动一个私有会话总线，并在成功时使用该总线。如果失败，则不会进行任何注册，这相当于 `none`。在生产系统上，您可能希望将应用管理器放在 `system` 总线上，在那里您可以使用标准 D-Bus 机制设置详细的安全策略，同时将 NotificationManager 放在会话总线上。请参阅下面的更高级的配置文件选项 `dbus`。注意：自 Qt 5.13 以来，新的 `auto` 关键字取代了旧的 `--start-session-dbus` 标志。
[`dbus`]	map<object>	允许更细粒度地控制D-Bus注册和功能调用策略。此映射中每个键（除了一个例外 - 见下文）都对应您想要配置的D-Bus接口名（`io.qt.ApplicationManager`，`io.qt.ApplicationInstaller`，`io.qt.WindowManager`和`org.freedesktop.Notifications`）。如果存在这样的键，则它将优先于`dbus`命令行选项。每个键的值是一个D-Bus规范对象。
--fullscreen [`ui/fullscreen`]	布尔值	全屏显示（默认：false）
--no-fullscreen	布尔值	覆盖系统UI配置文件中的全屏设置。对桌面开发很有用（默认：false）
[`ui/windowIcon`]	字符串	如果设置，则使用指定的图像文件作为所有应用程序管理器窗口的图标。此选项仅适用于开发和Windows、macOS和Linux/X11有效。
-I [`ui/importPaths`]	数组<字符串>	向系统UI添加额外的QML导入路径。
[`ui/pluginPaths`]	数组<字符串>	向系统UI添加额外的Qt插件路径。
[`ui/style`]	字符串	如果设置，将使用指定的样式。QtQuickControls 2将使用该样式。
[`ui/resources`]	数组<字符串>	接受一个Qt资源文件（.rcc）或已编译资源库的列表并将其注册到系统UI进程内。可以使用"："或"qrc://"作为文件路径前缀来访问资源。
[`plugins`]	map<array<string>>	这是一个字符串到字符串列表映射，定义了应用程序管理器应加载的插件。值必须是一个插件或插件库文件路径名的列表。当前只有有效的键是`startup`和`container` `startup`：这个插件必须实现启动接口。QML运行时在应用程序启动时调用功能挂钩。 `container`：这个插件必须实现容器接口（参见容器）。
[`systemProperties`]	object	将用户定义的属性（键/值对）导出到系统UI和应用程序。此字段只能有以下子项，它们控制对真实属性的访问：`private`，`protected`和`public`；其他子项被忽略。这些属性可以作为ApplicationManager::systemProperties暴露给系统UI，并作为ApplicationInterface::systemProperties暴露给所有QML应用程序系统UI可以访问公共、受保护和私有属性。内置应用程序可以访问公共和受保护属性。已安装（第三方）应用程序仅可以访问公共属性。私有键会覆盖相同的保护键和公共键；保护键会覆盖相同的公共键。这些属性将被转换为QVariantMaps，但应用程序管理器不会以任何方式解释它们。非QML应用程序可以通过`$AM_RUNTIME_SYSTEM_PROPERTIES`环境变量以YAML片段的形式访问这些数据。
--verbose	布尔值	启用详细输出。所有日志类别和消息类型都被启用，除了某些Qt内部调试消息；`logging-rules`被忽略。注意：通过QT_LOGGING_RULES环境变量提供的日志规则仍然有效。要更细致地控制日志输出，请参阅下面的`logging-rules`。
--slow-animations	布尔值	所有动画以慢动作运行（默认：false）
--load-dummydata [`ui/loadDummyData`]	布尔值	将QML虚拟数据加载到系统UI中，类似于`qmlscene`和`qml`。
--no-security [`flags/noSecurity`]	布尔值	禁用所有安全相关检查。仅在开发环境中使用此选项；永不用于生产环境。（默认：false）
--development-mode [`flags/developmentMode`]	布尔值	允许安装仅带有有效开发者签名的软件包。（默认：false）
[`flags/allowUnsignedPackages`]	布尔值	允许安装没有任何签名的软件包。仅在生产环境中，如果你通过其他方式验证软件包的同时限制了对安装程序API的访问时使用。（默认：false）
[`flags/allowUnknownUiClients`]	布尔值	如果设置，则Wayland组合器将接受由应用程序管理器未启动的客户端的表面。（默认：false）
--no-ui-watchdog [`flags/noUiWatchdog`]	布尔值	禁用检测挂起的UI应用程序（例如，通过Wayland的ping/pong机制）。（默认：false）
--force-single-process [`flags/forceSingleProcess`]	布尔值	即使是在启用Wayland的构建中，也强制使用单进程模式。（默认：false）
--force-multi-process [`flags/forceMultiProcess`]	布尔值	强制使用多进程模式；如果不可能则立即退出。（默认：false）
--single-app	字符串	仅使用单一应用程序运行应用程序管理器（忽略数据库）。在此模式下，应用程序管理器可以作为`qmlscene`或`qml`的替代品使用。参数是`info.yaml`的路径。也可以从给定路径加载别名（`info-*.yaml`）。
--log-instant	布尔值	启动时立即打印所有日志消息。通常，日志输出会延迟，直到了解日志配置（例如，日志规则）为止。启动时的输出和格式可能会有所不同。
--logging-rule [`logging/rules`]	数组<字符串>	添加标准的Qt日志规则 - 有关所需格式，请参阅QLoggingCategory文档。应用程序管理器特定的日志类别在日志和调试中描述。
[`logging/messagePattern`]	字符串	如果提供，用作Qt消息模式。有关格式的更多信息，请参阅qSetMessagePattern().
[`logging/useAMConsoleLogger`]	布尔值	始终使用应用程序管理器特定的日志功能，该功能启用带颜色的控制台输出。如果没有提供值或提供无效的值，则只有在消息模式未设置时才使用日志功能。
[`logging/dlt/id`]	字符串	如果提供，用作汽车DLT应用程序ID。大小限制为四个字符，额外的字符将被丢弃。注意：默认ID“PCAM”将在应用此配置选项之前使用。
[`logging/dlt/description`]	字符串	如果提供，用作汽车DLT应用程序描述。这允许通过更详细的定义增强简短的DLT应用程序ID。注意：在应用此配置选项之前，将使用默认描述。
[`logging/dlt/longMessageBehavior`]	字符串	配置在使用汽车DLT时如何处理非常长的消息（例如，大于 ~1000 个字符）。默认行为是截断消息到最大可能的大小。其他选项包括`split`将消息分成几个较小的消息、`pass`将其原样转发到DLT或`truncate`明确请求默认行为。
--no-dlt-logging	布尔值	禁用使用汽车DLT的日志记录。此选项在当前没有运行dlt-daemon时特别有用；否则，进程会在退出时挂起一会儿以发送日志。
--qml-debug	布尔值	启用QML调试/分析。有关更多信息，请参阅日志和调试。
[`installationLocations`]	对象数组<	系统上可用的安装位置定义。这已被弃用，因为现在只支持单个安装位置，由 `--installationDir` 或 `applications/installationDir` 定义。
[`runtimes`]	map<object>	此选项可用于指定运行时的选项，作为键值对映射。键是运行时的名称；值由相应的运行时实现解释。更多信息，请参见运行时配置。
[`containers`]	map<object>	此选项可用于指定容器的选项，作为键值对映射。键是容器的名称；值由相应的容器实现解释。更多信息，请参见容器。
[`quicklaunch/idleLoad`]	real	这是一个介于 `0` 和 `1` 之间的系统负载值。只要系统的空闲负载高于此值，应用程序管理器就不会启动新的快速启动器。（默认：0）
[`quicklaunch/runtimesPerContainer`]	int	指定对于所有活动的容器/运行时组合，应该始终准备好多少个快速启动器。（默认：0）注意：大于 10 的值将被忽略，因为这没有意义，而且在资源强大的容器插件中实例化可能会冻结您的设备。
--wayland-socket-name [`wayland/socketName`]	字符串	创建组合器组件时要使用的 Wayland 套接字的文件系统名称。注意：您只能在此处指定名称，而不能指定路径：Wayland 总是在 `$XDG_RUNTIME_DIR` 中创建此套接字。如果此目录不可写或者环境变量根本就没有设置，那么组合器将无法启动。有关解决这种限制的方法，请参见下面的 `wayland/extraSockets`。
[`wayland/extraSockets`]	list<object>	添加到 Wayland 服务器的附加套接字的列表。列表中的每个对象包含以下字段 `path`：套接字的绝对路径。 `permissions`：套接字的数字权限 - 可以用八进制给出，例如 `0640`。 `userId`：套接字的数字 uid。 `groupId`：套接字的数字 gid。只需 `path` 即可，其他字段是可选的，并回退到 QLocalServer 的默认值。如果应用程序管理器在 `sudo` 或 setuid-root 下运行，它将使用其扩展权限应用可选的 `permissions`、`userId` 和 `groupId` 设置。
--disable-installer [`installer/disable`]	布尔值	在运行时完全禁用安装器子系统。另一种选择是在 qmake 步骤中根本不编译它。
[`installer/caCertificates`]	list<string>	用于验证软件包的 CA 证书文件路径列表。有关更多详情，请参见安装器文档。
[`crashAction`]	object	指定在应用程序管理器崩溃时应采取哪些操作。有关更多详情，请参见崩溃操作规范。
[`ui/opengl`]	object	允许您指定所需的 OpenGL 版本和/或配置文件。有关更多详情，请参见 OpenGL 规范。
[`ui/iconThemeName`]	字符串	指定要使用哪个图标主题。有关如何将路径添加到自定义主题的详情，请参见 ui/iconThemeSearchPaths。
[`ui/iconThemeSearchPaths`]	list<string>	为系统 UI 和所有应用程序添加额外的图标主题搜索路径。此选项可以用来添加自定义图标主题到搜索路径，通过指定 ui/iconThemeName 来加载。
[`intents/disable`]	布尔值	在运行时完全禁用 intent 子系统。
[`intents/timeouts`]	object	允许您指定 intent 子系统中使用的处理超时。有关详细信息，请参阅 Intent 超时说明。

D-Bus 说明

这些 YAML 对象描述了哪些 D-Bus 接口被注册，以及访问策略。

配置密钥	类型	描述
`register`	字符串	在指定的 D-Bus 上注册接口：可以是 `session`、`system`、`none`、`~`（表示完全不禁用注册），或者一个完整的 D-Bus 总线规范字符串。
`policy`	map<object>	这些可选的访问策略可以用作或与标准 D-Bus 策略配置一起使用。此映射的键是未装饰的 D-Bus 函数名，如 `startApplication`。当指定键时，相应函数的访问策略为 `deny`，直到您添加 `allow` 标准 -- 所有的标准都通过 AND 进行组合。

下面的代码片段显示了一个简单示例，它仅为具有 appstore 功能且以用户 ID 1000 运行的应用程序允许调用安装器的 startPackageInstallation 函数，同时阻止任何人远程调用 acknowledgePackageInstallation。

...
dbus:
  io.qt.ApplicationInstaller:
    register: 'session'
    policy:
      startPackageInstallation:
        uids: [ 1000 ]
        capabilities: [ 'appstore' ]
      acknowledgePackageInstallation: null
...

只有应用程序管理器的公共 D-Bus 接口可以通过这种方式进行配置。这些可用接口的名称如下

接口	相应的 QML 类
`io.qt.ApplicationManager`	ApplicationManager
`io.qt.ApplicationInstaller`	ApplicationInstaller
`io.qt WindowManager`	WindowManager
`org.freedesktop.Notifications`	非应用程序管理系统特定 - 此接口遵循 freesdesktop.org 规范

运行时配置

运行时配置子对象是针对实际运行时的，因此下表还有一个额外的列指定哪个配置选项适用于哪个运行时

配置密钥	运行时	类型	描述
`environmentVariables`	native, qml	map<string>	这是一个简单的字符串到字符串映射，描述了在启动运行时进程时应设置的环境变量。要从默认环境中删除变量，请将其值设置为 null。
`importPaths`	qml	数组<字符串>	为此运行时启动的应用程序添加额外的 QML 导入路径。
`pluginPaths`	qml	数组<字符串>	为此运行时启动的应用程序添加额外的 Qt 插件路径。
`plugins`	qml	map<array<string>>	这是一个字符串到字符串列表映射，它定义了 QML 运行时应加载的插件。值必须是一个插件或插件库文件路径名列表。目前唯一的有效键是 `startup`。 `startup`：这个插件必须实现启动接口。QML运行时在应用程序启动时调用功能挂钩。
`resources`	qml	数组<字符串>	接受一个 Qt 资源文件 (.rcc) 或库列表，这些资源已编译并在每个 QML 运行时中注册。因此，所有运行的 QML 应用程序都将包含这些资源。可以通过 ":" 或 "qrc://" 文件路径前缀访问这些资源。
`quicklaunchQml`	qml	字符串	这是一个在启动快速启动器时加载的 QML 源文件；但在直接启动应用程序时不会加载。提供此文件只有在 `quicklaunch/runtimesPerContainer` > 0 时才有用。此选项可以用来改进实际应用程序的后续启动性能，例如通过导入并预先加载常用应用程序插件以及实例化昂贵的一次性对象。通常，创建其他对象是没有用的，因为创建的组件将被立即删除。出于同样的原因，不应创建视觉项目。始终牢记，此文件中包含的所有内容都将加载到所有使用 QML 运行时启动的应用程序中。
`加载数据示例`	qml	布尔值	将 QML 示例数据加载到应用中，类似于 `qmlscene` 和 `qml`。默认为：false。
`背景颜色`	qml	字符串	如果设置了，则应用的主窗口将以该颜色作为默认的透明颜色。此选项还为表面提供了一个 8 位(alpha)缓冲区。
`退出时间`	qml	int	定义了应用在关闭时获得的宽限期（以毫秒为单位）。这是从接收到“quit()”信号到响应“acknowledgeQuit()”之间的时间限制。默认：250。
`崩溃操作`	qml	object	指定在 QML 客户端应用崩溃时采取的操作。有关更多信息，请参阅崩溃操作规范。

崩溃操作规范

这些子对象指定在应用管理器或 QML 运行时崩溃时采取的操作。

注意：以下所有操作仅在 Linux 上有效。

以下条件得到处理

未捕获的异常。从 std::exception 衍生的异常也在 what() 中显示发生的详细信息。
SIGSEGV
SIGABRT
SIGBUS
SIGILL
SIGFPE
SIGPIPE
SIGQUIT
SIGSYS

配置密钥	类型	描述
`printBacktrace`	布尔值	尝试打印一个可读的堆栈跟踪。在 Linux 上，它使用 glibc 的原始堆栈跟踪功能，除非在配置时启用了 `libbacktrace`。在 Windows 上，只有在配置时启用了 `stackwalker`，才会打印堆栈跟踪。(默认：true)
`printQmlStack`	布尔值	尝试打印一个可读的 QML 堆栈跟踪。类似于上面的 `printBacktrace`，但是在崩溃发生时打印当前的 QML 函数堆栈。(默认：true)
`dumpCore`	布尔值	通过 `abort` 而不是 `_exit` 终止进程。根据内核配置，保存一个 `core` 文件。(默认：true)
`waitForGdbAttach`	int	指定在崩溃程序处于停止状态等待调试器附加时的超时时间（以秒为单位）。任何值 `<= 0` 将跳过此步骤。(默认：0)

Intent 超时规范

intents/timeouts 子对象允许您指定实现 Intent 机制所用的异步 IPC 的确切超时值（以毫秒为单位）。任何其生命周期超过以下阶段超时的 intent 都由系统取消，并将错误回复发送回原始发送者。将任何超时值设置为 0 或负数将禁用该特定阶段的超时处理。

配置密钥	类型	描述
`disambiguation`	int	系统 UI 中对 intent 进行去歧义决定的毫秒时间间隔。（默认：10000）
`startApplication`	int	应该处理 intent 请求的应用程序在多少毫秒后启动的时间间隔 - 当然，只有当它未运行时。(默认：3000)
`replyFromApplication`	int	处理应用程序需要在多少毫秒内确认收到 intent 请求的时间间隔。对于 QML 应用程序，这发生在 IntentHandler::requestReceived。(默认：5000)
`replyFromSystem`	int	在完成对单个 intent 的处理后需要多少毫秒：这是在请求应用中实际创建 intent、通过服务器到处理应用的始终，然后从处理应用返回（错误）结果时开始。注意：这个超时值略微大于上面描述的前三个超时值之和是有意义的：其他所有超时都是完成意图请求的子步骤，而此超时代表整个过程。使其略大于总和考虑了不属于单个子超时处理和通信开销。（默认：20000）

请注意，由于意图交付的异步性，系统可能会因为遇到 replyFromApplication 或 replyFromSystem 超时而取消意图，尽管接收者仍然接收并处理了它。

OpenGL 规范

OpenGL 子对象允许您指定所需的 OpenGL 版本和/或配置文件。

配置密钥类型描述

配置密钥	类型	描述
`desktopProfile`	字符串	在桌面上运行时，将此值设置为 `core` 或 `compatibility` 以获取非默认 OpenGL 配置文件。如果您在这里不指定任何内容，Qt 将使用此平台的默认设置。OpenGL ES 不支持配置文件，因此在此使用 OpenGL ES 的平台上忽略此设置。注意：请记住，这只是一个请求。如果请求的配置文件与实际配置文件不匹配，应用管理器将输出警告。
`esMajorVersion`	int	当设置时，应用管理器请求指定的 OpenGL ES 主版本。在桌面上，给定的 GLES 版本会被透明地映射到相应的桌面 GL 版本。当前的映射表如下 2.0 → 2.1 3.0 → 4.3 3.1 → 4.5 3.2 → 4.6 请确保指定两个选项：`esMajorVersion` 和 `esMinorVersion`；或者完全不指定。注意：记住，这只是一个请求。如果请求的版本与实际版本不匹配，应用管理器将输出警告。
`esMinorVersion`	int	当设置时，应用管理器请求指定的 OpenGL ES 次版本。更多信息，请见 `esMajorVersion` 上述内容。

desktopProfile

字符串

在桌面上运行时，将此值设置为 core 或 compatibility 以获取非默认 OpenGL 配置文件。如果您在这里不指定任何内容，Qt 将使用此平台的默认设置。OpenGL ES 不支持配置文件，因此在此使用 OpenGL ES 的平台上忽略此设置。

注意：请记住，这只是一个请求。如果请求的配置文件与实际配置文件不匹配，应用管理器将输出警告。

esMajorVersion

int

当设置时，应用管理器请求指定的 OpenGL ES 主版本。在桌面上，给定的 GLES 版本会被透明地映射到相应的桌面 GL 版本。当前的映射表如下

2.0 → 2.1
3.0 → 4.3
3.1 → 4.5
3.2 → 4.6

请确保指定两个选项：esMajorVersion 和 esMinorVersion；或者完全不指定。

注意：记住，这只是一个请求。如果请求的版本与实际版本不匹配，应用管理器将输出警告。

esMinorVersion int 当设置时，应用管理器请求指定的 OpenGL ES 次版本。更多信息，请见 esMajorVersion 上述内容。