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 từ Xcode sang Bazel

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

Trang này mô tả cách tạo hoặc thử nghiệm dự án Xcode bằng Bazel. Nó mô tả sự khác biệt giữa Xcode và Bazel, đồng thời cung cấp các bước để chuyển đổi dự án Xcode thành dự án Bazel. Chiến dịch này cũng cung cấp giải pháp khắc phục để giải quyết các lỗi thường gặp.

Sự khác biệt giữa Xcode và Bazel

Bazel yêu cầu bạn chỉ định rõ ràng mọi mục tiêu bản dựng và phần phụ thuộc, cùng với chế độ cài đặt bản dựng tương ứng thông qua quy tắc bản dựng.
Bazel yêu cầu phải có tất cả các tệp mà dự án phụ thuộc vào đó trong thư mục Workspace hoặc được chỉ định là dữ liệu nhập trong WORKSPACE .
Khi xây dựng dự án Xcode bằng Bazel, (các) tệp BUILD sẽ trở thành nguồn đáng tin cậy. Nếu làm việc trên dự án trong Xcode, bạn phải tạo một phiên bản mới của dự án Xcode khớp với các tệp BUILD sử dụng rules_xcodeproj mỗi khi bạn cập nhật các tệp BUILD. Một số thay đổi đối với các tệp BUILD chẳng hạn như thêm các phần phụ thuộc vào mục tiêu thì không cần phải tạo lại dự án có thể giúp đẩy nhanh quá trình phát triển. Nếu bạn không sử dụng Xcode, Các lệnh bazel build và bazel test cung cấp chức năng tạo và kiểm thử với một số hạn chế nhất định được mô tả ở phần sau của hướng dẫn này.

Trước khi bắt đầu

Trước khi bắt đầu, hãy làm như sau:

Cài đặt Bazel nếu bạn chưa thực hiện việc này.
Nếu bạn chưa hiểu rõ về Bazel và các khái niệm của nó, hãy hoàn thành Hướng dẫn về ứng dụng iOS. Chắc hẳn bạn đã hiểu về Bazel Workspace, bao gồm các tệp WORKSPACE và BUILD, cũng như khái niệm mục tiêu, quy tắc xây dựng và gói Bazel.
Phân tích và hiểu rõ các phần phụ thuộc của dự án.

Phân tích các phần phụ thuộc của dự án

Không giống như Xcode, Bazel yêu cầu bạn khai báo rõ ràng tất cả các phần phụ thuộc cho mọi mục tiêu trong tệp BUILD.

Để biết thêm thông tin về các phần phụ thuộc bên ngoài, hãy xem Làm việc với các phần phụ thuộc bên ngoài.

Tạo hoặc thử nghiệm dự án Xcode bằng Bazel

Để tạo hoặc kiểm thử một dự án Xcode bằng Bazel, hãy làm như sau:

Tạo tệp WORKSPACE
(Thử nghiệm) Tích hợp các phần phụ thuộc SwiftPM
Tạo một tệp BUILD:

a. Thêm mục tiêu ứng dụng

b. (Không bắt buộc) Thêm(các) mục tiêu thử nghiệm

c. Thêm(các) mục tiêu thư viện
(Không bắt buộc) Chi tiết hoá bản dựng
Chạy bản dựng
Tạo dự án Xcode bằng rules_xcodeproj

Bước 1: Tạo tệp `WORKSPACE`

Tạo tệp WORKSPACE trong một thư mục mới. Thư mục này trở thành Bazel không gian làm việc gốc. Nếu dự án không sử dụng phần phụ thuộc bên ngoài nào, tệp này có thể trống. Nếu dự án phụ thuộc vào các tệp hoặc gói không nằm trong một các thư mục của dự án, hãy chỉ định các phần phụ thuộc bên ngoài này trong WORKSPACE .

Bước 2: (Thử nghiệm) Tích hợp các phần phụ thuộc SwiftPM

Cách tích hợp các phần phụ thuộc SwiftPM vào không gian làm việc Bazel bằng swift_bazel, bạn phải chuyển đổi chúng thành các gói Bazel như mô tả trong hướng dẫn sau.

