跳转到内容

std.Target.Query

标准库Zig 0.17.1官方原文
源码std/Target/Query.zig

第 1 行

包含与 Target 相同的全部数据,并额外引入 “本机目标”的概念。此抽象旨在 提供有意义且符合预期的默认值。此结构体引用 资源且可复制(资源引用说明按原文保留)。

字段

cpu_arch: ?Target.Cpu.Arch = null

null 表示本机。

cpu_model: CpuModel = .determined_by_arch_os
cpu_features_add: Target.Cpu.Feature.Set = .empty

要在 cpu_model 的特性集合基础上添加的稀疏特性集合。

给定 Target.Cpu.Arch 对应的带类型特性可在 @field(Target, @tagName(arch.family())) 中找到。

例如 std.Target.x86.cpu.x86_64_v3.features 或 std.Target.s390x.cpu.z13.features。

cpu_features_sub: Target.Cpu.Feature.Set = .empty

要从 cpu_model 的特性集合中移除的稀疏特性集合。

给定 Target.Cpu.Arch 对应的带类型特性可在 @field(Target, @tagName(arch.family())) 中找到。

例如 std.Target.x86.cpu.x86_64_v3.features 或 std.Target.s390x.cpu.z13.features。

os_tag: ?Target.Os.Tag = null

null 表示本机。

os_version_min: ?OsVersion = null

os_tag 为本机时,null 表示本机版本;否则为 cpu_arch、os_tag 和 abi 的默认最低版本。

os_version_max: ?OsVersion = null

os_tag 为本机时,null 表示本机版本;否则表示已知的最新操作系统版本。

glibc_version: ?SemanticVersion = null

abi 为本机时,null 表示本机版本;否则为 cpu_arch、 os_tag 和 abi 的默认最低版本。

abi 为 null 或 isGnu() 为 false 时,必须为 null。

android_api_level: ?u32 = null

abi 为本机时,null 表示本机版本;否则为 cpu_arch 和 abi 的默认最低版本。

abi 为 null 或 isAndroid() 为 false 时,必须为 null。

abi: ?Target.Abi = null

null 在 os_tag 为本机时表示本机;否则,表示针对 cpu_arch 和 os_tag 尽力选择的默认值。

ofmt: ?Target.ObjectFormat = null

null 表示采用 cpu_arch 与 os_tag 组合的默认值。

dynamic_linker: ?Target.DynamicLinker = null

abi 为本机时,null 表示本机路径;否则为基于 cpu_arch、 os_tag 和 abi 的标准路径。非 null 的空字符串表示不使用动态链接器, 无论其他字段的值为何。

std.Target.Query.Allocator

别名

第 12 行

别名目标 std.mem.Allocator

std.Target.Query.allocDescription

函数

第 557 行

已弃用;请改用 zigTriple。将在 0.18.0 中移除。

pub fn allocDescription(self: Query, allocator: Allocator) ![]u8

参数

self: Query
allocator: Allocator

std.Target.Query.ArrayList

别名

第 13 行

别名目标 std.ArrayList

std.Target.Query.assert

别名

第 9 行

别名目标 std.debug.assert

std.Target.Query.builtin

常量

第 8 行

std.Target.Query.canDetectLibC

函数

第 420 行

pub fn canDetectLibC(self: Query) bool

参数

self: Query

std.Target.Query.CpuModel

容器

第 70 行

字段

native

始终为本机

baseline

始终为基线

determined_by_arch_os

若 CPU 架构为原生,则 CPU 型号也为原生;否则 为基线型号。

explicit: *const Target.Cpu.Model

std.Target.Query.CpuModel.eql

函数

第 83 行

pub fn eql(a: CpuModel, b: CpuModel) bool

参数

std.Target.Query.dynamicLinkerEqualOpt

函数

第 635 行

fn dynamicLinkerEqualOpt(a: ?Target.DynamicLinker, b: ?Target.DynamicLinker) bool

参数

std.Target.Query.eql

函数

第 612 行

pub fn eql(a: Query, b: Query) bool

参数

a: Query
b: Query

std.Target.Query.formatVersion

函数

第 433 行

格式化版本号;补丁部分为零时省略它, 而 SemanticVersion.format 始终格式化全部版本部分。

fn formatVersion(version: SemanticVersion, gpa: Allocator, list: *ArrayList(u8)) !void

参数

version: SemanticVersion
gpa: Allocator
list: *ArrayList(u8)

std.Target.Query.fromTarget

函数

第 121 行

pub fn fromTarget(target: *const Target) Query

参数

target: *const Target

std.Target.Query.isNative

函数

第 414 行

pub fn isNative(self: Query) bool

参数

self: Query

std.Target.Query.isNativeAbi

函数

第 403 行

pub fn isNativeAbi(self: Query) bool

参数

self: Query

std.Target.Query.isNativeCpu

函数

第 391 行

pub fn isNativeCpu(self: Query) bool

参数

self: Query

std.Target.Query.isNativeOs

函数

第 397 行

pub fn isNativeOs(self: Query) bool

参数

self: Query

std.Target.Query.isNativeTriple

函数

第 410 行

pub fn isNativeTriple(self: Query) bool

参数

self: Query

std.Target.Query.mem

别名

第 11 行

别名目标 std.mem

std.Target.Query.OsVersion

容器

第 95 行

字段

none: void
semver: SemanticVersion
windows: Target.Os.WindowsVersion

std.Target.Query.OsVersion.eql

函数

第 100 行

pub fn eql(a: OsVersion, b: OsVersion) bool

参数

std.Target.Query.OsVersion.eqlOpt

函数

第 112 行

pub fn eqlOpt(a: ?OsVersion, b: ?OsVersion) bool

参数

std.Target.Query.parse

函数

第 226 行

pub fn parse(args: ParseOptions) !Query

参数

args: ParseOptions

用法示例

