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

Tổng quan

Để gọi trình biên dịch bằng các lựa chọn phù hợp, Bazel cần có một số kiến thức về nội bộ trình biên dịch, chẳng hạn như các cờ quan trọng và thư mục bao gồm. Nói cách khác, Bazel cần một mô hình đơn giản của trình biên dịch để hiểu cách hoạt động của trình biên dịch.

Bazel cần biết những thông tin sau:

• Trình biên dịch có hỗ trợ thinLTO, các mô-đun, liên kết động hoặc PIC (mã độc lập với vị trí) hay không.
• Đường dẫn đến các công cụ bắt buộc như gcc, ld, ar, objcopy, v.v.
• Hệ thống tích hợp bao gồm các thư mục. Bazel cần những thông tin này để xác thực rằng tất cả các tiêu đề có trong tệp nguồn đều được khai báo đúng cách trong tệp BUILD.
• Sysroot mặc định.
• Cần sử dụng cờ nào để biên dịch, liên kết, lưu trữ.
• Những cờ cần dùng cho các chế độ biên dịch được hỗ trợ (opt, dbg, fastbuild).
• Tạo các biến mà trình biên dịch yêu cầu cụ thể.

Nếu trình biên dịch hỗ trợ nhiều cấu trúc, Bazel cần định cấu hình riêng các cấu trúc đó.

CcToolchainConfigInfo là một trình cung cấp cung cấp mức độ chi tiết cần thiết để định cấu hình hành vi của các quy tắc C++ của Bazel. Theo mặc định, Bazel sẽ tự động định cấu hình CcToolchainConfigInfo cho bản dựng của bạn, nhưng bạn có thể định cấu hình theo cách thủ công. Để làm việc đó, bạn cần có một quy tắc Starlark cung cấp CcToolchainConfigInfo và bạn cần trỏ thuộc tính toolchain_config của cc_toolchain đến quy tắc của bạn. Bạn có thể tạo CcToolchainConfigInfo bằng cách gọi cc_common.create_cc_toolchain_config_info(). Bạn có thể tìm thấy hàm khởi tạo Starlark cho tất cả các cấu trúc mà bạn sẽ cần trong quy trình này trong @rules_cc//cc:cc_toolchain_config_lib.bzl.

Khi một mục tiêu C++ bước vào giai đoạn phân tích, Bazel sẽ chọn mục tiêu cc_toolchain thích hợp dựa trên tệp BUILD và lấy trình cung cấp CcToolchainConfigInfo từ mục tiêu được chỉ định trong thuộc tính cc_toolchain.toolchain_config. Mục tiêu cc_toolchain sẽ truyền thông tin này đến mục tiêu C++ thông qua CcToolchainProvider.

Ví dụ: một thao tác biên dịch hoặc liên kết, được khởi tạo theo một quy tắc như cc_binary hoặc cc_library, cần có những thông tin sau:

• Trình biên dịch hoặc trình liên kết để sử dụng
• Cờ hiệu dòng lệnh cho trình biên dịch/trình liên kết
• Cờ cấu hình được truyền qua các tuỳ chọn --copt/--linkopt
• Biến môi trường
• Các cấu phần phần mềm cần thiết trong hộp cát mà thao tác sẽ thực thi

Tất cả thông tin trên (ngoại trừ các cấu phần phần mềm bắt buộc trong hộp cát) đều được chỉ định trong mục tiêu Starlark mà cc_toolchain trỏ đến.

Các cấu phần phần mềm sẽ được chuyển đến hộp cát được khai báo trong mục tiêu cc_toolchain. Ví dụ: với thuộc tính cc_toolchain.linker_files, bạn có thể chỉ định các thư viện nhị phân và chuỗi công cụ của trình liên kết để chuyển vào hộp cát.

Lựa chọn chuỗi công cụ

Logic lựa chọn chuỗi công cụ hoạt động như sau:

1. Người dùng chỉ định một mục tiêu cc_toolchain_suite trong tệp BUILD và chỉ Bazel đến mục tiêu đó bằng cách sử dụng lựa chọn --crosstool_top.

