配置

主要配置

您可以通过配置(config)文件和命令行来配置应用程序管理器。要显示当前支持的命令行选项,请运行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的平台的标准位置的值。例如,在Unix中,${stdpath:TempLocation}被替换为/tmp;除非您的系统管理员另行配置。

如果在一个以上的地方指定了选项:要么是在命令行和配置文件中,要么是在多个配置文件中,则最终值将根据以下规则解析

  • 选项是从所有可用的配置文件中按命令行上它们的顺序解析的。值由配置文件覆盖,因为它们被加载。
  • 直接通过命令行指定的选项始终覆盖任何配置文件中的值。

注意:有一个例外:期望值列表的选项,如-Iui/importPaths。在这种情况下,所有值,无论它们在哪里指定,都合并到一个单一的、最终的列表中。

一个非常简洁的am-config.yaml示例可能如下所示,它定义了主要的qml入口和两个导入路径

formatVersion: 1
formatType: am-configuration
---
ui:
  mainQml: "${CONFIG_PWD}/main.qml"
  importPaths: [ "${CONFIG_PWD}/imports/shared", "${CONFIG_PWD}/imports/sysui" ]
命令行
[配置键]
类型描述
(第一个非选项)
[ui/mainQml]
string主要QML文件。
--helpbool打印支持的选项并退出。
--versionbool打印应用程序管理器的当前版本并退出。
--build-configbool以YAML格式打印应用程序管理器的构建配置并退出。
--config-file-clist<string>从一组文件中加载配置设置。您可以使用多个配置文件,例如,将配置整齐地分割成设备特定部分和UI特定部分。所有配置文件的内容都按它们在命令行中出现的顺序合并:未出现在早期配置值中的键保持不变;重复的键按以下规则合并
  1. 标量值将覆盖早期配置值。
  2. 列表将附加到早期列表内容。
  3. 根据规则1和2,映射递归地在键键基础上合并。

应用程序管理器将解析和评估所有配置文件的结果保存到缓存中。在后续启动时,如果使用确切的配置文件集且未更改,则加载此缓存。

如果给定的参数是一个目录,那么将从该目录按字母顺序(ASCII排序顺序,非递归)加载所有扩展名为.yaml的文件。

--no-cachebool禁用配置文件和应用数据库的缓存功能:缓存既不读取也不写入。(默认值:false)
--clear-cachebool尽管应用程序管理器应该检测配置文件和应用数据库缓存是否不同步,但您可以使用此选项在启动时强制清除缓存。

旧选项--clear-config-cache-r--recreate-database也仍然受支持,并且也 clearing 两个缓存。(默认值:false)

(默认值:false)

--option-oYAML使用此选项,您可以从命令行设置或覆盖配置文件的某些部分。此选项可以指定多次,其值按与通过-c指定的配置文件内容相同的方式进行评估。评估顺序是在配置文件之后,但在更具体的直接选项(如--fullscreen之前,该选项可以重写为-o 'ui: { fullscreen: no }')。
--instance-id
[instanceId]
字符串 将名称分配给此应用程序管理器实例。只在您同时运行多个实例并且需要通过appman-controller工具访问它们时才有效。将该数字附加到id以使区分具有相同id的实例成为可能。(默认值:appman)
--database
[applications/database]
string已弃用并忽略。应用程序数据库将透明地缓存 - 参见--clear-cache--no-cache选项。
--recreate-database-rbool已弃用。这些选项对于应用程序管理器响应应用程序清单文件更改是必要的,但现在已经不再需要。为了向后兼容,这些选项映射到--clear-cache选项,该选项将清除配置和应用数据库缓存。(默认值:false)
--builtin-apps-manifest-dir
[applications/builtinAppsManifestDir]
string内置应用程序清单的基准目录;也可以指定多个目录作为列表。
--installation-dir
[applications/installationDir]
string包安装的基准目录。如果要安装新包,则必须指定此选项;否则,只能使用内置包。(默认值:空/禁用)
--document-dir
[applications/documentDir]
string每个包文档存储目录的基准目录。(默认值:空/禁用)

请注意,如果您在此处未设置documentDir,则在安装新包时不会创建每个应用程序的文档目录。

[applications/installationDirMountPoint]string如果设置,则将延迟加载包数据库,直到指定的mount point已挂载。(默认值:空/禁用)
--dbusstring在指定的 D-Bus 上注册 ApplicationManagerPackageManagerNotificationManagerWindowManager。这可以是一个完整的 D-Bus 总线指定字符串,sessionsystemauto(默认),或 none(完全不注册)。

