diff --git a/Modules/AndroidTestUtilities.cmake b/Modules/AndroidTestUtilities.cmake index e8c8ee66cb..70f4c36cd3 100644 --- a/Modules/AndroidTestUtilities.cmake +++ b/Modules/AndroidTestUtilities.cmake @@ -7,73 +7,87 @@ AndroidTestUtilities .. versionadded:: 3.7 -Create a test that automatically loads specified data onto an Android device. +This module provides a command to create a test that pushes data needed for +testing an Android device behavior onto a connected 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: +Load this module in a CMake project with: .. code-block:: cmake include(AndroidTestUtilities) - android_add_test_data( - example_setup_test - FILES ... - LIBS ... - DEVICE_TEST_DIR "/data/local/tests/example" - DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA" - ) +Commands +^^^^^^^^ -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 -^^^^^^^^^^^^^^^^ +This module provides the following command: .. command:: android_add_test_data + Creates a test that automatically loads specified data onto an Android + device: + .. code-block:: cmake - android_add_test_data( - [FILES ...] [FILES_DEST ] - [LIBS ...] [LIBS_DEST ] - [DEVICE_OBJECT_STORE ] - [DEVICE_TEST_DIR ] - [NO_LINK_REGEX ...] - ) + android_add_test_data( + + [FILES ...] + [FILES_DEST ] + [LIBS ...] + [LIBS_DEST ] + DEVICE_OBJECT_STORE + DEVICE_TEST_DIR + [NO_LINK_REGEX ...] + ) - 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 command accepts files and libraries needed to run project-specific + tests 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. - This function accepts the following named parameters: + On the host operating system, files and libraries are copied at build + time. For on-device testing, the files are loaded onto the device by the + manufactured test at run time. + + This command accepts the following named parameters: ``FILES ...`` - zero or more files needed for testing - ``LIBS ...`` - zero or more libraries needed for testing + Zero or more files needed for testing. ``FILES_DEST `` - absolute path where the data files are expected to be + Absolute path where the data files are expected to be. + ``LIBS ...`` + Zero or more libraries needed for testing. ``LIBS_DEST `` - absolute path where the libraries are expected to be + Absolute path where the libraries are expected to be. ``DEVICE_OBJECT_STORE `` - absolute path to the location where the data is stored on-device + Absolute path to the on-device location where the data files are initially + stored. ``DEVICE_TEST_DIR `` - absolute path to the root directory of the on-device test location - ``NO_LINK_REGEX ...`` - list of regex strings matching the names of files that should be - copied from the object store to the testing directory + Absolute path to the root directory of the on-device test location. + ``NO_LINK_REGEX ...`` + A list of regular expression patterns matching file names to be copied + from the object store to the test directory, instead of being symlinked. + +Examples +^^^^^^^^ + +The following example shows how to use this module to create a test named +``example_setup_test`` that prepares data during the build phase. This test +can then be run using :manual:`ctest(1)` to load the data onto the Android +device. + +.. code-block:: cmake + :caption: ``CMakeLists.txt`` + + include(AndroidTestUtilities) + + android_add_test_data( + example_setup_test + FILES data/protobuffer.p data/file.txt + LIBS libs/library_1 libs/library_2 + DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA" + DEVICE_TEST_DIR "/data/local/tests/example" + ) #]======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ExternalData.cmake)