Bước 3: Tạo tệp `BUILD`

Sau khi xác định không gian làm việc và các phần phụ thuộc bên ngoài, bạn cần tạo một tệp BUILD để cho Bazel biết cấu trúc dự án. Sáng tạo tệp BUILD ở gốc của không gian làm việc Bazel và định cấu hình tệp này để thực hiện bản dựng ban đầu của dự án như sau:

Bước 3a: Thêm mục tiêu ứng dụng
Bước 3b: (Không bắt buộc) Thêm(các) mục tiêu thử nghiệm
Bước 3c: Thêm(các) mục tiêu thư viện

Mẹo: Để tìm hiểu thêm về gói và các khái niệm khác của Bazel, hãy xem Không gian làm việc, gói và mục tiêu.

Bước 3a: Thêm mục tiêu ứng dụng

Thêm một macos_application hoặc ios_application mục tiêu của quy tắc. Mục tiêu này sẽ tạo gói ứng dụng macOS hoặc iOS tương ứng. Trong mục tiêu, hãy xác định tối thiểu những thông tin sau:

bundle_id – mã nhận dạng gói (đường dẫn ngược DNS theo sau là tên ứng dụng) của nhị phân.
provisioning_profile – hồ sơ cấp phép của Nhà phát triển Apple (nếu xây dựng cho thiết bị iOS).
families (chỉ iOS) - liệu có tạo ứng dụng cho iPhone, iPad, hoặc cả hai.
infoplists – danh sách các tệp .plist để hợp nhất thành tệp Info.plist cuối cùng.
minimum_os_version – phiên bản macOS hoặc iOS tối thiểu mà ứng dụng Google Maps hỗ trợ. Điều này đảm bảo rằng Bazel tạo ứng dụng bằng cấp độ API chính xác.

Bước 3b: (Không bắt buộc) Thêm(các) mục tiêu thử nghiệm

Hỗ trợ về các quy tắc xây dựng dành cho Apple của Bazel chạy các bài kiểm thử đơn vị dựa trên thư viện trên iOS và macOS, cũng như dựa trên ứng dụng trên macOS. Đối với các bài kiểm thử dựa trên ứng dụng trên iOS hoặc các bài kiểm thử giao diện người dùng trên nền tảng, Bazel sẽ tạo các kết quả thử nghiệm nhưng các thử nghiệm phải chạy trong Xcode thông qua một dự án được tạo bằng rules_xcodeproj. Thêm các mục tiêu kiểm thử như sau:

macos_unit_test để chạy các kiểm thử đơn vị dựa trên thư viện và ứng dụng trên macOS.
ios_unit_test để chạy kiểm thử đơn vị dựa trên thư viện trên iOS. Đối với các thử nghiệm yêu cầu iOS trình mô phỏng, Bazel sẽ tạo kết quả kiểm thử nhưng không chạy chương trình kiểm thử. Bạn phải tạo dự án Xcode bằng rules_xcodeproj rồi chạy thử nghiệm trong Xcode.
ios_ui_test để tạo đầu ra cần thiết để chạy kiểm thử giao diện người dùng trong trình mô phỏng iOS bằng Xcode. Bạn phải tạo dự án Xcode có rules_xcodeproj rồi chạy thử nghiệm trong Xcode. Bazel vốn không thể chạy các bài kiểm thử giao diện người dùng.

Ở mức tối thiểu, hãy chỉ định một giá trị cho thuộc tính minimum_os_version. Trong khi các thuộc tính đóng gói khác, chẳng hạn như bundle_identifier và infoplists, mặc định là các giá trị thường dùng nhất, hãy đảm bảo rằng các giá trị mặc định đó cũng tương thích với dự án và điều chỉnh chúng nếu cần. Đối với các thử nghiệm yêu cầu iOS trình mô phỏng, bạn cũng cần chỉ định tên mục tiêu ios_application làm giá trị của lệnh Thuộc tính test_host.

Bước 3c: Thêm(các) mục tiêu thư viện

Thêm một objc_library mục tiêu cho từng thư viện Target-C và một swift_library nhắm mục tiêu cho mỗi thư viện Swift mà ứng dụng và/hoặc kiểm thử phụ thuộc.