仅在桌面或开发期间使用 auto 关键字。此关键字意味着应用程序管理器尝试启动一个私有会话总线,如果成功则使用该总线。否则,将完全不进行注册,相当于 none

在生产系统中,你可能希望将应用程序管理器放在 system 总线上,在那里你可以使用标准的 D-Bus 机制设置详细的策略,同时保持 NotificationManager 在会话总线上。请参阅下面的更高级的配置文件选项dbus

[dbus]map<object>允许更精细地控制 D-Bus 注册和函数调用策略。此映射中此处的每个密钥(有一个例外 - 请见下文)都对应于您想配置的 D-Bus 接口名称(io.qt.ApplicationManagerio.qt.PackageManagerio.qt WindowManager、和 org.freedesktop.Notifications)。如果存在这样的键,则它优先于 dbus 命令行选项。每个键的值是一个 D-Bus 指定对象。
--fullscreen
[ui/fullscreen]
bool全屏显示。 (默认: false)
--no-fullscreenbool覆盖系统 UI 配置文件中的全屏设置。在对桌面的开发中很有用。 (默认: false)
[ui/windowIcon]string如果设置,给定的图像文件将用作所有应用程序管理器窗口的窗口图标。此选项仅为开发使用,在 Windows、macOS 和 Linux/X11 上生效。
-I
[ui/importPaths]
list<string>向系统 UI 添加额外的 QML 导入路径。
[ui/pluginPaths]list<string>向系统 UI 添加额外的 Qt 插件路径。
[ui/style]string如果设置,则给定的样式由 QtQuickControls 2 使用。
[ui/resources]list<string>接受 Qt 资源 文件 (.rcc) 或包含资源的库列表,并在 System UI 进程中注册它们。资源可以通过冒号或 "qrc://" 文件路径前缀访问。
[plugins]map<list<string>>定义应用程序管理器应该加载的插件的字符串到字符串列表的映射。值必须是一个插件或插件库文件路径名的列表。目前,仅有的有效密钥是 startupcontainer
[systemProperties]对象 将用户定义的属性(键/值对)导出到系统UI和应用程序。此字段只能有以下子字段,用于控制对实际属性的访问:privateprotectedpublic;其他子字段将被忽略。这些访问标签下的属性可以自由选择,也可以嵌套。这些属性以ApplicationManager::systemProperties的形式暴露给系统UI,并以ApplicationInterface::systemProperties的形式暴露给所有QML应用程序
  • 系统UI可以访问public、protected和private属性。
  • 内置应用程序可以访问public和protected属性。
  • 已安装的(第三方)应用程序只能访问public属性。

私有键会覆盖相同名称的保护键和公共键;保护键会覆盖相同名称的公共键。属性会被转换为QVariantMaps,但应用程序管理器不会对其进行任何解释。非QML应用程序可以通过$AM_RUNTIME_SYSTEM_PROPERTIES环境变量访问这些数据,作为YAML片段。

--verbosebool启用详细输出。除了某些Qt内部调试消息外,所有日志类别和消息类型都被启用;《code translate="no">logging-rules被忽略。

注意:通过QT_LOGGING_RULES环境变量提供的日志规则仍然有效。有关对日志输出的更多控制,请参阅下面的《code translate="no">logging-rules。

--slow-animationsbool以慢动作运行所有动画。(默认:false)
--load-dummydata
[ui/loadDummyData]
bool已弃用。将QML模拟数据加载到系统UI中,类似于qmlsceneqml
--no-security
[flags/noSecurity]
bool 禁用所有安全相关检查。仅在开发设置中使用此选项;永远不会在生产环境中使用。(默认:false)
--development-mode
[flags/developmentMode]
bool 允许安装仅带有有效开发者签名的包。(默认:false)
[flags/allowUnsignedPackages]bool 允许安装没有任何签名的包。仅在确认包的完整性通过其他手段时,以及在限制对安装程序API的访问时在生产环境中使用此选项。(默认:false)
[flags/allowUnknownUiClients]bool如果设置,Wayland合成器将接受由应用程序管理器未启动的客户端的表面。(默认:false)
--no-ui-watchdog
[flags/noUiWatchdog]
bool禁用检测挂起(例如,通过Wayland的ping/pong机制)的UI应用程序。(默认:false)
--force-single-process
[flags/forceSingleProcess]
bool即使在启用Wayland的构建中也强制单进程模式。(默认:false)
--force-multi-process
[flags/forceMultiProcess]
bool强制多进程模式;如果不可能,则立即退出。(默认:false)
--single-appstring仅运行一个应用程序(忽略数据库)。在此模式下,应用程序管理器可以代替qmlsceneqml使用。参数是info.yaml的路径。别名(info-*.yaml)也从此路径加载。
--log-instantbool在启动时立即打印所有日志消息。通常,日志输出会延迟到知道日志配置(例如,日志规则)后。启动时预期输出和格式不同。
--logging-rule
[logging/rules]
list<string>添加标准Qt日志规则 - 请参阅 QLoggingCategory 文档了解所需的格式。特定于应用管理器的日志类别在 日志与调试 中描述。
[logging/messagePattern]string如果提供,则用作Qt消息模式。有关格式更多信息,请参阅 qSetMessagePattern
[logging/useAMConsoleLogger]bool始终使用特定于应用管理器的日志功能,该功能可以启用彩色控制台输出。如果没有提供值或提供了无效值,则只在messagePattern未设置时使用日志功能。
[logging/dlt/id]string如果提供,则用作汽车DLT应用程序ID。大小限制为四个字符,额外的字符将被丢弃。

