精灵跑者

ELF 跑酷游戏是负责启动游戏的跑酷游戏 组件 基于标准可执行文件 (ELF) 格式）。它是一个内置运行程序，适用于所有组件。

使用 ELF Runner

如需使用 ELF 运行程序，该组件的清单必须包含一个 program 代码块， 包含：

{
    program: {
        runner: "elf",
        binary: "bin/foo",
    }
}

• 值设置为字符串 elf 的 runner 字段。
• binary 字段，其值设置为组件软件包中的二进制文件输出名称。

字段

此外，ELF 运行程序接受一组可选字段来配置 ELF 组件的运行时环境。

参数

参数（在大多数编程语言中即为 argv）可以传递给 使用 args 字段来确认组件进程。此字段接受以下向量： 字符串（请参阅下面的示例）。 参数集的传递顺序与清单中声明的顺序相同。

{
    program: {
        runner: "elf",
        binary: "bin/foo",
        args: ["--verbose", "--debug"]
    }
}

转发 stdout 和 stderr 流

ELF 组件的 stdout 和 stderr 流可以路由到 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",
    }

生命周期

组件具有生命周期。由 ELF 运行程序运行的组件可以 与生命周期集成（如果向组件添加 lifecycle 属性） 清单。目前 stop 是 Lifecycle 协议中的唯一方法。

{
    program: {
        runner: "elf",
        binary: "bin/foo",
        lifecycle: { stop_event: "notify" },
    }
}

程序应获取生命周期渠道的句柄，并提供 生命周期协议。组件应在以下时间后退出： 接收和处理 stop 调用。

ELF Runner 会监控其启动的进程，以处理 组件。如果此过程退出，ELF 运行程序将终止组件的 执行上下文，其中包括组件的作业和所有子进程。

安全

有多个特权字段受 allowlist。仅限此许可名单中包含的组件 都可以使用这些字段对于所有字段，该政策适用于第一个 组件中的流程第一个进程是由 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_SHARED 标志 调用 zx_process_create 时。此标志只能用于 如果该组件也将 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",
        ]
    }
}