2. Mục tiêu cc_toolchain_suite tham chiếu đến nhiều chuỗi công cụ. Các giá trị của cờ --cpu và --compiler xác định chuỗi công cụ nào trong số đó được chọn, chỉ dựa trên giá trị cờ --cpu hoặc dựa trên giá trị --cpu | --compiler chung. Quy trình lựa chọn như sau:

   • Nếu bạn chỉ định lựa chọn --compiler, Bazel sẽ chọn mục nhập tương ứng từ thuộc tính cc_toolchain_suite.toolchains bằng --cpu | --compiler. Nếu không tìm thấy mục nhập tương ứng, Bazel sẽ báo lỗi.

   • Nếu bạn không chỉ định lựa chọn --compiler, Bazel sẽ chọn mục nhập tương ứng trong thuộc tính cc_toolchain_suite.toolchains chỉ có --cpu.

   • Nếu bạn không chỉ định cờ nào, Bazel sẽ kiểm tra hệ thống máy chủ và chọn giá trị --cpu dựa trên kết quả tìm được. Xem mã cơ chế kiểm tra.

Sau khi bạn chọn một chuỗi công cụ, các đối tượng feature và action_config tương ứng trong quy tắc Starlark sẽ chi phối cấu hình của bản dựng (tức là các mục được mô tả sau). Những thông báo này cho phép triển khai các tính năng C++ đầy đủ trong Bazel mà không cần sửa đổi tệp nhị phân Bazel. Các quy tắc C++ hỗ trợ nhiều thao tác duy nhất được ghi lại chi tiết trong mã nguồn Bazel.

Tính năng

Tính năng là một thực thể yêu cầu các cờ dòng lệnh, hành động, các ràng buộc đối với môi trường thực thi hoặc các thay đổi về phần phụ thuộc. Một tính năng có thể đơn giản như cho phép các tệp BUILD chọn cấu hình cờ, chẳng hạn như treat_warnings_as_errors, hoặc tương tác với các quy tắc C++ và bao gồm các thao tác biên dịch cũng như dữ liệu đầu vào mới cho quá trình biên dịch, chẳng hạn như header_modules hoặc thin_lto.

Lý tưởng nhất là CcToolchainConfigInfo chứa một danh sách các tính năng, trong đó mỗi tính năng bao gồm một hoặc nhiều nhóm cờ, mỗi nhóm xác định một danh sách các cờ áp dụng cho các thao tác cụ thể của Bazel.

Một tính năng được chỉ định theo tên, cho phép tách hoàn toàn cấu hình quy tắc Starlark khỏi các bản phát hành Bazel. Nói cách khác, bản phát hành Bazel không ảnh hưởng đến hành vi của các cấu hình CcToolchainConfigInfo miễn là các cấu hình đó không yêu cầu sử dụng các tính năng mới.

Bạn có thể bật một tính năng theo một trong những cách sau:

• Trường enabled của tính năng được đặt thành true.
• Bazel hoặc chủ sở hữu quy tắc bật tính năng này một cách rõ ràng.
• Người dùng bật chế độ này thông qua lựa chọn --feature Bazel hoặc thuộc tính quy tắc features.

Các tính năng có thể có sự phụ thuộc lẫn nhau, phụ thuộc vào cờ dòng lệnh, chế độ cài đặt tệp BUILD và các biến khác.

Mối quan hệ giữa các đối tượng

Các phần phụ thuộc thường được quản lý trực tiếp bằng Bazel, chỉ đơn giản là thực thi các yêu cầu và quản lý các xung đột vốn có trong bản chất của các tính năng được xác định trong bản dựng. Quy cách chuỗi công cụ cho phép các ràng buộc chi tiết hơn để sử dụng trực tiếp trong quy tắc Starlark chi phối việc hỗ trợ và mở rộng tính năng. Đó là:

requires = [
   feature_set (features = [
       'feature-name-1',
       'feature-name-2'
   ]),
]

implies = ['feature']

provides = ['feature']

with_features = [
  with_feature_set(
    features = ['feature-1'],
    not_features = ['feature-2'],
  ),
]

