基于标准可执行文件 (ELF 格式) 的运行程序。它是内置的运行程序,适用于所有组件。
使用 ELF 运行程序
如需使用 ELF 运行程序,组件的清单必须包含 program
块,其中包含:
{
program: {
runner: "elf",
binary: "bin/foo",
}
}
- 将值设置为字符串
elf
的runner
字段。 binary
字段,其值设置为组件软件包中的二进制输出名称。
字段
此外,ELF 运行程序接受一组可选字段,用于配置 ELF 组件的运行时环境。
参数
您可以使用 args
字段将参数(即大多数编程语言中的 argv
)传递给组件的进程。此字段接受字符串矢量(请参阅以下示例)。系统将按清单中声明的顺序传递参数集。
{
program: {
runner: "elf",
binary: "bin/foo",
args: ["--verbose", "--debug"]
}
}
转发 stdout 和 stderr 流
ELF 组件的 stdout 和 stderr 流可以路由到 LogSink 服务。默认情况下,只有当组件可用 LogSink 时,ELF 运行程序才会转发这些数据流。如果您的组件向其中任一流输出诊断消息,您应将这些流转发到 LogSink 服务。
如需启用此功能,请将以下代码添加到清单文件中:
{
include: [ "syslog/client.shard.cml" ],
}
添加此分片后,所有对 stdout 的写入都将记录为 INFO
消息,所有对 stderr 的写入都将记录为 WARN
消息。消息会按换行符拆分,并解码为 UTF-8 字符串。无效的字节序列会转换为 U+FFFD 替换字符,通常看起来像 �
。
无论是否包含 syslog 分片,都可以使用显式标志停用此功能:
program: {
runner: "elf",
binary: "bin/foo",
forward_stdout_to: "none",
forward_stderr_to: "none",
}
生命周期
组件具有生命周期。如果您向组件清单添加 lifecycle
属性,由 ELF 运行程序运行的组件便可与生命周期集成。目前,stop
是生命周期协议中唯一的方法。
{
program: {
runner: "elf",
binary: "bin/foo",
lifecycle: { stop_event: "notify" },
}
}
该程序应获取生命周期通道的句柄,并在该通道上提供生命周期协议。组件应在接收并处理 stop
调用后退出。
ELF Runner 会监控它为组件的程序二进制文件启动的进程。如果此进程退出,ELF 运行程序将终止组件的执行上下文,其中包括组件的作业和所有子进程。
安全
有几个特许字段受许可名单控制。只有此许可名单中包含的组件才能使用这些字段。对于所有字段,该政策都适用于组件中的第一个进程。第一个进程是 ELF 运行程序为 program
块中声明的二进制文件创建的进程。所有字段均为布尔值,默认为 false
。
主要进程关键
main_process_critical
字段可用于将组件的第一个进程标记为对组件管理器作业至关重要,这会导致如果进程以非零代码退出,组件管理器(以及所有组件)都会终止。这会强制系统触发硬重启。
氛围 VMO 执行
ambient_mark_vmo_exec
字段可用于允许组件的第一个进程使用 zx_vmo_replace_as_executable
,并将 ZX_HANDLE_INVALID
作为第二个参数,而不是使用以 ZX_RSRC_SYSTEM_VMEX_BASE
为底数的有效 ZX_RSRC_KIND_SYSTEM
。
创建原始进程
job_policy_create_raw_processes
字段可用于允许组件使用 zx_process_create
创建进程。
{
program: {
runner: "elf",
binary: "bin/foo",
job_policy_create_raw_processes: "true"
}
}
是否为共享进程
在调用 zx_process_create
时,is_shared_process
字段可用于传递 ZX_PROCESS_SHARED
标志。只有当组件也将 job_policy_create_raw_processes
设置为 true
时,才能使用此标志。
{
program: {
runner: "elf",
binary: "bin/foo",
job_policy_create_raw_processes: "true",
is_shared_process: "true"
}
}
具有可用异常渠道的任务
job_with_available_exception_channel
字段可用于确保将组件创建为作业的直接后代,并且该作业将有可用的异常通道。
{
program: {
runner: "elf",
binary: "bin/foo",
job_with_available_exception_channel: "true"
}
}
环境变量
您可以使用 environ
属性为 ELF 组件设置环境变量。此字段必须是字符串的矢量,其中每个字符串都包含以等号分隔的变量和值。例如,以下示例代码将变量 FAVORITE_ANIMAL
和 FAVORITE_COLOR
声明为 cat
和 red
。
{
program: {
runner: "elf",
binary: "bin/echo",
environ: [
"FAVORITE_ANIMAL=cat",
"FAVORITE_COLOR=red",
]
}
}
延伸阅读
如需详细了解进程的创建方式,请参阅 Zircon 程序加载和动态链接。