Improve code comments and error messages

1 files changed, 57 insertions, 47 deletions

diff --git a/android.toolchain.cmake b/android.toolchain.cmake
index 53bb0e5..abcad7d 100644
--- a/android.toolchain.cmake
+++ b/android.toolchain.cmake
@@ -3,7 +3,7 @@
 #  Requires cmake 2.6.3 or newer (2.8.5 or newer is recommended).
 #  See home page: http://code.google.com/p/android-cmake/
 #
-#  The file is mantained by the OpenCV project. And also can be found at
+#  The file is mantained by the OpenCV project. The latest version can be get at
 #  http://code.opencv.org/projects/opencv/repository/revisions/master/changes/android/android.toolchain.cmake
 #
 #  Usage Linux:
@@ -29,7 +29,7 @@
 #   $ cmake.exe -G"MinGW Makefiles"
 #       -DCMAKE_TOOLCHAIN_FILE=path\to\the\android.toolchain.cmake
 #       -DCMAKE_MAKE_PROGRAM="%ANDROID_NDK%\prebuilt\windows\bin\make.exe" ..
-#   $ "%ANDROID_NDK%\prebuilt\windows\bin\make.exe"
+#   $ cmake.exe --build .
 #
 #
 #  Options (can be set as cmake parameters: -D<option_name>=<value>):
@@ -41,7 +41,7 @@
 #      (ignored if ANDROID_NDK is set).
 #      Can be set as environment variable. Can be set only at first cmake run.
 #
-#    ANDROID_ABI=armeabi-v7a -  specifies the target Application Binary
+#    ANDROID_ABI=armeabi-v7a - specifies the target Application Binary
 #      Interface (ABI). This option nearly matches to the APP_ABI variable
 #      used by ndk-build tool from Android NDK.
 #
@@ -58,27 +58,28 @@
 #        "x86" - matches to the NDK ABI with the same name.
 #            See ${ANDROID_NDK}/docs/CPU-ARCH-ABIS.html for the documentation.
 #        "mips" - matches to the NDK ABI with the same name
-#            (not testes on real devices)
+#            (It is not tested on real devices by the authos of this toolchain)
+#            See ${ANDROID_NDK}/docs/CPU-ARCH-ABIS.html for the documentation.
 #
 #    ANDROID_NATIVE_API_LEVEL=android-8 - level of Android API compile for.
-#      Option is read-only when standalone toolchain used.
+#      Option is read-only when standalone toolchain is used.
 #
-#    ANDROID_FORCE_ARM_BUILD=OFF - set true to generate 32-bit ARM instructions
-#      instead of Thumb-1. Is not available for "x86" (inapplicable) and
-#      "armeabi-v6 with VFP" (forced) ABIs.
+#    ANDROID_FORCE_ARM_BUILD=OFF - set ON to generate 32-bit ARM instructions
+#      instead of Thumb. Is not available for "x86" (inapplicable) and
+#      "armeabi-v6 with VFP" (is forced to be ON) ABIs.
 #
-#    ANDROID_NO_UNDEFINED=ON - set true to show all undefined symbols as linker
+#    ANDROID_NO_UNDEFINED=ON - set ON to show all undefined symbols as linker
 #      errors even if they are not used.
 #
-#    ANDROID_SO_UNDEFINED=OFF - set true to allow undefined symbols in shared
-#      libraries. Automatically turned on for NDK r5x and r6x due to GLESv2
+#    ANDROID_SO_UNDEFINED=OFF - set ON to allow undefined symbols in shared
+#      libraries. Automatically turned for NDK r5x and r6x due to GLESv2
 #      problems.
 #
 #    LIBRARY_OUTPUT_PATH_ROOT=${CMAKE_SOURCE_DIR} - where to output binary
 #      files. See additional details below.
 #
-#    ANDROID_SET_OBSOLETE_VARIABLES=ON - it set, then toolchain defines some
-#      obsolete variables which were set by previous versions of this file for
+#    ANDROID_SET_OBSOLETE_VARIABLES=ON - if set, then toolchain defines some
+#      obsolete variables which were used by previous versions of this file for
 #      backward compatibility.
 #
 #
@@ -94,15 +95,15 @@
 #    Make sure to do the following in your scripts:
 #      SET( CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${my_cxx_flags}" )
 #      SET( CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${my_cxx_flags}" )