Thao tác

Các thao tác mang đến sự linh hoạt để sửa đổi các trường hợp mà một thao tác thực thi mà không giả định cách thao tác sẽ chạy. action_config chỉ định tệp nhị phân của công cụ mà một thao tác gọi, trong khi feature chỉ định cấu hình (cờ) xác định cách công cụ đó hoạt động khi thao tác được gọi.

Tính năng tham chiếu các thao tác để báo hiệu những thao tác Bazel mà chúng ảnh hưởng vì các thao tác có thể sửa đổi biểu đồ thao tác Bazel. Trình cung cấp CcToolchainConfigInfo chứa các thao tác có cờ và công cụ được liên kết với các thao tác đó, chẳng hạn như c++-compile. Cờ được chỉ định cho từng thao tác bằng cách liên kết các thao tác đó với một tính năng.

Mỗi tên hành động đại diện cho một loại hành động duy nhất mà Bazel thực hiện, chẳng hạn như biên dịch hoặc liên kết. Tuy nhiên, có mối quan hệ nhiều-một giữa các hành động và các loại hành động Bazel, trong đó loại hành động Bazel đề cập đến một lớp Java triển khai một hành động (chẳng hạn như CppCompileAction). Cụ thể, "hành động của trình hợp ngữ" và "hành động của trình biên dịch" trong bảng dưới đây là CppCompileAction, trong khi các hành động liên kết là CppLinkAction.

Thao tác của trình hợp ngữ

Thao tác của trình biên dịch

Thao tác với đường liên kết

Thao tác thực tế tăng cường

Các thao tác AR tập hợp các tệp đối tượng vào các thư viện lưu trữ (tệp .a) thông qua ar và mã hoá một số ngữ nghĩa vào tên.

Thao tác LTO

Sử dụng action_config

action_config là một cấu trúc Starlark mô tả một thao tác Bazel bằng cách chỉ định công cụ (nhị phân) để gọi trong thao tác và các tập hợp cờ, do các tính năng xác định. Các cờ này áp dụng các ràng buộc cho quá trình thực thi hành động.

Hàm khởi tạo action_config() có các tham số sau:

Một action_config có thể yêu cầu và ngụ ý các tính năng và action_config khác theo mối quan hệ giữa các tính năng được mô tả trước đó. Hành vi này tương tự như hành vi của một tính năng.

Hai thuộc tính cuối cùng là dư thừa so với các thuộc tính tương ứng trên các tính năng và được đưa vào vì một số thao tác Bazel yêu cầu các cờ hoặc biến môi trường nhất định và mục tiêu là tránh các cặp action_config+feature không cần thiết. Thông thường, bạn nên chia sẻ một tính năng duy nhất trên nhiều action_config.

Bạn không thể xác định nhiều action_config có cùng action_name trong cùng một chuỗi công cụ. Điều này giúp tránh sự mơ hồ trong các đường dẫn công cụ và thực thi ý định đằng sau action_config – đó là các thuộc tính của một thao tác được mô tả rõ ràng ở một nơi duy nhất trong chuỗi công cụ.

Sử dụng hàm khởi tạo công cụ

action_config có thể chỉ định một bộ công cụ thông qua tham số tools. Hàm khởi tạo tool() có các tham số sau:

Đối với một action_config nhất định, chỉ một tool duy nhất áp dụng đường dẫn công cụ và các yêu cầu thực thi cho thao tác Bazel. Một công cụ được chọn bằng cách lặp lại thuộc tính tools trên action_config cho đến khi tìm thấy một công cụ có bộ with_feature được đặt khớp với cấu hình tính năng (xem phần Mối quan hệ giữa các tính năng trước đó trên trang này để biết thêm thông tin). Bạn nên kết thúc danh sách công cụ bằng một công cụ mặc định tương ứng với cấu hình tính năng trống.

Ví dụ về cách sử dụng