test parse {
    const io = std.testing.io;

    {
        const query = try Query.parse(.{
            .arch_os_abi = "aarch64-linux",
            .cpu_features = "native",
        });

        try std.testing.expect(query.cpu_arch.? == .aarch64);
        try std.testing.expect(query.cpu_model == .native);
    }
    {
        const query = try Query.parse(.{ .arch_os_abi = "native" });

        try std.testing.expect(query.cpu_arch == null);
        try std.testing.expect(query.isNative());

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "native", text);
    }
    {
        const query = try Query.parse(.{
            .arch_os_abi = "x86_64-linux-gnu",
            .cpu_features = "x86_64-sse-sse2-avx-cx8",
        });
        const target = try std.zig.system.resolveTargetQuery(io, query);

        try std.testing.expect(target.os.tag == .linux);
        try std.testing.expect(target.abi == .gnu);
        try std.testing.expect(target.cpu.arch == .x86_64);
        try std.testing.expect(!target.cpu.has(.x86, .sse));
        try std.testing.expect(!target.cpu.has(.x86, .avx));
        try std.testing.expect(!target.cpu.has(.x86, .cx8));
        try std.testing.expect(target.cpu.has(.x86, .cmov));
        try std.testing.expect(target.cpu.has(.x86, .fxsr));

        try std.testing.expect(target.cpu.hasAny(.x86, &.{ .sse, .avx, .cmov }));
        try std.testing.expect(!target.cpu.hasAny(.x86, &.{ .sse, .avx }));
        try std.testing.expect(target.cpu.hasAll(.x86, &.{ .mmx, .x87 }));
        try std.testing.expect(!target.cpu.hasAll(.x86, &.{ .mmx, .x87, .sse }));

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "x86_64-linux-gnu", text);
    }
    {
        const query = try Query.parse(.{
            .arch_os_abi = "arm-linux-musleabihf",
            .cpu_features = "generic+v8a",
        });
        const target = try std.zig.system.resolveTargetQuery(io, query);

        try std.testing.expect(target.os.tag == .linux);
        try std.testing.expect(target.abi == .musleabihf);
        try std.testing.expect(target.cpu.arch == .arm);
        try std.testing.expect(target.cpu.model == &Target.arm.cpu.generic);
        try std.testing.expect(target.cpu.has(.arm, .v8a));

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "arm-linux-musleabihf", text);
    }
    {
        const query = try Query.parse(.{
            .arch_os_abi = "aarch64-linux.3.10...4.4.1-gnu.2.27",
            .cpu_features = "generic+v8a",
        });
        const target = try std.zig.system.resolveTargetQuery(io, query);

        try std.testing.expect(target.cpu.arch == .aarch64);
        try std.testing.expect(target.os.tag == .linux);
        try std.testing.expect(target.os.version_range.linux.range.min.major == 3);
        try std.testing.expect(target.os.version_range.linux.range.min.minor == 10);
        try std.testing.expect(target.os.version_range.linux.range.min.patch == 0);
        try std.testing.expect(target.os.version_range.linux.range.max.major == 4);
        try std.testing.expect(target.os.version_range.linux.range.max.minor == 4);
        try std.testing.expect(target.os.version_range.linux.range.max.patch == 1);
        try std.testing.expect(target.os.version_range.linux.glibc.major == 2);
        try std.testing.expect(target.os.version_range.linux.glibc.minor == 27);
        try std.testing.expect(target.os.version_range.linux.glibc.patch == 0);
        try std.testing.expect(target.abi == .gnu);

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "aarch64-linux.3.10...4.4.1-gnu.2.27", text);
    }
    {
        const query = try Query.parse(.{
            .arch_os_abi = "aarch64-linux.3.10...4.4.1-android.30",
        });
        const target = try std.zig.system.resolveTargetQuery(io, query);

        try std.testing.expect(target.cpu.arch == .aarch64);
        try std.testing.expect(target.os.tag == .linux);
        try std.testing.expect(target.os.version_range.linux.range.min.major == 3);
        try std.testing.expect(target.os.version_range.linux.range.min.minor == 10);
        try std.testing.expect(target.os.version_range.linux.range.min.patch == 0);
        try std.testing.expect(target.os.version_range.linux.range.max.major == 4);
        try std.testing.expect(target.os.version_range.linux.range.max.minor == 4);
        try std.testing.expect(target.os.version_range.linux.range.max.patch == 1);
        try std.testing.expect(target.os.version_range.linux.android == 30);
        try std.testing.expect(target.abi == .android);

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "aarch64-linux.3.10...4.4.1-android.30", text);
    }
    {
        const query = try Query.parse(.{
            .arch_os_abi = "x86-windows.xp...win8-msvc",
        });
        const target = try std.zig.system.resolveTargetQuery(io, query);

        try std.testing.expect(target.cpu.arch == .x86);
        try std.testing.expect(target.os.tag == .windows);
        try std.testing.expect(target.os.version_range.windows.min == .xp);
        try std.testing.expect(target.os.version_range.windows.max == .win8);
        try std.testing.expect(target.abi == .msvc);

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "x86-windows.xp...win8-msvc", text);
    }
}

std.Target.Query.parseCpuArch

函数

第 343 行

类似 parse,但不完整解析,只判断处理器架构。若能确定,则返回该架构,否则返回 null。 适用于 Query 接口使用者需要先得知目标处理器架构,以便完整填充 ParseOptions 的情况。

pub fn parseCpuArch(args: ParseOptions) ?Target.Cpu.Arch

参数

args: ParseOptions

std.Target.Query.ParseOptions

容器

第 170 行

字段

arch_os_abi: []const u8 = "native"

有时称为“三元组”,大致如下: riscv64-linux-musl 各字段依次为:

  • CPU 架构
  • 操作系统,以及可选的版本范围
  • C ABI,可选,还可指定 glibc 版本或 Android API 级别 CPU 架构和操作系统均可使用字符串 "native"。 如果 CPU 架构指定为 "native",则可省略操作系统和 C ABI。
cpu_features: ?[]const u8 = null

