Trang này mô tả cách tạo hoặc thử nghiệm dự án Xcode bằng Bazel. Công cụ 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 một dự án Xcode thành một dự án Bazel. Ngoài ra, API này còn đưa ra 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 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 tệp nhập trong tệp
WORKSPACE.Khi xây dựng dự án Xcode bằng Bazel, (các) tệp
BUILDsẽ 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ệpBUILDbằng rules_xcodeproj bất cứ khi nào bạn cập nhật tệpBUILD. Một số thay đổi nhất định đối với các tệpBUILDnhư thêm các phần phụ thuộc vào một mục tiêu không yêu cầu bạn phải tạo lại dự án, nhờ đó có thể đẩy nhanh quá trình phát triển. Nếu bạn không sử dụng Xcode, thì các lệnhbazel buildvàbazel testsẽ cung cấp khả năng tạo và kiểm thử với một số hạn chế đượ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 xem hướng dẫn về ứng dụng iOS. Bạn nên nắm rõ không gian làm việc Bazel, bao gồm các tệp
WORKSPACEvà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.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ả 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 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:
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 thư mục gốc của 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 WORKSPACE.
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.
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 để Bazel biết cấu trúc 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 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 cũng như các khái niệm khác của 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 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 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 tệp nhị phân.provisioning_profile– hồ sơ cấp phép từ Tài khoản nhà phát triển của Apple (nếu bạn tạo bản dựng cho thiết bị iOS).families(chỉ dành cho iOS) – liệu nên tạo ứng dụng cho iPhone, iPad hay 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 hỗ trợ. Điều này đảm bảo rằng 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 dành cho Apple của Bazel hỗ trợ chạy các kiểm thử đơn vị dựa trên thư viện trên iOS và macOS, cũng như các kiểm thử dựa trên ứng dụng trên macOS. Đối với các thử nghiệm dựa trên ứng dụng trên iOS hoặc các thử nghiệm giao diện người dùng trên một trong hai nền tảng, Bazel sẽ tạo kết quả 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 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 kiểm thử yêu cầu trình mô phỏng iOS, Bazel sẽ tạo kết quả kiểm thử nhưng không chạy kiểm thử. Bạn phải tạo một dự án Xcode với rules_xcodeproj và chạy thử nghiệm từ bên trong Xcode.ios_ui_testđể tạo kết quả cần thiết cho việc 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 với rules_xcodeproj và chạy thử nghiệm từ bên 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. 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ị 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 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ột mục tiêu objc_library cho mỗi thư viện Target-C và một mục tiêu swift_library cho mỗi thư viện Swift mà ứng dụng và/hoặc bài 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 dưới dạng phần phụ thuộc vào các 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 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ềrules_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 có quy mô 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. Điều này giúp ngăn chặn các vấn đề như thư viện chứa thông tin triển khai bị rò rỉ trong 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. Hãy bắt đầu với những phần tử đòi hỏi í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
BUILDvà 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ínhdepscủa mục tiêu phụ thuộc vào chúng.Hàm
glob()không vượt qua ranh giới của gói, do đó, số lượng gói phát triển màglob()khớp với sẽ giảm xuống.Khi thêm tệp
BUILDvào thư mụcmain, hãy thêm tệpBUILDvào thư mụctesttươ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
BUILDvà sửa lỗi bản dựng khi bạn gặp 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 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 thấy 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 WORKSPACE 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ể phát sinh khi phiên bản này 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ố 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.
Hãy sử dụng lựa chọn Xcode để cho biết đú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/Developersudo xcodebuild -licensebazel 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.