精灵跑者

这是一个内置运行程序,适用于所有组件。

使用 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_ANIMALFAVORITE_COLOR 声明为 catred

{
    program: {
        runner: "elf",
        binary: "bin/echo",
        environ: [
            "FAVORITE_ANIMAL=cat",
            "FAVORITE_COLOR=red",
        ]
    }
}