格式类似“name+a+b-c-d+e”,其中“name”为处理器型号名称,“a”“b”“e”表示要加入集合的处理器特性,“c”“d”表示要从集合中移除的处理器特性。 处理器型号名称识别以下特殊字符串:

  • “baseline”:交叉编译时的默认处理器特性集合,较为保守,预期大多数可用硬件均支持。
  • “native”:编译时检测原生处理器型号。 若未提供此字段,即为 null,则其值取决于解析出的处理器架构。若为原生架构,则使用“native”;否则使用“baseline”。
object_format: ?[]const u8 = null
dynamic_linker: ?[]const u8 = null

动态链接器的绝对路径,用于覆盖默认路径;默认值来自原生检测或标准路径。

diagnostics: ?*Diagnostics = null

若提供此项,函数将填充有关解析失败的信息,以便生成易于理解的错误消息。

std.Target.Query.ParseOptions.Diagnostics

容器

第 202 行

字段

arch: ?Target.Cpu.Arch = null

如果已确定架构,则填充此值。

os_name: ?[]const u8 = null

若已确定操作系统名称,则填充此项。

os_tag: ?Target.Os.Tag = null

若已确定操作系统标签,则填充此项。

abi: ?Target.Abi = null

若已确定 ABI,则填充此项。

cpu_name: ?[]const u8 = null

若已确定 CPU 名称,则填充此字段。

unknown_feature_name: ?[]const u8 = null

如果返回 error.UnknownCpuFeature,则会填充此项。

unknown_architecture_name: ?[]const u8 = null

若返回 error.UnknownArchitecture,则填充此项。

std.Target.Query.parseOs

函数

第 566 行

fn parseOs(result: *Query, diags: *ParseOptions.Diagnostics, text: []const u8) !void

参数

result: *Query
diags: *ParseOptions.Diagnostics
text: []const u8

std.Target.Query.parseVersion

函数

第 358 行

类似 SemanticVersion.parse,但有以下区别:

  • 允许前导零。
  • 仅支持 2 或 3 个版本分量(主版本、次版本、[修订版本])。若省略第 3 个分量,则为 0。
  • 不允许预发布分量和构建元数据分量。
pub fn parseVersion(ver: []const u8) error{ InvalidVersion, Overflow }!SemanticVersion

参数

ver: []const u8

错误

InvalidVersion
Overflow

用法示例

test parseVersion {
    try std.testing.expectEqual(SemanticVersion{ .major = 1, .minor = 2, .patch = 0 }, try parseVersion("1.2"));
    try std.testing.expectEqual(SemanticVersion{ .major = 1, .minor = 2, .patch = 3 }, try parseVersion("1.2.3"));

    try std.testing.expectError(error.InvalidVersion, parseVersion("1"));
    try std.testing.expectError(error.InvalidVersion, parseVersion("1.2.3.4"));
    try std.testing.expectError(error.InvalidVersion, parseVersion("1.2.3-dev"));
}

std.Target.Query.parseVersion.parseVersionComponentInner

函数

第 360 行

fn parseVersionComponentInner(component: []const u8) error{ InvalidVersion, Overflow }!usize

参数

component: []const u8

错误

InvalidVersion
Overflow

std.Target.Query.Query

别名

第 6 行

别名目标 std.Target.Query

std.Target.Query.SemanticVersion

别名

第 119 行

别名目标 std.SemanticVersion

std.Target.Query.serializeCpu

函数

第 508 行

将查询渲染为文本表示,可由传给 Zig 编译器的 -mcpu 标志解析。 将结果追加到 buffer。

pub fn serializeCpu(q: Query, buffer: *std.array_list.Managed(u8)) Allocator.Error!void

参数

q: Query
buffer: *std.array_list.Managed(u8)

错误

OutOfMemory

std.Target.Query.serializeCpuAlloc

函数

第 550 行

pub fn serializeCpuAlloc(q: Query, ally: Allocator) Allocator.Error![]u8

参数

q: Query
ally: Allocator

错误

OutOfMemory

std.Target.Query.setGnuLibCVersion

函数

第 562 行

已弃用;请直接设置 glibc_version。将在 0.18.0 中移除。

pub fn setGnuLibCVersion(self: *Query, major: u32, minor: u32, patch: u32) void

参数

self: *Query
major: u32
minor: u32
patch: u32

std.Target.Query.std

别名

第 7 行

别名目标 std

std.Target.Query.Target

别名

第 10 行

别名目标 std.Target

std.Target.Query.updateOsVersionRange

函数

第 152 行

fn updateOsVersionRange(self: *Query, os: Target.Os) void

参数

self: *Query
os: Target.Os

std.Target.Query.versionEqualOpt

函数

第 629 行

fn versionEqualOpt(a: ?SemanticVersion, b: ?SemanticVersion) bool

参数

std.Target.Query.zigTriple

函数

第 441 行

pub fn zigTriple(self: Query, gpa: Allocator) Allocator.Error![]u8

参数

self: Query
gpa: Allocator

错误

OutOfMemory
源码

std/Target/Query.zig

//! 包含与 `Target` 相同的全部数据,并额外引入
//! “本机目标”的概念。此抽象旨在
//! 提供有意义且符合预期的默认值。此结构体引用
//! 资源且可复制(资源引用说明按原文保留)。

const Query = @This();
const std = @import("../std.zig");
const builtin = @import("builtin");
const assert = std.debug.assert;
const Target = std.Target;
const mem = std.mem;
const Allocator = std.mem.Allocator;
const ArrayList = std.ArrayList;

/// `null` 表示本机。
cpu_arch: ?Target.Cpu.Arch = null,

cpu_model: CpuModel = .determined_by_arch_os,

/// 要在 `cpu_model` 的特性集合基础上添加的稀疏特性集合。
///
/// 给定 `Target.Cpu.Arch` 对应的带类型特性可在
/// `@field(Target, @tagName(arch.family()))` 中找到。
///
/// 例如 `std.Target.x86.cpu.x86_64_v3.features` 或 `std.Target.s390x.cpu.z13.features`。
cpu_features_add: Target.Cpu.Feature.Set = .empty,

