Merge topic 'patch-AndroidTestUtilities'

16a05e4e7a AndroidTestUtilities: Update documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10819

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 <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>...]
+    )
+
+  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.
 
-  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.
+  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 function accepts the following named parameters:
+  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)