Hướng dẫn về Bazel: Định cấu hình chuỗi công cụ C++

Báo cáo vấn đề Xem nguồn Hằng đêm · 7,3 · 7,2 · 7.1 · 7 · 6,5

Hướng dẫn này sử dụng một tình huống mẫu để mô tả cách định cấu hình C++ cho một dự án.

Kiến thức bạn sẽ học được

Trong hướng dẫn này, bạn sẽ tìm hiểu cách:

  • Thiết lập môi trường tạo bản dựng
  • Sử dụng --toolchain_resolution_debug để gỡ lỗi quá trình phân giải chuỗi công cụ
  • Định cấu hình chuỗi công cụ C++
  • Tạo một quy tắc Starlark cung cấp thêm cấu hình cho cc_toolchain để Bazel có thể tạo ứng dụng với clang
  • Tạo tệp nhị phân C++ bằng cách chạy bazel build //main:hello-world trên máy Linux
  • Biên dịch chéo tệp nhị phân cho Android bằng cách chạy bazel build //main:hello-world --platforms=//:android_x86_64

Trước khi bắt đầu

Hướng dẫn này giả định bạn đang sử dụng Linux và đã tạo thành công C++ và đã cài đặt công cụ cũng như thư viện thích hợp. Hướng dẫn này sử dụng clang version 16 mà bạn có thể cài đặt trên hệ thống của mình.

Thiết lập môi trường tạo bản dựng

Thiết lập môi trường tạo bản dựng như sau:

  1. Nếu chưa thực hiện, tải xuống và cài đặt Bazel 7.0.2 trở lên.

  2. Thêm một tệp WORKSPACE trống ở thư mục gốc.

  3. Thêm mục tiêu cc_binary sau đây vào tệp main/BUILD:

    load("@rules_cc//cc:defs.bzl", "cc_binary")

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
)

    Vì Bazel sử dụng nhiều công cụ nội bộ được viết bằng C++ trong quá trình tạo bản dựng, chẳng hạn như là process-wrapper, chuỗi công cụ C++ mặc định có sẵn sẽ được chỉ định cho nền tảng lưu trữ. Nhờ vậy, các công cụ nội bộ này có thể xây dựng bằng cách sử dụng của chuỗi công cụ được tạo trong hướng dẫn này. Do đó, mục tiêu cc_binary cũng được tạo bằng chuỗi công cụ mặc định.

  4. Chạy bản dựng bằng lệnh sau:

    bazel build //main:hello-world

    Bản dựng này thành công mà không cần bất kỳ chuỗi công cụ nào được đăng ký trong WORKSPACE.

    Để xem thêm tính năng nâng cao, hãy chạy:

    bazel build //main:hello-world --toolchain_resolution_debug='@bazel_tools//tools/cpp:toolchain_type'

INFO: ToolchainResolution: Target platform @@local_config_platform//:host: Selected execution platform @@local_config_platform//:host, type @@bazel_tools//tools/cpp:toolchain_type -> toolchain @@bazel_tools+cc_configure_extension+local_config_cc//:cc-compiler-k8

    Nếu không chỉ định --platforms, Bazel sẽ tạo mục tiêu cho @local_config_platform//:host đang sử dụng @bazel_tools//cc_configure_extension/local_config_cc//:cc-compiler-k8

Định cấu hình chuỗi công cụ C++

Để định cấu hình chuỗi công cụ C++, hãy liên tục tạo ứng dụng và loại bỏ từng lỗi một như được mô tả như sau.

Hàm này cũng giả định clang version 9.0.1, mặc dù thông tin chi tiết chỉ thay đổi một chút giữa các phiên bản clang khác nhau.

  1. Thêm toolchain/BUILD bằng

    filegroup(name = "empty")

cc_toolchain(
    name = "linux_x86_64_toolchain",
    toolchain_identifier = "linux_x86_64-toolchain",
    toolchain_config = ":linux_x86_64_toolchain_config",
    all_files = ":empty",
    compiler_files = ":empty",
    dwp_files = ":empty",
    linker_files = ":empty",
    objcopy_files = ":empty",
    strip_files = ":empty",
    supports_param_files = 0,
)