/// 要从 `cpu_model` 的特性集合中移除的稀疏特性集合。
///
/// 给定 `Target.Cpu.Arch` 对应的带类型特性可在
/// `@field(Target, @tagName(arch.family()))` 中找到。
///
/// 例如 `std.Target.x86.cpu.x86_64_v3.features` 或 `std.Target.s390x.cpu.z13.features`。
cpu_features_sub: Target.Cpu.Feature.Set = .empty,

/// `null` 表示本机。
os_tag: ?Target.Os.Tag = null,

/// `os_tag` 为本机时,`null` 表示本机版本;否则为
/// `cpu_arch`、`os_tag` 和 `abi` 的默认最低版本。
os_version_min: ?OsVersion = null,

/// `os_tag` 为本机时,`null` 表示本机版本;否则表示已知的最新操作系统版本。
os_version_max: ?OsVersion = null,

/// `abi` 为本机时,`null` 表示本机版本;否则为 `cpu_arch`、
/// `os_tag` 和 `abi` 的默认最低版本。
///
/// `abi` 为 `null` 或 `isGnu()` 为 `false` 时,必须为 `null`。
glibc_version: ?SemanticVersion = null,

/// `abi` 为本机时,`null` 表示本机版本;否则为 `cpu_arch`
/// 和 `abi` 的默认最低版本。
///
/// `abi` 为 `null` 或 `isAndroid()` 为 `false` 时,必须为 `null`。
android_api_level: ?u32 = null,

/// `null` 在 `os_tag` 为本机时表示本机;否则,表示针对 `cpu_arch` 和
/// `os_tag` 尽力选择的默认值。
abi: ?Target.Abi = null,

/// `null` 表示采用 `cpu_arch` 与 `os_tag` 组合的默认值。
ofmt: ?Target.ObjectFormat = null,

/// `abi` 为本机时,`null` 表示本机路径;否则为基于 `cpu_arch`、
/// `os_tag` 和 `abi` 的标准路径。非 `null` 的空字符串表示不使用动态链接器,
/// 无论其他字段的值为何。
dynamic_linker: ?Target.DynamicLinker = null,

pub const CpuModel = union(enum) {
    /// 始终为本机
    native,

    /// 始终为基线
    baseline,

    /// 若 CPU 架构为原生,则 CPU 型号也为原生;否则
    /// 为基线型号。
    determined_by_arch_os,

    explicit: *const Target.Cpu.Model,

    pub fn eql(a: CpuModel, b: CpuModel) bool {
        const Tag = @typeInfo(CpuModel).@"union".tag_type.?;
        const a_tag: Tag = a;
        const b_tag: Tag = b;
        if (a_tag != b_tag) return false;
        return switch (a) {
            .native, .baseline, .determined_by_arch_os => true,
            .explicit => |a_model| a_model == b.explicit,
        };
    }
};

pub const OsVersion = union(enum) {
    none: void,
    semver: SemanticVersion,
    windows: Target.Os.WindowsVersion,

    pub fn eql(a: OsVersion, b: OsVersion) bool {
        const Tag = @typeInfo(OsVersion).@"union".tag_type.?;
        const a_tag: Tag = a;
        const b_tag: Tag = b;
        if (a_tag != b_tag) return false;
        return switch (a) {
            .none => true,
            .semver => |a_semver| a_semver.order(b.semver) == .eq,
            .windows => |a_windows| a_windows == b.windows,
        };
    }

    pub fn eqlOpt(a: ?OsVersion, b: ?OsVersion) bool {
        if (a == null and b == null) return true;
        if (a == null or b == null) return false;
        return OsVersion.eql(a.?, b.?);
    }
};

pub const SemanticVersion = std.SemanticVersion;

pub fn fromTarget(target: *const Target) Query {
    var result: Query = .{
        .cpu_arch = target.cpu.arch,
        .cpu_model = .{ .explicit = target.cpu.model },
        .os_tag = target.os.tag,
        .os_version_min = undefined,
        .os_version_max = undefined,
        .abi = target.abi,
        .glibc_version = if (target.abi.isGnu()) target.os.versionRange().gnuLibCVersion() else null,
        .android_api_level = if (target.abi.isAndroid()) target.os.version_range.linux.android else null,
    };
    result.updateOsVersionRange(target.os);

    const all_features = target.cpu.arch.allFeaturesList();
    var cpu_model_set = target.cpu.model.features;
    cpu_model_set.populateDependencies(all_features);
    {
        // “add”集合是从完整集合中移除 CPU 模型集合后的结果。
        const add_set = &result.cpu_features_add;
        add_set.* = target.cpu.features;
        add_set.removeFeatureSet(cpu_model_set);
    }
    {
        // “sub” 集合包含在 CPU Model 集合中启用、但在完整集合中禁用的特性。
        const sub_set = &result.cpu_features_sub;
        sub_set.* = cpu_model_set;
        sub_set.removeFeatureSet(target.cpu.features);
    }
    return result;
}

fn updateOsVersionRange(self: *Query, os: Target.Os) void {
    self.os_version_min, self.os_version_max = switch (os.tag.versionRangeTag()) {
        .none => .{ .{ .none = {} }, .{ .none = {} } },
        .semver => .{
            .{ .semver = os.version_range.semver.min },
            .{ .semver = os.version_range.semver.max },
        },
        inline .hurd, .linux => |t| .{
            .{ .semver = @field(os.version_range, @tagName(t)).range.min },
            .{ .semver = @field(os.version_range, @tagName(t)).range.max },
        },
        .windows => .{
            .{ .windows = os.version_range.windows.min },
            .{ .windows = os.version_range.windows.max },
        },
    };
}

