Merge topic 'add-setup-projects-tests-module'

130784e0 AndroidTestUtilities: Add module to help drive Android device tests

Help/manual/cmake-modules.7.rst

@@ -14,6 +14,7 @@ All Modules
    :maxdepth: 1
 
    /module/AddFileDependencies
+   /module/AndroidTestUtilities
    /module/BundleUtilities
    /module/CheckCCompilerFlag
    /module/CheckCSourceCompiles

Help/module/AndroidTestUtilities.rst

+.. cmake-module:: ../../Modules/AndroidTestUtilities.cmake

Help/release/dev/add-android-test-utilities-module.rst

+add-android-test-utilities-module
+---------------------------------
+
+* A :module:`AndroidTestUtilities` module was added to manage transfer of
+  test data to an Android device.

Modules/AndroidTestUtilities.cmake

+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+# file Copyright.txt or https://cmake.org/licensing for details.
+
+#[======================================================================[.rst:
+AndroidTestUtilities
+------------------------
+
+Create a test that automatically loads specified data onto an Android device.
+
+Introduction
+^^^^^^^^^^^^
+
+Use this module to push data needed for testing an Android device behavior
+onto a connected Android device. The module will accept files and libraries as
+well as separate destinations for each. It will create a test that loads the
+files into a device object store and link to them from the specified
+destination. The files are only uploaded if they are not already in the object
+store.
+
+For example:
+
+.. code-block:: cmake
+
+  include(AndroidTestUtilities)
+  android_add_test_data(
+    example_setup_test
+    FILES <files>...
+    LIBS <libs>...
+    DEVICE_TEST_DIR "/data/local/tests/example"
+    DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA"
+    )
+
+
+At build time a test named "example_setup_test" will be created.  Run this test
+on the command line with :manual:`ctest(1)` to load the data onto the Android
+device.
+
+Module Functions
+^^^^^^^^^^^^^^^^
+
+.. command:: android_add_test_data
+
+  ::
+
+    android_add_test_data(<test-name>
+      [FILES <files>...] [FILES_DEST <device-dir>]
+      [LIBS <libs>...]   [LIBS_DEST <device-dir>]
+      [DEVICE_OBJECT_STORE <device-dir>]
+      [DEVICE_TEST_DIR <device-dir>]
+      [NO_LINK_REGEX <strings>...]
+      )
+
+  The ``android_add_test_data`` function is used to copy files and libraries
+  needed to run project-specific tests. On the host operating system, this is
+  done at build time. For on-device testing, the files are loaded onto the
+  device by the manufactured test at run time.
+
+  This function accepts the following named parameters:
+
+  ``FILES <files>...``
+    zero or more files needed for testing
+  ``LIBS <libs>...``
+    zero or more libraries needed for testing
+  ``FILES_DEST <device-dir>``
+    absolute path where the data files are expected to be
+  ``LIBS_DEST <device-dir>``
+    absolute path where the libraries are expected to be
+  ``DEVICE_OBJECT_STORE <device-dir>``
+    absolute path to the location where the data is stored on-device
+  ``DEVICE_TEST_DIR <device-dir>``
+    absolute path to the root directory of the on-device test location
+  ``NO_LINK_REGEX <strings>...``
+    list of regex strings matching the names of files that should be
+    copied from the object store to the testing directory
+#]======================================================================]
+
+include(${CMAKE_CURRENT_LIST_DIR}/ExternalData.cmake)
+
+set(_AndroidTestUtilities_SELF_DIR "${CMAKE_CURRENT_LIST_DIR}")
+
+# The parameters to this function should be set to the list of directories,
+# files, and libraries that need to be installed prior to testing.
+function(android_add_test_data test_name)
+  # As the names suggest, oneValueArgs lists the arguments that specify a
+  # single value, while multiValueArgs can contain one or more values.
+  set(keywordArgs)
+  set(oneValueArgs FILES_DEST LIBS_DEST DEVICE_OBJECT_STORE DEVICE_TEST_DIR)
+  set(multiValueArgs FILES LIBS NO_LINK_REGEX)
+
+  # For example, if you called this function with FILES </path/to/file>
+  # then this path would be stored in the variable AST_FILES.
+  # The AST prefix stands for the name of this function (android_add_test_data).
+  cmake_parse_arguments(AST "${keywordArgs}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+  if(NOT AST_DEVICE_TEST_DIR)
+    message(FATAL_ERROR "-- You must specify the location of the on device test directory.")
+  endif()
+  if(NOT AST_DEVICE_OBJECT_STORE)
+    message(FATAL_ERROR "-- You must specify the location of the on device object store.")
+  endif()
+  if(${AST_DEVICE_TEST_DIR} STREQUAL "/")
+    message(FATAL_ERROR "-- The device test directory cannot be '/'")
+  endif()
+
+  # Copy all test data files into the binary directory, where tests are run.
+  # ExternalData will handle fetching DATA{...} references.
+  string(REPLACE "|" ";" hash_algs "${_ExternalData_REGEX_EXT}")
+  # Convert ExternalData placeholder file names to DATA{} syntax.
+  foreach(alg ${hash_algs})
+    string(REGEX REPLACE "([^ ;]+)\\.${alg}" "DATA{\\1}" AST_FILES "${AST_FILES}")
+  endforeach()
+
+  set(DATA_TARGET_NAME "${test_name}")
+  ExternalData_Expand_Arguments(
+    ${DATA_TARGET_NAME}
+    extern_data_output
+    ${AST_FILES})
+  ExternalData_Add_Target(${DATA_TARGET_NAME})
+
+  # For regular files on Linux, just copy them directly.
+  foreach(path ${AST_FILES})
+    foreach(output ${extern_data_output})
+      if(${output} STREQUAL ${path})
+        # Check if a destination was specified.  If not, we copy by default
+        # into this project's binary directory, preserving its relative path.
+        if(AST_${VAR}_DEST)
+          set(DEST ${CMAKE_BINARY_DIR}/${parent_dir}/${AST_${VAR}_DEST})
+        else()
+          get_filename_component(parent_dir ${path} DIRECTORY)
+          set(DEST "${CMAKE_BINARY_DIR}/${parent_dir}")
+        endif()
+        get_filename_component(extern_data_source ${output} REALPATH)
+        get_filename_component(extern_data_basename ${output} NAME)
+        add_custom_command(
+          TARGET ${DATA_TARGET_NAME} POST_BUILD
+          DEPENDS ${extern_data_source}
+          COMMAND ${CMAKE_COMMAND} -E copy_if_different ${extern_data_source} ${DEST}/${extern_data_basename}
+        )
+      endif()
+    endforeach()
+  endforeach()
+
+  if(ANDROID)
+    string(REGEX REPLACE "DATA{([^ ;]+)}" "\\1"  processed_FILES "${AST_FILES}")
+    add_test(
+      NAME ${test_name}
+      COMMAND ${CMAKE_COMMAND}
+      "-Darg_files_dest=${AST_FILES_DEST}"
+      "-Darg_libs_dest=${AST_LIBS_DEST}"
+      "-Darg_dev_test_dir=${AST_DEVICE_TEST_DIR}"
+      "-Darg_dev_obj_store=${AST_DEVICE_OBJECT_STORE}"
+      "-Darg_no_link_regex=${AST_NO_LINK_REGEX}"
+      "-Darg_files=${processed_FILES}"
+      "-Darg_libs=${AST_LIBS}"
+      "-Darg_src_dir=${CMAKE_CURRENT_SOURCE_DIR}"
+      -P ${_AndroidTestUtilities_SELF_DIR}/AndroidTestUtilities/PushToAndroidDevice.cmake)
+  endif()
+endfunction()

Modules/AndroidTestUtilities/PushToAndroidDevice.cmake

+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+# file Copyright.txt or https://cmake.org/licensing for details.
+
+# This function handles pushing all of the test files needed to the device.
+# It places the data files in the object store and makes links to them from
+# the appropriate directories.
+#
+# This function accepts the following named parameters:
+# DIRS          : one or more directories needed for testing.
+# FILES         : one or more files needed for testing.
+# LIBS          : one or more libraries needed for testing.
+# DIRS_DEST     : specify where the directories should be installed.
+# FILES_DEST    : specify where the files should be installed.
+# LIBS_DEST     : specify where the libraries should be installed.
+# DEV_OBJ_STORE : specify where the actual data files should be placed.
+# DEV_TEST_DIR  : specify the root file for the module test directory.
+# The DEV_OBJ_STORE and DEV_TEST_DIR variables are required.
+
+# The parameters to this function should be set to the list of directories,
+# files, and libraries that need to be installed prior to testing.
+function(android_push_test_files_to_device)
+
+  # The functions in the module need the adb executable.
+  find_program(adb_executable adb)
+  if(NOT adb_executable)
+    message(FATAL_ERROR "could not find adb")
+  endif()
+
+  function(execute_adb_command)
+    execute_process(COMMAND ${adb_executable} ${ARGN} RESULT_VARIABLE res_var OUTPUT_VARIABLE out_var ERROR_VARIABLE err_var)
+    set(out_var ${out_var} PARENT_SCOPE)
+    if(res_var)
+      string(REGEX REPLACE ";" " " com "${ARGN}")
+      message(FATAL_ERROR "Error occured during adb command: adb ${com}\nError: ${err_var}.")
+    endif()
+  endfunction()
+
+  # Checks to make sure that a given file exists on the device. If it does,
+  # if(file_exists) will return true.
+  macro(check_device_file_exists device_file file_exists)
+    set(${file_exists} "")
+    execute_adb_command(shell ls ${device_file})
+    if(NOT out_var) # when a directory exists but is empty the output is empty
+      set(${file_exists} "YES")
+    else()
+      string(FIND ${out_var} "No such file or directory" no_file_exists)
+      if(${no_file_exists} STREQUAL "-1") # -1 means the file exists
+        set(${file_exists} "YES")
+      endif()
+    endif()
+  endmacro()
+
+  # Checks to see if a filename matches a regex.
+  function(filename_regex filename reg_ex)
+    string(REGEX MATCH ${reg_ex} filename_match ${filename})
+    set(filename_match ${filename_match} PARENT_SCOPE)
+  endfunction()
+
+  # If a file with given name exists in the CMAKE_BINARY_DIR then use that file.
+  # Otherwise use the file with root in CMAKE_CURRENT_SOURCE_DIR.
+  macro(set_absolute_path relative_path absolute_path)
+    set(${absolute_path} ${arg_src_dir}/${relative_path})
+    if(EXISTS ${CMAKE_BINARY_DIR}/${relative_path})
+      set(${absolute_path} ${CMAKE_BINARY_DIR}/${relative_path})
+    endif()
+    if(NOT EXISTS ${${absolute_path}})
+      if(EXISTS ${relative_path})
+        set(${absolute_path} ${relative_path})
+      else()
+        message(FATAL_ERROR "Cannot find file for specified path: ${relative_path}")
+      endif()
+    endif()
+  endmacro()
+
+  # This function pushes the data into the device object store and
+  # creates a link to that data file in a specified location.
+  #
+  # This function requires the following un-named parameters:
+  # data_path        : absolute path to data to load into dev obj store.
+  # dev_object_store : absolute path to the device object store directory.
+  # link_origin      : absolute path to the origin of the link to the dev obj store data file.
+  function(push_and_link data_path dev_object_store link_origin)
+    FILE(SHA1 ${data_path} hash_val)
+    set(obj_store_dst ${dev_object_store}/${hash_val})
+    check_device_file_exists(${obj_store_dst} obj_store_file_exists)
+    # TODO: Verify that the object store file is indeed hashed correctly. Could use md5.
+    if(NOT obj_store_file_exists)
+      execute_adb_command(push ${data_path} ${obj_store_dst})
+    endif()
+    check_device_file_exists(${link_origin} link_exists)
+    if(link_exists)
+      execute_adb_command(shell rm -f ${link_origin})
+    endif()
+    foreach(ex ${arg_no_link_regex})
+      filename_regex(${data_path} ${ex})
+      LIST(APPEND match_ex ${filename_match})
+    endforeach()
+    if(match_ex)
+      execute_adb_command(shell cp ${obj_store_dst} ${link_origin})
+    else()
+      execute_adb_command(shell ln -s ${obj_store_dst} ${link_origin})
+    endif()
+  endfunction()
+
+  #----------------------------------------------------------------------------
+  #--------------------Beginning of actual function----------------------------
+  #----------------------------------------------------------------------------
+  set(oneValueArgs FILES_DEST LIBS_DEST DEV_TEST_DIR DEV_OBJ_STORE)
+  set(multiValueArgs FILES LIBS)
+  cmake_parse_arguments(_ptd "" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+
+  # Setup of object store and test dir.
+  check_device_file_exists(${_ptd_DEV_OBJ_STORE} dev_obj_store_exists)
+  if(NOT dev_obj_store_exists)
+    execute_adb_command(shell mkdir -p ${_ptd_DEV_OBJ_STORE})
+  endif()
+  check_device_file_exists(${_ptd_DEV_TEST_DIR} test_dir_exists)
+  if(test_dir_exists)
+    # This is protected in the SetupProjectTests module.
+    execute_adb_command(shell echo rm -r ${_ptd_DEV_TEST_DIR} | su)
+  endif()
+  execute_adb_command(shell mkdir -p ${_ptd_DEV_TEST_DIR})
+
+  # Looping over the various types of test data possible.
+  foreach(TYPE ${multiValueArgs})
+    if(_ptd_${TYPE})
+
+      # determine if the data type destination has been explicitly specified.
+      if(_ptd_${TYPE}_DEST)
+        set(dest ${_ptd_${TYPE}_DEST})
+      else()
+        if(${TYPE} STREQUAL LIBS)
+          set(dest ${_ptd_DEV_TEST_DIR}/lib)
+        else()
+          set(dest ${_ptd_DEV_TEST_DIR})
+        endif()
+      endif()
+      execute_adb_command(shell mkdir -p ${dest})
+
+      # Loop over the files passed in
+      foreach(relative_path ${_ptd_${TYPE}})
+        # The absolute path can be through the source directory or the build directory.
+        # If the file/dir exists in the build directory that version is chosen.
+        set_absolute_path(${relative_path} absolute_path)
+        # Need to transfer all data files in the data directories to the device
+        # except those explicitly ignored.
+        if(${TYPE} STREQUAL FILES)
+          get_filename_component(file_dir ${relative_path} DIRECTORY)
+          # dest was determined earlier, relative_path is a dir, file is path from relative path to a data
+          set(cur_dest ${dest}/${relative_path})
+          set(on_dev_dir ${dest}/${file_dir})
+          execute_adb_command(shell mkdir -p ${on_dev_dir})
+          if(IS_SYMLINK ${absolute_path})
+            get_filename_component(real_data_origin ${absolute_path} REALPATH)
+            push_and_link(${real_data_origin} ${_ptd_DEV_OBJ_STORE} ${cur_dest})
+          else()
+            push_and_link(${absolute_path} ${_ptd_DEV_OBJ_STORE} ${cur_dest})
+          endif()
+        else() # LIBS
+          execute_adb_command(push ${absolute_path} ${dest})
+        endif()
+      endforeach()
+    endif()
+  endforeach()
+endfunction()
+
+android_push_test_files_to_device(
+  FILES_DEST ${arg_files_dest}
+  LIBS_DEST ${arg_libs_dest}
+  DEV_TEST_DIR ${arg_dev_test_dir}
+  DEV_OBJ_STORE ${arg_dev_obj_store}
+  FILES ${arg_files}
+  LIBS ${arg_libs}
+  )

Tests/RunCMake/AndroidTestUtilities/CMakeLists.txt

+cmake_minimum_required(VERSION 3.6)
+project(${RunCMake_TEST} NONE)
+include(${RunCMake_TEST}.cmake)

Tests/RunCMake/AndroidTestUtilities/RunCMakeTest.cmake

+include(RunCMake)
+
+function(run_ATU case target)
+  # Use a single build tree for a few tests without cleaning.
+  set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/${case}-build)
+  set(RunCMake_TEST_NO_CLEAN 1)
+  file(REMOVE_RECURSE "${RunCMake_TEST_BINARY_DIR}")
+  file(MAKE_DIRECTORY "${RunCMake_TEST_BINARY_DIR}")
+  if(target)
+    set(build_args --target ${target})
+  else()
+    set(build_args)
+  endif()
+  run_cmake(${case})
+  run_cmake_command(${case}Build ${CMAKE_COMMAND} --build . --config Debug ${build_args})
+endfunction()
+
+run_ATU(SetupTest1 "")
+run_ATU(SetupTest2 "tests")
+run_ATU(SetupTest3 "tests")

Tests/RunCMake/AndroidTestUtilities/SetupTest1.cmake

+enable_testing()
+include(AndroidTestUtilities)
+
+find_program(adb_executable adb)
+
+set(ExternalData_URL_TEMPLATES
+  "https://data.kitware.com/api/v1/file/hashsum/%(algo)/%(hash)/download"
+  )
+
+set(test_files "data/a.txt")
+
+set(ANDROID 1)
+
+android_add_test_data(setup_test
+  FILES ${test_files}
+  DEVICE_TEST_DIR "/data/local/tests/example1"
+  DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA")

Tests/RunCMake/AndroidTestUtilities/SetupTest1Build-check.cmake

+include(${CMAKE_CURRENT_LIST_DIR}/check.cmake)
+compare_build_to_expected(FILES
+  "data/a.txt"
+  )
+check_for_setup_test()

Tests/RunCMake/AndroidTestUtilities/SetupTest2.cmake

+enable_testing()
+include(AndroidTestUtilities)
+
+add_custom_target(tests)
+find_program(adb_executable adb)
+
+set(ExternalData_URL_TEMPLATES
+  "https://data.kitware.com/api/v1/file/hashsum/%(algo)/%(hash)/download"
+  )
+set(test_files
+  "data/a.txt"
+  "data/subfolder/b.txt"
+  "data/subfolder/protobuffer.p"
+  )
+
+set(test_libs "data/subfolder/exampleLib.txt")
+
+set(ANDROID 1)
+
+android_add_test_data(setup_test
+  FILES ${test_files}
+  LIBS ${test_libs}
+  DEVICE_TEST_DIR "/data/local/tests/example2"
+  DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA"
+  NO_LINK_REGEX "\\.p$")
+
+set_property(
+  TARGET setup_test
+  PROPERTY EXCLUDE_FROM_ALL 1)
+add_dependencies(tests setup_test)

Tests/RunCMake/AndroidTestUtilities/SetupTest2Build-check.cmake

+include(${CMAKE_CURRENT_LIST_DIR}/check.cmake)
+compare_build_to_expected(FILES
+  "data/a.txt"
+  "data/subfolder/b.txt"
+  "data/subfolder/protobuffer.p"
+  )
+check_for_setup_test()

Tests/RunCMake/AndroidTestUtilities/SetupTest3.cmake

+enable_testing()
+include(AndroidTestUtilities)
+
+add_custom_target(tests)
+find_program(adb_executable adb)
+
+set(ExternalData_URL_TEMPLATES
+  "https://data.kitware.com/api/v1/file/hashsum/%(algo)/%(hash)/download"
+  )
+set(test_dir "/data/local/tests/example3")
+set(test_files
+  "data/a.txt"
+  "data/subfolder/b.txt"
+  )
+set(test_libs "libs/exampleLib.txt")
+set(files_dest "${test_dir}/storage_folder")
+set(libs_dest "${test_dir}/lib/lib/lib")
+
+set(ANDROID 1)
+
+android_add_test_data(setup_test
+  FILES ${test_files}
+  LIBS ${test_libs}
+  FILES_DEST ${files_dest}
+  LIBS_DEST ${libs_dest}
+  DEVICE_TEST_DIR "/data/local/tests/example3"
+  DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA"
+  NO_LINK_REGEX "\\.p$")
+
+set_property(
+  TARGET setup_test
+  PROPERTY EXCLUDE_FROM_ALL 1)
+add_dependencies(tests setup_test)

Tests/RunCMake/AndroidTestUtilities/SetupTest3Build-check.cmake

+include(${CMAKE_CURRENT_LIST_DIR}/check.cmake)
+compare_build_to_expected(FILES
+  "data/a.txt"
+  "data/subfolder/b.txt"
+  )
+check_for_setup_test()

Tests/RunCMake/AndroidTestUtilities/check.cmake

+function(compare_build_to_expected)
+  cmake_parse_arguments(_comp "" "" "FILES" ${ARGN})
+  set(missing)
+  foreach(file ${_comp_FILES})
+    if(NOT EXISTS "${RunCMake_TEST_BINARY_DIR}/${file}")
+      list(APPEND missing "${file}")
+    endif()
+  endforeach()
+  if(missing)
+    string(APPEND RunCMake_TEST_FAILED "Missing files:\n ${missing}")
+    set(RunCMake_TEST_FAILED "${RunCMake_TEST_FAILED}" PARENT_SCOPE)
+  endif()
+endfunction()
+
+function(check_for_setup_test)
+  file(STRINGS "${RunCMake_TEST_BINARY_DIR}/CTestTestfile.cmake" output_var REGEX "add_test\\(setup_test.*")
+  if(NOT output_var)
+    set(RunCMake_TEST_FAILED "Could not find the test: setup_test" PARENT_SCOPE)
+  endif()
+endfunction()

Tests/RunCMake/AndroidTestUtilities/data/a.txt

+Here is a file to test.

Tests/RunCMake/AndroidTestUtilities/data/proto.proto

+proto.proto

Tests/RunCMake/AndroidTestUtilities/data/subfolder/b.txt

+SetupTest2.cmake

Tests/RunCMake/AndroidTestUtilities/data/subfolder/protobuffer.p

+protobuffer.p

Tests/RunCMake/AndroidTestUtilities/libs/exampleLib.so

+here is a fake lib.

Tests/RunCMake/AndroidTestUtilities/libs/exampleLib.txt

+here is an example lib!

Tests/RunCMake/CMakeLists.txt

@@ -131,6 +131,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
     )
 endif()
 
+add_RunCMake_test(AndroidTestUtilities)
 add_RunCMake_test(BuildDepends)
 if(UNIX AND "${CMAKE_GENERATOR}" MATCHES "Unix Makefiles|Ninja")
   add_RunCMake_test(CompilerChange)