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 tuỳ chọn phù hợp, Bazel cần có một số kiến thức về trình biên dịch bên trong, chẳng hạn như bao gồm các thư mục và cờ quan trọng. Nói cách khác, Bazel cần một mô hình trình biên dịch được đơn giản hoá để hiểu hoạt động.

Bazel cần biết những điều sau:

• Trình biên dịch có hỗ trợ mỏngLTO, mô-đun, liên kết động hoặc PIC hay không (mã độc lập về vị trí).
• Đường dẫn đến các công cụ bắt buộc, chẳng hạn 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ả tiêu đề có trong tệp nguồn được khai báo đúng cách trong tệp BUILD.
• sysroot mặc định.
• Cờ nào nên sử dụng để biên dịch, liên kết, lưu trữ.
• Cờ nào cần sử dụng cho các chế độ biên dịch được hỗ trợ (opt, dbg, nhanh).
• 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, thì Bazel cần định cấu hình chúng một cách riêng biệt.

CcToolchainConfigInfo là một nhà cung cấp cung cấp cấp độ cần thiết độ chi tiế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 tự động định cấu hình CcToolchainConfigInfo cho bản dựng, nhưng bạn có lựa chọn định cấu hình theo cách thủ công. Để làm được điều đó, bạn cần quy tắc Starlark cung cấp CcToolchainConfigInfo và bạn cần chỉ định thuộc tính toolchain_config của cc_toolchain vào quy tắc của mình. 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 các hàm khởi tạo Starlark cho mọi cấu trúc cần thiết trong quá trình này @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 chọn đối tượng cc_toolchain nhắm mục tiêu dựa trên tệp BUILD và nhận được CcToolchainConfigInfo khỏi mục tiêu đã chỉ định trong Thuộc tính cc_toolchain.toolchain_config. Mục tiêu cc_toolchain truyền thông tin này đến mục tiêu C++ thông qua CcToolchainProvider.

Ví dụ: hành động biên dịch hoặc liên kết, được tạo thực thể bằng một quy tắc như cc_binary hoặc cc_library cần các thông tin sau:

• Trình biên dịch hoặc trình liên kết cần sử dụng
• Cờ 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ấu phần phần mềm cần thiết trong hộp cát mà thao tác thực thi

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

Cấu phần phần mềm cần vận chuyển đến hộp cát được khai báo trong cc_toolchain . Ví dụ: với thuộc tính cc_toolchain.linker_files, bạn có thể chỉ định thư viện chuỗi công cụ và tệp nhị phân 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 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à điểm Bazel đến mục tiêu bằng cách sử dụng Tuỳ chọn --crosstool_top.

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

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

   • Nếu không chỉ định tuỳ chọn --compiler, Bazel sẽ chọn mục nhập tương ứng từ cc_toolchain_suite.toolchains chỉ với --cpu.

   • Nếu không có cờ nào được chỉ định, Bazel sẽ kiểm tra hệ thống máy chủ lưu trữ và chọn một --cpu giá trị dựa trên phát hiện của công cụ này. Xem mã cơ chế kiểm tra.

Sau khi bạn chọn một chuỗi công cụ, hãy chọn feature và action_config tương ứng các đối tượng trong quy tắc Starlark chi phối cấu hình của bản dựng (tức là mục được mô tả sau). Các thông báo này cho phép triển khai các tính năng C++ hoàn chỉnh trong Bazel mà không cần sửa đổi Tệp nhị phân Bazel. Quy tắc C++ hỗ trợ nhiều thao tác riêng biệ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ờ hiệu dòng lệnh, hành động các hạn chế về môi trường thực thi hoặc các thay đổi phần phụ thuộc. Một đối tượng có thể đơn giản như cho phép tệp BUILD chọn cấu hình cờ hiệu, 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 hành động biên dịch mới và dữ liệu đầu vào vào quá trình biên dịch, chẳng hạn như header_modules hoặc thin_lto.

Tốt nhất là CcToolchainConfigInfo chứa danh sách các tính năng, trong đó mỗi tính năng tính năng này 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ờ áp dụng cho các thao tác cụ thể của Bazel.

Một đối tượng được chỉ định theo tên, cho phép tách hoàn toàn Starlark cấu hình quy tắc từ 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ấ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.

Tính năng được bật theo một trong những cách sau:

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

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

Mối quan hệ giữa tính năng

Các phần phụ thuộc thường được quản lý trực tiếp bằng Bazel, vốn chỉ đơn giản là thực thi các yêu cầu và quản lý những xung đột nội tại về bản chất của các tính năng được xác định trong bản dựng. Thông số kỹ thuật của chuỗi công cụ cho phép bạn chi tiết hơn các hạn chế để sử dụng trực tiếp bên trong quy tắc Starlark chi phối tính năng hỗ trợ và mở rộ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

Hành động mang đến sự linh hoạt để điều chỉnh tình huống trong một hành động thực thi mà không giả định hành động đó sẽ được thực hiện như thế nào. Một action_config chỉ định tệp nhị phân của công cụ mà một hành động gọi ra, trong khi feature chỉ định cấu hình (gắn cờ) để xác định cách công cụ đó hoạt động khi hành động được gọi.

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

Mỗi tên hành động đại diện cho một loại hành động do 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 với một giữa các hành động và các loại hành động Bazel, trong đó một loại hành động Bazel đề cập đến một lớp Java triển khai một thao tác (chẳng hạn như CppCompileAction). Cụ thể, "hành động liên quan đến tập hợp" và "hành động của trình biên dịch" trong bảng bên dưới là CppCompileAction, còn thao tác liên kết là CppLinkAction.