pub const ParseOptions = struct {
    /// 有时称为“三元组”,大致如下:
    ///     riscv64-linux-musl
    /// 各字段依次为:
    /// * CPU 架构
    /// * 操作系统,以及可选的版本范围
    /// * C ABI,可选,还可指定 glibc 版本或 Android API 级别
    /// CPU 架构和操作系统均可使用字符串 "native"。
    /// 如果 CPU 架构指定为 "native",则可省略操作系统和 C ABI。
    arch_os_abi: []const u8 = "native",

    /// 格式类似“name+a+b-c-d+e”,其中“name”为处理器型号名称,“a”“b”“e”表示要加入集合的处理器特性,“c”“d”表示要从集合中移除的处理器特性。
    /// 处理器型号名称识别以下特殊字符串:
    /// * “baseline”:交叉编译时的默认处理器特性集合,较为保守,预期大多数可用硬件均支持。
    /// * “native”:编译时检测原生处理器型号。
    /// 若未提供此字段,即为 `null`,则其值取决于解析出的处理器架构。若为原生架构,则使用“native”;否则使用“baseline”。
    ///
    ///
    ///
    ///
    cpu_features: ?[]const u8 = null,

    object_format: ?[]const u8 = null,

    /// 动态链接器的绝对路径,用于覆盖默认路径;默认值来自原生检测或标准路径。
    ///
    dynamic_linker: ?[]const u8 = null,

    /// 若提供此项,函数将填充有关解析失败的信息,以便生成易于理解的错误消息。
    ///
    diagnostics: ?*Diagnostics = null,

    pub const Diagnostics = struct {
        /// 如果已确定架构,则填充此值。
        arch: ?Target.Cpu.Arch = null,

        /// 若已确定操作系统名称,则填充此项。
        os_name: ?[]const u8 = null,

        /// 若已确定操作系统标签,则填充此项。
        os_tag: ?Target.Os.Tag = null,

        /// 若已确定 ABI,则填充此项。
        abi: ?Target.Abi = null,

        /// 若已确定 CPU 名称,则填充此字段。
        cpu_name: ?[]const u8 = null,

        /// 如果返回 error.UnknownCpuFeature,则会填充此项。
        unknown_feature_name: ?[]const u8 = null,

        /// 若返回 error.UnknownArchitecture,则填充此项。
        unknown_architecture_name: ?[]const u8 = null,
    };
};

pub fn parse(args: ParseOptions) !Query {
    var dummy_diags: ParseOptions.Diagnostics = undefined;
    const diags = args.diagnostics orelse &dummy_diags;

    var result: Query = .{
        .dynamic_linker = if (args.dynamic_linker) |dynamic_linker| .init(dynamic_linker) else null,
    };

    var it = mem.splitScalar(u8, args.arch_os_abi, '-');
    const arch_name = it.first();
    const arch_is_native = mem.eql(u8, arch_name, "native");
    if (!arch_is_native) {
        result.cpu_arch = std.meta.stringToEnum(Target.Cpu.Arch, arch_name) orelse {
            diags.unknown_architecture_name = arch_name;
            return error.UnknownArchitecture;
        };
    }
    const arch = result.cpu_arch orelse builtin.cpu.arch;
    diags.arch = arch;

    if (it.next()) |os_text| {
        try parseOs(&result, diags, os_text);
    } else if (!arch_is_native) {
        return error.MissingOperatingSystem;
    }

    const opt_abi_text = it.next();
    if (opt_abi_text) |abi_text| {
        var abi_it = mem.splitScalar(u8, abi_text, '.');
        const abi = std.meta.stringToEnum(Target.Abi, abi_it.first()) orelse
            return error.UnknownApplicationBinaryInterface;
        result.abi = abi;
        diags.abi = abi;

        const abi_ver_text = abi_it.rest();
        if (abi_it.next() != null) {
            if (abi.isGnu()) {
                result.glibc_version = parseVersion(abi_ver_text) catch |err| switch (err) {
                    error.Overflow => return error.InvalidAbiVersion,
                    error.InvalidVersion => return error.InvalidAbiVersion,
                };
            } else if (abi.isAndroid()) {
                result.android_api_level = std.fmt.parseUnsigned(u32, abi_ver_text, 10) catch |err| switch (err) {
                    error.InvalidCharacter => return error.InvalidVersion,
                    error.Overflow => |e| return e,
                };
            } else {
                return error.InvalidAbiVersion;
            }
        }
    }

    if (it.next() != null) return error.UnexpectedExtraField;

    if (args.cpu_features) |cpu_features| {
        const all_features = arch.allFeaturesList();
        var index: usize = 0;
        while (index < cpu_features.len and
            cpu_features[index] != '+' and
            cpu_features[index] != '-')
        {
            index += 1;
        }
        const cpu_name = cpu_features[0..index];
        diags.cpu_name = cpu_name;

        const add_set = &result.cpu_features_add;
        const sub_set = &result.cpu_features_sub;
        if (mem.eql(u8, cpu_name, "native")) {
            result.cpu_model = .native;
        } else if (mem.eql(u8, cpu_name, "baseline")) {
            result.cpu_model = .baseline;
        } else {
            result.cpu_model = .{ .explicit = arch.parseCpuModel(cpu_name) orelse return error.UnknownCpuModel };
        }

        while (index < cpu_features.len) {
            const op = cpu_features[index];
            const set = switch (op) {
                '+' => add_set,
                '-' => sub_set,
                else => unreachable,
            };
            index += 1;
            const start = index;
            while (index < cpu_features.len and
                cpu_features[index] != '+' and
                cpu_features[index] != '-')
            {
                index += 1;
            }
            const feature_name = cpu_features[start..index];
            for (all_features, 0..) |feature, feat_index_usize| {
                const feat_index = @as(Target.Cpu.Feature.Set.Index, @intCast(feat_index_usize));
                if (mem.eql(u8, feature_name, feature.name)) {
                    set.addFeature(feat_index);
                    break;
                }
            } else {
                diags.unknown_feature_name = feature_name;
                return error.UnknownCpuFeature;
            }
        }
    }

    if (args.object_format) |ofmt_name| {
        result.ofmt = std.meta.stringToEnum(Target.ObjectFormat, ofmt_name) orelse
            return error.UnknownObjectFormat;
    }

    return result;
}

