Skrypt kompilacji CMake to zwykły plik tekstowy, który musisz nazwać CMakeLists.txt i który zawiera polecenia używane przez CMake do kompilowania bibliotek C/C++. Jeśli Twoje źródła natywne nie mają jeszcze skryptu kompilacji CMake, musisz go utworzyć i uwzględnić odpowiednie polecenia CMake. Aby dowiedzieć się, jak zainstalować CMake, przeczytaj artykuł Instalowanie i konfigurowanie NDK i CMake.
W tej sekcji znajdziesz kilka podstawowych poleceń, które należy uwzględnić w skrypcie kompilacji, aby poinformować CMake, których źródeł ma używać podczas tworzenia biblioteki natywnej. Więcej informacji znajdziesz w oficjalnej dokumentacji dotyczącej poleceń CMake.
Po skonfigurowaniu nowego skryptu kompilacji CMake musisz skonfigurować Gradle, aby uwzględniał projekt CMake jako zależność kompilacji, dzięki czemu Gradle będzie kompilować i pakować bibliotekę natywną z pakietem APK aplikacji.
Uwaga: jeśli Twój projekt używa ndk-build, nie musisz tworzyć skryptu kompilacji CMake. Możesz po prostu skonfigurować Gradle, aby uwzględnić istniejący projekt biblioteki natywnej, podając ścieżkę do pliku Android.mk.
Tworzenie skryptu kompilacji CMake
Aby utworzyć plik zwykłego tekstu, którego możesz użyć jako skryptu kompilacji CMake, wykonaj te czynności:
- Otwórz panel Project (Projekt) po lewej stronie IDE i wybierz widok Project (Projekt) z menu.
- Kliknij prawym przyciskiem myszy katalog główny your-module i wybierz New > File (Nowy > Plik).
Uwaga: skrypt kompilacji możesz utworzyć w dowolnej lokalizacji. Jednak podczas konfigurowania skryptu kompilacji ścieżki do natywnych plików źródłowych i bibliotek są względne względem lokalizacji skryptu kompilacji.
- Wpisz „CMakeLists.txt” jako nazwę pliku i kliknij OK.
Możesz teraz skonfigurować skrypt kompilacji, dodając polecenia CMake. Aby CMake utworzył bibliotekę natywną z natywnego kodu źródłowego, dodaj do skryptu kompilacji polecenia cmake_minimum_required() i add_library():
# 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 )
Wskazówka: podobnie jak w przypadku polecenia CMake, które tworzy bibliotekę natywną z plików źródłowych, możesz użyć polecenia add_executable(), aby CMake utworzył z tych plików źródłowych plik wykonywalny. Jednak tworzenie plików wykonywalnych z natywnych źródeł jest opcjonalne, a tworzenie bibliotek natywnych do spakowania w pliku APK spełnia większość wymagań projektu.
Gdy dodasz plik źródłowy lub bibliotekę do skryptu kompilacji CMake za pomocą add_library(), Android Studio po zsynchronizowaniu projektu wyświetli też powiązane pliki nagłówka w widoku Projekt. Aby jednak CMake mógł znaleźć pliki nagłówka podczas kompilowania, musisz dodać do skryptu kompilacji CMake polecenie include_directories() i określić ścieżkę do nagłówków:
add_library(...) # Specifies a path to native header files. include_directories(src/main/cpp/include/)
Konwencja, której CMake używa do nazywania pliku biblioteki, jest następująca:
liblibrary-name.so
Jeśli na przykład w skrypcie kompilacji jako nazwę biblioteki udostępnionej podasz „native-lib”, CMake utworzy plik o nazwie libnative-lib.so. Jednak podczas wczytywania tej biblioteki w kodzie Java lub Kotlin użyj nazwy określonej w skrypcie kompilacji CMake:
companion object { init { System.loadLibrary("native-lib") } }
Uwaga: jeśli zmienisz nazwę biblioteki lub usuniesz ją w skrypcie kompilacji CMake, musisz wyczyścić projekt, zanim Gradle zastosuje zmiany lub usunie starszą wersję biblioteki z pliku APK. Aby wyczyścić projekt, na pasku menu kliknij Build > Clean Project (Kompilacja > Wyczyść projekt).
Android Studio automatycznie dodaje pliki źródłowe i nagłówki do grupy cpp w panelu Projekt. Używając wielu poleceń add_library(), możesz zdefiniować dodatkowe biblioteki, które CMake ma utworzyć z innych plików źródłowych.
Dodawanie interfejsów API NDK
Android NDK udostępnia zestaw natywnych interfejsów API i bibliotek, które mogą być przydatne. Możesz używać dowolnego z tych interfejsów API, dołączając biblioteki NDK do pliku skryptu CMakeLists.txt projektu.
Gotowe biblioteki NDK są już dostępne na platformie Androida, więc nie musisz ich tworzyć ani pakować do pliku APK. Biblioteki NDK są już częścią ścieżki wyszukiwania CMake, więc nie musisz nawet określać lokalizacji biblioteki w lokalnej instalacji NDK – wystarczy, że podasz CMake nazwę biblioteki, której chcesz użyć, i połączysz ją z własną biblioteką natywną.
Dodaj polecenie find_library() do skryptu kompilacji CMake, aby zlokalizować bibliotekę NDK i zapisać jej ścieżkę jako zmienną. Za pomocą tej zmiennej możesz odwoływać się do biblioteki NDK w innych częściach skryptu kompilacji.
Poniższy przykład lokalizuje bibliotekę obsługi logów na Androida i zapisuje jej ścieżkę w zmiennej log-lib:
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 )
Aby biblioteka natywna mogła wywoływać funkcje w bibliotece log, musisz połączyć biblioteki za pomocą polecenia target_link_libraries() w skrypcie kompilacji CMake:
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 zawiera też niektóre biblioteki jako kod źródłowy, który musisz skompilować i połączyć z biblioteką natywną. Kod źródłowy możesz skompilować do biblioteki natywnej za pomocą polecenia add_library() w skrypcie kompilacji CMake. Aby podać ścieżkę do lokalnej biblioteki NDK, możesz użyć zmiennej ścieżki ANDROID_NDK, którą Android Studio automatycznie definiuje.
To polecenie nakazuje CMake utworzenie android_native_app_glue.c, który zarządza zdarzeniami cyklu życia NativeActivity i dotykowym wprowadzaniem danych, w bibliotece statycznej i połączenie go z native-lib:
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} )
Dodawanie innych gotowych bibliotek
Dodawanie gotowej biblioteki jest podobne do określania innej biblioteki natywnej do skompilowania przez CMake. Biblioteka jest już jednak skompilowana, więc musisz użyć flagi IMPORTED, aby poinformować CMake, że chcesz tylko zaimportować bibliotekę do projektu:
add_library( imported-lib
SHARED
IMPORTED )
Następnie musisz określić ścieżkę do biblioteki za pomocą polecenia set_target_properties(), jak pokazano poniżej.
Niektóre biblioteki udostępniają osobne pakiety dla konkretnych architektur procesorów lub interfejsów binarnych aplikacji (ABI) i porządkują je w osobnych katalogach. Dzięki temu biblioteki mogą korzystać z określonych architektur procesorów, a Ty możesz używać tylko tych wersji biblioteki, które chcesz. Aby dodać do skryptu kompilacji CMake wiele wersji ABI biblioteki bez konieczności pisania wielu poleceń dla każdej wersji, możesz użyć zmiennej ścieżki ANDROID_ABI. Ta zmienna używa listy domyślnych interfejsów ABI obsługiwanych przez NDK lub przefiltrowanej listy interfejsów ABI, które ręcznie skonfigurujesz w Gradle. Na przykład:
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 )
Aby CMake mógł znaleźć pliki nagłówka podczas kompilowania, musisz użyć polecenia include_directories() i podać ścieżkę do plików nagłówka:
include_directories( imported-lib/include/ )
Uwaga: jeśli chcesz spakować gotową bibliotekę, która nie jest zależnością czasu kompilacji – na przykład podczas dodawania gotowej biblioteki, która jest zależnością imported-lib – nie musisz wykonywać tych instrukcji, aby połączyć bibliotekę.
Aby połączyć gotową bibliotekę z własną biblioteką natywną, dodaj ją do polecenia target_link_libraries() w skrypcie kompilacji CMake:
target_link_libraries( native-lib imported-lib app-glue ${log-lib} )
Aby umieścić gotową bibliotekę w pliku APK, musisz ręcznie skonfigurować Gradle za pomocą bloku sourceSets, aby uwzględnić ścieżkę do pliku .so. Po utworzeniu pliku APK możesz sprawdzić, które biblioteki Gradle umieszcza w pakiecie, korzystając z APK Analyzer.
Uwzględnianie innych projektów CMake
Jeśli chcesz utworzyć kilka projektów CMake i uwzględnić ich dane wyjściowe w projekcie Androida, możesz użyć jednego pliku CMakeLists.txt jako skryptu kompilacji CMake najwyższego poziomu (połączonego z Gradle) i dodać kolejne projekty CMake jako zależności tego skryptu kompilacji. Poniższy skrypt kompilacji CMake najwyższego poziomu używa polecenia add_subdirectory(), aby określić inny plik CMakeLists.txt jako zależność kompilacji, a następnie łączy się z jego danymi wyjściowymi tak samo jak w przypadku każdej innej gotowej biblioteki.
# 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 )
Wywoływanie CMake z wiersza poleceń
Aby wywołać CMake i wygenerować projekt Ninja poza Android Studio, użyj tego polecenia:
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
To polecenie wygeneruje projekt Ninja, który można wykonać, aby utworzyć biblioteki wykonywalne Androida (pliki .so). Do korzystania z obsługi CMake w NDK wymagany jest CMAKE_TOOLCHAIN_FILE. W przypadku CMake w wersji 3.21 lub nowszej można zamiast tego użyć wbudowanej obsługi NDK, ale trzeba użyć innej grupy zmiennych, zgodnie z opisem w dokumentacji CMake dotyczącej kompilacji skrośnej na Androida.