Chương trình đăng ký tham gia sự kiện BazelCon 2024 đã bắt đầu!

Trang này được dịch bởi Cloud Translation API.

Di chuyển sang nền tảng

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

Bazel có dịch vụ hỗ trợ tinh vi cho quy trình lập mô hình nền tảng và chuỗi công cụ dành cho đa kiến trúc và các bản dựng được biên dịch chéo.

Trang này tóm tắt trạng thái của việc hỗ trợ này.

Xem thêm:

Trạng thái

C++

Quy tắc C++ sử dụng nền tảng để chọn chuỗi công cụ khi Đã đặt --incompatible_enable_cc_toolchain_resolution.

Điều này có nghĩa là bạn có thể định cấu hình dự án C++ bằng:

bazel build //:my_cpp_project --platforms=//:myplatform

thay vì phiên bản cũ:

bazel build //:my_cpp_project` --cpu=... --crosstool_top=...  --compiler=...

Tính năng này sẽ được bật theo mặc định trong Bazel 7.0 (#7260).

Để kiểm thử dự án C++ với các nền tảng, hãy xem Di chuyển dự án và Định cấu hình chuỗi công cụ C++.

Java

Các quy tắc Java sử dụng nền tảng để chọn chuỗi công cụ.

Thao tác này sẽ thay thế các cờ cũ --java_toolchain, --host_java_toolchain, --javabase và --host_javabase.

Vui lòng xem Java và Bazel để biết thông tin chi tiết.

Android

Quy tắc Android sử dụng nền tảng để chọn chuỗi công cụ khi Đã đặt --incompatible_enable_android_toolchain_resolution.

Điều này có nghĩa là bạn có thể định cấu hình dự án Android bằng:

bazel build //:my_android_project --android_platforms=//:my_android_platform

thay vì sử dụng cờ cũ như --android_crosstool_top, --android_cpu và --fat_apk_cpu.

Tính năng này sẽ được bật theo mặc định trong Bazel 7.0 (#16285).

Để kiểm thử dự án Android của bạn với các nền tảng, hãy xem Di chuyển dự án.

Quả táo

Các quy tắc của Apple không hỗ trợ các nền tảng và chưa được lên lịch để được hỗ trợ.

Bạn vẫn có thể sử dụng API nền tảng với các bản dựng của Apple (ví dụ: khi tạo bằng sự kết hợp giữa các quy tắc của Apple và C++ thuần tuý) với nền tảng ánh xạ.

Ngôn ngữ khác

Quy tắc Go hỗ trợ đầy đủ cho các nền tảng
Quy tắcRust hỗ trợ đầy đủ cho các nền tảng.

Nếu bạn sở hữu bộ quy tắc ngôn ngữ, hãy xem phần Di chuyển bộ quy tắc để thêm của Google.

Thông tin khái quát

Nền tảng và chuỗi công cụ được ra mắt để chuẩn hoá cách phần mềm các dự án nhắm mục tiêu đến nhiều cấu trúc và biên dịch chéo.

Đây là truyền cảm hứng bởi quan sát thấy rằng các nhà duy trì ngôn ngữ đã làm việc này trong quảng cáo theo cách tạm thời, không tương thích. Ví dụ: các quy tắc C++ đã sử dụng --cpu và --crosstool_top để khai báo CPU mục tiêu và chuỗi công cụ. Không có chủ đề nào phù hợp lập mô hình chính xác một "nền tảng". Điều này tạo ra các bản dựng khó xử lý và không chính xác.

Java, Android và các ngôn ngữ khác cũng phát triển cờ riêng cho các mục đích tương tự, không có hình ảnh nào hoạt động với nhau. Bản dựng này hỗ trợ nhiều ngôn ngữ khó hiểu và phức tạp.

Bazel dành cho các dự án lớn, đa ngôn ngữ và đa nền tảng. Chiến dịch này đòi hỏi hỗ trợ nguyên tắc hơn cho các khái niệm này, bao gồm định nghĩa rõ ràng API chuẩn.

Cần di chuyển

Việc nâng cấp lên API mới yêu cầu hai nỗ lực: phát hành API và nâng cấp để sử dụng logic quy tắc đó.

Hành động đầu tiên đã hoàn tất, nhưng quảng cáo thứ hai vẫn đang diễn ra. Việc này bao gồm việc đảm bảo chuỗi công cụ và nền tảng dành riêng cho ngôn ngữ được xác định, đọc logic ngôn ngữ chuỗi công cụ thông qua API mới thay vì các cờ cũ như --crosstool_top và config_setting chọn trên API mới thay vì cờ cũ.

Công việc này rất đơn giản nhưng đòi hỏi nỗ lực riêng cho từng ngôn ngữ, cùng với cảnh báo công bằng để chủ sở hữu dự án thử nghiệm những thay đổi sắp tới.

Đây là lý do tại sao quá trình di chuyển này diễn ra liên tục.

Mục tiêu

Quá trình di chuyển này hoàn tất khi tất cả dự án được tạo bằng biểu mẫu:

bazel build //:myproject --platforms=//:myplatform

Điều này có nghĩa là:

Các quy tắc của dự án chọn chuỗi công cụ phù hợp cho //:myplatform.
Các phần phụ thuộc của dự án chọn chuỗi công cụ phù hợp cho //:myplatform.
//:myplatform nội dung tham khảo khai báo phổ biến của CPU, OS và các thuộc tính chung, độc lập về ngôn ngữ khác
Tất cả select() liên quan đều khớp đúng với //:myplatform.
//:myplatform được xác định ở một nơi rõ ràng, dễ tiếp cận: trong tệp kho lưu trữ nếu nền tảng đó là dành riêng cho dự án của bạn hoặc một vị trí chung nào đó có thể tìm thấy mã này

Những cờ cũ như --cpu, --crosstool_top và --fat_apk_cpu sẽ được và bị xoá ngay khi thấy an toàn.

Cuối cùng, đây sẽ là cách duy nhất để định cấu hình kiến trúc.

Di chuyển dự án

Nếu bạn tạo bản dựng bằng các ngôn ngữ hỗ trợ nền tảng, thì bản dựng của bạn phải làm việc với một lệnh gọi như:

bazel build //:myproject --platforms=//:myplatform

Xem phần Trạng thái và tài liệu về ngôn ngữ của bạn để biết thông tin chi tiết chính xác.

Nếu một ngôn ngữ yêu cầu cờ để cho phép hỗ trợ nền tảng, bạn cũng cần đặt cờ đó. Xem phần Trạng thái để biết chi tiết.

Để tạo bản dựng dự án, bạn cần kiểm tra những điều sau:

//:myplatform phải tồn tại. Thông thường, trách nhiệm của chủ dự án để xác định nền tảng vì các dự án khác nhau nhắm mục tiêu đến các máy khác nhau. Hãy xem phần Nền tảng mặc định.
Chuỗi công cụ bạn muốn sử dụng phải tồn tại. Nếu sử dụng chuỗi công cụ cổ phiếu, chủ sở hữu ngôn ngữ cần cung cấp hướng dẫn về cách đăng ký chúng. Nếu bằng cách viết chuỗi công cụ tuỳ chỉnh của riêng bạn, bạn cần phải đăng ký các chuỗi công cụ đó trong MODULE.bazel hoặc với --extra_toolchains.
Các select() và chuyển đổi cấu hình phải và chính xác. Hãy xem select() và Transitions.
Nếu bản dựng của bạn kết hợp các ngôn ngữ có hỗ trợ và không hỗ trợ nền tảng, bạn có thể cần ánh xạ nền tảng để giúp các ngôn ngữ cũ hoạt động với API mới. Xem bài viết Ánh xạ nền tảng để biết thông tin chi tiết.

Nếu bạn vẫn gặp vấn đề, hãy liên hệ với nhóm hỗ trợ.

Nền tảng mặc định

Chủ sở hữu dự án nên xác định platforms để mô tả kiến trúc mà họ muốn xây dựng. Sau đó, các hành động này sẽ được kích hoạt bằng --platforms.

Khi bạn không thiết lập --platforms, Bazel sẽ mặc định dùng platform đại diện cho cục bộ. Tệp này được tạo tự động vào @platforms//host (có tên là @bazel_tools//tools:host_platform) nên bạn không cần phải xác định rõ ràng. Chế độ này ánh xạ OS của máy cục bộ và CPU với constraint_value được khai báo trong @platforms.

`select()`

Những dự án có thể select() trên constraint_value mục tiêu nhưng chưa hoàn thành nền tảng. Đây là chủ ý nên select() hỗ trợ nhiều máy tính nhất có thể. Thư viện có các nguồn cụ thể là ARM phải hỗ trợ tất cả Máy hỗ trợ ARM trừ khi có lý do để cụ thể hơn.

Để chọn một hoặc nhiều constraint_value, hãy sử dụng:

config_setting(
    name = "is_arm",
    constraint_values = [
        "@platforms//cpu:arm",
    ],
)

Điều này tương đương với việc chọn theo cách truyền thống trên --cpu:

config_setting(
    name = "is_arm",
    values = {
        "cpu": "arm",
    },
)

Bạn có thể xem thêm thông tin tại đây.

select trên --cpu, --crosstool_top, v.v. không hiểu --platforms. Khi di chuyển dự án của bạn sang nền tảng, bạn phải chuyển đổi chúng thành constraint_values hoặc dùng mối liên kết nền tảng để hỗ trợ cả hai kiểu trong quá trình di chuyển.

Kiểu chuyển cảnh

Thay đổi về hiệu ứng chuyển đổi Starlark gắn cờ các phần của biểu đồ bản dựng. Nếu dự án của bạn sử dụng hiệu ứng chuyển đổi đặt --cpu, --crossstool_top hoặc cờ cũ, các quy tắc đọc --platforms sẽ không thấy những thay đổi này.

Khi di chuyển dự án sang nền tảng, bạn phải chuyển đổi các thay đổi như return { "//command_line_option:cpu": "arm" } đến return { "//command_line_option:platforms": "//:my_arm_platform" } hoặc sử dụng nền tảng ánh xạ để hỗ trợ cả hai kiểu trong quá trình di chuyển. cửa sổ.

Di chuyển bộ quy tắc của bạn

Nếu sở hữu một bộ quy tắc và muốn hỗ trợ các nền tảng, bạn cần phải:

Để logic quy tắc phân giải chuỗi công cụ bằng API chuỗi công cụ. Xem toolchain API (ctx.toolchains).
Không bắt buộc: xác định cờ --incompatible_enable_platforms_for_my_language để logic quy tắc luân phiên phân giải các chuỗi công cụ thông qua API mới hoặc cờ cũ như --crosstool_top trong quá trình kiểm thử quá trình di chuyển.
Xác định các thuộc tính có liên quan tạo nên thành phần của nền tảng. Xem Các thuộc tính phổ biến của nền tảng
Xác định chuỗi công cụ chuẩn và giúp người dùng có thể truy cập chúng thông qua hướng dẫn đăng ký của quy tắc (chi tiết)
Đảm bảo select() và chuyển đổi cấu hình. Đây là thách thức lớn nhất. Đặc biệt khó khăn đối với các dự án đa ngôn ngữ (có thể không thành công nếu tất cả ngôn ngữ đều không đọc được --platforms).

Nếu cần kết hợp với các quy tắc không hỗ trợ nền tảng, có thể bạn cần ánh xạ nền tảng để thu hẹp khoảng cách.

Các thuộc tính phổ biến của nền tảng

Các thuộc tính nền tảng phổ biến, đa ngôn ngữ như OS và CPU phải là được khai báo trong @platforms. Điều này khuyến khích việc chia sẻ, tiêu chuẩn hoá và tương thích với nhiều ngôn ngữ.

Bạn phải khai báo các thuộc tính dành riêng cho quy tắc của mình trong kho lưu trữ của quy tắc. Chiến dịch này cho phép bạn duy trì quyền sở hữu rõ ràng đối với những khái niệm cụ thể mà quy tắc của bạn chịu trách nhiệm.

Nếu các quy tắc của bạn sử dụng hệ điều hành hoặc CPU có mục đích tuỳ chỉnh, bạn phải khai báo các quy tắc này trong repo của quy tắc so với @platforms.

Liên kết nền tảng

Ánh xạ nền tảng là một API tạm thời cho phép kết hợp logic nhận biết nền tảng với logic cũ trong cùng một bản dựng. Đây là một công cụ cùn chỉ nhằm mục đích không tương thích mượt mà với các khung thời gian di chuyển khác nhau.

Ánh xạ nền tảng là bản đồ của platform() đến một bộ cờ cũ tương ứng hoặc đảo ngược. Ví dụ:

platforms:
  # Maps "--platforms=//platforms:ios" to "--ios_multi_cpus=x86_64 --apple_platform_type=ios".
  //platforms:ios
    --ios_multi_cpus=x86_64
    --apple_platform_type=ios

flags:
  # Maps "--ios_multi_cpus=x86_64 --apple_platform_type=ios" to "--platforms=//platforms:ios".
  --ios_multi_cpus=x86_64
  --apple_platform_type=ios
    //platforms:ios

  # Maps "--cpu=darwin_x86_64 --apple_platform_type=macos" to "//platform:macos".
  --cpu=darwin_x86_64
  --apple_platform_type=macos
    //platforms:macos

Bazel sử dụng mã này để đảm bảo tất cả các chế độ cài đặt, cả dựa trên nền tảng và cũ, được áp dụng nhất quán trong suốt quá trình xây dựng, bao gồm cả thông qua chuyển đổi.

Theo mặc định, Bazel sẽ đọc các tệp ánh xạ từ tệp platform_mappings trong không gian làm việc gốc. Bạn cũng có thể đặt --platform_mappings=//:my_custom_mapping.

Xem thiết kế liên kết nền tảng để biết thông tin chi tiết.

Đánh giá API

platform là một tập hợp constraint_value mục tiêu:

platform(
    name = "myplatform",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

constraint_value là một máy thuộc tính này. Giá trị thuộc cùng một loại được nhóm theo một chỉ số chung constraint_setting:

constraint_setting(name = "os")
constraint_value(
    name = "linux",
    constraint_setting = ":os",
)
constraint_value(
    name = "mac",
    constraint_setting = ":os",
)

toolchain là một quy tắc Starlark. khai báo công cụ của ngôn ngữ (như compiler = "//mytoolchain:custom_gcc"). Thẻ providers (nhà cung cấp) thông tin này cho các quy tắc cần xây dựng bằng các công cụ này.

Chuỗi công cụ khai báo constraint_value máy mà chúng có thể mục tiêu (target_compatible_with = ["@platforms//os:linux"]) và máy móc mà công cụ của họ có thể chạy trên (exec_compatible_with = ["@platforms//os:mac"]).

Khi xây dựng $ bazel build //:myproject --platforms=//:myplatform, Bazel tự động chọn một chuỗi công cụ có thể chạy trên máy xây dựng và tạo tệp nhị phân cho //:myplatform. Đây gọi là quá trình giải quyết bằng chuỗi công cụ.

Bạn có thể đăng ký tập hợp các chuỗi công cụ hiện có trong tệp MODULE.bazel với register_toolchains hoặc tại dòng lệnh bằng --extra_toolchains.

Để biết thêm thông tin, hãy xem tại đây.

Câu hỏi

Nếu bạn có câu hỏi và dịch vụ hỗ trợ chung về tiến trình di chuyển, hãy liên hệ thảo luận về hoặc chủ sở hữu của các quy tắc phù hợp.

Để thảo luận về việc thiết kế và phát triển các API nền tảng/chuỗi công cụ, hãy liên hệ với bazel-dev.