Di chuyển từ Xcode sang Bazel

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Báo cáo sự cố Xem nguồn

Trang này mô tả cách tạo hoặc kiểm thử một dự án Xcode với 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. Công cụ này cũng cung cấp các giải pháp khắc phục sự cố để xử lý 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 phải 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 nó, cùng với các chế độ cài đặt bản dựng tương ứng thông qua quy tắc tạo bản dựng.

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

  • Khi xây dựng các dự án Xcode bằng Bazel, (các) tệp BUILD sẽ trở thành nguồn đáng tin. Nếu xử lý 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 tệp BUILD bằng Tulsi bất cứ khi nào bạn cập nhật tệp BUILD. Nếu bạn không sử dụng Xcode, các lệnh bazel buildbazel test sẽ cung cấp khả năng xây dựng và thử nghiệm với một số giới hạn nhất định được mô tả ở phần sau trong 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 toàn bộ "hình ảnh lớn" của bản dựng và do đó, một số tính năng của Xcode có thể không hoạt động. Cụ thể:

    • 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 lập chỉ mục được nguồn dự án. Điều này ảnh hưởng đến việc hoàn tất và điều hướng mã trong Xcode, vì Xcode sẽ không thể xem toàn bộ mã nguồn của dự án.

    • Công cụ 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 ra kết quả 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ừ trong Xcode, 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 tương ứng, hãy hoàn thành hướng dẫn về ứng dụng iOS. Bạn sẽ nắm được không gian làm việc của Bazel, bao gồm cả các tệp WORKSPACEBUILD, 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à 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 tường minh 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 Xử lý các phần phụ thuộc bên ngoài.

Tạo hoặc kiểm thử một dự án Xcode với Bazel

Để tạo hoặc kiểm thử một 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 các 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) Chi tiết bản dựng

  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 các 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ư được mô tả trong phần 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 tệp BUILD để cho Bazel biết cấu trúc dự án như thế nào. 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 đó để thực hiện bản dựng ban đầu của dự án như sau:

Mẹo: Để tìm hiểu thêm về các gói và khái niệm khác về 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 của ứng dụng

Thêm mục tiêu quy tắc macos_application hoặc ios_application. Mục tiêu này xây dựng một gói ứng dụng macOS hoặc iOS tương ứng. Trong mục tiêu, hãy chỉ định những thông tin tối thiểu 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 – cấp phép hồ sơ từ tài khoản nhà phát triển Apple của bạn (nếu xây dựng cho thiết bị iOS).

  • families (chỉ iOS) – xây dựng ứng dụng cho iPhone, iPad hay cả hai.

  • 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 tối thiểu của macOS hoặc iOS mà ứng dụng hỗ trợ. Việc này đảm bảo Bazel xây dựng ứng dụng với 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ử

Quy tắc xây dựng 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 thử nghiệm dựa trên ứng dụng trên thử nghiệm iOS hoặc giao diện người dùng trên một trong hai nền tảng, Bazel sẽ tạo đầu ra thử nghiệm nhưng thử nghiệm 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 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à 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 chương trình kiểm thử yêu cầu trình mô phỏng iOS, Bazel sẽ tạo đầu ra kiểm thử nhưng không chạy kiểm thử. Bạn phải tạo một dự án Xcode bằng Tulsi và chạy các chương trình kiểm thử từ bên trong Xcode.

  • ios_ui_test để tạo kết quả cần thiết để chạy các thử nghiệm giao diện người dùng trong trình mô phỏng iOS bằng cách sử dụng Xcode. Bạn phải tạo dự án Xcode bằng Tulsi và chạy các chương trình kiểm thử từ bên trong Xcode. Bazel vốn không thể chạy các thử nghiệm giao diện người dùng.

Ở mức tối thiểu, hãy chỉ định 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_identifierinfoplists) được đặt mặc định là các giá trị thường dùng 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 nếu cần. Đối với các thử nghiệm yêu cầu trình mô phỏng iOS, hãy chỉ định cả 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 Objective C và mục tiêu swift_library cho từng thư viện Swift mà ứng dụng và/hoặc thử nghiệm 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 các 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ử dưới dạng 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.

  • Hãy 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 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) Chia nhỏ bản dựng

Nếu dự án lớn hoặc khi phát triển, hãy cân nhắc việc chia dự án thành nhiều gói Baroque. Mức độ chi tiết cao hơn này cung cấp:

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

  • Tăng cường khả năng tải song song các tác vụ tạo bản dựng,

  • Duy 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ị của mã nguồn trên các mục tiêu và gói. Điều này ngăn chặn các vấn đề như thư viện chứa thông tin triển khai bị rò rỉ vào API công khai.

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

  • Đặt mỗi thư viện trong gói Bazel riêng. Hãy bắt đầu với những cây phụ thuộc ít nhất và hoạt động theo cách phù hợp với cây phụ thuộc.

  • Khi bạn thêm các 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 những mục tiêu đó.

  • Hàm glob() không vượt qua ranh giới của gói. Do đó, khi số lượng gói tăng lên, các tệp do glob() so khớp 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 hiện giới hạn hiển thị lành mạnh trên các gói.

  • Tạo bản dựng dự án sau mỗi lần thay đổi chính đố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 chỉnh để đả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à kiểm thử từng mục tiêu để dễ dàng tìm thấy nguồn của mọi 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ằng Bazel, các tệp WORKSPACEBUILD 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 Bielel bằng cách sử dụng Tulsi.

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 một bản cập nhật. Dưới đây là một số điều cần thử nếu bạn gặp phải 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 và chấp nhận mọi điều khoản và điều kiện.

  • Sử dụng lựa chọn Xcode để cho biết phiên bản chính xác, chấp nhận giấy phép và xóa 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.