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. Hướng dẫn 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. Ngoài ra, API này còn 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 bản dựng đó, cộng với các 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 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 tệp nhập trong tệp WORKSPACE.

• Khi tạo dự án Xcode cùng với Bazel, (các) tệp BUILD sẽ trở thành nguồn đáng tin cậy. Nếu làm việc với 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 bằng cách sử dụng Tulsi mỗi khi cập nhật các tệp BUILD. Nếu bạn không sử dụng Xcode, các lệnh bazel build và bazel test sẽ cung cấp khả năng tạo và kiểm thử với một số giới hạn nhất định được mô tả ở phần sau của hướng dẫn này.

• Do sự khác biệt về giản đồ cấu hình bản dựng, chẳng hạn như bố cục thư mục hoặc cờ bản dựng, Xcode có thể không nhận biết được đầy đủ "ảnh lớn" của bản dựng, do đó một số tính năng của Xcode có thể không hoạt động. Cụ thể là:

  • Tuỳ thuộc vào các mục tiêu mà bạn chọn cho lượt chuyển đổi trong Tulsi, Xcode có thể không thể lập chỉ mục nguồn dự án đúng cách. Điều này ảnh hưởng đến việc hoàn thành mã và điều hướng trong Xcode, vì Xcode sẽ không thể xem tất cả mã nguồn của dự án.

  • Tính năng phân tích tĩnh, trình dọn dẹp địa chỉ và trình dọn dẹp luồng có thể không hoạt động vì Bazel không tạo đầu ra mà Xcode mong đợi cho các tính năng đó.

  • Nếu bạn tạo một dự án Xcode bằng Tulsi và sử dụng dự án đó để chạy kiểm thử từ bên trong Xcode, thì Xcode sẽ chạy kiểm thử thay vì Bazel. Để chạy kiểm thử bằng Bazel, hãy chạy lệnh bazel test theo cách thủ công.

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 công cụ này, hãy xem hết hướng dẫn về ứng dụng dành cho iOS). Bạn nên tìm hiểu không gian làm việc của Bazel, bao gồm cả các tệp WORKSPACE và BUILD, cũng như các khái niệm về mục tiêu, quy tắc tạo bản 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 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 bài viết Xử lý 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ử dự án Xcode với Bazel, hãy làm như sau:

1. Tạo tệp WORKSPACE

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

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 bản dựng một cách chi tiết

5. Chạy bản dựng

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

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

Tạo tệp WORKSPACE trong thư mục mới. Thư mục này trở thành thư mục gốc của không gian làm việc Bazel. Nếu dự án không sử dụng các 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 WORKSPACE.

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

Để tích hợp các phần phụ thuộc CocoaPods vào không gian làm việc của 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 bài viết Chuyển đổi các phần phụ thuộc CocoaPods.

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. Tạo tệp BUILD ở thư mục gốc của không gian làm việc Bazel và định cấu hình tệp đó để tạo bản dựng ban đầu của dự án như sau:

• Bước 3a: Thêm mục tiêu của ứ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ề các gói và các khái niệm khác về Bazel, hãy xem bài viết 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 macos_application hoặc mục tiêu quy tắc ios_application. Mục tiêu này tạo gói ứng dụng macOS hoặc iOS tương ứng. Trong mục tiêu, hãy chỉ định ở mức tối thiểu 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 của bạn (nếu xây dựng cho một thiết bị iOS).

• families (chỉ iOS) – cho phép tạo ứng dụng cho iPhone, iPad hay cả hai.

• infoplists – danh sách các tệp .plist cần 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 giúp đả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 thử nghiệm

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

• macos_unit_test để chạy các bài kiểm thử đơn vị dựa trên thư viện và dựa trên ứ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 kiểm thử yêu cầu trình mô phỏng iOS, Bazel sẽ tạo các kết quả kiểm thử nhưng không chạy kiểm thử. Bạn phải tạo dự án Xcode bằng Tulsi và chạy kiểm thử từ 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 một dự án Xcode bằng Tulsi và chạy kiểm thử từ bên trong Xcode. Bazel vốn không thể chạy 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 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 đó tương thích với dự án và điều chỉnh 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 từng thư viện Mục tiêu C và mục tiêu swift_library cho mỗi thư viện Swift mà ứng dụng và/hoặc hoạt động kiểm thử phụ thuộc vào đó.

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

• Thêm mục tiêu thư viện ứng dụng dưới dạng phần phụ thuộc vào mục tiêu ứng dụng.

• Thêm 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.

Để biết thêm thông tin về quy tắc xây dựng, hãy xem 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) Chi tiết bản dựng

Nếu dự án có quy mô lớn hoặc đang phát triển, hãy cân nhắc việ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 bản dựng,

• Tăng cường việc tải song song các tác vụ xây dựng,

• Cải thiện khả năng bảo trì cho người dùng trong tương lai,

• Kiểm soát tốt hơn khả năng 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 ngừa các vấn đề như thư viện chứa chi tiết triển khai bị rò rỉ vào các API công khai.

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

• Đặt mỗi thư viện vào gói Bazel riêng. Bắt đầu với những yêu cầu cần ít phần phụ thuộc nhất và xử lý 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 của gói, vì vậy, khi số lượng gói tăng lên, số tệp khớp với glob() sẽ giảm xuống.

• 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.

• Áp dụng giới hạn hiển thị lành mạnh trên các gói.

• Xây dựng dự án sau mỗi lần thay đổi lớn đối với các tệp BUILD và sửa lỗi bản dựng khi bạn gặp phải lỗ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 gặp lỗi hoặc cảnh báo. Chạy từng ứng dụng và mục tiêu kiểm thử riêng lẻ để dễ dàng tìm ra nguồn gây ra lỗi xảy ra.

Ví dụ:

bazel build //:my-target

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

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

Khắc phục sự cố

Lỗi Bazel có thể phát sinh khi không đồng bộ hoá 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 bạn có thể thử nếu gặp lỗi với Xcode, ví dụ: "Bạn 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, đồng thời chấp nhận mọi điều khoản và điều kiện.

• Hãy sử dụng Xcode chọn để chỉ định đúng phiên bản, 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.