Thao tác với trình tập hợp

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

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

Hành động thực tế tăng cường

Các hành động thực tế tăng cường (AR) sẽ tập hợp các tệp đối tượng thành 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 của LTO

Sử dụng action_config

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

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

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

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

Bạn không thể xác định nhiều hơn một action_config bằng cùng một action_name trong cùng một chuỗi công cụ. Điều này giúp tránh tình trạng không rõ ràng trong đường dẫn công cụ và thực thi ý định đằng sau action_config – rằng thuộc tính của một hành động được mô tả rõ ràng tại một vị trí 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() nhận các tham số sau:

Đối với một action_config nhất định, chỉ áp dụng một tool duy nhất đường dẫn công cụ và các yêu cầu thực thi đối với hành động Bazel. Một công cụ được chọn bằng cách lặp lại thông qua thuộc tính tools trên action_config cho đến khi có một công cụ có một tập hợp with_feature khớp với cấu hình tính năng được tìm thấy (xem Mối quan hệ với tính năng ở phần 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 công cụ tương ứng với một 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 kết hợp các tính năng và thao tác để triển khai các thao tác trên Bazel với ngữ nghĩa đa nền tảng. Ví dụ: gỡ lỗi tạo biểu tượng trên macOS yêu cầu tạo các biểu tượng trong thao tác biên dịch, sau đó gọi một công cụ chuyên biệt trong quá trình thực hiện thao tác liên kết để tạo tệp lưu trữ dsym được nén và sau đó giải nén tệp lưu trữ đó để tạo gói ứng dụng và .plist được cung cấp bởi Xcode.

Với Bazel, quy trình này có thể được triển khai như sau, với unbundle-debuginfo là một hành động 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"],
   ),
]

Tính năng tương tự này cũng có thể được triển khai hoàn toàn khác cho Linux, nền tảng sử dụng fission hoặc dành cho Windows (tạo tệp .pdb). Ví dụ: quá trình triển khai việc tạo biểu tượng gỡ lỗi dựa trên fission có thể trông giố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"],
                    ),
                ],
            ),
      ],
    ),
]

Gắn cờ nhóm

CcToolchainConfigInfo cho phép bạn gói các cờ vào các nhóm phân phát mục đích cụ thể. Bạn có thể chỉ định cờ trong phạm vi sử dụng các biến được xác định trước trong giá trị cờ mà trình biên dịch sẽ mở rộng khi thêm cờ và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 hành động.

Nhóm gắn 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 bản dựng , nhóm gắn cờ có thể lặp lại các biến thuộc kiểu list. Ví dụ: biến include_path thuộc loại list:

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

sẽ 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 phần nội dung khai báo nhóm cờ được mở rộng dưới dạng một đơn vị. Ví dụ:

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

sẽ 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 cấu trúc có thể truy cập được bằng cách sử dụ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ể lồng ghép vào nhau và cũng có thể chứa trình tự. Để tránh trường hợp xung đột tên Ngoài ra, để trình bày 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

Nhóm gắn cờ hỗ trợ mở rộng có điều kiện dựa trên sự hiện diện của một thuộc tính cụ thể biến hoặc trường của biến đó bằng cách sử dụng expand_if_available, expand_if_not_available, Thuộc tính 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"],
                ),
            ],
        ),
    ],
)

Tài liệu tham khảo về CcToolchainConfigInfo

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

Biến bản dựng CcToolchainConfigInfo

Sau đây là tài liệu tham khảo về các biến bản dựng CcToolchainConfigInfo.

Các tính năng nổi tiếng

Sau đây là tài liệu tham khảo về các tính năng và cách kích hoạt các tính năng đó .

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

Bazel áp dụng các thay đổi sau cho các tính năng của chuỗi công cụ để quay lại khả năng tương thích:

• 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 không có) vào đầu chuỗi công cụ
• Thêm tính năng pic (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng per_object_debug_info (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng preprocessor_defines (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng includes (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng include_paths (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng fdo_instrument (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng fdo_optimize (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng cs_fdo_instrument (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng cs_fdo_optimize (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng fdo_prefetch_hints (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng autofdo (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng build_interface_libraries (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng dynamic_library_linker_tool (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng shared_flag (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng linkstamps (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng output_execpath_flags (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng runtime_library_search_directories (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng library_search_directories (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng archiver_flags (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng libraries_to_link (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng force_pic_flags (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng user_link_flags (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng legacy_link_flags (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng static_libgcc (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng fission_support (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng strip_debug_symbols (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng coverage (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng llvm_coverage_map_format (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng gcc_coverage_map_format (nếu không có) vào đầu chuỗi công cụ
• Thêm tính năng fully_static_link (nếu không có) vào cuối chuỗi công cụ
• Thêm tính năng user_compile_flags (nếu không có) vào cuối chuỗi công cụ
• Thêm tính năng sysroot (nếu không có) vào cuối chuỗi công cụ
• Thêm tính năng unfiltered_compile_flags (nếu không có) vào cuối chuỗi công cụ
• Thêm tính năng linker_param_file (nếu không có) vào cuối chuỗi công cụ
• Thêm tính năng compiler_input_flags (nếu không có) vào cuối chuỗi công cụ
• Thêm tính năng compiler_output_flags (nếu không có) vào cuối chuỗi công cụ

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