Di chuyển sang nền tảng

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

Trang này tóm tắt trạng thái của dịch vụ hỗ trợ này.

Xem thêm:

• Nền tảng
• Chuỗi công cụ
• Nền

Trạng thái

C++

Quy tắc C++ sử dụng các 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ì cách 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++ của bạn với các nền tảng, hãy xem phần Di chuyển dự án và Định cấu hình chuỗi công cụ C++.

Java

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

Phương thức này sẽ thay thế các cờ cũ --java_toolchain, --host_java_toolchain, --javabase và --host_javabase.

Hãy xem phần Java và Bazel để biết thông tin chi tiết.

Android

Các 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ì dùng các 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 với các nền tảng, hãy xem phần Di chuyển dự án.

Quả táo

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

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

Ngôn ngữ khác

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

Nếu bạn sở hữu một bộ quy tắc ngôn ngữ, hãy xem phần Di chuyển bộ quy tắc để biết thêm thông tin hỗ trợ.

Thông tin khái quát

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

Điều này được lấy cảm hứng từ việc quan sát thấy các trình duy trì ngôn ngữ đã thực hiện việc này theo cách không tương thích, tuỳ ý. Ví dụ: các quy tắc C++ sử dụng --cpu và --crosstool_top để khai báo CPU và chuỗi công cụ mục tiêu. Cả hai cách này đều không mô hình hoá 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ử và không chính xác.

Java, Android và các ngôn ngữ khác đã phát triển cờ riêng cho các mục đích tương tự, nhưng không có cờ nào trong số đó hoạt động với nhau. Điều này khiến các bản dựng đa ngôn ngữ trở nên 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. Điều này đòi hỏi sự hỗ trợ nguyên tắc hơn cho các khái niệm này, bao gồm cả API tiêu chuẩn rõ ràng.

Nhu cầu di chuyển

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

Lệnh đầu tiên đã hoàn tất nhưng lệnh thứ hai vẫn đang diễn ra. Việc này bao gồm việc đảm bảo các nền tảng và chuỗi công cụ dành riêng cho ngôn ngữ được xác định, logic ngôn ngữ đọc các 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ờ cũ.

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

Đó là lý do quá trình di chuyển này vẫn đang diễn ra.

Mục tiêu

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

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

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

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

Các cờ cũ như --cpu, --crosstool_top và --fat_apk_cpu sẽ không được dùng nữa 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 cấu 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 sẽ hoạt động với lệnh gọi như sau:

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, thì bạn cũng cần đặt cờ đó. Hãy xem phần Trạng thái để biết thông tin chi tiết.

Để xây dựng dự án, bạn cần kiểm tra những điều sau:

1. //:myplatform phải tồn tại. Thông thường, chủ sở hữu dự án có trách nhiệm xác định nền tảng vì các dự án khác nhau nhắm đến các máy khác nhau. Hãy xem phần Nền tảng mặc định.

2. 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ụ thương mại, thì chủ sở hữu ngôn ngữ nên cung cấp hướng dẫn về cách đăng ký các chuỗi công cụ đó. Nếu viết chuỗi công cụ tuỳ chỉnh của riêng mình, bạn cần register các chuỗi công cụ đó trong WORKSPACE hoặc bằng --extra_toolchains.

3. select() và quá trình chuyển đổi cấu hình phải được phân giải đúng cách. Xem select() và Chuyển đổi.

4. Nếu bản dựng của bạn kết hợp các ngôn ngữ hỗ trợ và không hỗ trợ nền tảng, thì 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. Hãy xem phần Liên kết 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ệ để được hỗ trợ.

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

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

Khi bạn không đặt --platforms, Bazel sẽ mặc định là platform đại diện cho máy tạo bản dựng cục bộ. Tệp này được tạo tự động tại @local_config_platform//:host, vì vậy, bạn không cần phải xác định rõ ràng. Phương thức này liên kết OS và CPU của máy cục bộ với constraint_value được khai báo trong @platforms.

select()