/// 类似 `parse`,但不完整解析,只判断处理器架构。若能确定,则返回该架构,否则返回 `null`。
/// 适用于 Query 接口使用者需要先得知目标处理器架构,以便完整填充 `ParseOptions` 的情况。
///
///
pub fn parseCpuArch(args: ParseOptions) ?Target.Cpu.Arch {
    var it = mem.splitScalar(u8, args.arch_os_abi, '-');
    const arch_name = it.first();
    const arch_is_native = mem.eql(u8, arch_name, "native");
    if (arch_is_native) {
        return builtin.cpu.arch;
    } else {
        return std.meta.stringToEnum(Target.Cpu.Arch, arch_name);
    }
}

/// 类似 `SemanticVersion.parse`,但有以下区别:
/// * 允许前导零。
/// * 仅支持 2 或 3 个版本分量(主版本、次版本、[修订版本])。若省略第 3 个分量,则为 0。
/// * 不允许预发布分量和构建元数据分量。
pub fn parseVersion(ver: []const u8) error{ InvalidVersion, Overflow }!SemanticVersion {
    const parseVersionComponentFn = (struct {
        fn parseVersionComponentInner(component: []const u8) error{ InvalidVersion, Overflow }!usize {
            return std.fmt.parseUnsigned(usize, component, 10) catch |err| switch (err) {
                error.InvalidCharacter => return error.InvalidVersion,
                error.Overflow => |e| return e,
            };
        }
    }).parseVersionComponentInner;

    var version_components = mem.splitScalar(u8, ver, '.');

    const major = version_components.first();
    const minor = version_components.next() orelse return error.InvalidVersion;
    const patch = version_components.next() orelse "0";
    if (version_components.next() != null) return error.InvalidVersion;

    return .{
        .major = try parseVersionComponentFn(major),
        .minor = try parseVersionComponentFn(minor),
        .patch = try parseVersionComponentFn(patch),
    };
}

test parseVersion {
    try std.testing.expectEqual(SemanticVersion{ .major = 1, .minor = 2, .patch = 0 }, try parseVersion("1.2"));
    try std.testing.expectEqual(SemanticVersion{ .major = 1, .minor = 2, .patch = 3 }, try parseVersion("1.2.3"));

    try std.testing.expectError(error.InvalidVersion, parseVersion("1"));
    try std.testing.expectError(error.InvalidVersion, parseVersion("1.2.3.4"));
    try std.testing.expectError(error.InvalidVersion, parseVersion("1.2.3-dev"));
}

pub fn isNativeCpu(self: Query) bool {
    return self.cpu_arch == null and
        (self.cpu_model == .native or self.cpu_model == .determined_by_arch_os) and
        self.cpu_features_sub.isEmpty() and self.cpu_features_add.isEmpty();
}

pub fn isNativeOs(self: Query) bool {
    return self.os_tag == null and
        self.os_version_min == null and
        self.os_version_max == null;
}

pub fn isNativeAbi(self: Query) bool {
    return self.os_tag == null and
        self.abi == null and
        self.glibc_version == null and
        self.android_api_level == null;
}

pub fn isNativeTriple(self: Query) bool {
    return self.isNativeCpu() and self.isNativeOs() and self.isNativeAbi();
}

pub fn isNative(self: Query) bool {
    return self.isNativeTriple() and
        self.ofmt == null and
        self.dynamic_linker == null;
}

pub fn canDetectLibC(self: Query) bool {
    if (self.isNativeOs() and self.isNativeAbi()) return true;
    if (self.os_tag) |os| {
        if (builtin.os.tag == .macos and os.isDarwin()) return true;
        if (os == .linux) {
            if (self.abi) |abi| if (abi.isAndroid()) return true;
        }
    }
    return false;
}

/// 格式化版本号;补丁部分为零时省略它,
/// 而 SemanticVersion.format 始终格式化全部版本部分。
fn formatVersion(version: SemanticVersion, gpa: Allocator, list: *ArrayList(u8)) !void {
    if (version.patch == 0) {
        try list.print(gpa, "{d}.{d}", .{ version.major, version.minor });
    } else {
        try list.print(gpa, "{d}.{d}.{d}", .{ version.major, version.minor, version.patch });
    }
}

pub fn zigTriple(self: Query, gpa: Allocator) Allocator.Error![]u8 {
    if (self.isNativeTriple()) return gpa.dupe(u8, "native");

    const arch_name = if (self.cpu_arch) |arch| @tagName(arch) else "native";
    const os_name = if (self.os_tag) |os_tag| @tagName(os_tag) else "native";

    var result: ArrayList(u8) = .empty;
    defer result.deinit(gpa);

    try result.print(gpa, "{s}-{s}", .{ arch_name, os_name });

    // zig 目标语法不允许仅指定操作系统最高版本而不指定最低版本,
    // 因此只要指定其中之一,就必须有最低版本。
    if (self.os_version_min) |min| {
        switch (min) {
            .none => {},
            .semver => |v| {
                try result.appendSlice(gpa, ".");
                try formatVersion(v, gpa, &result);
            },
            .windows => |v| {
                try result.print(gpa, "{f}", .{v});
            },
        }
    }
    if (self.os_version_max) |max| {
        switch (max) {
            .none => {},
            .semver => |v| {
                try result.appendSlice(gpa, "...");
                try formatVersion(v, gpa, &result);
            },
            .windows => |v| {
                // 依赖 `WindowsVersion` 上定义的自定义 format() 函数添加前缀“.”,使总共出现三个点。
                //
                try result.print(gpa, "..{f}", .{v});
            },
        }
    }

    if (self.glibc_version) |v| {
        const name = @tagName(self.abi.?);
        try result.ensureUnusedCapacity(gpa, name.len + 2);
        result.appendAssumeCapacity('-');
        result.appendSliceAssumeCapacity(name);
        result.appendAssumeCapacity('.');
        try formatVersion(v, gpa, &result);
    } else if (self.android_api_level) |lvl| {
        const name = @tagName(self.abi.?);
        try result.ensureUnusedCapacity(gpa, name.len + 2);
        result.appendAssumeCapacity('-');
        result.appendSliceAssumeCapacity(name);
        result.appendAssumeCapacity('.');
        try result.print(gpa, "{d}", .{lvl});
    } else if (self.abi) |abi| {
        const name = @tagName(abi);
        try result.ensureUnusedCapacity(gpa, name.len + 1);
        result.appendAssumeCapacity('-');
        result.appendSliceAssumeCapacity(name);
    }

    return result.toOwnedSlice(gpa);
}

