การย้ายข้อมูลจาก Xcode ไปยัง Bazel

รายงานปัญหา ดูแหล่งที่มา

ต่อคืน · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7

หน้านี้อธิบายวิธีสร้างหรือทดสอบโปรเจ็กต์ Xcode ด้วย Bazel โดยจะอธิบายความแตกต่างระหว่าง Xcode กับ Bazel และแสดงขั้นตอน ในการแปลงโปรเจ็กต์ Xcode เป็นโปรเจ็กต์ Bazel นอกจากนี้ ยังมี วิธีแก้ปัญหาเพื่อแก้ไขข้อผิดพลาดที่พบบ่อย

ความแตกต่างระหว่าง Xcode กับ Bazel

• Bazel กำหนดให้คุณต้องระบุเป้าหมายการสร้างทุกรายการและการ อ้างอิงอย่างชัดเจน รวมถึงการตั้งค่าการสร้างที่เกี่ยวข้องผ่านกฎการสร้าง

• Bazel กำหนดให้ไฟล์ทั้งหมดที่โปรเจ็กต์ขึ้นอยู่กับต้องอยู่ในไดเรกทอรีพื้นที่ทำงานหรือระบุเป็นการนำเข้าในไฟล์ WORKSPACE

• เมื่อสร้างโปรเจ็กต์ Xcode ด้วย Bazel BUILDไฟล์จะกลายเป็นแหล่งข้อมูลที่เชื่อถือได้ หากคุณทำงานในโปรเจ็กต์ใน Xcode คุณต้องสร้างโปรเจ็กต์ Xcode เวอร์ชันใหม่ที่ตรงกับไฟล์ BUILD โดยใช้ rules_xcodeproj ทุกครั้งที่อัปเดตไฟล์ BUILD การเปลี่ยนแปลงบางอย่างในไฟล์ BUILD เช่น การเพิ่มการอ้างอิงไปยังเป้าหมาย ไม่จำเป็นต้องสร้างโปรเจ็กต์ใหม่ ซึ่งจะช่วยเร่งการพัฒนาได้ หากไม่ได้ใช้ Xcode คำสั่ง bazel build และ bazel test จะมีฟีเจอร์การสร้างและการทดสอบ โดยมีข้อจำกัดบางอย่างที่อธิบายไว้ในคู่มือนี้ในภายหลัง

ก่อนเริ่มต้น

ก่อนเริ่มต้น ให้ทำดังนี้

1. ติดตั้ง Bazel หากยังไม่ได้ติดตั้ง

2. หากคุณไม่คุ้นเคยกับ Bazel และแนวคิดของ Bazel ให้ทำตามบทแนะนำเกี่ยวกับแอป iOS) คุณควรทำความเข้าใจพื้นที่ทำงานของ Bazel ซึ่งรวมถึงไฟล์ WORKSPACE และ BUILD ตลอดจนแนวคิดของเป้าหมาย กฎการบิลด์ และแพ็กเกจ Bazel

3. วิเคราะห์และทำความเข้าใจทรัพยากร Dependency ของโปรเจ็กต์

วิเคราะห์ทรัพยากร Dependency ของโปรเจ็กต์

Bazel กำหนดให้คุณต้องประกาศทรัพยากร Dependency ทั้งหมดสำหรับทุกเป้าหมายในไฟล์ BUILD อย่างชัดเจน ซึ่งแตกต่างจาก Xcode

ดูข้อมูลเพิ่มเติมเกี่ยวกับทรัพยากรภายนอกได้ที่ การทำงานกับทรัพยากรภายนอก

สร้างหรือทดสอบโปรเจ็กต์ Xcode ด้วย Bazel

หากต้องการสร้างหรือทดสอบโปรเจ็กต์ Xcode ด้วย Bazel ให้ทำดังนี้

1. สร้างไฟล์ WORKSPACE

2. (ทดลอง) ผสานรวมการขึ้นต่อกันของ SwiftPM

3. สร้างไฟล์ BUILD

   ก. เพิ่มเป้าหมายแอปพลิเคชัน

   ข. (ไม่บังคับ) เพิ่มเป้าหมายการทดสอบ

   ค. เพิ่มเป้าหมายไลบรารี

4. (ไม่บังคับ) แยกย่อยการสร้าง

