ExternalData: Re-order documentation
Put example usage just after the intro. Put hash algos last. Put variables right after functions since they both cover the module API.
This commit is contained in:
Brad King
parent
531e75e0b7
commit
a32b2245ca
|
|
@ -26,6 +26,27 @@ For example, the argument ``DATA{img.png}`` may be satisfied by either a
|
||||||
real ``img.png`` file in the current source directory or a ``img.png.md5``
|
real ``img.png`` file in the current source directory or a ``img.png.md5``
|
||||||
file containing its MD5 sum.
|
file containing its MD5 sum.
|
||||||
|
|
||||||
|
Example Usage
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
include(ExternalData)
|
||||||
|
set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
|
||||||
|
"file:////host/share/%(algo)/%(hash)"
|
||||||
|
"http://data.org/%(algo)/%(hash)")
|
||||||
|
ExternalData_Add_Test(MyData
|
||||||
|
NAME MyTest
|
||||||
|
COMMAND MyExe DATA{MyInput.png}
|
||||||
|
)
|
||||||
|
ExternalData_Add_Target(MyData)
|
||||||
|
|
||||||
|
When test ``MyTest`` runs the ``DATA{MyInput.png}`` argument will be
|
||||||
|
replaced by the full path to a real instance of the data file
|
||||||
|
``MyInput.png`` on disk. If the source tree contains a content link
|
||||||
|
such as ``MyInput.png.md5`` then the ``MyData`` target creates a real
|
||||||
|
``MyInput.png`` in the build tree.
|
||||||
|
|
||||||
Module Functions
|
Module Functions
|
||||||
^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
|
@ -74,43 +95,76 @@ Module Functions
|
||||||
in one of the paths specified in the ``ExternalData_OBJECT_STORES``
|
in one of the paths specified in the ``ExternalData_OBJECT_STORES``
|
||||||
variable.
|
variable.
|
||||||
|
|
||||||
Hash Algorithms
|
Module Variables
|
||||||
^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
The following hash algorithms are supported::
|
The following variables configure behavior. They should be set before
|
||||||
|
calling any of the functions provided by this module.
|
||||||
|
|
||||||
%(algo) <ext> Description
|
.. variable:: ExternalData_BINARY_ROOT
|
||||||
------- ----- -----------
|
|
||||||
MD5 .md5 Message-Digest Algorithm 5, RFC 1321
|
|
||||||
SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
|
|
||||||
SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
|
|
||||||
SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
|
|
||||||
SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
|
|
||||||
SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
|
|
||||||
|
|
||||||
Note that the hashes are used only for unique data identification and
|
The ``ExternalData_BINARY_ROOT`` variable may be set to the directory to
|
||||||
download verification.
|
hold the real data files named by expanded ``DATA{}`` references. The
|
||||||
|
default is ``CMAKE_BINARY_DIR``. The directory layout will mirror that of
|
||||||
|
content links under ``ExternalData_SOURCE_ROOT``.
|
||||||
|
|
||||||
Example Usage
|
.. variable:: ExternalData_LINK_CONTENT
|
||||||
^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
The ``ExternalData_LINK_CONTENT`` variable may be set to the name of a
|
||||||
|
supported hash algorithm to enable automatic conversion of real data
|
||||||
|
files referenced by the ``DATA{}`` syntax into content links. For each
|
||||||
|
such ``<file>`` a content link named ``<file><ext>`` is created. The
|
||||||
|
original file is renamed to the form ``.ExternalData_<algo>_<hash>`` to
|
||||||
|
stage it for future transmission to one of the locations in the list
|
||||||
|
of URL templates (by means outside the scope of this module). The
|
||||||
|
data fetch rule created for the content link will use the staged
|
||||||
|
object if it cannot be found using any URL template.
|
||||||
|
|
||||||
include(ExternalData)
|
.. variable:: ExternalData_OBJECT_STORES
|
||||||
set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
|
|
||||||
"file:////host/share/%(algo)/%(hash)"
|
|
||||||
"http://data.org/%(algo)/%(hash)")
|
|
||||||
ExternalData_Add_Test(MyData
|
|
||||||
NAME MyTest
|
|
||||||
COMMAND MyExe DATA{MyInput.png}
|
|
||||||
)
|
|
||||||
ExternalData_Add_Target(MyData)
|
|
||||||
|
|
||||||
When test ``MyTest`` runs the ``DATA{MyInput.png}`` argument will be
|
The ``ExternalData_OBJECT_STORES`` variable may be set to a list of local
|
||||||
replaced by the full path to a real instance of the data file
|
directories that store objects using the layout ``<dir>/%(algo)/%(hash)``.
|
||||||
``MyInput.png`` on disk. If the source tree contains a content link
|
These directories will be searched first for a needed object. If the
|
||||||
such as ``MyInput.png.md5`` then the ``MyData`` target creates a real
|
object is not available in any store then it will be fetched remotely
|
||||||
``MyInput.png`` in the build tree.
|
using the URL templates and added to the first local store listed. If
|
||||||
|
no stores are specified the default is a location inside the build
|
||||||
|
tree.
|
||||||
|
|
||||||
|
.. variable:: ExternalData_SERIES_PARSE
|
||||||
|
ExternalData_SERIES_PARSE_PREFIX
|
||||||
|
ExternalData_SERIES_PARSE_NUMBER
|
||||||
|
ExternalData_SERIES_PARSE_SUFFIX
|
||||||
|
ExternalData_SERIES_MATCH
|
||||||
|
|
||||||
|
See `Referencing File Series`_.
|
||||||
|
|
||||||
|
.. variable:: ExternalData_SOURCE_ROOT
|
||||||
|
|
||||||
|
The ``ExternalData_SOURCE_ROOT`` variable may be set to the highest source
|
||||||
|
directory containing any path named by a ``DATA{}`` reference. The
|
||||||
|
default is ``CMAKE_SOURCE_DIR``. ``ExternalData_SOURCE_ROOT`` and
|
||||||
|
``CMAKE_SOURCE_DIR`` must refer to directories within a single source
|
||||||
|
distribution (e.g. they come together in one tarball).
|
||||||
|
|
||||||
|
.. variable:: ExternalData_TIMEOUT_ABSOLUTE
|
||||||
|
|
||||||
|
The ``ExternalData_TIMEOUT_ABSOLUTE`` variable sets the download
|
||||||
|
absolute timeout, in seconds, with a default of ``300`` seconds.
|
||||||
|
Set to ``0`` to disable enforcement.
|
||||||
|
|
||||||
|
.. variable:: ExternalData_TIMEOUT_INACTIVITY
|
||||||
|
|
||||||
|
The ``ExternalData_TIMEOUT_INACTIVITY`` variable sets the download
|
||||||
|
inactivity timeout, in seconds, with a default of ``60`` seconds.
|
||||||
|
Set to ``0`` to disable enforcement.
|
||||||
|
|
||||||
|
.. variable:: ExternalData_URL_TEMPLATES
|
||||||
|
|
||||||
|
The ``ExternalData_URL_TEMPLATES`` may be set to provide a list of
|
||||||
|
of URL templates using the placeholders ``%(algo)`` and ``%(hash)``
|
||||||
|
in each template. Data fetch rules try each URL template in order
|
||||||
|
by substituting the hash algorithm name for ``%(algo)`` and the hash
|
||||||
|
value for ``%(hash)``.
|
||||||
|
|
||||||
Referencing File Series
|
Referencing File Series
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
@ -171,76 +225,22 @@ directory on the command line and ensure that the directory contains
|
||||||
files corresponding to every file or content link in the ``MyDataDir``
|
files corresponding to every file or content link in the ``MyDataDir``
|
||||||
source directory.
|
source directory.
|
||||||
|
|
||||||
Module Variables
|
Hash Algorithms
|
||||||
^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
The following variables configure behavior. They should be set before
|
The following hash algorithms are supported::
|
||||||
calling any of the functions provided by this module.
|
|
||||||
|
|
||||||
.. variable:: ExternalData_URL_TEMPLATES
|
%(algo) <ext> Description
|
||||||
|
------- ----- -----------
|
||||||
|
MD5 .md5 Message-Digest Algorithm 5, RFC 1321
|
||||||
|
SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
|
||||||
|
SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
|
||||||
|
SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
|
||||||
|
SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
|
||||||
|
SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
|
||||||
|
|
||||||
The ``ExternalData_URL_TEMPLATES`` may be set to provide a list of
|
Note that the hashes are used only for unique data identification and
|
||||||
of URL templates using the placeholders ``%(algo)`` and ``%(hash)``
|
download verification.
|
||||||
in each template. Data fetch rules try each URL template in order
|
|
||||||
by substituting the hash algorithm name for ``%(algo)`` and the hash
|
|
||||||
value for ``%(hash)``.
|
|
||||||
|
|
||||||
.. variable:: ExternalData_LINK_CONTENT
|
|
||||||
|
|
||||||
The ``ExternalData_LINK_CONTENT`` variable may be set to the name of a
|
|
||||||
supported hash algorithm to enable automatic conversion of real data
|
|
||||||
files referenced by the ``DATA{}`` syntax into content links. For each
|
|
||||||
such ``<file>`` a content link named ``<file><ext>`` is created. The
|
|
||||||
original file is renamed to the form ``.ExternalData_<algo>_<hash>`` to
|
|
||||||
stage it for future transmission to one of the locations in the list
|
|
||||||
of URL templates (by means outside the scope of this module). The
|
|
||||||
data fetch rule created for the content link will use the staged
|
|
||||||
object if it cannot be found using any URL template.
|
|
||||||
|
|
||||||
.. variable:: ExternalData_OBJECT_STORES
|
|
||||||
|
|
||||||
The ``ExternalData_OBJECT_STORES`` variable may be set to a list of local
|
|
||||||
directories that store objects using the layout ``<dir>/%(algo)/%(hash)``.
|
|
||||||
These directories will be searched first for a needed object. If the
|
|
||||||
object is not available in any store then it will be fetched remotely
|
|
||||||
using the URL templates and added to the first local store listed. If
|
|
||||||
no stores are specified the default is a location inside the build
|
|
||||||
tree.
|
|
||||||
|
|
||||||
.. variable:: ExternalData_SOURCE_ROOT
|
|
||||||
|
|
||||||
The ``ExternalData_SOURCE_ROOT`` variable may be set to the highest source
|
|
||||||
directory containing any path named by a ``DATA{}`` reference. The
|
|
||||||
default is ``CMAKE_SOURCE_DIR``. ``ExternalData_SOURCE_ROOT`` and
|
|
||||||
``CMAKE_SOURCE_DIR`` must refer to directories within a single source
|
|
||||||
distribution (e.g. they come together in one tarball).
|
|
||||||
|
|
||||||
.. variable:: ExternalData_BINARY_ROOT
|
|
||||||
|
|
||||||
The ``ExternalData_BINARY_ROOT`` variable may be set to the directory to
|
|
||||||
hold the real data files named by expanded ``DATA{}`` references. The
|
|
||||||
default is ``CMAKE_BINARY_DIR``. The directory layout will mirror that of
|
|
||||||
content links under ``ExternalData_SOURCE_ROOT``.
|
|
||||||
|
|
||||||
.. variable:: ExternalData_TIMEOUT_INACTIVITY
|
|
||||||
|
|
||||||
The ``ExternalData_TIMEOUT_INACTIVITY`` variable sets the download
|
|
||||||
inactivity timeout, in seconds, with a default of ``60`` seconds.
|
|
||||||
Set to ``0`` to disable enforcement.
|
|
||||||
|
|
||||||
.. variable:: ExternalData_TIMEOUT_ABSOLUTE
|
|
||||||
|
|
||||||
The ``ExternalData_TIMEOUT_ABSOLUTE`` variable sets the download
|
|
||||||
absolute timeout, in seconds, with a default of ``300`` seconds.
|
|
||||||
Set to ``0`` to disable enforcement.
|
|
||||||
|
|
||||||
.. variable:: ExternalData_SERIES_PARSE
|
|
||||||
ExternalData_SERIES_PARSE_PREFIX
|
|
||||||
ExternalData_SERIES_PARSE_NUMBER
|
|
||||||
ExternalData_SERIES_PARSE_SUFFIX
|
|
||||||
ExternalData_SERIES_MATCH
|
|
||||||
|
|
||||||
See `Referencing File Series`_.
|
|
||||||
#]=======================================================================]
|
#]=======================================================================]
|
||||||
|
|
||||||
#=============================================================================
|
#=============================================================================
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue