diff options
| -rw-r--r-- | README.rst | 9 | ||||
| -rw-r--r-- | docs/manual/ecm-modules.7.rst | 16 | ||||
| -rw-r--r-- | docs/manual/ecm-toolchains.7.rst | 33 | ||||
| -rw-r--r-- | docs/sphinx/ecm.py | 3 | ||||
| -rw-r--r-- | docs/toolchain/Android.rst | 1 | ||||
| -rw-r--r-- | toolchain/Android.cmake | 114 |
6 files changed, 121 insertions, 55 deletions
@@ -5,8 +5,9 @@ Introduction ============ The Extra CMake Modules package, or ECM, adds to the modules provided by CMake, -including both ones used by ``find_package()`` to find common software and ones -that can be used directly in ``CMakeLists.txt`` files to perform common tasks. +including ones used by ``find_package()`` to find common software, ones that +can be used directly in ``CMakeLists.txt`` files to perform common tasks and +toolchain files that must be specified on the commandline by the user. In addition, it provides common build settings used in software produced by the KDE community. @@ -54,7 +55,7 @@ some of the settings. Some of the functionality of Organization ------------ -ECM provides three different types of modules. +ECM provides four different types of modules. * Core modules provide helpful macros for use in project CMake scripts. See :manual:`ecm-modules(7)` for more information. @@ -63,6 +64,8 @@ ECM provides three different types of modules. * KDE modules provide common settings for software produced by KDE; much of this may also be useful to other projects. See :manual:`ecm-kde-modules(7)` for more information. +* Toolchain files change the build tools and targets used by CMake. See + :manual:`ecm-toolchains(7)` for more information. The ``${ECM_MODULE_DIR}``, ``${ECM_FIND_MODULE_DIR}`` and ``${ECM_KDE_MODULE_DIR}`` variables may be used instead of diff --git a/docs/manual/ecm-modules.7.rst b/docs/manual/ecm-modules.7.rst index 16fd8612..ee0e4638 100644 --- a/docs/manual/ecm-modules.7.rst +++ b/docs/manual/ecm-modules.7.rst @@ -11,12 +11,12 @@ Introduction ============ Extra CMake Modules (ECM) provides various modules that provide useful functions -for CMake scripts. ECM actually provides three types of modules: those that -extend the functionality of the ``find_package`` command are documented in -:manual:`ecm-find-modules(7)`; those that provide standard settings for software -produced by the KDE community are documented in :manual:`ecm-kde-modules(7)`. -The rest provide macros and functions for general use by CMake scripts and are -documented here. +for CMake scripts. ECM actually provides three types of modules that can be +used from CMake scripts: those that extend the functionality of the +``find_package`` command are documented in :manual:`ecm-find-modules(7)`; those +that provide standard settings for software produced by the KDE community are +documented in :manual:`ecm-kde-modules(7)`. The rest provide macros and +functions for general use by CMake scripts and are documented here. To use these modules, you need to tell CMake to find the ECM package, and then add either ``${ECM_MODULE_PATH}`` or ``${ECM_MODULE_DIR}`` to the @@ -30,6 +30,10 @@ then add either ``${ECM_MODULE_PATH}`` or ``${ECM_MODULE_DIR}`` to the Using ``${ECM_MODULE_PATH}`` will also make the find modules and KDE modules available. +Note that there are also toolchain modules, documented in +:manual:`ecm-toolchains(7)`, but these are used by users building the software +rather than developers writing CMake scripts. + All Modules =========== diff --git a/docs/manual/ecm-toolchains.7.rst b/docs/manual/ecm-toolchains.7.rst new file mode 100644 index 00000000..66f685e2 --- /dev/null +++ b/docs/manual/ecm-toolchains.7.rst @@ -0,0 +1,33 @@ +.. ecm-manual-description: ECM Toolchains Reference + +ecm-toolchains(7) +***************** + +.. only:: html or latex + + .. contents:: + +Introduction +============ + +Extra CMake Modules (ECM) provides some toolchain modules. Unlike normal +modules, these are not included directly in projects, but specified with +the ``CMAKE_TOOLCHAIN_FILE`` cache variable on the commandline. + + +All Modules +=========== + +.. toctree:: + :maxdepth: 1 + :glob: + + /toolchain/* + +.. only:: man + + See Also + ======== + + :manual:`ecm(7)` + diff --git a/docs/sphinx/ecm.py b/docs/sphinx/ecm.py index 3eb75248..ed966bfb 100644 --- a/docs/sphinx/ecm.py +++ b/docs/sphinx/ecm.py @@ -154,6 +154,7 @@ _ecm_index_objs = { 'module': _ecm_index_entry('module'), 'find-module': _ecm_index_entry('find-module'), 'kde-module': _ecm_index_entry('kde-module'), + 'toolchain': _ecm_index_entry('toolchain'), } def _ecm_object_inventory(env, document, line, objtype, targetid): @@ -264,6 +265,7 @@ class ECMDomain(Domain): 'kde-module': ObjType('kde-module', 'kde-module'), 'find-module': ObjType('find-module', 'find-module'), 'manual': ObjType('manual', 'manual'), + 'toolchain': ObjType('toolchain', 'toolchain'), } directives = {} roles = { @@ -271,6 +273,7 @@ class ECMDomain(Domain): 'kde-module': XRefRole(), 'find-module': XRefRole(), 'manual': XRefRole(), + 'toolchain': XRefRole(), } initial_data = { 'objects': {}, # fullname -> docname, objtype diff --git a/docs/toolchain/Android.rst b/docs/toolchain/Android.rst new file mode 100644 index 00000000..9103e622 --- /dev/null +++ b/docs/toolchain/Android.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../toolchain/Android.cmake diff --git a/toolchain/Android.cmake b/toolchain/Android.cmake index 8272ef9d..55d2ca81 100644 --- a/toolchain/Android.cmake +++ b/toolchain/Android.cmake @@ -1,57 +1,79 @@ #.rst: # AndroidToolchain -# ------------------- +# ---------------- # -# Enable easy compilation of cmake projects on Android +# Enable easy compilation of cmake projects on Android. # # By using this android toolchain, the projects will be set up to compile the # specified project targeting an Android platform, depending on its input. # Furthermore, if desired, an APK can be directly generated by using the -# androiddeployqt tool. -# -# Note: Requires CMake 3.1 -# -# How to use it? -# -------------- -# First of all, to make use of this toolchain file it's required to specify the -# CMAKE_TOOLCHAIN_FILE variable pointing to AndroidToolchain.cmake. -# -# Then, there's many settings that we may want to specify under what circumstances -# the project will be built. This will be done through environment variables: -# - ANDROID_NDK: points to the NDK root path -# - ANDROID_SDK_ROOT: points to the SDK root path -# -# Also there's some cache variables we can pass as well to narrow down the -# preferred settings: -# - ANDROID_NDK: Points to the NDK root, defaults to the environment variable -# with the same name. -# - ANDROID_SDK_ROOT: Points to the Android SDK root, defaults to the environment -# variable with the same name. -# - ANDROID_ARCHITECTURE: Specifies the used architecture, "arm" by default. See -# arch-* directory. -# - ANDROID_TOOLCHAIN: Specifies the toolchain to be used. Defaults to -# "arm-linux-androideabi". See <ndk>/toolchains/ directory. -# - ANDROID_ABI: Specifies the ABI to be used. Defaults to "armeabi-v7a". See -# <ndk>/sources/cxx-stl/gnu-libstdc++/*/libs/ directories. -# - ANDROID_GCC_VERSION: Specifies the GCC version. Defaults to "4.9". -# - ANDROID_API_LEVEL: Specifies the API level to require. Defaults to "14". See -# http://developer.android.com/guide/topics/manifest/uses-sdk-element.html -# - ANDROID_SDK_BUILD_TOOLS_REVISION: Specifies the build tools version to be used. -# Defaults to "21.1.1". -# -# Once we have the application built, we will want to generate an APK that we -# can run on an Android device. To this end we've integrated androiddeployqt so -# this can be done easily. This won't work with non-qt projects. -# To make use of the APK generation, we'll define QTANDROID_EXPORTED_TARGET with -# the target we want to have exported. -# Additionally, we'll need to specify a ANDROID_APK_DIR with the base information -# to set the project up. For more information see: -# https://qt-project.org/doc/qt-5-snapshot/deployment-android.html -# -# Once set up, after building, make create-apk-<target_name> will process this -# input and generate an apk that can be found inside the build directory: -# ${CMAKE_BINARY_DIR}/<target_name>_build_apk/bin/QtApp-*.apk. +# `androiddeployqt <http://doc.qt.io/qt-5/deployment-android.html>`_ tool. # +# .. note:: +# +# This module requires CMake 3.1. +# +# Since 1.7.0. +# +# Usage +# ===== +# +# To use this file, you need to set the ``CMAKE_TOOLCHAIN_FILE`` to point to +# ``AndroidToolchain.cmake`` on the command line:: +# +# cmake -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/AndroidToolchain.cmake +# +# You will also need to provide the locations of the Android NDK and SDK. This +# can be done on the commandline or with environment variables; in either case +# the variable names are: +# +# ``ANDROID_NDK`` +# The NSK root path. +# ``ANDROID_SDK_ROOT`` +# The SSK root path. +# +# Additional options are specified as cache variables (eg: on the command line): +# +# ``ANDROID_ARCHITECTURE`` +# The architecture to compile for. Default: ``arm``. +# ``ANDROID_TOOLCHAIN`` +# The toolchain to use. See the ``toolchains`` directory of the NDK. +# Default: ``arm-linux-androideabi``. +# ``ANDROID_ABI`` +# The ABI to use. See the ``sources/cxx-stl/gnu-libstdc++/*/libs`` +# directories in the NDK. Default: ``armeabi-v7a``. +# ``ANDROID_GCC_VERSION`` +# The GCC version to use. Default: ``4.9``. +# ``ANDROID_API_LEVEL`` +# The `API level +# <http://developer.android.com/guide/topics/manifest/uses-sdk-element.html>`_ +# to require. Default: ``14``. +# ``ANDROID_SDK_BUILD_TOOLS_REVISION`` +# The build tools version to use. Default: ``21.1.1``. +# +# Deploying Qt Applications +# ========================= +# +# After building the application, you will need to generate an APK that can be +# deployed to an Android device. This module integrates androiddeployqt support +# to help with this for Qt-based projects. To enable this, set the +# ``QTANDROID_EXPORTED_TARGET`` variable to the target you wish to export as an +# APK, as well as ``ANDROID_APK_DIR`` to a directory containing some basic +# information. This will create a ``create-apk-<target>`` target that will +# generate the APK file. See the `Qt on Android deployment documentation +# <http://doc.qt.io/qt-5/deployment-android.html>`_ for more information. +# +# For example, you could do:: +# +# cmake \ +# -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/AndroidToolchain.cmake \ +# -DQTANDROID_EXPORTED_TARGET=myapp \ +# -DANDROID_APK_DIR=myapp-apk +# make +# make create-apk-myapp +# +# The APK would then be found in ``myapp_build_apk/bin`` in the build directory. + # ============================================================================= # Copyright 2014 Aleix Pol i Gonzalez <aleixpol@kde.org> # |