5. เรียกใช้บิลด์

6. สร้างโปรเจ็กต์ Xcode ด้วย rules_xcodeproj

ขั้นตอนที่ 1: สร้างไฟล์ WORKSPACE

สร้างไฟล์ WORKSPACE ในไดเรกทอรีใหม่ ไดเรกทอรีนี้จะกลายเป็นรูทของพื้นที่ทำงาน Bazel หากโปรเจ็กต์ไม่ได้ใช้ทรัพยากรภายนอก ไฟล์นี้จะว่างเปล่าได้ หากโปรเจ็กต์ขึ้นอยู่กับไฟล์หรือแพ็กเกจที่ไม่ได้อยู่ในไดเรกทอรีของโปรเจ็กต์ ให้ระบุการอ้างอิงภายนอกเหล่านี้ในไฟล์ WORKSPACE

หมายเหตุ: วางซอร์สโค้ดของโปรเจ็กต์ไว้ในโครงสร้างไดเรกทอรีที่มีไฟล์ WORKSPACE

ขั้นตอนที่ 2: (ทดลอง) ผสานรวมทรัพยากร Dependency ของ SwiftPM

หากต้องการผสานรวมการอ้างอิง SwiftPM เข้ากับพื้นที่ทํางาน Bazel ด้วย swift_bazel คุณต้องแปลงการอ้างอิงเหล่านั้นเป็นแพ็กเกจ Bazel ตามที่อธิบายไว้ในบทแนะนำต่อไปนี้

หมายเหตุ: การรองรับ SwiftPM เป็นกระบวนการที่ต้องทำด้วยตนเองและมีตัวแปรหลายอย่าง การผสานรวม SwiftPM กับ Bazel ยังไม่ได้รับการยืนยันอย่างเต็มรูปแบบและไม่ได้รับการสนับสนุนอย่างเป็นทางการ

ขั้นตอนที่ 3: สร้างไฟล์ BUILD

เมื่อกำหนดพื้นที่ทำงานและการอ้างอิงภายนอกแล้ว คุณจะต้อง สร้างไฟล์ BUILD ที่บอก Bazel ว่าโปรเจ็กต์มีโครงสร้างอย่างไร สร้างไฟล์ BUILD ที่รูทของพื้นที่ทำงาน Bazel แล้วกำหนดค่าให้สร้างโปรเจ็กต์ครั้งแรกดังนี้

• ขั้นตอนที่ 3ก: เพิ่มเป้าหมายแอปพลิเคชัน
• ขั้นตอนที่ 3b: (ไม่บังคับ) เพิ่มเป้าหมายการทดสอบ
• ขั้นตอนที่ 3ค: เพิ่มเป้าหมายไลบรารี

เคล็ดลับ: ดูข้อมูลเพิ่มเติมเกี่ยวกับแพ็กเกจและแนวคิดอื่นๆ ของ Bazel ได้ที่ พื้นที่ทำงาน แพ็กเกจ และเป้าหมาย

ขั้นตอนที่ 3ก: เพิ่มเป้าหมายการสมัคร

เพิ่มเป้าหมายกฎ macos_application หรือ ios_application เป้าหมายนี้จะสร้าง App Bundle ของ macOS หรือ iOS ตามลำดับ ในเป้าหมาย ให้ระบุอย่างน้อยรายการต่อไปนี้

• bundle_id - รหัสชุด (เส้นทาง DNS แบบย้อนกลับตามด้วยชื่อแอป) ของไบนารี

• provisioning_profile - โปรไฟล์การจัดสรรจากบัญชี Apple Developer (หากสร้างสำหรับอุปกรณ์ iOS)

• families (iOS เท่านั้น) - เลือกว่าจะสร้างแอปพลิเคชันสำหรับ iPhone, iPad หรือทั้ง 2 อย่าง

• infoplists - รายการไฟล์ .plist ที่จะผสานรวมกับไฟล์ Info.plist สุดท้าย

• minimum_os_version - เวอร์ชันขั้นต่ำของ macOS หรือ iOS ที่แอปพลิเคชันรองรับ เพื่อให้มั่นใจว่า Bazel จะสร้างแอปพลิเคชันด้วย ระดับ API ที่ถูกต้อง