注意:默认ID "PCAM" 在应用此配置选项之前使用。

[logging/dlt/description]string如果提供,则用作汽车DLT应用程序描述。这允许使用更详细的定义扩展简短的DLT应用程序ID。

注意:在应用此配置选项之前使用默认描述。

[logging/dlt/longMessageBehavior]string配置在使用汽车DLT时如何处理非常长的消息(超过~1000个字符)。默认行为是截断消息到最大可能大小。其他选项包括 split (将消息分割成几个较小的消息)、pass (将消息按原样转发到DLT)或truncate (显式请求默认行为)。
--no-dlt-loggingbool禁用汽车DLT日志。当没有运行dlt-daemon时,此选项特别有用;否则,进程会在退出时挂起一段时间以发送日志。
--qml-debugbool启用QML调试/分析。有关更多信息,请参阅 日志与调试
[installationLocations]list<object>系统上可用的安装位置的定义。这已弃用,因为现在只支持一个安装位置,由--installationDirapplications/installationDir定义。
[runtimes]map<object>可以使用键值对映射指定运行时的选项。键是运行时的名称;值由相应的运行时实现解释。有关更多信息,请参阅 运行时配置。有一个特殊的键名为additionalLaunchers:值是字符串id的数组,所有这些id都注册为自定义运行时。当基于相应运行时启动应用程序时,预期将提供相应的appman-launcher-<id>可执行文件。
[containers]map<object>可以使用键值对映射指定容器的选项。键是容器的名称;值由相应的容器实现解释。有关更多信息,请参阅 容器
[quicklaunch/idleLoad]实数这是介于 01 之间的系统负载值。只要系统的空闲负载高于此值,应用管理器就不会启动新的快速启动器。(默认:0)
[quicklaunch/runtimesPerContainer]int 指定为任何容器/运行时组合始终准备多少个快速启动器。(默认:0)

设置此值的不同方法

  • 单个整数值,该值适用于所有可能的容器/运行时组合。
  • 从容器ID到整数值的映射,该值适用于相应容器中所有可能的运行时ID。
  • 从容器ID到runtime ID映射再到一个整数值的映射,这将仅应用于相应的容器/运行时组合。

方法2和方法3可以自由混合,特殊通配符ID "*" 表示“任何容器ID”或“任何运行时ID”。

注意:大于10的值将被忽略,因为这没有意义,并且如果在一个实例化成本很高的容器插件中,可能会潜在地冻结你的设备。

