使用 ELF 运行程序
如需使用 ELF 运行程序,组件的清单必须包含 program
块,其中包含:
{
program: {
runner: "elf",
binary: "bin/foo",
}
}
runner
字段,其值设置为字符串elf
。binary
字段,其值设为组件软件包中的二进制输出名称。
字段
此外,ELF 运行程序还接受一组可选字段来配置 ELF 组件的运行时环境。
参数
参数(即在大多数编程语言中是 argv
)可以使用 args
字段传递给组件进程。此字段接受字符串矢量(请参阅下面的示例)。参数设置的顺序与清单中声明的顺序相同。
{
program: {
runner: "elf",
binary: "bin/foo",
args: ["--verbose", "--debug"]
}
}
转发 stdout 和 stderr 流
ELF 组件的 stdout 和 stderr 流可以路由到 LogSink 服务。默认情况下,ELF 运行程序仅在 LogSink 可用于组件时转发这些数据流。如果您的组件将诊断消息输出到其中任何一个流,您应将这些流转发到 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。如果您将 lifecycle
属性添加到组件清单中,则 ELF 运行程序运行的组件可以与生命周期集成。目前,stop
是 Lifecycle 协议中的唯一方法。
{
program: {
runner: "elf",
binary: "bin/foo",
lifecycle: { stop_event: "notify" },
}
}
程序应将句柄传递给生命周期通道,并在该通道上提供 Lifecycle 协议。该组件应在收到并处理 stop
调用后退出。
ELF 运行程序会监控其启动的进程,以获取组件的程序二进制文件。如果此过程退出,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"
}
}
是共享进程
is_shared_process
字段可用于在调用 zx_process_create
时传递 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"
}
}
延伸阅读
如需详细了解如何创建进程,请参阅 Zircon 程序加载和动态链接。
环境变量
您可以使用 environ
属性为 ELF 组件设置环境变量。此字段必须是字符串矢量,其中每个字符串都包含变量和由等号分隔的值。例如,以下示例代码将变量 FAVORITE_ANIMAL
和 FAVORITE_COLOR
声明为 cat
和 red
。
{
program: {
runner: "elf",
binary: "bin/echo",
environ: [
"FAVORITE_ANIMAL=cat",
"FAVORITE_COLOR=red",
]
}
}