Dự án có thể select() trên các mục tiêu constraint_value nhưng không hoàn tất các nền tảng. Đây là ý định của select() để hỗ trợ nhiều máy nhất có thể. Thư viện có các nguồn dành riêng cho ARM phải hỗ trợ tất cả máy chạy ARM, trừ phi 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",
    },
)

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 sang các nền tảng, bạn phải chuyển đổi các dự án đó thành constraint_values hoặc sử dụng tính năng 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

Hiệu ứng chuyển đổi Starlark sẽ gắn cờ cho 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ũ khác, thì 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" } thành return { "//command_line_option:platforms": "//:my_arm_platform" } hoặc sử 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 cửa sổ.

Di chuyển bộ quy tắc

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:

1. Yêu cầu logic quy tắc phân giải chuỗi công cụ bằng API chuỗi công cụ. Xem API chuỗi công cụ (ctx.toolchains).

2. Không bắt buộc: xác định cờ --incompatible_enable_platforms_for_my_language để logic quy tắc lần lượt phân giải 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ử di chuyển.

3. Xác định các thuộc tính liên quan tạo nên các 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

4. Xác định chuỗi công cụ tiêu chuẩn và cho phép người dùng truy cập vào các chuỗi công cụ đó thông qua hướng dẫn đăng ký của quy tắc (thông tin chi tiết)

5. Đảm bảo select() và chuyển đổi cấu hình hỗ trợ các nền tảng. Đây là thách thức lớn nhất. Điều này đặ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ữ không thể đọ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, bạn có thể cần liên kết nền tảng để khắc phục vấn đề này.

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 được khai báo trong @platforms. Điều này khuyến khích việc chia sẻ, chuẩn hoá và khả năng tương thích trên 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. Điều này giúp bạn duy trì quyền sở hữu rõ ràng đối với các khái niệm cụ thể mà quy tắc của bạn chịu trách nhiệm.

Nếu quy tắc của bạn sử dụng các hệ điều hành hoặc CPU dành cho mục đích tuỳ chỉnh, thì bạn phải khai báo các hệ điều hành hoặc CPU này trong kho lưu trữ của quy tắc thay vì @platforms.

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

Mối liên kết nền tảng là một API tạm thời cho phép logic nhận biết nền tảng kết hợp 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 xử lý các trường hợp không tương thích 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 nhóm cờ cũ tương ứng hoặc ngược lại. Ví dụ:

platforms:
  # Maps "--platforms=//platforms:ios" to "--cpu=ios_x86_64 --apple_platform_type=ios".
  //platforms:ios
    --cpu=ios_x86_64
    --apple_platform_type=ios

flags:
  # Maps "--cpu=ios_x86_64 --apple_platform_type=ios" to "--platforms=//platforms:ios".
  --cpu=ios_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 tính năng 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ũ, đều đượ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 các quá trình chuyển đổi.

Theo mặc định, Bazel đọc các mối liên kết từ tệp platform_mappings trong thư mục gốc của không gian làm việc. Bạn cũng có thể đặt --platform_mappings=//:my_custom_mapping.

Hãy xem thiết kế ánh xạ nền tảng để biết thông tin chi tiết.

Xem xét API

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

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

constraint_value là một thuộc tính máy. Các giá trị thuộc cùng một "loại" được nhóm lại trong một constraint_setting chung:

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. Các thuộc tính của lớp này khai báo các công cụ của ngôn ngữ (như compiler = "//mytoolchain:custom_gcc"). Nhà cung cấp của lớp này truyền thông tin này đến 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 của các máy mà chúng có thể nhắm đến (target_compatible_with = ["@platforms//os:linux"]) và các máy mà công cụ của chúng có thể chạy trên đó (exec_compatible_with = ["@platforms//os:mac"]).

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

Bạn có thể đăng ký tập hợp các chuỗi công cụ có sẵn trong WORKSPACE bằng 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 cần được hỗ trợ chung và có câu hỏi về tiến trình di chuyển, hãy liên hệ với bazel-discuss hoặc chủ sở hữu của các quy tắc thích hợp.

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

Xem thêm

• Bản dựng có thể định cấu hình – Phần 1
• Nền tảng
• Chuỗi công cụ
• Sách công thức về Nền tảng Bazel
• Ví dụ về nền tảng
• Ví dụ về chuỗi công cụ C++