toolchain(
    name = "cc_toolchain_for_linux_x86_64",
    toolchain = ":linux_x86_64_toolchain",
    toolchain_type = "@bazel_tools//tools/cpp:toolchain_type",
    exec_compatible_with = [
        "@platforms//cpu:x86_64",
        "@platforms//os:linux",
    ],
    target_compatible_with = [
        "@platforms//cpu:x86_64",
        "@platforms//os:linux",
    ],
)

    Sau đó, đăng ký chuỗi công cụ với WORKSPACE với

    register_toolchains(
    "//toolchain:cc_toolchain_for_linux_x86_64"
)

    Bước này xác định một cc_toolchain và liên kết nó với một toolchain đích cho cấu hình máy chủ lưu trữ.

  2. Chạy lại bản dựng. Vì gói toolchain chưa xác định linux_x86_64_toolchain_config mục tiêu, Bazel sẽ đưa ra lỗi sau:

    ERROR: toolchain/BUILD:4:13: in toolchain_config attribute of cc_toolchain rule //toolchain:linux_x86_64_toolchain: rule '//toolchain:linux_x86_64_toolchain_config' does not exist.

  3. Trong tệp toolchain/BUILD, hãy xác định một nhóm tệp trống như sau:

    package(default_visibility = ["//visibility:public"])

filegroup(name = "linux_x86_64_toolchain_config")

  4. Chạy lại bản dựng. Bazel đưa ra lỗi sau:

    '//toolchain:linux_x86_64_toolchain_config' does not have mandatory providers: 'CcToolchainConfigInfo'.

    CcToolchainConfigInfo là một trình cung cấp mà bạn dùng để định cấu hình chuỗi công cụ C++ của bạn. Để khắc phục lỗi này, hãy tạo một quy tắc Starlark cung cấp CcToolchainConfigInfo cho Bazel bằng cách tạo ra Tệp toolchain/cc_toolchain_config.bzl có nội dung sau:

    def _impl(ctx):
    return cc_common.create_cc_toolchain_config_info(
        ctx = ctx,
        toolchain_identifier = "k8-toolchain",
        host_system_name = "local",
        target_system_name = "local",
        target_cpu = "k8",
        target_libc = "unknown",
        compiler = "clang",
        abi_version = "unknown",
        abi_libc_version = "unknown",
    )

cc_toolchain_config = rule(
    implementation = _impl,
    attrs = {},
    provides = [CcToolchainConfigInfo],
)

    cc_common.create_cc_toolchain_config_info() tạo trình cung cấp cần thiết CcToolchainConfigInfo. Để sử dụng quy tắc cc_toolchain_config, hãy thêm một tải cho toolchain/BUILD ngay bên dưới câu lệnh của gói:

    load(":cc_toolchain_config.bzl", "cc_toolchain_config")

    Và thay thế "linux_x86_64_toolchain_config" nhóm tệp có một phần khai báo của quy tắc cc_toolchain_config:

    cc_toolchain_config(name = "linux_x86_64_toolchain_config")

  5. Chạy lại bản dựng. Bazel đưa ra lỗi sau:

    .../BUILD:1:1: C++ compilation of rule '//:hello-world' failed (Exit 1)
src/main/tools/linux-sandbox-pid1.cc:421:
"execvp(toolchain/DUMMY_GCC_TOOL, 0x11f20e0)": No such file or directory
Target //:hello-world failed to build`

    Tại thời điểm này, Bazel đã có đủ thông tin để thử tạo mã, nhưng vẫn không biết nên dùng công cụ nào để hoàn thành bản dựng theo yêu cầu hành động. Bạn sẽ sửa đổi quy trình triển khai quy tắc Starlark để cho Bazel biết những gì để sử dụng. Để làm được điều đó, bạn cần hàm khởi tạo tool_path() từ @bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl:

    # toolchain/cc_toolchain_config.bzl:
# NEW
load("@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl", "tool_path")

