mirror of
https://github.com/Kitware/CMake.git
synced 2025-10-14 02:08:27 +08:00
AndroidTestUtilities: Update documentation
- Refactored module introduction. - Used "commands" instead of "functions". - Updated module documentation and synced it with other similar utility modules. - Synced command arguments with implementation (DEVICE_OBJECT_STORE and DEVICE_TEST_DIR are required arguments). - Added separate examples section.
This commit is contained in:
Peter Kokot
@@ -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 <files>...
|
||||
LIBS <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(<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>...]
|
||||
)
|
||||
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 <regexes>...]
|
||||
)
|
||||
|
||||
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 <files>...``
|
||||
zero or more files needed for testing
|
||||
``LIBS <libs>...``
|
||||
zero or more libraries needed for testing
|
||||
Zero or more files needed for testing.
|
||||
``FILES_DEST <device-dir>``
|
||||
absolute path where the data files are expected to be
|
||||
Absolute path where the data files are expected to be.
|
||||
``LIBS <libs>...``
|
||||
Zero or more libraries needed for testing.
|
||||
``LIBS_DEST <device-dir>``
|
||||
absolute path where the libraries are expected to be
|
||||
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
|
||||
Absolute path to the on-device location where the data files are initially
|
||||
stored.
|
||||
``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
|
||||
Absolute path to the root directory of the on-device test location.
|
||||
``NO_LINK_REGEX <regexes>...``
|
||||
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)
|
||||
|
||||
Reference in New Issue
Block a user