ผสานรวมระบบสร้าง C/C++ ที่กำหนดเองโดยใช้ Ninja (ทดลอง)

หากคุณไม่ได้ใช้ CMake หรือ ndk-build แต่ต้องการผสานรวมบิลด์ C/C++ ของปลั๊กอิน Android Gradle (AGP) และ Android Studio อย่างเต็มรูปแบบ คุณสามารถสร้างระบบบิลด์ C/C++ ที่กำหนดเองได้โดยสร้างสคริปต์ของ Shell ที่เขียนข้อมูลบิลด์ในรูปแบบไฟล์บิลด์ Ninja

เราได้เพิ่มการรองรับเวอร์ชันทดลองสำหรับระบบบิลด์ C/C++ ที่กำหนดเองลงใน Android Studio และ AGP ฟีเจอร์นี้พร้อมใช้งานตั้งแต่ Android Studio Dolphin | 2021.3.1 Canary 4 เป็นต้นไป

ภาพรวม

รูปแบบที่พบบ่อยสำหรับโปรเจ็กต์ C/C++ โดยเฉพาะโปรเจ็กต์ที่กำหนดเป้าหมายเป็นหลายแพลตฟอร์ม คือการสร้างโปรเจ็กต์สำหรับแต่ละแพลตฟอร์มเหล่านั้นจากการนำเสนอที่สำคัญบางอย่าง ตัวอย่างที่โดดเด่นของรูปแบบนี้คือ CMake CMake สามารถสร้างโปรเจ็กต์สำหรับ Android, iOS และแพลตฟอร์มอื่นๆ จากการนำเสนอพื้นฐานเดียวที่บันทึกไว้ในไฟล์ CMakeLists.txt

แม้ว่า AGP จะรองรับ CMake โดยตรง แต่ก็มีเครื่องมือสร้างโปรเจ็กต์อื่นๆ ที่ไม่รองรับโดยตรง ดังนี้

  • Premake

  • gn

  • Sharpmake

  • GENie

  • เครื่องมือสร้างโปรเจ็กต์ที่สร้างขึ้นเองแบบส่วนตัว

เครื่องมือสร้างโปรเจ็กต์ประเภทนี้รองรับ Ninja เป็นการแสดงแบ็กเอนด์ของบิลด์ C/C++ หรือสามารถปรับให้สร้าง Ninja เป็นการแสดงแบ็กเอนด์ได้

เมื่อกำหนดค่าอย่างถูกต้อง โปรเจ็กต์ AGP ที่มีเครื่องมือสร้างระบบโปรเจ็กต์ C/C++ ในตัวจะช่วยให้ผู้ใช้ทำสิ่งต่อไปนี้ได้

  • สร้างจากบรรทัดคำสั่งและ Android Studio

  • แก้ไขแหล่งที่มาด้วยการรองรับบริการด้านภาษาอย่างเต็มรูปแบบ (เช่น ไปที่คำจำกัดความ) ใน Android Studio

  • ใช้โปรแกรมแก้ไขข้อบกพร่องของ Android Studio เพื่อแก้ไขข้อบกพร่องของกระบวนการแบบเนทีฟและแบบผสม

วิธีแก้ไขบิลด์เพื่อใช้สคริปต์การกำหนดค่าบิลด์ C/C++ ที่กำหนดเอง

ส่วนนี้จะอธิบายขั้นตอนการใช้สคริปต์การกำหนดค่าบิลด์ C/C++ ที่กำหนดเองจาก AGP

ขั้นตอนที่ 1: แก้ไขไฟล์ build.gradle ระดับโมดูลเพื่ออ้างอิงสคริปต์การกำหนดค่า

หากต้องการเปิดใช้การรองรับ Ninja ใน AGP ให้กำหนดค่า experimentalProperties ในไฟล์ build.gradle ระดับโมดูล ดังนี้