def _impl(ctx):
    tool_paths = [ # NEW
        tool_path(
            name = "gcc",
            path = "/usr/bin/clang",
        ),
        tool_path(
            name = "ld",
            path = "/usr/bin/ld",
        ),
        tool_path(
            name = "ar",
            path = "/usr/bin/ar",
        ),
        tool_path(
            name = "cpp",
            path = "/bin/false",
        ),
        tool_path(
            name = "gcov",
            path = "/bin/false",
        ),
        tool_path(
            name = "nm",
            path = "/bin/false",
        ),
        tool_path(
            name = "objdump",
            path = "/bin/false",
        ),
        tool_path(
            name = "strip",
            path = "/bin/false",
        ),
    ]

    return cc_common.create_cc_toolchain_config_info(
        ctx = ctx,
        toolchain_identifier = "local",
        host_system_name = "local",
        target_system_name = "local",
        target_cpu = "k8",
        target_libc = "unknown",
        compiler = "clang",
        abi_version = "unknown",
        abi_libc_version = "unknown",
        tool_paths = tool_paths, # NEW
    )

    Đảm bảo rằng /usr/bin/clang và /usr/bin/ld là các đường dẫn chính xác cho hệ thống của bạn.

  6. Chạy lại bản dựng. Bazel đưa ra lỗi sau:

    ERROR: main/BUILD:3:10: Compiling main/hello-world.cc failed: absolute path inclusion(s) found in rule '//main:hello-world':
the source file 'main/hello-world.cc' includes the following non-builtin files with absolute paths (if these are builtin files, make sure these paths are in your toolchain):
  '/usr/include/c++/13/ctime'
  '/usr/include/x86_64-linux-gnu/c++/13/bits/c++config.h'
  '/usr/include/x86_64-linux-gnu/c++/13/bits/os_defines.h'
  ...

    Bazel cần biết nơi tìm kiếm các tiêu đề đi kèm. Có nhiều cách để giải quyết vấn đề này, chẳng hạn như sử dụng thuộc tính includes của cc_binary, nhưng ở đây, vấn đề này được giải quyết ở cấp chuỗi công cụ với cxx_builtin_include_directories tham số của cc_common.create_cc_toolchain_config_info. Xin lưu ý rằng nếu bạn đang sử dụng một phiên bản khác của clang, đường dẫn bao gồm sẽ là khác. Các đường dẫn này cũng có thể khác nhau tuỳ thuộc vào cách thức phân phối.

    Sửa đổi giá trị trả về trong toolchain/cc_toolchain_config.bzl để xem như sau:

    return cc_common.create_cc_toolchain_config_info(
    ctx = ctx,
    cxx_builtin_include_directories = [ # NEW
        "/usr/lib/llvm-16/lib/clang/16/include",
        "/usr/include",
    ],
    toolchain_identifier = "local",
    host_system_name = "local",
    target_system_name = "local",
    target_cpu = "k8",
    target_libc = "unknown",
    compiler = "clang",
    abi_version = "unknown",
    abi_libc_version = "unknown",
    tool_paths = tool_paths,
)

  7. Chạy lại lệnh bản dựng, bạn sẽ thấy một lỗi như:

    /usr/bin/ld: bazel-out/k8-fastbuild/bin/main/_objs/hello-world/hello-world.o: in function `print_localtime()':
hello-world.cc:(.text+0x68): undefined reference to `std::cout'

    Nguyên nhân là do trình liên kết thiếu tiêu chuẩn C++ thư viện và không thể tìm thấy các ký hiệu của thư viện đó. Có nhiều cách để giải quyết vấn đề này, chẳng hạn như sử dụng thuộc tính linkopts của cc_binary. Ở đây, vấn đề được giải quyết bằng cách giúp đảm bảo mọi mục tiêu sử dụng chuỗi công cụ đều không phải chỉ định cờ này.

    Sao chép mã nguồn sau đây vào toolchain/cc_toolchain_config.bzl:

    # NEW
load("@bazel_tools//tools/build_defs/cc:action_names.bzl", "ACTION_NAMES")
# NEW
load(
    "@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl",
    "feature",    # NEW
    "flag_group", # NEW
    "flag_set",   # NEW
    "tool_path",
)

all_link_actions = [ # NEW
    ACTION_NAMES.cpp_link_executable,
    ACTION_NAMES.cpp_link_dynamic_library,
    ACTION_NAMES.cpp_link_nodeps_dynamic_library,
]