ขั้นตอนที่ 3b: (ไม่บังคับ) เพิ่มเป้าหมายการทดสอบ

กฎการสร้างของ Apple ใน Bazel รองรับการ เรียกใช้การทดสอบหน่วยและ UI ในแพลตฟอร์ม Apple ทั้งหมด เพิ่มเป้าหมายการทดสอบดังนี้

• macos_unit_test เพื่อเรียกใช้การทดสอบหน่วยที่อิงตามไลบรารีและที่อิงตามแอปพลิเคชันใน macOS

• ios_unit_test เพื่อสร้างและเรียกใช้การทดสอบ 1 หน่วยที่อิงตามไลบรารีใน iOS

• ios_ui_test เพื่อสร้างและเรียกใช้การทดสอบอินเทอร์เฟซผู้ใช้ในโปรแกรมจำลอง iOS

• tvOS, watchOS และ visionOS ก็มีกฎการทดสอบที่คล้ายกัน

ระบุค่าสำหรับแอตทริบิวต์ minimum_os_version อย่างน้อย แม้ว่าแอตทริบิวต์การแพ็กเกจอื่นๆ เช่น bundle_identifier และ infoplists จะมีค่าเริ่มต้นเป็นค่าที่ใช้กันโดยทั่วไป แต่โปรดตรวจสอบว่าค่าเริ่มต้นเหล่านั้นเข้ากันได้กับโปรเจ็กต์และปรับค่าตามที่จำเป็น สำหรับเทสต์ที่ต้องใช้โปรแกรมจำลอง iOS ให้ระบุios_applicationชื่อเป้าหมายเป็นค่าของแอตทริบิวต์ test_host ด้วย

ขั้นตอนที่ 3ค: เพิ่มเป้าหมายห้องสมุด

เพิ่มobjc_library เป้าหมายสำหรับไลบรารี Objective-C แต่ละรายการ และswift_library เป้าหมายสำหรับไลบรารี Swift แต่ละรายการที่แอปพลิเคชันและ/หรือการทดสอบขึ้นอยู่ด้วย

เพิ่มเป้าหมายไลบรารีดังนี้

• เพิ่มเป้าหมายไลบรารีแอปพลิเคชันเป็นทรัพยากร Dependency ให้กับเป้าหมายแอปพลิเคชัน

• เพิ่มเป้าหมายไลบรารีทดสอบเป็นทรัพยากร Dependency ให้กับเป้าหมายทดสอบ

• ระบุแหล่งที่มาของการติดตั้งใช้งานในแอตทริบิวต์ srcs

• ระบุส่วนหัวในhdrsแอตทริบิวต์

หมายเหตุ: คุณสามารถใช้ฟังก์ชัน glob เพื่อรวมแหล่งที่มาและ/หรือส่วนหัวทั้งหมดของประเภทหนึ่งๆ โปรดใช้ด้วยความระมัดระวังเนื่องจากอาจมีไฟล์ที่คุณไม่ต้องการให้ Bazel สร้าง

คุณสามารถเรียกดูตัวอย่างที่มีอยู่สำหรับแอปพลิเคชันประเภทต่างๆ ได้โดยตรงในไดเรกทอรีตัวอย่าง rules_apple เช่น

• เป้าหมายแอปพลิเคชัน macOS

• เป้าหมายของแอปพลิเคชัน iOS

• แอปพลิเคชันแบบหลายแพลตฟอร์ม (macOS, iOS, watchOS, tvOS)

ดูข้อมูลเพิ่มเติมเกี่ยวกับกฎการสร้างได้ที่กฎของ Apple สำหรับ Bazel

ในตอนนี้ คุณควรทดสอบบิลด์โดยทำดังนี้

bazel build //:<application_target>

ขั้นตอนที่ 4: (ไม่บังคับ) แยกย่อยการสร้าง

หากโปรเจ็กต์มีขนาดใหญ่หรือขยายขนาดขึ้น ให้พิจารณาแบ่งโปรเจ็กต์ออกเป็นแพ็กเกจ Bazel หลายแพ็กเกจ การเพิ่มความละเอียดนี้จะช่วยให้คุณได้รับสิ่งต่อไปนี้

• เพิ่มการเพิ่มขึ้นของบิลด์

