Di chuyển từ Xcode sang Bazel

Trang này mô tả cách tạo hoặc thử nghiệm dự án Xcode bằng Bazel. Tài liệu này 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. Tài liệu này cũng cung cấp các giải pháp khắc phục sự 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à các phần phụ thuộc của mục tiêu đó, cùng với các chế độ cài đặt bản dựng tương ứng thông qua các quy tắc bản dựng.

• Bazel yêu cầu tất cả các tệp mà dự án phụ thuộc phải hiển thị trong thư mục không gian làm việc hoặc được chỉ định làm phần phụ thuộc trong tệp MODULE.bazel.

• Khi tạo 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 phiên bản mới của dự án Xcode khớp với các tệp BUILD bằng cách sử dụng rules_xcodeproj mỗi khi cập nhật tệp BUILD. Một số thay đổi đối với tệp BUILD, chẳng hạn như thêm phần phụ thuộc vào một mục tiêu, không yêu cầu tạo lại dự án, điều này 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 sẽ cung cấp các tính năng xây dựng 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:

1. Cài đặt Bazel nếu bạn chưa cài đặt.

2. 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 dành cho iOS). Bạn nên hiểu rõ không gian làm việc Bazel, bao gồm cả các tệp MODULE.bazel và BUILD, cũng như các khái niệm về mục tiêu, quy tắc xây dựng và gói Bazel.

3. Phân tích và tìm hiểu 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 phải khai báo rõ ràng tất 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 phần Làm việc với các phần phụ thuộc bên ngoài.

Tạo hoặc kiểm thử 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:

1. Tạo tệp MODULE.bazel

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

3. Tạo 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

4. (Không bắt buộc) Phân tích chi tiết bản dựng

5. Chạy bản dựng

6. Tạo dự án Xcode bằng rules_xcodeproj

Bước 1: Tạo tệp MODULE.bazel

Tạo tệp MODULE.bazel trong một thư mục mới. Thư mục này sẽ trở thành gốc không gian làm việc Bazel. Nếu dự án không sử dụng phần phụ thuộc bên ngoài, thì 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 trong 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 tệp MODULE.bazel.

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

Để 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 các phần phụ thuộc đó thành các gói Bazel như mô tả trong hướng dẫn sau đây.

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 của dự án. Tạo tệp BUILD ở gốc không gian làm việc Bazel và định cấu hình tệp này để tạo 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 kiểm thử
• Bước 3c: Thêm(các) mục tiêu thư viện

Mẹo: Để tìm hiểu thêm về các gói và các khái niệm khác của Bazel, hãy xem phần 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ục tiêu quy tắc macos_application hoặc ios_application. 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 chỉ định ít nhất những thông tin sau:

• bundle_id – mã nhận dạng gói (đường dẫn DNS ngược theo sau là tên ứng dụng) của tệp nhị phân.

• provisioning_profile – hồ sơ cấp phép từ tài khoản Nhà phát triển Apple (nếu bạn tạo ứng dụng cho thiết bị iOS).

• families (chỉ dành cho iOS) – liệu có tạo ứng dụng cho iPhone, iPad hay cả hai hay không.

• infoplists – danh sách các tệp .plist để hợp nhất vào 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 hỗ trợ. Điều này đảm bảo Bazel tạo ứng dụng với các cấp độ API chính xác.

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

Các quy tắc xây dựng dành cho Apple của Bazel hỗ trợ chạy các kiểm thử đơn vị và giao diện người dùng trên tất cả các nền tảng của Apple. Thêm 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 để tạo và chạy kiểm thử đơn vị dựa trên thư viện trên iOS.

• ios_ui_test để tạo và chạy các kiểm thử giao diện người dùng trong trình mô phỏng iOS.

• Có các quy tắc kiểm thử tương tự cho tvOS, watchOS và visionOS.

Ở mức tối thiểu, hãy chỉ định một giá trị cho thuộc tính minimum_os_version. Mặc dù 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ị được sử dụng phổ biến nhất, nhưng hãy đảm bảo rằng các giá trị mặc định đó tương thích với dự án và điều chỉnh các giá trị đó nếu cần. Đối với các chương trình kiểm thử yêu cầu trình mô phỏng iOS, hãy chỉ định tên mục tiêu ios_application làm giá trị của thuộc tính test_host.

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

Thêm mục tiêu objc_library cho mỗi thư viện Objective-C và mục tiêu swift_library cho mỗi thư viện Swift mà ứng dụng và/hoặc kiểm thử phụ thuộc vào đó.

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 làm phần phụ thuộc vào mục tiêu ứng dụng.

• Thêm các mục tiêu thư viện kiểm thử làm phần phụ thuộc vào các 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 các ví dụ vềrules_apple. Ví dụ:

• Mục tiêu ứng dụng macOS

• Mục tiêu ứng dụng iOS

• Ứng dụng đa nền tảng (macOS, iOS, watchOS, tvOS)

Để biết thêm thông tin về quy tắc bản dựng, hãy xem phần Quy tắc của Apple dành 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) Phân tích chi tiết 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 dự án thành nhiều gói Bazel. Độ chi tiết cao hơn này mang lại:

• Tăng mức độ gia tăng của bản dựng,

• Tăng mức độ song song của các tác vụ bản dựng,

• Khả năng bảo trì tốt hơn cho người dùng trong tương lai,

• 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. Điều này giúp ngăn chặn các vấn đề như thư viện chứa thông tin chi tiết về việc triển khai bị rò rỉ vào API công khai.

Mẹo để phân tích chi tiết dự án:

• Đặt mỗi thư viện vào gói Bazel riêng. Bắt đầu với những phần phụ thuộc yêu cầu ít phần phụ thuộc nhất và tiến dần lên cây phần phụ thuộc.

• Khi bạn thêm tệp BUILD và chỉ định các 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 chúng.

• Hàm glob() không vượt qua ranh giới gói, vì vậy, khi số lượng gói tăng lên, các tệp được glob() so khớp sẽ thu hẹp lại.

• Khi thêm tệp BUILD vào thư mục main, hãy thêm 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 lần thay đổi lớn đối với các tệp BUILD và khắc phục lỗi bản dựng khi bạn gặp phải.

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

Chạy bản dựng đã di chuyển hoàn toàn để đả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à kiểm thử mục tiêu riêng lẻ để dễ dàng tìm nguồn gây ra lỗi.

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 MODULE.bazel và BUILD sẽ trở thành nguồn thông tin đáng tin cậy về bản dựng. Để cho 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 Squarespace bằng cách sử dụng rules_xcodeproj .

Khắc phục sự cố

Lỗi Bazel có thể xảy ra khi không đồng bộ với phiên bản Xcode đã chọn, chẳng hạn như khi bạn áp dụng bản cập nhật. Dưới đây là một số việc nên thử nếu bạn gặp lỗi với Xcode, ví dụ: "Phải chỉ định phiên bản Xcode để 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.

• Sử dụng Xcode select để cho biết 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.