-#      The flags will be prepopulated with critical flags, so don't loose them.
-#      Also be aware that toolchain also sets configuration-specific compiler
-#      flags and linker flags.
+#    The flags will be prepopulated with critical flags, so don't loose them.
+#    Also be aware that toolchain also sets configuration-specific compiler
+#    flags and linker flags.
 #
 #    ANDROID and BUILD_ANDROID will be set to true, you may test any of these
 #    variables to make necessary Android-specific configuration changes.
 #
-#    Also ARMEABI or ARMEABI_V7A or X86 will be set true, mutually exclusive.
-#    NEON option will be set true if VFP is set to NEON.
+#    Also ARMEABI or ARMEABI_V7A or X86 or MIPS will be set true, mutually
+#    exclusive. NEON option will be set true if VFP is set to NEON.
 #
 #    LIBRARY_OUTPUT_PATH_ROOT should be set in cache to determine where Android
 #    libraries will be installed.
@@ -185,7 +186,7 @@
 #     [+] added mips architecture support
 #   - modified August 2012
 #     [+] updated for NDK r8b
-#     [~] all intermediate files generated by toolchain are moved into CMakeFiles
+#     [~] all intermediate files generated by toolchain are moved to CMakeFiles
 #     [~] libstdc++ and libsupc are removed from explicit link libraries
 #     [+] added CCache support (via NDK_CCACHE environment or cmake variable)
 #     [+] added gold linker support for NDK r8b
@@ -199,7 +200,7 @@ if( DEFINED CMAKE_CROSSCOMPILING )
  return()
 endif()
 
-get_property(_CMAKE_IN_TRY_COMPILE GLOBAL PROPERTY IN_TRY_COMPILE)
+get_property( _CMAKE_IN_TRY_COMPILE GLOBAL PROPERTY IN_TRY_COMPILE )
 if( _CMAKE_IN_TRY_COMPILE )
  include( "${CMAKE_CURRENT_SOURCE_DIR}/../android.toolchain.config.cmake" OPTIONAL )
 endif()
@@ -279,15 +280,15 @@ macro( __INIT_VARIABLE var_name )
     if( NOT "${__value}" STREQUAL "" )
      if( __test_path )
       if( EXISTS "${__value}" )
-       set( ${var_name} "${__value}" )
-       if( __obsolete )
+       file( TO_CMAKE_PATH "${__value}" ${var_name} )
+       if( __obsolete AND NOT _CMAKE_IN_TRY_COMPILE )
         message( WARNING "Using value of obsolete variable ${__var} as initial value for ${var_name}. Please note, that ${__var} can be completely removed in future versions of the toolchain." )
        endif()
        break()
       endif()
      else()
       set( ${var_name} "${__value}" )
-       if( __obsolete )
+       if( __obsolete AND NOT _CMAKE_IN_TRY_COMPILE )
         message( WARNING "Using value of obsolete variable ${__var} as initial value for ${var_name}. Please note, that ${__var} can be completely removed in future versions of the toolchain." )
        endif()
       break()
@@ -298,6 +299,8 @@ macro( __INIT_VARIABLE var_name )
   unset( __value )
   unset( __values )
   unset( __obsolete )
+ elseif( __test_path )
+  file( TO_CMAKE_PATH "${${var_name}}" ${var_name} )
  endif()
  unset( __test_path )
 endmacro()
@@ -314,19 +317,23 @@ macro( __DETECT_NATIVE_API_LEVEL _var _path )
 endmacro()
 
 macro( __DETECT_TOOLCHAIN_MACHINE_NAME _var _root )
- file( GLOB __gccExePath "${_root}/bin/*-gcc${TOOL_OS_SUFFIX}" )
- __LIST_FILTER( __gccExePath "bin/[.].*-gcc${TOOL_OS_SUFFIX}$" )
- list( LENGTH __gccExePath __gccExePathsCount )
- if( NOT __gccExePathsCount EQUAL 1 )
-  message( WARNING "Could not uniquely determine machine name for compiler from ${_root}." )
-  set( ${_var} "" )
+ if( EXISTS "${_root}" )
+  file( GLOB __gccExePath "${_root}/bin/*-gcc${TOOL_OS_SUFFIX}" )
+  __LIST_FILTER( __gccExePath "bin/[.].*-gcc${TOOL_OS_SUFFIX}$" )
+  list( LENGTH __gccExePath __gccExePathsCount )
+  if( NOT __gccExePathsCount EQUAL 1  AND NOT _CMAKE_IN_TRY_COMPILE )
+   message( WARNING "Could not determine machine name for compiler from ${_root}" )
+   set( ${_var} "" )
+  else()
+   get_filename_component( __gccExeName "${__gccExePath}" NAME_WE )
+   string( REPLACE "-gcc" "" ${_var} "${__gccExeName}" )
+  endif()
+  unset( __gccExePath )
+  unset( __gccExePathsCount )
+  unset( __gccExeName )
  else()
