Ninja kullanarak özel C/C++ derleme sistemlerini entegre edin (deneysel)

CMake veya ndk-build kullanmıyor ancak Android Gradle eklentisi (AGP) C/C++ derlemesi ve Android Studio'nun tam entegrasyonunu istiyorsanız derleme bilgilerini Ninja derleme dosyası biçiminde yazan bir kabuk komut dosyası oluşturarak özel bir C/C++ derleme sistemi oluşturabilirsiniz.

Özel C/C++ derleme sistemleri için deneysel destek, Android Studio ve AGP'ye eklendi. Bu özellik, Android Studio Dolphin | 2021.3.1 Canary 4 sürümünden itibaren kullanılabilir.

Genel Bakış

C/C++ projelerinde, özellikle de birden fazla platformu hedefleyen projelerde yaygın bir model, temel bir temsilden bu platformların her biri için proje oluşturmaktır. Bu kalıbın öne çıkan bir örneği CMake'tir. CMake, CMakeLists.txt dosyasında kaydedilen tek bir temel temsilden Android, iOS ve diğer platformlar için projeler oluşturabilir.

CMake, AGP tarafından doğrudan desteklenir ancak doğrudan desteklenmeyen başka proje oluşturucular da vardır:

Bu tür proje oluşturucular, C/C++ derlemesinin arka uç temsili olarak Ninja'yı destekler veya arka uç temsili olarak Ninja'yı oluşturacak şekilde uyarlanabilir.

Doğru şekilde yapılandırıldığında, entegre C/C++ proje sistemi oluşturucuya sahip bir AGP projesi, kullanıcıların şunları yapmasına olanak tanır:

  • Komut satırından ve Android Studio'dan derleme yapma

  • Android Studio'da tam dil hizmeti desteğiyle (ör. tanıma gitme) kaynakları düzenleyin.

  • Yerel ve karma işlemlerde hata ayıklamak için Android Studio hata ayıklayıcılarını kullanın.

Özel bir C/C++ derleme yapılandırma komut dosyası kullanmak için derlemenizi değiştirme

Bu bölümde, AGP'den özel bir C/C++ derleme yapılandırması komut dosyası kullanma adımları açıklanmaktadır.

1. adım: Modül düzeyindeki build.gradle dosyasını bir yapılandırma komut dosyasına referans verecek şekilde değiştirin

AGP'de Ninja desteğini etkinleştirmek için modül düzeyindeki build.gradle dosyasında experimentalProperties özelliğini yapılandırın:

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}"
       ]
     }
   }

Özellikler, AGP tarafından aşağıdaki gibi yorumlanır:

  • ninja.abiFilters, derlenecek ABI'lerin listesidir. Geçerli değerler: x86, x86-64, armeabi-v7a ve arm64-v8a.

  • ninja.path, bir C/C++ proje dosyasının yoludur. Bu dosyanın biçimi istediğiniz herhangi bir şey olabilir. Bu dosyada yapılan değişiklikler, Android Studio'da Gradle senkronizasyonu istemini tetikler.

  • ninja.configure, C/C++ projesini yapılandırmak gerektiğinde Gradle tarafından yürütülecek bir komut dosyası yoludur. Projeler ilk derleme sırasında, Android Studio'da Gradle senkronizasyonu yapılırken veya yapılandırma komut dosyası girişlerinden biri değiştiğinde yapılandırılır.

  • ninja.arguments, ninja.configure tarafından tanımlanan komut dosyasına iletilecek bağımsız değişkenlerin listesidir. Bu listedeki öğeler, değerleri AGP'deki mevcut yapılandırma bağlamına bağlı olan bir dizi makroya başvurabilir:

    • ${ndk.moduleMakeFile}, ninja.configure dosyasının tam yoludur. Örnekte bu değer C:\path\to\configure-ninja.bat olur.

    • ${ndk.variantName}, derlenmekte olan mevcut AGP değişkeninin adıdır. Örneğin, hata ayıklama veya yayınlama.

    • ${ndk.abi}, derlenmekte olan mevcut AGP ABI'nin adıdır. Örneğin, x86 veya arm64-v8a.

    • ${ndk.buildRoot}, AGP tarafından oluşturulan ve komut dosyasının çıkışını yazdığı bir klasörün adıdır. Bununla ilgili ayrıntılar 2. adım: Yapılandırma komut dosyasını oluşturma bölümünde açıklanacaktır.

    • ${ndk.ndkVersion}, kullanılacak NDK sürümüdür. Bu genellikle build.gradle dosyasında android.ndkVersion'a iletilen değer veya yoksa varsayılan değerdir.

    • ${ndk.minPlatform}, AGP tarafından istenen minimum hedef Android platformudur.

  • ninja.targets, derlenmesi gereken belirli Ninja hedeflerinin listesidir.