Thêm các mục tiêu thư viện như sau:

Thêm các mục tiêu thư viện ứng dụng dưới dạng phần phụ thuộc vào ứng dụng mục tiêu.
Thêm các mục tiêu thư viện kiểm thử dưới dạng phần phụ thuộc vào mục tiêu kiểm thử.
Liệt kê các nguồn triển khai trong thuộc tính srcs.
Liệt kê các tiêu đề trong thuộc tính hdrs.

Bạn có thể duyệt qua các ví dụ hiện có cho nhiều loại ứng dụng ngay trong thư mục ví dụ về quy tắc_apple. Ví dụ:

Để biết thêm thông tin về quy tắc bản dựng, hãy xem Quy tắc của Apple cho Bazel.

Tại thời điểm này, bạn nên kiểm thử bản dựng:

bazel build //:<application_target>

Bước 4: (Không bắt buộc) Thu nhỏ bản dựng

Nếu dự án lớn hoặc khi dự án phát triển, hãy cân nhắc chia nhỏ dự án thành nhiều Gói Bazel. Việc tăng độ chi tiết này mang lại:

Tăng mức độ gia tăng của các bản dựng,
Tăng song song các tác vụ tạo bản dựng,
Giúp người dùng trong tương lai có thể duy trì hoạt động hiệu quả hơn,
Kiểm soát tốt hơn chế độ hiển thị mã nguồn trên các mục tiêu và gói. Chiến dịch này ngăn chặn các sự cố như thư viện chứa thông tin triển khai bị rò rỉ vào các API công khai.

Mẹo chi tiết hoá dự án:

Đặt mỗi thư viện vào gói Bazel riêng. Bắt đầu với những người yêu cầu có ít phần phụ thuộc nhất và tìm cách xây dựng cây phần phụ thuộc.
Khi bạn thêm tệp BUILD và chỉ định mục tiêu, hãy thêm các mục tiêu mới này vào Thuộc tính deps của các mục tiêu phụ thuộc vào các mục tiêu đó.
Hàm glob() không vượt qua ranh giới gói, do đó số số gói tăng trưởng các tệp phù hợp với glob() sẽ thu nhỏ.
Khi thêm một tệp BUILD vào thư mục main, hãy thêm cả tệp BUILD vào thư mục test tương ứng.
Thực thi giới hạn mức độ hiển thị lành mạnh trên các gói.
Tạo dự án sau mỗi thay đổi lớn đối với các tệp BUILD và khắc phục tạo lỗi khi gặp phải.

Bước 5: Chạy bản dựng

Chạy bản dựng được di chuyển toàn bộ để đảm bảo bản dựng hoàn tất mà không có lỗi hoặc cảnh báo. Chạy từng ứng dụng và thử nghiệm mục tiêu riêng lẻ để tìm nguồn dễ dàng hơn bất kỳ lỗi nào xảy ra.

Ví dụ:

bazel build //:my-target

Bước 6: Tạo dự án Xcode bằng rules_xcodeproj

Khi tạo bản dựng bằng Bazel, các tệp WORKSPACE và BUILD sẽ trở thành nguồn xác thực về bản dựng. Để Xcode biết về điều này, bạn phải tạo một Dự án Xcode tương thích với Bazel bằng rules_xcodeproj.

Khắc phục sự cố

Lỗi Bazel có thể phát sinh khi không đồng bộ hoá được với phiên bản Xcode đã chọn, chẳng hạn như khi bạn áp dụng một bản cập nhật. Sau đây là một số việc nên thử nếu bạn gặp phải lỗi với Xcode, ví dụ: "Phải chỉ định phiên bản Xcode thành hãy sử dụng CROSSTOOL của Apple".

Chạy Xcode theo cách thủ công và chấp nhận mọi điều khoản và điều kiện.
Hãy sử dụng lựa chọn Xcode để chỉ định phiên bản chính xác, chấp nhận giấy phép và xoá trạng thái của Bazel.

  sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
  sudo xcodebuild -license
  bazel sync --configure

Nếu cách này không hiệu quả, bạn cũng có thể thử chạy bazel clean --expunge.