/// 将查询渲染为文本表示,可由传给 Zig 编译器的
/// `-mcpu` 标志解析。
/// 将结果追加到 `buffer`。
pub fn serializeCpu(q: Query, buffer: *std.array_list.Managed(u8)) Allocator.Error!void {
    try buffer.ensureUnusedCapacity(8);
    switch (q.cpu_model) {
        .native => {
            buffer.appendSliceAssumeCapacity("native");
        },
        .baseline => {
            buffer.appendSliceAssumeCapacity("baseline");
        },
        .determined_by_arch_os => {
            if (q.cpu_arch == null) {
                buffer.appendSliceAssumeCapacity("native");
            } else {
                buffer.appendSliceAssumeCapacity("baseline");
            }
        },
        .explicit => |model| {
            try buffer.appendSlice(model.name);
        },
    }

    if (q.cpu_features_add.isEmpty() and q.cpu_features_sub.isEmpty()) {
        // CPU 名称本身已足够。
        return;
    }

    const cpu_arch = q.cpu_arch orelse builtin.cpu.arch;
    const all_features = cpu_arch.allFeaturesList();

    for (all_features, 0..) |feature, i_usize| {
        const i: Target.Cpu.Feature.Set.Index = @intCast(i_usize);
        try buffer.ensureUnusedCapacity(feature.name.len + 1);
        if (q.cpu_features_sub.isEnabled(i)) {
            buffer.appendAssumeCapacity('-');
            buffer.appendSliceAssumeCapacity(feature.name);
        } else if (q.cpu_features_add.isEnabled(i)) {
            buffer.appendAssumeCapacity('+');
            buffer.appendSliceAssumeCapacity(feature.name);
        }
    }
}

pub fn serializeCpuAlloc(q: Query, ally: Allocator) Allocator.Error![]u8 {
    var buffer = std.array_list.Managed(u8).init(ally);
    try serializeCpu(q, &buffer);
    return buffer.toOwnedSlice();
}

/// 已弃用;请改用 `zigTriple`。将在 0.18.0 中移除。
pub fn allocDescription(self: Query, allocator: Allocator) ![]u8 {
    return self.zigTriple(allocator);
}

/// 已弃用;请直接设置 `glibc_version`。将在 0.18.0 中移除。
pub fn setGnuLibCVersion(self: *Query, major: u32, minor: u32, patch: u32) void {
    self.glibc_version = SemanticVersion{ .major = major, .minor = minor, .patch = patch };
}

fn parseOs(result: *Query, diags: *ParseOptions.Diagnostics, text: []const u8) !void {
    var it = mem.splitScalar(u8, text, '.');
    const os_name = it.first();
    diags.os_name = os_name;
    const os_is_native = mem.eql(u8, os_name, "native");
    if (!os_is_native) {
        result.os_tag = std.meta.stringToEnum(Target.Os.Tag, os_name) orelse
            return error.UnknownOperatingSystem;
    }
    const tag = result.os_tag orelse builtin.os.tag;
    diags.os_tag = tag;

    const version_text = it.rest();
    if (version_text.len > 0) switch (tag.versionRangeTag()) {
        .none => return error.InvalidOperatingSystemVersion,
        .semver, .hurd, .linux => {
            var range_it = mem.splitSequence(u8, version_text, "...");
            result.os_version_min = .{
                .semver = parseVersion(range_it.first()) catch |err| switch (err) {
                    error.Overflow => return error.InvalidOperatingSystemVersion,
                    error.InvalidVersion => return error.InvalidOperatingSystemVersion,
                },
            };
            if (range_it.next()) |v| {
                result.os_version_max = .{
                    .semver = parseVersion(v) catch |err| switch (err) {
                        error.Overflow => return error.InvalidOperatingSystemVersion,
                        error.InvalidVersion => return error.InvalidOperatingSystemVersion,
                    },
                };
            }
        },
        .windows => {
            var range_it = mem.splitSequence(u8, version_text, "...");
            result.os_version_min = .{
                .windows = try Target.Os.WindowsVersion.parse(range_it.first()),
            };
            if (range_it.next()) |v| {
                result.os_version_max = .{
                    .windows = try Target.Os.WindowsVersion.parse(v),
                };
            }
        },
    };
}

pub fn eql(a: Query, b: Query) bool {
    if (a.cpu_arch != b.cpu_arch) return false;
    if (!a.cpu_model.eql(b.cpu_model)) return false;
    if (!a.cpu_features_add.eql(b.cpu_features_add)) return false;
    if (!a.cpu_features_sub.eql(b.cpu_features_sub)) return false;
    if (a.os_tag != b.os_tag) return false;
    if (!OsVersion.eqlOpt(a.os_version_min, b.os_version_min)) return false;
    if (!OsVersion.eqlOpt(a.os_version_max, b.os_version_max)) return false;
    if (!versionEqualOpt(a.glibc_version, b.glibc_version)) return false;
    if (a.android_api_level != b.android_api_level) return false;
    if (a.abi != b.abi) return false;
    if (a.ofmt != b.ofmt) return false;
    if (!dynamicLinkerEqualOpt(a.dynamic_linker, b.dynamic_linker)) return false;

    return true;
}