• เพิ่มการทำงานแบบคู่ขนานของงานบิลด์

• ดูแลรักษาได้ดีขึ้นสำหรับผู้ใช้ในอนาคต

• ควบคุมระดับการเข้าถึงซอร์สโค้ดในเป้าหมายและแพ็กเกจได้ดียิ่งขึ้น ซึ่งจะช่วยป้องกันปัญหาต่างๆ เช่น การรั่วไหลของรายละเอียดการติดตั้งใช้งานในไลบรารีไปยัง API สาธารณะ

เคล็ดลับในการแบ่งย่อยโปรเจ็กต์

• ใส่แต่ละไลบรารีในแพ็กเกจ Bazel ของตัวเอง เริ่มจากรายการที่ต้องมีการอ้างอิงน้อยที่สุด แล้วค่อยๆ ไล่ไปตามแผนผังการอ้างอิง

• เมื่อเพิ่มBUILDไฟล์และระบุเป้าหมาย ให้เพิ่มเป้าหมายใหม่เหล่านี้ลงในแอตทริบิวต์ depsของเป้าหมายที่ขึ้นอยู่กับเป้าหมายใหม่

• ฟังก์ชัน glob() จะไม่ข้ามขอบเขตของแพ็กเกจ ดังนั้นเมื่อจำนวนแพ็กเกจเพิ่มขึ้น ไฟล์ที่ตรงกับ glob() จะลดลง

• เมื่อเพิ่มไฟล์ BUILD ลงในไดเรกทอรี main ให้เพิ่มไฟล์ BUILD ลงในไดเรกทอรี test ที่เกี่ยวข้องด้วย

• บังคับใช้ขีดจำกัดการแสดงผลที่เหมาะสมในแพ็กเกจต่างๆ

• สร้างโปรเจ็กต์หลังจากการเปลี่ยนแปลงที่สำคัญแต่ละครั้งในไฟล์ BUILD และแก้ไข ข้อผิดพลาดในการสร้างเมื่อพบ

ขั้นตอนที่ 5: เรียกใช้บิลด์

เรียกใช้บิลด์ที่ย้ายข้อมูลทั้งหมดเพื่อให้แน่ใจว่าบิลด์จะเสร็จสมบูรณ์โดยไม่มีข้อผิดพลาดหรือคำเตือน เรียกใช้แอปพลิเคชันและเป้าหมายการทดสอบแต่ละรายการแยกกันเพื่อให้ค้นหาแหล่งที่มา ของข้อผิดพลาดที่เกิดขึ้นได้ง่ายขึ้น

เช่น

bazel build //:my-target

ขั้นตอนที่ 6: สร้างโปรเจ็กต์ Xcode ด้วย rules_xcodeproj

เมื่อสร้างด้วย Bazel ไฟล์ WORKSPACE และ BUILD จะกลายเป็นแหล่งข้อมูล ที่เชื่อถือได้เกี่ยวกับการบิลด์ หากต้องการให้ Xcode ทราบถึงเรื่องนี้ คุณต้องสร้างโปรเจ็กต์ Xcode ที่เข้ากันได้กับ Bazel โดยใช้ rules_xcodeproj

การแก้ปัญหา

ข้อผิดพลาดของ Bazel อาจเกิดขึ้นเมื่อไม่ซิงค์กับ Xcode เวอร์ชันที่เลือก เช่น เมื่อคุณใช้การอัปเดต ลองทำตามขั้นตอนต่อไปนี้หากคุณพบข้อผิดพลาดเกี่ยวกับ Xcode เช่น "ต้องระบุเวอร์ชัน Xcode เพื่อใช้ Apple CROSSTOOL"

• เรียกใช้ Xcode ด้วยตนเองและยอมรับข้อกำหนดและเงื่อนไข

• ใช้ Xcode select เพื่อระบุเวอร์ชันที่ถูกต้อง ยอมรับใบอนุญาต และ ล้างสถานะของ Bazel

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

• หากไม่ได้ผล คุณอาจลองเรียกใช้ bazel clean --expunge

หมายเหตุ: หากบันทึก Xcode ไว้ในเส้นทางอื่น คุณสามารถใช้ xcode-select -s เพื่อชี้ไปยังเส้นทางนั้นได้