Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
ECM-TOOLCHAINS(7)	      Extra CMake Modules	     ECM-TOOLCHAINS(7)

NAME
       ecm-toolchains -	ECM Toolchains Reference

INTRODUCTION
       Extra  CMake Modules (ECM) provides some	toolchain modules. Unlike nor-
       mal modules, these are not included directly in projects, but specified
       with the	CMAKE_TOOLCHAIN_FILE cache variable on the commandline.

ALL MODULES
   AndroidToolchain
       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.

       CMake upstream has Android support now. This module will	still give  us
       some  useful features offering androiddeployqt integration and adequate
       executables format for our Android applications.

       Since we	are using CMake	Android	support, any  information  from	 CMake
       documentation			   still		      applies:
       https://cmake.org/cmake/help/v3.7/manual/cmake-toolchains.7.html#cross-compiling-for-android

       NOTE:
	  This module requires CMake 3.18.

       Since 1.7.0.

   Usage
       To use this file, you need to set the CMAKE_TOOLCHAIN_FILE to point  to
       Android.cmake on	the command line:

	  cmake	-DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.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:

       CMAKE_ANDROID_NDK
	      The NDK root path.

       ANDROID_SDK_ROOT
	      The SDK root path.

       Additional options are specified	as cache variables (eg:	on the command
       line):

       ANDROID_ABI
	      The ABI to use. See the sources/cxx-stl/gnu-libstdc++/*/libs di-
	      rectories	in the NDK. Default: armeabi-v7a.

       ANDROID_SDK_COMPILE_API
	      The platform API level to	compile	against. May be	different from
	      the NDK target. Default:	newest	installed  version  (e.g.  an-
	      droid-30).

       ANDROID_SDK_BUILD_TOOLS_REVISION
	      The  build tools version to use.	Default: newest	installed ver-
	      sion (e.g. 30.0.2).

       ANDROID_EXTRA_LIBS
	      The ;-separated list of full paths to libs to include in result-
	      ing APK (Qt 5 only).

       For integrating other libraries which are not part of the Android tool-
       chain, like Qt5,	and installed to a separate prefix on the host system,
       the install prefixes of those libraries would be	passed as  alternative
       roots as	list via ECM_ADDITIONAL_FIND_ROOT_PATH.	Since 5.30.0.

       For   example,	for   integrating   a	Qt5  for  Android  present  at
       ~/Qt/5.14.2/android/ and	some other libraries installed to  the	prefix
       /opt/android/foo, you would use:

	  cmake	\
	    -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \
	    -DECM_ADDITIONAL_FIND_ROOT_PATH="~/Qt/5.14.2/android/;/opt/android/foo"

       If  your	 project uses find_package() to	locate build tools on the host
       system,	 make	 sure	 to    pass    CMAKE_FIND_ROOT_PATH_BOTH    or
       NO_CMAKE_FIND_ROOT_PATH as argument in the call.	See the	find_package()
       documentation for more details.

   Deploying Qt	5 Applications
       After  building	the application, you will need to generate an APK that
       can be deployed to an Android device. This module integrates androidde-
       ployqt support to help with this	for Qt-based projects. To enable this,
       set the QTANDROID_EXPORTED_TARGET variable to the targets you  wish  to
       export as an APK	(in a ;-separed	list), as well as ANDROID_APK_DIR to a
       directory  containing  some  basic information. This will create	a cre-
       ate-apk-<target>	target that will generate the APK file.	 See the Qt on
       Android deployment documentation	for more information.

       For example, you	could do:

	  cmake	\
	    -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \
	    -DQTANDROID_EXPORTED_TARGET=myapp \
	    -DANDROID_APK_DIR=myapp-apk
	  make
	  make create-apk-myapp

       You can specify the APK output directory	 by  setting  ANDROID_APK_OUT-
       PUT_DIR.	  Otherwise  the  APK  can be found in myapp_build_apk/	in the
       build directory.

       The create-apk-myapp target will	be able	to take	an ARGS	parameter with
       further arguments for androiddeployqt. For example, one can use:

	  make create-apk-myapp	ARGS="--install"

       To install the apk to test. To generate a signed	apk,  one  can	do  it
       with the	following syntax:

	  make create-apk-myapp	ARGS="--sign ~/my.keystore alias_name"

       In  case	 its needed for	your application to set	the APK	directory from
       cmake scripting you can also set	the directory as  the  ANDROID_APK_DIR
       property	of the create-apk-myapp	target.

       See Android documentation on how	to create a keystore to	use

   Advanced Options
       The  following  packaging options are mainly interesting	for automation
       or integration with CI/CD pipelines:

       ANDROID_APK_OUTPUT_DIR
	      Specifies	a folder where	the  generated	APK  files  should  be
	      placed.

       ANDROID_FASTLANE_METADATA_OUTPUT_DIR
	      Specifies	 a folder where	the generated metadata for the F-Droid
	      store should be placed.

       ANDROIDDEPLOYQT_EXTRA_ARGS
	      Allows to	pass additional	arguments to androiddeployqt. This  is
	      an  alternative  to  the ARGS= argument for make and unlike that
	      works with all CMake generators.

SEE ALSO
       ecm(7)

COPYRIGHT
       KDE Developers

6.14				 May 27, 2025		     ECM-TOOLCHAINS(7)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ecm-toolchains&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>

home | help