Bạn có thể sử dụng các tính năng và thao tác cùng nhau để triển khai các thao tác Bazel với nhiều ngữ nghĩa trên nhiều nền tảng. Ví dụ: quá trình tạo biểu tượng gỡ lỗi trên macOS yêu cầu tạo biểu tượng trong thao tác biên dịch, sau đó gọi một công cụ chuyên dụng trong thao tác liên kết để tạo kho lưu trữ dsym nén, rồi giải nén kho lưu trữ đó để tạo gói ứng dụng và các tệp .plist mà Xcode có thể sử dụng.

Với Bazel, quy trình này có thể được triển khai như sau, trong đó unbundle-debuginfo là một thao tác Bazel:

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

action_configs = [
    action_config (
        action_name = ACTION_NAMES.cpp_link_executable,
        tools = [
            tool(
                with_features = [
                    with_feature(features=["generate-debug-symbols"]),
                ],
                path = "toolchain/mac/ld-with-dsym-packaging",
            ),
            tool (path = "toolchain/mac/ld"),
        ],
    ),
]

features = [
    feature(
        name = "generate-debug-symbols",
        flag_sets = [
            flag_set (
                actions = [
                    ACTION_NAMES.c_compile,
                    ACTION_NAMES.cpp_compile
                ],
                flag_groups = [
                    flag_group(
                        flags = ["-g"],
                    ),
                ],
            )
        ],
        implies = ["unbundle-debuginfo"],
   ),
]

Bạn có thể triển khai tính năng tương tự này theo cách hoàn toàn khác cho Linux (dùng fission) hoặc cho Windows (tạo ra các tệp .pdb). Ví dụ: việc triển khai để tạo biểu tượng gỡ lỗi dựa trên fission có thể có dạng như sau:

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

action_configs = [
    action_config (
        name = ACTION_NAMES.cpp_compile,
        tools = [
            tool(
                path = "toolchain/bin/gcc",
            ),
        ],
    ),
]

features = [
    feature (
        name = "generate-debug-symbols",
        requires = [with_feature_set(features = ["dbg"])],
        flag_sets = [
            flag_set(
                actions = [ACTION_NAMES.cpp_compile],
                flag_groups = [
                    flag_group(
                        flags = ["-gsplit-dwarf"],
                    ),
                ],
            ),
            flag_set(
                actions = [ACTION_NAMES.cpp_link_executable],
                flag_groups = [
                    flag_group(
                        flags = ["-Wl", "--gdb-index"],
                    ),
                ],
            ),
      ],
    ),
]

Nhóm cờ

CcToolchainConfigInfo cho phép bạn kết hợp các cờ thành những nhóm phục vụ một mục đích cụ thể. Bạn có thể chỉ định một cờ trong khi sử dụng các biến được xác định trước trong giá trị cờ. Trình biên dịch sẽ mở rộng cờ này khi thêm cờ vào lệnh tạo. Ví dụ:

flag_group (
    flags = ["%{output_execpath}"],
)

Trong trường hợp này, nội dung của cờ sẽ được thay thế bằng đường dẫn tệp đầu ra của thao tác.

Các nhóm cờ được mở rộng thành lệnh tạo theo thứ tự xuất hiện trong danh sách, từ trên xuống dưới, từ trái sang phải.

Đối với những cờ cần lặp lại với các giá trị khác nhau khi được thêm vào lệnh tạo, nhóm cờ có thể lặp lại các biến thuộc loại list. Ví dụ: biến include_path thuộc loại list:

flag_group (
    iterate_over = "include_paths",
    flags = ["-I%{include_paths}"],
)

mở rộng thành -I<path> cho từng phần tử đường dẫn trong danh sách include_paths. Tất cả cờ (hoặc flag_group) trong nội dung của một khai báo nhóm cờ đều được mở rộng dưới dạng một đơn vị. Ví dụ:

flag_group (
    iterate_over = "include_paths",
    flags = ["-I", "%{include_paths}"],
)

mở rộng thành -I <path> cho từng phần tử đường dẫn trong danh sách include_paths.

Một biến có thể lặp lại nhiều lần. Ví dụ:

flag_group (
    iterate_over = "include_paths",
    flags = ["-iprefix=%{include_paths}", "-isystem=%{include_paths}"],
)

mở rộng thành:

-iprefix=<inc0> -isystem=<inc0> -iprefix=<inc1> -isystem=<inc1>

Các biến có thể tương ứng với những cấu trúc có thể truy cập bằng ký hiệu dấu chấm. Ví dụ:

flag_group (
    flags = ["-l%{libraries_to_link.name}"],
)

Các cấu trúc có thể được lồng vào nhau và cũng có thể chứa các chuỗi. Để tránh xung đột tên và để rõ ràng, bạn phải chỉ định đường dẫn đầy đủ thông qua các trường. Ví dụ:

flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flags = ["-l%{libraries_to_link.shared_libraries.name}"],
        ),
    ],
)

Mở rộng có điều kiện

Các nhóm cờ hỗ trợ việc mở rộng có điều kiện dựa trên sự hiện diện của một biến cụ thể hoặc trường của biến đó bằng cách sử dụng các thuộc tính expand_if_available, expand_if_not_available, expand_if_true, expand_if_false hoặc expand_if_equal. Ví dụ:

flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flag_groups = [
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--whole_archive"],
                ),
                flag_group (
                    flags = ["-l%{libraries_to_link.shared_libraries.name}"],
                ),
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--no_whole_archive"],
                ),
            ],
        ),
    ],
)

Thông tin tham chiếu CcToolchainConfigInfo

Phần này cung cấp thông tin tham khảo về các biến, tính năng bản dựng và thông tin khác cần thiết để định cấu hình thành công các quy tắc C++.

Biến bản dựng CcToolchainConfigInfo

Sau đây là thông tin tham khảo về các biến bản dựng CcToolchainConfigInfo.

Các tính năng phổ biến

Sau đây là thông tin tham khảo về các tính năng và điều kiện kích hoạt của chúng.

Logic vá các tính năng cũ

Bazel áp dụng các thay đổi sau đối với các tính năng của chuỗi công cụ để có khả năng tương thích ngược:

• Di chuyển tính năng legacy_compile_flags lên đầu chuỗi công cụ
• Di chuyển tính năng default_compile_flags lên đầu chuỗi công cụ
• Thêm tính năng dependency_file (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng pic (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng per_object_debug_info (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng preprocessor_defines (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng includes (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng include_paths (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng fdo_instrument (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng fdo_optimize (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng cs_fdo_instrument (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng cs_fdo_optimize (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng fdo_prefetch_hints (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng autofdo (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng build_interface_libraries (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng dynamic_library_linker_tool (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng shared_flag (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng linkstamps (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng output_execpath_flags (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng runtime_library_search_directories (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng library_search_directories (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng archiver_flags (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng libraries_to_link (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng force_pic_flags (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng user_link_flags (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng legacy_link_flags (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng static_libgcc (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng fission_support (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng strip_debug_symbols (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng coverage (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng llvm_coverage_map_format (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng gcc_coverage_map_format (nếu chưa có) vào đầu chuỗi công cụ
• Thêm tính năng fully_static_link (nếu chưa có) vào cuối chuỗi công cụ
• Thêm tính năng user_compile_flags (nếu chưa có) vào cuối chuỗi công cụ
• Thêm tính năng sysroot (nếu chưa có) vào cuối chuỗi công cụ
• Thêm tính năng unfiltered_compile_flags (nếu chưa có) vào cuối chuỗi công cụ
• Thêm tính năng linker_param_file (nếu chưa có) vào cuối chuỗi công cụ
• Thêm tính năng compiler_input_flags (nếu chưa có) vào cuối chuỗi công cụ
• Thêm tính năng compiler_output_flags (nếu chưa có) vào cuối chuỗi công cụ

Đây là một danh sách dài các tính năng. Kế hoạch là loại bỏ các tệp này sau khi hoàn tất Crosstool trong Starlark. Đối với những độc giả tò mò, hãy xem cách triển khai trong CppActionConfigs và đối với chuỗi công cụ sản xuất, hãy cân nhắc thêm no_legacy_features để làm cho chuỗi công cụ độc lập hơn.