[*code translate="no">quicklaunch/failedStartLimit"*]int任何在failedStartLimitIntervalSec内失败次数多于failedStartLimit的快速启动容器/运行时组合将被禁用。(默认: 5)
[*code translate="no">quicklaunch/failedStartLimitIntervalSec"*]int参见上文的failedStartLimit。(默认: 10)
[*--wayland-socket-name*
[*wayland/socketName]
string用于创建合成器组件的Wayland套接字文件系统名称。(默认:由应用程序管理器自动检测,可能是qtam-wayland-0

注意:您只能在此处指定名称,但不能指定路径:Wayland始终在$XDG_RUNTIME_DIR中创建此套接字。如果此目录不可写或环境变量根本未设置,则合成器将无法启动。有关绕过此限制的方法,请参见下文的wayland/extraSockets

[*wayland/extraSockets]list<object>要添加到Wayland服务器中的附加套接字列表。列表中的每个对象包含以下字段
  • path:套接字的绝对路径。
  • permissions:套接字的数字权限 - 可以用八进制表示,例如 0640
  • userId:套接字的数字uid。
  • groupId:套接字的数字gid。

只需要path,而其他字段是可选的,并回退到QLocalServer的默认值。

如果应用程序管理器在sudo或setuid-root下运行,它将使用其扩展权限来应用可选的permissionsuserIdgroupId设置。

[*--disable-installer*
[*installer/disable]
bool在运行时完全禁用安装器子模块。另一种选择是在qmake步骤中根本不编译它。
[*installer/caCertificates]list 用于验证包的CA证书文件路径列表。有关详细信息,请参阅安装器文档
[*crashAction]object指定在应用程序管理器崩溃时要采取的操作。有关详细信息,请参阅崩溃操作规范
[*ui/opengl]object允许您指定所需的OpenGL版本和/或配置文件。有关详细信息,请参阅OpenGL规范
[*ui/iconThemeName]string 指定要使用的图标主题。有关如何将路径添加到自定义主题的详细信息,请参阅ui/iconThemeSearchPaths
[*ui/iconThemeSearchPaths]list 向系统UI和所有应用程序添加附加图标主题搜索路径。此选项可用于将自定义图标主题添加到搜索路径,并通过指定ui/iconThemeName来加载它。
[*intents/disable]bool在运行时完全禁用intent子模块。
[*intents/timeouts]object 允许您指定在意图子系统中使用的处理超时。有关详细信息,请参阅意图超时规范

D-Bus 规范

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

配置键类型描述
registerstring在指定的 D-Bus 上注册接口:可以是 sessionsystemnone~(用于完全不注册),或者完整的 D-Bus 总线规范字符串。
策略map<object>这些可选的访问策略可以用作替换或补充标准 D-Bus 策略配置。这个映射的键是未装饰的 D-Bus 函数名称,例如 startApplication。当指定一个键时,相应函数的访问策略是 deny,直到您添加 allow 标准——所有这些标准都是 AND 结合在一起。由于 D-Bus 属性的实现方式,这些策略仅适用于方法,但不适用于属性获取器和设置器。

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

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

仅可以通过这种方式配置应用程序管理器的公共 D-Bus 接口。以下列出的是可用的接口名称

接口相应的 QML 类
io.qt.ApplicationManagerApplicationManager
io.qt.PackageManagerPackageManager
io.qt.WindowManagerWindowManager
org.freedesktop.Notifications非应用程序管理器特定 - 此接口遵循frees desktop.org 规范

运行时配置

运行时配置子对象是针对实际运行时的特定配置,因此下表增加了指定配置选项适用于哪个运行时的额外列

配置键运行时类型描述
环境变量native、qmlmap<string>这是一个简单的字符串到字符串映射,描述在启动运行时进程时应设置的环境变量。要从默认环境变量中删除变量,请给它提供一个空值。
导入路径qmllist<string>为通过此运行时启动的应用程序添加额外的 QML 导入路径。
插件路径qmllist<string>为通过此运行时启动的应用程序添加额外的 Qt 插件路径。
插件qmlmap<list<string>>这是一个字符串到字符串列表映射,定义 QML 运行时应加载的插件。值必须是单个插件或插件库文件路径名称的列表。目前唯一有效的键是 startup
  • startup:此插件必须实现 StartupInterface。在应用程序启动时,QML 运行时调用该函数钩子。
资源qmllist<string>接受一个 Qt 资源文件 (.rcc) 或已经编译入库的资源的列表,将在每个 QML 运行时注册。因此,所有运行的 QML 应用程序都将包括这些资源。可以使用 ":" 或 "qrc://" 文件路径前缀访问这些资源。
quicklaunchQmlqmlstring这是一个在启动快速启动器时加载的 QML 源文件;但不适用于直接启动应用程序的情况。提供此文件仅在使用 quicklaunch/runtimesPerContainer > 0 时有用。此选项可用于提高实际应用程序的后续启动性能,例如通过导入并因此预加载常见的应用程序插件和实例化昂贵的单例。通常,创建其他对象是没有用的,因为创建的组件会立即再次删除。同样,出于相同的原因,不应创建视觉元素。始终记住,包含在此文件中的所有内容都将加载到所有使用 QML 运行时启动的应用程序中。
loadDummyDataqmlbool已废弃。将 QML 模拟数据加载到应用程序中,就像 qmlsceneqml 一样。(默认:false)
quitTimeqmlint 定义了应用程序在关闭之前获得的宽限期(以毫秒为单位)。这是从接收到 quit() 信号到用 acknowledgeQuit() 方法响应的时间限制。(默认:250)
crashActionqmlobject指定在 QML 客户端应用程序崩溃时应采取哪些操作。有关更多信息,请参阅崩溃动作规范

崩溃动作规范

这些子对象指定如果应用程序管理器或 QML 运行时崩溃时,应采取哪些动作。

注意:所有这些动作仅在 Linux 上有效。

以下条件被处理

  • 未捕获的异常。派生于 std::exception 的异常也会在 what() 中显示发生的详细信息。
  • SIGSEGV
  • SIGABRT
  • SIGBUS
  • SIGILL
  • SIGFPE
  • SIGPIPE
  • SIGQUIT
  • SIGSYS
配置键类型描述
printBacktracebool尝试打印可读的堆栈跟踪。在 Linux 上,除非在配置时启用了 libbacktrace,否则它使用 glibc 的原始回溯功能。在 Windows 上,只有当在配置时启用了 stackwalker 时才会打印回溯。(默认:true)
printQmlStackbool尝试打印可读的 QML 堆栈跟踪。类似于上面的 printBacktrace,但在崩溃发生时打印当前的 QML 函数堆栈。(默认:true)
dumpCorebool通过 abort 结束进程而不是 _exit。根据您的内核配置转储 core 文件。(默认:true)
waitForGdbAttachint指定在崩溃程序处于停止状态等待调试器附加时的超时时间(以秒为单位)。任何小于等于 <= 0 的值都将跳过此步骤。(默认:0)
stackFramesToIgnore/onCrashint不应在回溯中打印的堆栈帧数。这是为了避免操作系统和应用程序管理器的内部处理程序同时出现在回溯中。(默认:最新的 XCode 和最新的 gcc 版本的合理值)
stackFramesToIgnore/onExceptionint不应在回溯中打印的堆栈帧数。这是为了避免 C++ 库和应用程序管理器的内部处理程序同时出现在回溯中。(默认:最新的 XCode 和最新的 gcc 版本的合理值)

Intent 超时规范

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

配置键类型描述
disambiguationint在系统 UI 中对意图进行去混淆决策的时间间隔(以毫秒为单位)。(默认:10000)
startApplicationint以毫秒为单位的应用程序应该启动以处理意图请求的时间间隔——当然,前提是它尚未运行。(默认:3000)
replyFromApplicationint处理应用程序需要在毫秒级时间内确认已接收意图请求的时间间隔。对于QML应用程序,这是在IntentHandler::requestReceived中完成的。(默认值:5000)
replyFromSystemint从单个意图处理的完成所需毫秒级时间间隔:这从请求应用程序中实际创建意图开始,通过服务器到处理应用程序,然后从处理到请求应用程序返回(错误)结果。

注意:这个超时值略微大于上述描述的三个超时值之和是有道理的:所有其他超时都是向意图请求完成的方向的子步骤,而此超时代表整个过程。使其略大于总和可考虑到不属于单个子超时的处理和通信开销。(默认值:20000)

请注意,由于意图传递的异步性,系统可能会因为遇到replyFromApplicationreplyFromSystem超时而取消意图,尽管接收器仍然接收并处理了它。

OpenGL规范

使用opengl子对象,您可以指定所需的OpenGL版本和/或配置文件。

配置键类型描述
desktopProfilestring在桌面运行时,将此值设置为corecompatibility以请求非默认OpenGL配置文件。如果您在此处不指定任何内容,Qt将使用该平台的默认设置。OpenGL ES不支持配置文件,因此在使用OpenGL ES的平台上忽略此设置。

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

esMajorVersionint当设置时,应用程序管理器请求指定的OpenGL ES主版本。在桌面上,给定GLES版本会被透明地映射到相应的桌面GL版本。当前的映射表如下
  • 2.0 → 2.1
  • 3.0 → 4.3
  • 3.1 → 4.5
  • 3.2 → 4.6

确保指定两种选项:esMajorVersionesMinorVersion;或都不设定

注意:请注意,这只是一个请求。如果请求的版本与实际版本不匹配,应用程序管理器会输出警告。

esMinorVersionint当设置时,应用程序管理器请求指定的OpenGL ES次版本。有关更多信息,请参阅上文的esMajorVersion

© 2024 The Qt Company Ltd. 本文档中的文档贡献者是其各自所有者的版权拥有者。本处提供的文档是根据Free Software Foundation发布的GNU自由文档许可证版本1.3的条款许可的。Qt和相关标识是芬兰及/或其他国家的The Qt Company Ltd.的商标。所有其他商标均为其各自所有者的财产。