android {
  defaultConfig {
    externalNativeBuild {
      experimentalProperties["ninja.abiFilters"] = [ "x86", "arm64-v8a" ]
      experimentalProperties["ninja.path"] = "source-file-list.txt"
      experimentalProperties["ninja.configure"] = "configure-ninja"
      experimentalProperties["ninja.arguments"] = [
            "\${ndk.moduleMakeFile}",
            "--variant=\${ndk.variantName}",
            "--abi=Android-\${ndk.abi}",
            "--configuration-dir=\${ndk.configurationDir}",
            "--ndk-version=\${ndk.moduleNdkVersion}",
            "--min-sdk-version=\${ndk.minSdkVersion}"
       ]
     }
   }

AGP จะตีความพร็อพเพอร์ตี้ดังนี้

  • ninja.abiFilters คือรายการ ABI ที่จะสร้าง ค่าที่ถูกต้องคือ x86, x86-64, armeabi-v7a และ arm64-v8a

  • ninja.path คือเส้นทางไปยังไฟล์โปรเจ็กต์ C/C++ รูปแบบของไฟล์นี้จะเป็นอะไรก็ได้ตามต้องการ การเปลี่ยนแปลงในไฟล์นี้จะทริกเกอร์ข้อความแจ้งให้ซิงค์ Gradle ใน Android Studio

  • ninja.configure คือเส้นทางไปยังไฟล์สคริปต์ที่ Gradle จะเรียกใช้เมื่อจำเป็นต้องกำหนดค่าโปรเจ็กต์ C/C++ ระบบจะกำหนดค่าโปรเจ็กต์ในบิลด์แรก ระหว่างการซิงค์ Gradle ใน Android Studio หรือเมื่ออินพุตสคริปต์การกำหนดค่ารายการใดรายการหนึ่งมีการเปลี่ยนแปลง

  • ninja.arguments คือรายการอาร์กิวเมนต์ที่จะส่งไปยังสคริปต์ที่กำหนดโดย ninja.configure องค์ประกอบในรายการนี้สามารถอ้างอิงชุดมาโครที่มีค่าขึ้นอยู่กับบริบทการกำหนดค่าปัจจุบันใน AGP ได้ ดังนี้

    • ${ndk.moduleMakeFile} คือเส้นทางแบบเต็มไปยังไฟล์ ninja.configure ดังนั้นในตัวอย่างนี้จะเป็น C:\path\to\configure-ninja.bat

    • ${ndk.variantName} คือชื่อของตัวแปร AGP ปัจจุบันที่กำลังสร้าง เช่น การแก้ไขข้อบกพร่องหรือการเผยแพร่

    • ${ndk.abi} คือชื่อของ AGP ABI ปัจจุบันที่กำลังสร้าง เช่น x86 หรือ arm64-v8a

    • ${ndk.buildRoot} คือชื่อโฟลเดอร์ที่ AGP สร้างขึ้น ซึ่งสคริปต์จะเขียนเอาต์พุตลงในโฟลเดอร์นี้ รายละเอียดเกี่ยวกับเรื่องนี้จะอธิบายไว้ในขั้นตอนที่ 2: สร้างสคริปต์การกำหนดค่า

    • ${ndk.ndkVersion} คือเวอร์ชันของ NDK ที่จะใช้ โดยปกติแล้วค่านี้จะเป็นค่าที่ส่งไปยัง android.ndkVersion ในไฟล์ build.gradle หรือค่าเริ่มต้นหากไม่มีค่าใดๆ

    • ${ndk.minPlatform} คือแพลตฟอร์ม Android เป้าหมายขั้นต่ำที่ AGP ขอ

  • ninja.targets คือรายการเป้าหมาย Ninja ที่เฉพาะเจาะจงที่ควรสร้าง

ขั้นตอนที่ 2: สร้างสคริปต์การกำหนดค่า

หน้าที่ขั้นต่ำของสคริปต์การกำหนดค่า (configure-ninja.bat ในตัวอย่างก่อนหน้านี้) คือการสร้างไฟล์ build.ninja ซึ่งเมื่อสร้างด้วย Ninja จะคอมไพล์และลิงก์เอาต์พุตเนทีฟทั้งหมดของโปรเจ็กต์ โดยปกติแล้วจะเป็นไฟล์ .o (ออบเจ็กต์), .a (ที่เก็บถาวร) และ .so (ออบเจ็กต์ที่แชร์)

สคริปต์การกำหนดค่าสามารถเขียนไฟล์ build.ninja ได้ใน 2 ตำแหน่งที่แตกต่างกัน โดยขึ้นอยู่กับความต้องการของคุณ

  • หาก AGP เลือกตำแหน่งได้ สคริปต์การกำหนดค่าจะเขียน build.ninja ที่ตำแหน่งที่ตั้งไว้ในมาโคร ${ndk.buildRoot}

  • หากสคริปต์การกำหนดค่าต้องเลือกตำแหน่งของไฟล์ build.ninja สคริปต์จะเขียนไฟล์ชื่อ build.ninja.txt ที่ตำแหน่งที่ตั้งไว้ในมาโคร ${ndk.buildRoot} ด้วย ไฟล์นี้มีเส้นทางแบบเต็มไปยังไฟล์ build.ninja ที่สคริปต์การกำหนดค่าเขียนไว้

โครงสร้างของไฟล์ build.ninja

โดยทั่วไปแล้ว โครงสร้างส่วนใหญ่ที่แสดงบิลด์ Android C/C++ อย่างถูกต้องจะใช้งานได้ องค์ประกอบหลักที่ AGP และ Android Studio ต้องการมีดังนี้

  • รายการไฟล์ต้นฉบับ C/C++ พร้อมด้วยแฟล็กที่ Clang ต้องใช้ในการคอมไพล์

  • รายการไลบรารีเอาต์พุต โดยปกติแล้วไฟล์เหล่านี้จะเป็นไฟล์ .so (ออบเจ็กต์ที่แชร์) แต่ก็อาจเป็นไฟล์ .a (ที่เก็บถาวร) หรือไฟล์ปฏิบัติการ (ไม่มีนามสกุล) ได้เช่นกัน

หากต้องการตัวอย่างวิธีสร้างไฟล์ build.ninja คุณสามารถดูเอาต์พุตของ CMake เมื่อใช้โปรแกรมสร้าง build.ninja

ตัวอย่างเทมเพลต build.ninja ขั้นต่ำมีดังนี้

rule COMPILE
   command = /path/to/ndk/clang -c $in -o $out {other flags}
rule LINK
   command = /path/to/ndk/clang $in -o $out {other flags}

build source.o : COMPILE source.cpp
build lib.so : LINK source.o

คำแนะนำ

นอกเหนือจากข้อกำหนด (รายการไฟล์ต้นฉบับและไลบรารีเอาต์พุต) แล้ว เรายังมีคำแนะนำบางอย่างดังนี้

ประกาศเอาต์พุตที่มีชื่อด้วยกฎ phony

หากเป็นไปได้ ขอแนะนำให้โครงสร้าง build.ninja ใช้กฎ phony เพื่อให้เอาต์พุตของบิลด์มีชื่อที่มนุษย์อ่านได้ เช่น หากคุณมีเอาต์พุตชื่อ c:/path/to/lib.so คุณสามารถตั้งชื่อที่มนุษย์อ่านได้ดังนี้

build curl: phony /path/to/lib.so

ประโยชน์ของการทำเช่นนี้คือคุณสามารถระบุชื่อนี้เป็นเป้าหมายบิลด์ในไฟล์ build.gradle ได้ เช่น

android {
  defaultConfig {
    externalNativeBuild {
      ...
      experimentalProperties["ninja.targets"] = [ "curl" ]

ระบุเป้าหมาย "ทั้งหมด"

เมื่อคุณระบุเป้าหมาย all ชุดไลบรารีเริ่มต้นที่ AGP สร้างขึ้นจะเป็นชุดนี้เมื่อไม่มีการระบุเป้าหมายอย่างชัดเจนในไฟล์ build.gradle

rule COMPILE
   command = /path/to/ndk/clang $in -o $out {other flags}
rule LINK
   command = /path/to/ndk/clang $in -o $out {other flags}

build foo.o : COMPILE foo.cpp
build bar.o : COMPILE bar.cpp
build libfoo.so : LINK foo.o
build libbar.so : LINK bar.o
build all: phony libfoo.so libbar.so

ระบุวิธีการสร้างทางเลือก (ไม่บังคับ)

กรณีการใช้งานขั้นสูงขึ้นคือการรวมระบบบิลด์ที่มีอยู่ซึ่งไม่ได้ใช้ Ninja ในกรณีนี้ คุณยังคงต้องแสดงแหล่งที่มาทั้งหมดพร้อมแฟล็กและไลบรารีเอาต์พุต เพื่อให้ Android Studio แสดงฟีเจอร์บริการภาษาที่เหมาะสม เช่น การเติมข้อความอัตโนมัติและคำจำกัดความของ Go-To อย่างไรก็ตาม คุณต้องการให้ AGP เลื่อนการทำงานไปยังระบบบิลด์ที่เกี่ยวข้องในระหว่างการบิลด์จริง

ซึ่งทำได้โดยใช้เอาต์พุตบิลด์ Ninja ที่มีส่วนขยาย .passthrough ที่เฉพาะเจาะจง

ตัวอย่างที่เป็นรูปธรรมมากขึ้นคือ หากต้องการรวม MSBuild สคริปต์การกำหนดค่าจะสร้าง build.ninja ตามปกติ แต่จะเพิ่มเป้าหมายแบบพาสทรูที่กำหนดวิธีที่ AGP จะเรียกใช้ MSBuild ด้วย

rule COMPILE
   command = /path/to/ndk/clang $in -o $out {other flags}
rule LINK
   command = /path/to/ndk/clang $in -o $out {other flags}

rule MBSUILD_CURL
  command = /path/to/msbuild {flags to build curl with MSBuild}

build source.o : COMPILE source.cpp
build lib.so : LINK source.o
build curl : phony lib.so
build curl.passthrough : MBSUILD_CURL

แสดงความคิดเห็น

ฟีเจอร์นี้ยังอยู่ระหว่างการทดสอบ เราจึงยินดีรับฟังความคิดเห็นจากคุณเป็นอย่างยิ่ง คุณแสดงความคิดเห็นได้ผ่านช่องทางต่อไปนี้

  • สำหรับความคิดเห็นทั่วไป ให้เพิ่มความคิดเห็นในข้อบกพร่องที่เกี่ยวข้อง

  • หากต้องการรายงานข้อบกพร่อง ให้เปิด Android Studio แล้วคลิกความช่วยเหลือ > ส่งความคิดเห็น โปรดอ้างอิง "ระบบบิลด์ C/C++ ที่กำหนดเอง" เพื่อช่วยระบุข้อบกพร่อง

  • หากต้องการรายงานข้อบกพร่องในกรณีที่ไม่ได้ติดตั้ง Android Studio ให้รายงานข้อบกพร่องโดยใช้เทมเพลตข้อบกพร่อง