fn versionEqualOpt(a: ?SemanticVersion, b: ?SemanticVersion) bool {
    if (a == null and b == null) return true;
    if (a == null or b == null) return false;
    return SemanticVersion.order(a.?, b.?) == .eq;
}

fn dynamicLinkerEqualOpt(a: ?Target.DynamicLinker, b: ?Target.DynamicLinker) bool {
    if (a == null and b == null) return true;
    if (a == null or b == null) return false;
    return a.?.eql(b.?);
}

test parse {
    const io = std.testing.io;

    {
        const query = try Query.parse(.{
            .arch_os_abi = "aarch64-linux",
            .cpu_features = "native",
        });

        try std.testing.expect(query.cpu_arch.? == .aarch64);
        try std.testing.expect(query.cpu_model == .native);
    }
    {
        const query = try Query.parse(.{ .arch_os_abi = "native" });

        try std.testing.expect(query.cpu_arch == null);
        try std.testing.expect(query.isNative());

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "native", text);
    }
    {
        const query = try Query.parse(.{
            .arch_os_abi = "x86_64-linux-gnu",
            .cpu_features = "x86_64-sse-sse2-avx-cx8",
        });
        const target = try std.zig.system.resolveTargetQuery(io, query);

        try std.testing.expect(target.os.tag == .linux);
        try std.testing.expect(target.abi == .gnu);
        try std.testing.expect(target.cpu.arch == .x86_64);
        try std.testing.expect(!target.cpu.has(.x86, .sse));
        try std.testing.expect(!target.cpu.has(.x86, .avx));
        try std.testing.expect(!target.cpu.has(.x86, .cx8));
        try std.testing.expect(target.cpu.has(.x86, .cmov));
        try std.testing.expect(target.cpu.has(.x86, .fxsr));

        try std.testing.expect(target.cpu.hasAny(.x86, &.{ .sse, .avx, .cmov }));
        try std.testing.expect(!target.cpu.hasAny(.x86, &.{ .sse, .avx }));
        try std.testing.expect(target.cpu.hasAll(.x86, &.{ .mmx, .x87 }));
        try std.testing.expect(!target.cpu.hasAll(.x86, &.{ .mmx, .x87, .sse }));

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "x86_64-linux-gnu", text);
    }
    {
        const query = try Query.parse(.{
            .arch_os_abi = "arm-linux-musleabihf",
            .cpu_features = "generic+v8a",
        });
        const target = try std.zig.system.resolveTargetQuery(io, query);

        try std.testing.expect(target.os.tag == .linux);
        try std.testing.expect(target.abi == .musleabihf);
        try std.testing.expect(target.cpu.arch == .arm);
        try std.testing.expect(target.cpu.model == &Target.arm.cpu.generic);
        try std.testing.expect(target.cpu.has(.arm, .v8a));

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "arm-linux-musleabihf", text);
    }
    {
        const query = try Query.parse(.{
            .arch_os_abi = "aarch64-linux.3.10...4.4.1-gnu.2.27",
            .cpu_features = "generic+v8a",
        });
        const target = try std.zig.system.resolveTargetQuery(io, query);

        try std.testing.expect(target.cpu.arch == .aarch64);
        try std.testing.expect(target.os.tag == .linux);
        try std.testing.expect(target.os.version_range.linux.range.min.major == 3);
        try std.testing.expect(target.os.version_range.linux.range.min.minor == 10);
        try std.testing.expect(target.os.version_range.linux.range.min.patch == 0);
        try std.testing.expect(target.os.version_range.linux.range.max.major == 4);
        try std.testing.expect(target.os.version_range.linux.range.max.minor == 4);
        try std.testing.expect(target.os.version_range.linux.range.max.patch == 1);
        try std.testing.expect(target.os.version_range.linux.glibc.major == 2);
        try std.testing.expect(target.os.version_range.linux.glibc.minor == 27);
        try std.testing.expect(target.os.version_range.linux.glibc.patch == 0);
        try std.testing.expect(target.abi == .gnu);

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "aarch64-linux.3.10...4.4.1-gnu.2.27", text);
    }
    {
        const query = try Query.parse(.{
            .arch_os_abi = "aarch64-linux.3.10...4.4.1-android.30",
        });
        const target = try std.zig.system.resolveTargetQuery(io, query);

        try std.testing.expect(target.cpu.arch == .aarch64);
        try std.testing.expect(target.os.tag == .linux);
        try std.testing.expect(target.os.version_range.linux.range.min.major == 3);
        try std.testing.expect(target.os.version_range.linux.range.min.minor == 10);
        try std.testing.expect(target.os.version_range.linux.range.min.patch == 0);
        try std.testing.expect(target.os.version_range.linux.range.max.major == 4);
        try std.testing.expect(target.os.version_range.linux.range.max.minor == 4);
        try std.testing.expect(target.os.version_range.linux.range.max.patch == 1);
        try std.testing.expect(target.os.version_range.linux.android == 30);
        try std.testing.expect(target.abi == .android);

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "aarch64-linux.3.10...4.4.1-android.30", text);
    }
    {
        const query = try Query.parse(.{
            .arch_os_abi = "x86-windows.xp...win8-msvc",
        });
        const target = try std.zig.system.resolveTargetQuery(io, query);

        try std.testing.expect(target.cpu.arch == .x86);
        try std.testing.expect(target.os.tag == .windows);
        try std.testing.expect(target.os.version_range.windows.min == .xp);
        try std.testing.expect(target.os.version_range.windows.max == .win8);
        try std.testing.expect(target.abi == .msvc);

        const text = try query.zigTriple(std.testing.allocator);
        defer std.testing.allocator.free(text);
        try std.testing.expectEqualSlices(u8, "x86-windows.xp...win8-msvc", text);
    }
}