kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

ExternalData: Improve documentation organization 

Move the basic DATA{} description to a section just before the
file series description.  Move all sections on referencing files
into subsections of a common "Referencing Files" section.

Subsume example usage into the introduction since it gives a
high-level starting point to understand the rest of the docs.
This commit is contained in:
Brad King 2015-01-12 15:14:45 -05:00
parent a32b2245ca
commit 945571db74
1 changed files with 18 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
Modules/ExternalData.cmake
View File

@ -18,16 +18,7 @@ recognize arguments with the syntax ``DATA{<name>}`` as references to
external data, replace them with full paths to local copies of those external data, replace them with full paths to local copies of those
data, and create build rules to fetch and update the local copies. data, and create build rules to fetch and update the local copies.
The ``DATA{}`` syntax is literal and the ``<name>`` is a full or relative path For example:
within the source tree. The source tree must contain either a real
data file at ``<name>`` or a "content link" at ``<name><ext>`` containing a
hash of the real file using a hash algorithm corresponding to ``<ext>``.
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``
file containing its MD5 sum.
Example Usage
^^^^^^^^^^^^^
.. code-block:: cmake .. code-block:: cmake
@ -166,8 +157,22 @@ calling any of the functions provided by this module.
by substituting the hash algorithm name for ``%(algo)`` and the hash by substituting the hash algorithm name for ``%(algo)`` and the hash
value for ``%(hash)``. value for ``%(hash)``.
Referencing Files
^^^^^^^^^^^^^^^^^
Referencing Single Files
""""""""""""""""""""""""
The ``DATA{}`` syntax is literal and the ``<name>`` is a full or relative path
within the source tree. The source tree must contain either a real
data file at ``<name>`` or a "content link" at ``<name><ext>`` containing a
hash of the real file using a hash algorithm corresponding to ``<ext>``.
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``
file containing its MD5 sum.
Referencing File Series Referencing File Series
^^^^^^^^^^^^^^^^^^^^^^^ """""""""""""""""""""""
The ``DATA{}`` syntax can be told to fetch a file series using the form The ``DATA{}`` syntax can be told to fetch a file series using the form
``DATA{<name>,:}``, where the ``:`` is literal. If the source tree ``DATA{<name>,:}``, where the ``:`` is literal. If the source tree
@ -198,7 +203,7 @@ Note that the ``<suffix>`` of a series does not include a hash-algorithm
extension. extension.
Referencing Associated Files Referencing Associated Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ """"""""""""""""""""""""""""
The ``DATA{}`` syntax can alternatively match files associated with the The ``DATA{}`` syntax can alternatively match files associated with the
named file and contained in the same directory. Associated files may named file and contained in the same directory. Associated files may
@ -214,7 +219,7 @@ will pass ``MyInput.mha`` and ``MyFrames00.png`` on the command line but
ensure that the associated files are present next to them. ensure that the associated files are present next to them.
Referencing Directories Referencing Directories
^^^^^^^^^^^^^^^^^^^^^^^ """""""""""""""""""""""
The ``DATA{}`` syntax may reference a directory using a trailing slash and The ``DATA{}`` syntax may reference a directory using a trailing slash and
a list of associated files. The form ``DATA{<name>/,<opt1>,<opt2>,...}`` a list of associated files. The form ``DATA{<name>/,<opt1>,<opt2>,...}``