2. adım: Yapılandırma komut dosyasını oluşturun

Yapılandırma komut dosyasının (önceki örnekte configure-ninja.bat) minimum sorumluluğu, Ninja ile derlendiğinde projenin tüm yerel çıktılarını derleyip bağlayacak bir build.ninja dosyası oluşturmaktır. Bunlar genellikle .o (Nesne), .a (Arşiv) ve .so (Paylaşılan Nesne) dosyalarıdır.

Yapılandırma komut dosyası, ihtiyaçlarınıza bağlı olarak build.ninja dosyasını iki farklı yere yazabilir.

  • AGP'nin bir konum seçmesi uygunsa yapılandırma komut dosyası, ${ndk.buildRoot} makrosunda ayarlanan konuma build.ninja yazar.

  • Yapılandırma komut dosyasının build.ninja dosyasının konumunu seçmesi gerekiyorsa ${ndk.buildRoot} makrosunda ayarlanan konuma build.ninja.txt adlı bir dosya da yazar. Bu dosya, yapılandırma komut dosyasının yazdığı build.ninja dosyasının tam yolunu içerir.

build.ninja dosyasının yapısı

Genellikle Android C/C++ derlemesini doğru şekilde temsil eden çoğu yapı çalışır. AGP ve Android Studio için gereken temel öğeler şunlardır:

  • C/C++ kaynak dosyalarının listesi ve Clang'in bunları derlemek için ihtiyaç duyduğu işaretler.

  • Çıkış kitaplıklarının listesi. Bunlar genellikle .so (paylaşılan nesne) dosyalarıdır ancak .a (arşiv) veya yürütülebilir (uzantısız) dosyalar da olabilir.

build.ninja dosyası oluşturmayla ilgili örneklere ihtiyacınız varsa build.ninja oluşturucu kullanıldığında CMake'in çıktısına bakabilirsiniz.

Aşağıda, minimum düzeyde build.ninja şablonu örneği verilmiştir.

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

Öneriler

Şartlara (kaynak dosyaların ve çıkış kitaplıklarının listesi) ek olarak, aşağıda bazı öneriler verilmiştir.

phony kurallarıyla adlandırılmış çıkışları bildirme

Mümkün olduğunda, derleme çıktılarına kullanıcılar tarafından okunabilir adlar vermek için build.ninja yapısının phony kurallarını kullanması önerilir. Örneğin, c:/path/to/lib.so adlı bir çıkışınız varsa buna aşağıdaki gibi okunabilir bir ad verebilirsiniz.

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

Bunu yapmanın avantajı, bu adı build.gradle dosyasında derleme hedefi olarak belirtebilmenizdir. Örneğin:

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

"Tümü" hedefi belirtme

Bir all hedefi belirttiğinizde bu, build.gradle dosyasında açıkça belirtilen bir hedef olmadığında AGP tarafından oluşturulan varsayılan kitaplık grubu olur.

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

Alternatif bir derleme yöntemi belirtme (isteğe bağlı)

Daha gelişmiş bir kullanım alanı, Ninja tabanlı olmayan mevcut bir derleme sistemini sarmalamaktır. Bu durumda, Android Studio'nun otomatik tamamlama ve tanıma gitme gibi uygun dil hizmeti özelliklerini sunabilmesi için tüm kaynakları işaretleriyle birlikte çıkış kitaplıklarıyla temsil etmeniz gerekir. Ancak AGP'nin, asıl derleme sırasında temel derleme sistemine uymasını istiyorsunuz.

Bunu yapmak için belirli bir uzantıya sahip Ninja derleme çıkışını kullanabilirsiniz .passthrough.

Daha somut bir örnek vermek gerekirse MSBuild'i sarmalamak için yapılandırma komut dosyanız her zamanki gibi build.ninja oluşturur ancak AGP'nin MSBuild'i nasıl çağıracağını tanımlayan bir geçiş hedefi de ekler.

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

Geri bildirim gönder

Bu özellik deneysel olduğundan geri bildirimleriniz bizim için çok önemlidir. Aşağıdaki kanallardan geri bildirimde bulunabilirsiniz:

  • Genel geri bildirim için ilgili hataya yorum ekleyin.

  • Hata bildirmek için Android Studio'yu açıp Help > Submit Feedback'i (Yardım > Geri Bildirim Gönder) tıklayın. Hatanın yönlendirilmesine yardımcı olmak için "Özel C/C++ Derleme Sistemleri"ne başvurduğunuzdan emin olun.

  • Android Studio yüklü değilse hata şablonunu kullanarak hata bildiriminde bulunabilirsiniz.