diff options
Diffstat (limited to 'Help/command/file.rst')
| -rw-r--r-- | Help/command/file.rst | 47 |
1 files changed, 39 insertions, 8 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst index b2e4eea..5ce86e5 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -13,8 +13,11 @@ File manipulation command. Write ``<content>`` into a file called ``<filename>``. If the file does not exist, it will be created. If the file already exists, ``WRITE`` mode will overwrite it and ``APPEND`` mode will append to the end. -(If the file is a build input, use the :command:`configure_file` command -to update the file only when its content changes.) +Any directories in the path specified by ``<filename>`` that do not +exist will be created. + +If the file is a build input, use the :command:`configure_file` command +to update the file only when its content changes. ------------------------------------------------------------------------------ @@ -105,11 +108,9 @@ Generate a list of files that match the ``<globbing-expressions>`` and store it into the ``<variable>``. Globbing expressions are similar to regular expressions, but much simpler. If ``RELATIVE`` flag is specified, the results will be returned as relative paths to the given -path. No specific order of results is defined other than that it is -deterministic. If order is important then sort the list explicitly -(e.g. using the :command:`list(SORT)` command). +path. The results will be ordered lexicographically. -By default ``GLOB`` lists directories - directories are omited in result if +By default ``GLOB`` lists directories - directories are omitted in result if ``LIST_DIRECTORIES`` is set to false. .. note:: @@ -231,6 +232,31 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: ``HTTPHEADER <HTTP-header>`` HTTP header for operation. Suboption can be repeated several times. +``NETRC <level>`` + Specify whether the .netrc file is to be used for operation. If this + option is not specified, the value of the ``CMAKE_NETRC`` variable + will be used instead. + Valid levels are: + + ``IGNORED`` + The .netrc file is ignored. + This is the default. + ``OPTIONAL`` + The .netrc file is optional, and information in the URL is preferred. + The file will be scanned to find which ever information is not specified + in the URL. + ``REQUIRED`` + The .netrc file is required, and information in the URL is ignored. + +``NETRC_FILE <file>`` + Specify an alternative .netrc file to the one in your home directory, + if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option + is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will + be used instead. + +If neither ``NETRC`` option is given CMake will check variables +``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively. + Additional options to ``DOWNLOAD`` are: ``EXPECTED_HASH ALGO=<value>`` @@ -291,6 +317,8 @@ from the input content to produce the output content. The options are: ``INPUT <input-file>`` Use the content from a given file as input. + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. ``OUTPUT <output-file>`` Specify the output file name to generate. Use generator expressions @@ -298,11 +326,14 @@ from the input content to produce the output content. The options are: name. Multiple configurations may generate the same output file only if the generated content is identical. Otherwise, the ``<output-file>`` must evaluate to an unique name for each configuration. + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. -Generated files are modified on subsequent cmake runs only if their content -is changed. +Generated files are modified and their timestamp updated on subsequent cmake +runs only if their content is changed. Note also that ``file(GENERATE)`` does not create the output file until the generation phase. The output file will not yet have been written when the |