Warning, /multimedia/kid3/android/qt-android-cmake/readme.md is written in an unsupported language. File is not indexed.
0001 # Qt Android CMake utility 0002 0003 ## What it is 0004 0005 When using Qt for Android development, QMake & QtCreator is the only sane option for compiling and deploying. But if you prefer CMake, you're stuck and have no choice but writing .pro files that duplicate the functionality of your CMake files. 0006 0007 This utility tries to avoid this by providing a CMake way of doing Android compilation and deployment, without QtCreator. It is based on: 0008 0009 * the Android CMake toolchains available in the NDK 0010 * the ```androiddeployqt``` utility from the Qt Android SDK 0011 * the QML / Android example at https://github.com/calincru/QML-Android-Demo 0012 0013 This utility has been developed for my own needs. Don't hesitate to use / share / fork / modify / improve it freely :) 0014 0015 ## How to use it 0016 0017 ### How to integrate it to your CMake configuration 0018 0019 The toolchain file defines the ```ANDROID``` variable, so that everything which is added specifically for Android in your CMake files can be surrounded with 0020 0021 ```cmake 0022 if(ANDROID) 0023 ... 0024 endif() 0025 ``` 0026 0027 The first thing to do is to change your executable target into a library, because on Android, the entry point has to be a Java activity, and your C++ code is then loaded (as a library) and called by this activity. 0028 0029 ```cmake 0030 if(ANDROID) 0031 add_library(my_app SHARED ...) 0032 else() 0033 add_executable(my_app ...) 0034 endif() 0035 ``` 0036 0037 Then all you have to do is to call the ```add_qt_android_apk``` macro to create a new target that will create the Android APK. 0038 0039 ```cmake 0040 if(ANDROID) 0041 include(qt-android-cmake/AddQtAndroidApk.cmake) 0042 add_qt_android_apk(my_app_apk my_app) 0043 endif() 0044 ``` 0045 0046 And that's it. Your APK can now be created by running "make" (or "cmake --build ." if you don't want to bother typing the full path to the make.exe program included in the NDK). 0047 0048 Of course, ```add_qt_android_apk``` accepts more options, see below for the detail. 0049 0050 ### How to run CMake 0051 0052 First, you must make sure that the following environment variables are defined: 0053 0054 * ```ANDROID_NDK```: root directory of the Android NDK 0055 * ```JAVA_HOME```: root directory of the Java JDK 0056 0057 **IMPORTANT** ```JAVA_HOME``` must be defined when you compile the APK too. 0058 0059 Additionally, you can define the following ones, but you can also define them as CMake variables if you prefer: 0060 0061 * ```ANDROID_SDK```: root directory of the Android SDK 0062 0063 You can then run CMake:. 0064 0065 **On Windows** 0066 ``` 0067 cmake -G"MinGW Makefiles" 0068 -DCMAKE_TOOLCHAIN_FILE="%ANDROID_NDK%/build/cmake/android.toolchain.cmake" 0069 -DCMAKE_MAKE_PROGRAM="%ANDROID_NDK%/prebuilt/windows-x86_64/bin/make.exe" . 0070 ``` 0071 0072 **On Linux** 0073 ``` 0074 cmake -DCMAKE_TOOLCHAIN_FILE=path/to/the/android.toolchain.cmake . 0075 ``` 0076 0077 **On Mac OS X** 0078 ``` 0079 This utility has not been tested on this OS yet :) 0080 ``` 0081 0082 The Android toolchain can be customized with environment variables and/or CMake variables. Refer to its documentation (at the beginning of the toolchain file) for more details. 0083 0084 ## Options of the ```add_qt_android_apk``` macro 0085 0086 The first two arguments of the macro are the name of the APK target to be created, and the target it must be based on (your executable). These are of course mandatory. 0087 0088 The macro also accepts optional named arguments. Any combination of these arguments is valid, so that you can customize the generated APK according to your own needs. 0089 0090 Here is the full list of possible arguments: 0091 0092 ### NAME 0093 0094 The name of the application. If not given, the name of the source target is taken. 0095 0096 Example: 0097 0098 ```cmake 0099 add_qt_android_apk(my_app_apk my_app 0100 NAME "My App" 0101 ) 0102 ``` 0103 0104 ### VERSION_CODE 0105 0106 The internal version of the application. It must be a single number, incremented everytime your app is updated on the play store (otherwise it has no importance). If not given, the number 1 is used. 0107 0108 Note that the public version of the application, which is a different thing, is taken from the VERSION property of the CMake target. If none is provided, the VERSION_CODE number is used. 0109 0110 Example: 0111 0112 ```cmake 0113 add_qt_android_apk(my_app_apk my_app 0114 VERSION_CODE 6 0115 ) 0116 ``` 0117 0118 ### PACKAGE_NAME 0119 0120 The name of the application package. If not given, "org.qtproject.${source_target}" , where source_target is the name of the source target, is taken. 0121 0122 Example: 0123 0124 ```cmake 0125 add_qt_android_apk(my_app_apk my_app 0126 PACKAGE_NAME "org.mycompany.myapp" 0127 ) 0128 ``` 0129 0130 ### PACKAGE_SOURCES 0131 0132 The path to a directory containing additional files for the package (custom manifest, resources, translations, Java classes, ...). If you were using a regular QMake project file (.pro), this directory would be the one that you assign to the ```ANDROID_PACKAGE_SOURCE_DIR``` variable. 0133 0134 If you don't provide this argument, a default manifest is generated from the ```AndroidManifest.xml.in``` template and automatically used for building the APK. 0135 0136 Example: 0137 0138 ```cmake 0139 add_qt_android_apk(my_app_apk my_app 0140 PACKAGE_SOURCES ${CMAKE_CURRENT_LIST_DIR}/my-android-sources 0141 ) 0142 ``` 0143 0144 ### KEYSTORE 0145 0146 The path to a keystore file and an alias, for signing the APK. If not provided, the APK won't be signed. 0147 0148 Example: 0149 0150 ```cmake 0151 add_qt_android_apk(my_app_apk my_app 0152 KEYSTORE ${CMAKE_CURRENT_LIST_DIR}/mykey.keystore myalias 0153 ) 0154 ``` 0155 0156 ### KEYSTORE_PASSWORD 0157 0158 The password associated to the given keystore. Note that this option is only considered if the ```KEYSTORE``` argument is used. If it is not given, the password will be asked directly in the console at build time. 0159 0160 Example: 0161 0162 ```cmake 0163 add_qt_android_apk(my_app_apk my_app 0164 KEYSTORE ${CMAKE_CURRENT_LIST_DIR}/mykey.keystore myalias 0165 KEYSTORE_PASSWORD xxxxx 0166 ) 0167 ``` 0168 0169 ### DEPENDS 0170 0171 A list of dependencies (libraries) to be included into the APK. All the dependencies of the application must be listed here; if one is missing, the deployed application will fail to run on the device. The listed items can be either target names, or library paths. 0172 0173 Example: 0174 0175 ```cmake 0176 add_qt_android_apk(my_app_apk my_app 0177 DEPENDS a_linked_target "path/to/a_linked_library.so" etc. 0178 ) 0179 ``` 0180 0181 ### INSTALL 0182 0183 If this option is given, the created APK will be deployed to a connected Android device. By default, the chosen device is the default one, i.e. the first one of the ADB device list. 0184 0185 Example: 0186 0187 ```cmake 0188 add_qt_android_apk(my_app_apk my_app 0189 INSTALL 0190 ) 0191 ``` 0192 ## Troubleshooting 0193 0194 In case of 0195 ``` 0196 -- Configuring done 0197 CMake Error in CMakeLists.txt: 0198 No known features for CXX compiler 0199 0200 "GNU" 0201 0202 version 4.9. 0203 ``` 0204 see [Qt bug 54666](https://bugreports.qt.io/browse/QTBUG-54666) for details. 0205 0206 ## Contact 0207 0208 Laurent Gomila: laurent.gom@gmail.com