CMake derleme komut dosyası, CMakeLists.txt olarak adlandırmanız gereken düz metin dosyasıdır ve CMake'in C/C++ kitaplıklarınızı derlemek için kullandığı komutları içerir. Yerel kaynaklarınızda CMake derleme komut dosyası yoksa kendiniz bir tane oluşturmanız ve uygun CMake komutlarını eklemeniz gerekir. CMake'i nasıl yükleyeceğinizi öğrenmek için NDK ve CMake'i yükleme ve yapılandırma başlıklı makaleyi inceleyin.
Bu bölümde, yerel kitaplığınızı oluştururken CMake'e hangi kaynakları kullanacağını söylemek için derleme komut dosyanıza eklemeniz gereken bazı temel komutlar ele alınmaktadır. Daha fazla bilgi edinmek için CMake komutları ile ilgili resmi belgeleri okuyun.
Yeni bir CMake derleme komut dosyası yapılandırdıktan sonra, Gradle'ın yerel kitaplığınızı uygulamanızın APK'sıyla derleyip paketlemesi için CMake projenizi derleme bağımlılığı olarak içerecek şekilde Gradle'ı yapılandırmanız gerekir.
Not: Projeniz ndk-build kullanıyorsa CMake derleme komut dosyası oluşturmanız gerekmez. Android.mk dosyanızın yolunu sağlayarak mevcut yerel kitaplık projenizi dahil etmek için Gradle'ı yapılandırmanız yeterlidir.
CMake derleme komut dosyası oluşturma
CMake derleme komut dosyanız olarak kullanabileceğiniz bir düz metin dosyası oluşturmak için aşağıdaki adımları uygulayın:
- IDE'nin sol tarafındaki Project (Proje) bölmesini açın ve açılır menüden Project (Proje) görünümünü seçin.
- your-module kök dizinini sağ tıklayın ve Yeni > Dosya'yı seçin.
Not: Derleme komut dosyasını istediğiniz konumda oluşturabilirsiniz. Ancak derleme komut dosyasını yapılandırırken yerel kaynak dosyalarınızın ve kitaplıklarınızın yolları, derleme komut dosyasının konumuna göre belirlenir.
- Dosya adı olarak "CMakeLists.txt" yazın ve OK'i (Tamam) tıklayın.
Artık CMake komutları ekleyerek derleme komut dosyanızı yapılandırabilirsiniz. CMake'e yerel kaynak kodundan yerel bir kitaplık oluşturma talimatı vermek için derleme komut dosyanıza cmake_minimum_required() ve add_library() komutlarını ekleyin:
# Sets the minimum version of CMake required to build your native library.
# This ensures that a certain set of CMake features is available to
# your build.
cmake_minimum_required(VERSION 3.4.1)
# Specifies a library name, specifies whether the library is STATIC or
# SHARED, and provides relative paths to the source code. You can
# define multiple libraries by adding multiple add_library() commands,
# and CMake builds them for you. When you build your app, Gradle
# automatically packages shared libraries with your APK.
add_library( # Specifies the name of the library.
native-lib
# Sets the library as a shared library.
SHARED
# Provides a relative path to your source file(s).
src/main/cpp/native-lib.cpp )
İpucu: CMake'e kaynak dosyalardan yerel kitaplık oluşturmasını söyleyebildiğiniz gibi, add_executable() komutunu kullanarak CMake'e bu kaynak dosyalardan yürütülebilir dosya oluşturmasını da söyleyebilirsiniz. Ancak yerel kaynaklarınızdan yürütülebilir dosyalar oluşturmak isteğe bağlıdır ve APK'nızda paketlenecek yerel kitaplıklar oluşturmak çoğu proje şartını karşılar.
add_library() kullanarak CMake derleme komut dosyanıza bir kaynak dosya veya kitaplık eklediğinizde Android Studio, projenizi senkronize ettikten sonra ilişkili üstbilgi dosyalarını da Proje görünümünde gösterir. Ancak CMake'in derleme süresi boyunca üst dosyalarınızı bulabilmesi için CMake derleme komut dosyanıza include_directories() komutunu eklemeniz ve üst dosyalarınızın yolunu belirtmeniz gerekir:
add_library(...) # Specifies a path to native header files. include_directories(src/main/cpp/include/)
CMake'in kitaplığınızın dosyasını adlandırmak için kullandığı kural aşağıdaki gibidir:
liblibrary-name.so
Örneğin, derleme komut dosyasında paylaşılan kitaplığınızın adını "native-lib" olarak belirtirseniz CMake, libnative-lib.so adlı bir dosya oluşturur. Ancak bu kitaplığı Java veya Kotlin kodunuza yüklerken CMake derleme komut dosyasında belirttiğiniz adı kullanın:
companion object { init { System.loadLibrary("native-lib") } }
Not: CMake derleme komut dosyanızdaki bir kitaplığı yeniden adlandırır veya kaldırırsanız Gradle değişiklikleri uygulamadan ya da kitaplığın eski sürümünü APK'nızdan kaldırmadan önce projenizi temizlemeniz gerekir. Projenizi temizlemek için menü çubuğundan Build > Clean Project'i (Derle > Projeyi Temizle) seçin.
Android Studio, kaynak dosyaları ve başlıkları Proje bölmesindeki cpp grubuna otomatik olarak ekler. Birden fazla add_library() komutu kullanarak CMake'in diğer kaynak dosyalardan derlemesi için ek kitaplıklar tanımlayabilirsiniz.
NDK API'leri ekleme
Android NDK, faydalı bulabileceğiniz bir dizi yerel API ve kitaplık sağlar. Projenizin CMakeLists.txt komut dosyasına NDK kitaplıklarını ekleyerek bu API'lerden herhangi birini kullanabilirsiniz.
Önceden derlenmiş NDK kitaplıkları Android platformunda zaten mevcut olduğundan bunları derlemeniz veya APK'nıza paketlemeniz gerekmez. NDK kitaplıkları zaten CMake'in arama yolunun bir parçası olduğundan, yerel NDK yüklemenizde kitaplığın konumunu belirtmeniz bile gerekmez. CMake'e yalnızca kullanmak istediğiniz kitaplığın adını vermeniz ve bunu kendi yerel kitaplığınıza bağlamanız yeterlidir.
Bir NDK kitaplığını bulmak ve yolunu değişken olarak depolamak için CMake derleme komut dosyanıza find_library() komutunu ekleyin. Bu değişkeni, derleme komut dosyasının diğer bölümlerinde NDK kitaplığına başvurmak için kullanırsınız.
Aşağıdaki örnekte, Android'e özgü günlük destek kitaplığı bulunur ve yolu log-lib içinde depolanır:
find_library( # Defines the name of the path variable that stores the
# location of the NDK library.
log-lib
# Specifies the name of the NDK library that
# CMake needs to locate.
log )
Yerel kitaplığınızın log kitaplığındaki işlevleri çağırabilmesi için CMake derleme komut dosyanızda target_link_libraries() komutunu kullanarak kitaplıkları bağlamanız gerekir:
find_library(...)
# Links your native library against one or more other native libraries.
target_link_libraries( # Specifies the target library.
native-lib
# Links the log library to the target library.
${log-lib} )
NDK, yerel kitaplığınızı oluşturmak ve bağlamak için ihtiyaç duyduğunuz bazı kitaplıkları kaynak kodu olarak da içerir. CMake derleme komut dosyanızda add_library() komutunu kullanarak kaynak kodunu yerel bir kitaplıkta derleyebilirsiniz. Yerel NDK kitaplığınıza giden bir yol sağlamak için Android Studio'nun sizin için otomatik olarak tanımladığı ANDROID_NDK yol değişkenini kullanabilirsiniz.
Aşağıdaki komut, CMake'e NativeActivity yaşam döngüsü etkinliklerini ve dokunmatik girişi yöneten android_native_app_glue.c öğesini statik bir kitaplıkta derlemesini ve native-lib öğesine bağlamasını söyler:
add_library( app-glue
STATIC
${ANDROID_NDK}/sources/android/native_app_glue/android_native_app_glue.c )
# You need to link static libraries against your shared native library.
target_link_libraries( native-lib app-glue ${log-lib} )
Önceden oluşturulmuş diğer kitaplıkları ekleme
Önceden derlenmiş bir kitaplık eklemek, CMake'in derlemesi için başka bir yerel kitaplık belirtmeye benzer. Ancak kitaplık zaten oluşturulduğundan CMake'e yalnızca kitaplığı projenize aktarmak istediğinizi bildirmek için IMPORTED işaretini kullanmanız gerekir:
add_library( imported-lib
SHARED
IMPORTED )
Ardından, aşağıda gösterildiği gibi set_target_properties() komutunu kullanarak kitaplığın yolunu belirtmeniz gerekir.
Bazı kitaplıklar, belirli CPU mimarileri veya Uygulama İkili Arabirimleri (ABI) için ayrı paketler sunar ve bunları ayrı dizinlerde düzenler. Bu yaklaşım, kitaplıkların belirli CPU mimarilerinden yararlanmasına yardımcı olurken yalnızca istediğiniz kitaplık sürümlerini kullanmanıza olanak tanır. Kitaplığın her sürümü için birden fazla komut yazmak zorunda kalmadan CMake derleme komut dosyanıza bir kitaplığın birden fazla ABI sürümünü eklemek için ANDROID_ABI yol değişkenini kullanabilirsiniz. Bu değişken, NDK'nin desteklediği varsayılan ABI'lerin listesini veya Gradle'ı kullanmak üzere manuel olarak yapılandırdığınız ABI'lerin filtrelenmiş bir listesini kullanır. Örneğin:
add_library(...)
set_target_properties( # Specifies the target library.
imported-lib
# Specifies the parameter you want to define.
PROPERTIES IMPORTED_LOCATION
# Provides the path to the library you want to import.
imported-lib/src/${ANDROID_ABI}/libimported-lib.so )
CMake'in derleme süresi sırasında üstbilgi dosyalarınızı bulması için include_directories() komutunu kullanmanız ve üstbilgi dosyalarınızın yolunu eklemeniz gerekir:
include_directories( imported-lib/include/ )
Not: Derleme zamanı bağımlılığı olmayan önceden derlenmiş bir kitaplığı paketlemek istiyorsanız (örneğin, imported-lib bağımlılığı olan önceden derlenmiş bir kitaplık eklerken) kitaplığı bağlamak için aşağıdaki talimatları uygulamanız gerekmez.
Önceden oluşturulmuş kitaplığı kendi yerel kitaplığınıza bağlamak için CMake derleme komut dosyanızdaki target_link_libraries() komutuna ekleyin:
target_link_libraries( native-lib imported-lib app-glue ${log-lib} )
Önceden derlenmiş kitaplığı APK'nıza paketlemek için .so dosyanızın yolunu içerecek şekilde sourceSets bloğuyla Gradle'ı manuel olarak yapılandırmanız gerekir. APK'nızı oluşturduktan sonra APK Analyzer'ı kullanarak Gradle'ın APK'nızda hangi kitaplıkları paketlediğini doğrulayabilirsiniz.
Diğer CMake projelerini dahil etme
Birden fazla CMake projesi oluşturmak ve bunların çıkışlarını Android projenize dahil etmek istiyorsanız üst düzey CMake derleme komut dosyası olarak bir CMakeLists.txt dosyası kullanabilir (Gradle'a bağladığınız dosya) ve ek CMake projelerini bu derleme komut dosyasının bağımlılıkları olarak ekleyebilirsiniz. Aşağıdaki üst düzey CMake derleme komut dosyası, başka bir CMakeLists.txt dosyasını derleme bağımlılığı olarak belirtmek için add_subdirectory() komutunu kullanır ve ardından diğer önceden derlenmiş kitaplıklarda olduğu gibi çıkışına bağlanır.
# Sets lib_src_DIR to the path of the target CMake project.
set( lib_src_DIR ../gmath )
# Sets lib_build_DIR to the path of the desired output directory.
set( lib_build_DIR ../gmath/outputs )
file(MAKE_DIRECTORY ${lib_build_DIR})
# Adds the CMakeLists.txt file located in the specified directory
# as a build dependency.
add_subdirectory( # Specifies the directory of the CMakeLists.txt file.
${lib_src_DIR}
# Specifies the directory for the build outputs.
${lib_build_DIR} )
# Adds the output of the additional CMake build as a prebuilt static
# library and names it lib_gmath.
add_library( lib_gmath STATIC IMPORTED )
set_target_properties( lib_gmath PROPERTIES IMPORTED_LOCATION
${lib_build_DIR}/${ANDROID_ABI}/lib_gmath.a )
include_directories( ${lib_src_DIR}/include )
# Links the top-level CMake build output against lib_gmath.
target_link_libraries( native-lib ... lib_gmath )
Komut satırından CMake'i çağırma
Android Studio dışında bir Ninja projesi oluşturmak üzere CMake'i çağırmak için aşağıdaki komutu kullanın:
cmake
-Hpath/to/cmakelists/folder
-Bpath/to/generated/ninja/project/debug/ABI
-DANDROID_ABI=ABI // For example, arm64-v8a
-DANDROID_PLATFORM=platform-version-string // For example, android-16
-DANDROID_NDK=android-sdk/ndk/ndk-version
-DCMAKE_TOOLCHAIN_FILE=android-sdk/ndk/ndk-version/build/cmake/android.toolchain.cmake
-G Ninja
Bu komut, Android yürütülebilir kitaplıkları (.so dosyaları) oluşturmak için yürütülebilecek Ninja projesini oluşturur. NDK'nin CMake desteğini kullanmak için CMAKE_TOOLCHAIN_FILE gereklidir. CMake 3.21 veya sonraki sürümlerde, CMake'in yerleşik NDK desteği kullanılabilir ancak CMake'in Android için Çapraz Derleme dokümanlarında açıklandığı gibi farklı bir değişken grubu kullanılmalıdır.