-  get_filename_component( __gccExeName "${__gccExePath}" NAME_WE )
-  string( REPLACE "-gcc" "" ${_var} "${__gccExeName}" )
+  set( ${_var} "" )
  endif()
- unset( __gccExePath )
- unset( __gccExePathsCount )
- unset( __gccExeName )
 endmacro()
 
 macro( __COPY_IF_DIFFERENT _source _destination )
@@ -403,7 +410,6 @@ if( NOT ANDROID_NDK )
   endif( ANDROID_NDK )
  endif( NOT ANDROID_STANDALONE_TOOLCHAIN )
 endif( NOT ANDROID_NDK )
-
 # remember found paths
 if( ANDROID_NDK )
  get_filename_component( ANDROID_NDK "${ANDROID_NDK}" ABSOLUTE )
@@ -412,12 +418,13 @@ if( ANDROID_NDK )
   string( LENGTH "${ANDROID_NDK}" __length )
   string( SUBSTRING "${CMAKE_AR}" 0 ${__length} __androidNdkPreviousPath )
   if( NOT __androidNdkPreviousPath STREQUAL ANDROID_NDK )
-   message( FATAL_ERROR "It is not possible to change path to the NDK on subsequent run." )
+   message( FATAL_ERROR "It is not possible to change the path to the NDK on subsequent CMake run. You must remove all files from your build folder first.
+   " )
   endif()
   unset( __androidNdkPreviousPath )
   unset( __length )
  endif()
- set( ANDROID_NDK "${ANDROID_NDK}" CACHE INTERNAL "Path of the Android NDK" )
+ set( ANDROID_NDK "${ANDROID_NDK}" CACHE INTERNAL "Path of the Android NDK" FORCE )
  set( BUILD_WITH_ANDROID_NDK True )
 elseif( ANDROID_STANDALONE_TOOLCHAIN )
  get_filename_component( ANDROID_STANDALONE_TOOLCHAIN "${ANDROID_STANDALONE_TOOLCHAIN}" ABSOLUTE )
@@ -431,7 +438,7 @@ elseif( ANDROID_STANDALONE_TOOLCHAIN )
   unset( __androidStandaloneToolchainPreviousPath )
   unset( __length )
  endif()
- set( ANDROID_STANDALONE_TOOLCHAIN "${ANDROID_STANDALONE_TOOLCHAIN}" CACHE INTERNAL "Path of the Android standalone toolchain" )
+ set( ANDROID_STANDALONE_TOOLCHAIN "${ANDROID_STANDALONE_TOOLCHAIN}" CACHE INTERNAL "Path of the Android standalone toolchain" FORCE )
  set( BUILD_WITH_STANDALONE_TOOLCHAIN True )
 else()
  list(GET ANDROID_NDK_SEARCH_PATHS 0 ANDROID_NDK_SEARCH_PATH)
@@ -585,7 +592,7 @@ if( CMAKE_BINARY_DIR AND EXISTS "${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMa
  file( APPEND "${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeSystem.cmake" "SET(CMAKE_SYSTEM_PROCESSOR \"${CMAKE_SYSTEM_PROCESSOR}\")\n" )
 endif()
 
-set( ANDROID_SUPPORTED_ABIS ${ANDROID_SUPPORTED_ABIS_${ANDROID_ARCH_FULLNAME}} CACHE INTERNAL "ANDROID_ABI can be changed only to one of these ABIs. Changing to any other ABI requires to reset cmake cache." )
+set( ANDROID_SUPPORTED_ABIS ${ANDROID_SUPPORTED_ABIS_${ANDROID_ARCH_FULLNAME}} CACHE INTERNAL "ANDROID_ABI can be changed only to one of these ABIs. Changing to any other ABI requires to reset cmake cache." FORCE )
 if( CMAKE_VERSION VERSION_GREATER "2.8" )
  list( SORT ANDROID_SUPPORTED_ABIS_${ANDROID_ARCH_FULLNAME} )
  set_property( CACHE ANDROID_ABI PROPERTY STRINGS ${ANDROID_SUPPORTED_ABIS_${ANDROID_ARCH_FULLNAME}} )
@@ -636,8 +643,8 @@ endif()
 list( GET __availableToolchains ${__toolchainIdx} ANDROID_TOOLCHAIN_NAME )
 list( GET __availableToolchainMachines ${__toolchainIdx} ANDROID_TOOLCHAIN_MACHINE_NAME )
 list( GET __availableToolchainCompilerVersions ${__toolchainIdx} ANDROID_COMPILER_VERSION )
-set( ANDROID_TOOLCHAIN_NAME "${ANDROID_TOOLCHAIN_NAME}" CACHE INTERNAL "Name of toolchain used" )
-set( ANDROID_COMPILER_VERSION "${ANDROID_COMPILER_VERSION}" CACHE INTERNAL "compiler version from selected toolchain" )
+set( ANDROID_TOOLCHAIN_NAME "${ANDROID_TOOLCHAIN_NAME}" CACHE INTERNAL "Name of toolchain used" FORCE )
+set( ANDROID_COMPILER_VERSION "${ANDROID_COMPILER_VERSION}" CACHE INTERNAL "compiler version from selected toolchain" FORCE )
 unset( __toolchainIdx )
 unset( __availableToolchains )
 unset( __availableToolchainMachines )
@@ -769,8 +776,10 @@ endif()
 # flags and definitions
 if(ANDROID_SYSROOT MATCHES "[ ;\"]")
  set( ANDROID_CXX_FLAGS "--sysroot=\"${ANDROID_SYSROOT}\"" )
- # quotes will break try_compile and compiler identification
- message(WARNING "Your Android system root has non-alphanumeric symbols. It can break compiler features detection and the whole build.")
+ if( NOT _CMAKE_IN_TRY_COMPILE )
+  # quotes will break try_compile and compiler identification
+  message(WARNING "Your Android system root has non-alphanumeric symbols. It can break compiler features detection and the whole build.")
+ endif()
 else()
  set( ANDROID_CXX_FLAGS "--sysroot=${ANDROID_SYSROOT}" )
 endif()
@@ -981,8 +990,8 @@ include_directories( SYSTEM ${ANDROID_SYSTEM_INCLUDE_DIRS} )
 link_directories( ${ANDROID_SYSTEM_LIB_DIRS} )
 
 # finish flags
-set( ANDROID_CXX_FLAGS    "${ANDROID_CXX_FLAGS}"    CACHE INTERNAL "Extra Android compiler flags")
-set( ANDROID_LINKER_FLAGS "${ANDROID_LINKER_FLAGS}" CACHE INTERNAL "Extra Android linker flags")
+set( ANDROID_CXX_FLAGS    "${ANDROID_CXX_FLAGS}"    CACHE INTERNAL "Extra Android compiler flags" )
+set( ANDROID_LINKER_FLAGS "${ANDROID_LINKER_FLAGS}" CACHE INTERNAL "Extra Android linker flags" )
 set( CMAKE_CXX_FLAGS           "${ANDROID_CXX_FLAGS} ${CMAKE_CXX_FLAGS}" )
 set( CMAKE_C_FLAGS             "${ANDROID_CXX_FLAGS} ${CMAKE_C_FLAGS}" )
 if( MIPS AND BUILD_WITH_ANDROID_NDK AND ANDROID_NDK MATCHES "-r8$" )
@@ -1129,16 +1138,17 @@ endif()
 #   NEON : TRUE if NEON unit is enabled
 #   VFPV3 : TRUE if VFP version 3 is enabled
 #   X86 : TRUE if configured for x86
+#   MIPS : TRUE if configured for mips
 #   BUILD_ANDROID : always TRUE
 #   BUILD_WITH_ANDROID_NDK : TRUE if NDK is used
 #   BUILD_WITH_STANDALONE_TOOLCHAIN : TRUE if standalone toolchain is used
 #   ANDROID_NDK_HOST_SYSTEM_NAME : "windows", "linux-x86" or "darwin-x86" depending on host platform
-#   ANDROID_NDK_ABI_NAME : "armeabi", "armeabi-v7a" or "x86" depending on ANDROID_ABI
+#   ANDROID_NDK_ABI_NAME : "armeabi", "armeabi-v7a", "x86" or "mips" depending on ANDROID_ABI
 #   ANDROID_ARCH_NAME : "arm" or "x86" or "mips" depending on ANDROID_ABI
-#   TOOL_OS_SUFFIX : "" or ".exe" depending on host platform
 #   ANDROID_SYSROOT : path to the compiler sysroot
 #   ANDROID_SYSTEM_INCLUDE_DIRS
 #   ANDROID_SYSTEM_LIB_DIRS
+#   TOOL_OS_SUFFIX : "" or ".exe" depending on host platform
 # Obsolete:
 #   ARMEABI_NDK_NAME : superseded by ANDROID_NDK_ABI_NAME
 #