def _impl(ctx):
    tool_paths = [
        tool_path(
            name = "gcc",
            path = "/usr/bin/clang",
        ),
        tool_path(
            name = "ld",
            path = "/usr/bin/ld",
        ),
        tool_path(
            name = "ar",
            path = "/bin/false",
        ),
        tool_path(
            name = "cpp",
            path = "/bin/false",
        ),
        tool_path(
            name = "gcov",
            path = "/bin/false",
        ),
        tool_path(
            name = "nm",
            path = "/bin/false",
        ),
        tool_path(
            name = "objdump",
            path = "/bin/false",
        ),
        tool_path(
            name = "strip",
            path = "/bin/false",
        ),
    ]

    features = [ # NEW
        feature(
            name = "default_linker_flags",
            enabled = True,
            flag_sets = [
                flag_set(
                    actions = all_link_actions,
                    flag_groups = ([
                        flag_group(
                            flags = [
                                "-lstdc++",
                            ],
                        ),
                    ]),
                ),
            ],
        ),
    ]

    return cc_common.create_cc_toolchain_config_info(
        ctx = ctx,
        features = features, # NEW
        cxx_builtin_include_directories = [
            "/usr/lib/llvm-9/lib/clang/9.0.1/include",
            "/usr/include",
        ],
        toolchain_identifier = "local",
        host_system_name = "local",
        target_system_name = "local",
        target_cpu = "k8",
        target_libc = "unknown",
        compiler = "clang",
        abi_version = "unknown",
        abi_libc_version = "unknown",
        tool_paths = tool_paths,
    )

cc_toolchain_config = rule(
    implementation = _impl,
    attrs = {},
    provides = [CcToolchainConfigInfo],
)

  8. Đang chạy bazel build //main:hello-world, cuối cùng tệp nhị phân sẽ được tạo thành công cho máy chủ lưu trữ.

  9. Trong toolchain/BUILD, hãy sao chép cc_toolchain_config, cc_toolchain và Nhắm mục tiêu toolchain và thay thế linux_x86_64 bằng android_x86_64trong mục tiêu tên.

    Trong WORKSPACE, hãy đăng ký chuỗi công cụ cho Android

    register_toolchains(
    "//toolchain:cc_toolchain_for_linux_x86_64",
    "//toolchain:cc_toolchain_for_android_x86_64"
)

  10. Chạy bazel build //main:hello-world --android_platforms=//toolchain:android_x86_64 để tạo tệp nhị phân cho Android.

Trong thực tế, Linux và Android nên có các cấu hình chuỗi công cụ C++ khác nhau. Bạn có thể sửa đổi cc_toolchain_config hiện tại cho phù hợp với sự khác biệt hoặc tạo một quy tắc riêng (tức là nhà cung cấp CcToolchainConfigInfo) cho nền tảng.

Xem lại bài tập của bạn

Trong hướng dẫn này, bạn đã tìm hiểu cách định cấu hình chuỗi công cụ C++ cơ bản, nhưng chuỗi công cụ mạnh mẽ hơn ví dụ đơn giản này.

Những điểm chính cần ghi nhớ là:

  • Bạn cần chỉ định một cờ platforms trùng khớp trong dòng lệnh để Bazel phân giải cho chuỗi công cụ cho các giá trị ràng buộc tương tự trên nền tảng. Tài liệu này cung cấp thêm thông tin về cờ cấu hình dành riêng cho từng ngôn ngữ.
  • Bạn phải cho chuỗi công cụ biết vị trí của các công cụ. Nội dung của hướng dẫn này có một phiên bản đơn giản giúp bạn truy cập vào các công cụ từ hệ thống. Nếu bạn quan tâm đến một cách tiếp cận độc lập hơn, bạn có thể đọc về không gian làm việc. Công cụ của bạn có thể đến từ không gian làm việc khác nhau và bạn sẽ phải cung cấp các tệp của họ vào cc_toolchain với các phần phụ thuộc mục tiêu trên các thuộc tính, chẳng hạn như compiler_files. Bạn cũng cần thay đổi tool_paths.
  • Bạn có thể tạo các tính năng để tuỳ chỉnh những cờ sẽ được truyền đến các hành động khác nhau, có thể là liên kết hoặc bất kỳ loại hành động nào khác.

Tài liệu đọc thêm

Để biết thêm thông tin, hãy xem Cấu hình chuỗi công cụ C++