diff options
Diffstat (limited to 'share/cmake-3.17/Help/command/file.rst')
| -rw-r--r-- | share/cmake-3.17/Help/command/file.rst | 848 |
1 files changed, 848 insertions, 0 deletions
diff --git a/share/cmake-3.17/Help/command/file.rst b/share/cmake-3.17/Help/command/file.rst new file mode 100644 index 0000000..df7d8ba --- /dev/null +++ b/share/cmake-3.17/Help/command/file.rst @@ -0,0 +1,848 @@ +file +---- + +File manipulation command. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Reading`_ + file(`READ`_ <filename> <out-var> [...]) + file(`STRINGS`_ <filename> <out-var> [...]) + file(`\<HASH\> <HASH_>`_ <filename> <out-var>) + file(`TIMESTAMP`_ <filename> <out-var> [...]) + file(`GET_RUNTIME_DEPENDENCIES`_ [...]) + + `Writing`_ + file({`WRITE`_ | `APPEND`_} <filename> <content>...) + file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...]) + file(`GENERATE`_ OUTPUT <output-file> [...]) + + `Filesystem`_ + file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) + file(`RENAME`_ <oldname> <newname>) + file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) + file(`MAKE_DIRECTORY`_ [<dir>...]) + file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) + file(`SIZE`_ <filename> <out-var>) + file(`READ_SYMLINK`_ <linkname> <out-var>) + file(`CREATE_LINK`_ <original> <linkname> [...]) + + `Path Conversion`_ + file(`RELATIVE_PATH`_ <out-var> <directory> <file>) + file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>) + + `Transfer`_ + file(`DOWNLOAD`_ <url> <file> [...]) + file(`UPLOAD`_ <file> <url> [...]) + + `Locking`_ + file(`LOCK`_ <path> [...]) + +Reading +^^^^^^^ + +.. _READ: + +.. code-block:: cmake + + file(READ <filename> <variable> + [OFFSET <offset>] [LIMIT <max-in>] [HEX]) + +Read content from a file called ``<filename>`` and store it in a +``<variable>``. Optionally start from the given ``<offset>`` and +read at most ``<max-in>`` bytes. The ``HEX`` option causes data to +be converted to a hexadecimal representation (useful for binary data). + +.. _STRINGS: + +.. code-block:: cmake + + file(STRINGS <filename> <variable> [<options>...]) + +Parse a list of ASCII strings from ``<filename>`` and store it in +``<variable>``. Binary data in the file are ignored. Carriage return +(``\r``, CR) characters are ignored. The options are: + +``LENGTH_MAXIMUM <max-len>`` + Consider only strings of at most a given length. + +``LENGTH_MINIMUM <min-len>`` + Consider only strings of at least a given length. + +``LIMIT_COUNT <max-num>`` + Limit the number of distinct strings to be extracted. + +``LIMIT_INPUT <max-in>`` + Limit the number of input bytes to read from the file. + +``LIMIT_OUTPUT <max-out>`` + Limit the number of total bytes to store in the ``<variable>``. + +``NEWLINE_CONSUME`` + Treat newline characters (``\n``, LF) as part of string content + instead of terminating at them. + +``NO_HEX_CONVERSION`` + Intel Hex and Motorola S-record files are automatically converted to + binary while reading unless this option is given. + +``REGEX <regex>`` + Consider only strings that match the given regular expression. + +``ENCODING <encoding-type>`` + Consider strings of a given encoding. Currently supported encodings are: + UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. If the ENCODING option + is not provided and the file has a Byte Order Mark, the ENCODING option + will be defaulted to respect the Byte Order Mark. + +For example, the code + +.. code-block:: cmake + + file(STRINGS myfile.txt myfile) + +stores a list in the variable ``myfile`` in which each item is a line +from the input file. + +.. _HASH: + +.. code-block:: cmake + + file(<HASH> <filename> <variable>) + +Compute a cryptographic hash of the content of ``<filename>`` and +store it in a ``<variable>``. The supported ``<HASH>`` algorithm names +are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>` +command. + +.. _TIMESTAMP: + +.. code-block:: cmake + + file(TIMESTAMP <filename> <variable> [<format>] [UTC]) + +Compute a string representation of the modification time of ``<filename>`` +and store it in ``<variable>``. Should the command be unable to obtain a +timestamp variable will be set to the empty string (""). + +See the :command:`string(TIMESTAMP)` command for documentation of +the ``<format>`` and ``UTC`` options. + +.. _GET_RUNTIME_DEPENDENCIES: + +.. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + [RESOLVED_DEPENDENCIES_VAR <deps_var>] + [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>] + [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>] + [EXECUTABLES [<executable_files>...]] + [LIBRARIES [<library_files>...]] + [MODULES [<module_files>...]] + [DIRECTORIES [<directories>...]] + [BUNDLE_EXECUTABLE <bundle_executable_file>] + [PRE_INCLUDE_REGEXES [<regexes>...]] + [PRE_EXCLUDE_REGEXES [<regexes>...]] + [POST_INCLUDE_REGEXES [<regexes>...]] + [POST_EXCLUDE_REGEXES [<regexes>...]] + ) + +Recursively get the list of libraries depended on by the given files. + +Please note that this sub-command is not intended to be used in project mode. +Instead, use it in an :command:`install(CODE)` or :command:`install(SCRIPT)` +block. For example: + +.. code-block:: cmake + + install(CODE [[ + file(GET_RUNTIME_DEPENDENCIES + # ... + ) + ]]) + +The arguments are as follows: + +``RESOLVED_DEPENDENCIES_VAR <deps_var>`` + Name of the variable in which to store the list of resolved dependencies. + +``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>`` + Name of the variable in which to store the list of unresolved dependencies. + If this variable is not specified, and there are any unresolved dependencies, + an error is issued. + +``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>`` + Variable prefix in which to store conflicting dependency information. + Dependencies are conflicting if two files with the same name are found in + two different directories. The list of filenames that conflict are stored in + ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list of paths + that were found for that filename are stored in + ``<conflicting_deps_prefix>_<filename>``. + +``EXECUTABLES <executable_files>`` + List of executable files to read for dependencies. These are executables that + are typically created with :command:`add_executable`, but they do not have to + be created by CMake. On Apple platforms, the paths to these files determine + the value of ``@executable_path`` when recursively resolving the libraries. + Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here + will result in undefined behavior. + +``LIBRARIES <library_files>`` + List of library files to read for dependencies. These are libraries that are + typically created with :command:`add_library(SHARED)`, but they do not have + to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` + libraries, or executables here will result in undefined behavior. + +``MODULES <module_files>`` + List of loadable module files to read for dependencies. These are modules + that are typically created with :command:`add_library(MODULE)`, but they do + not have to be created by CMake. They are typically used by calling + ``dlopen()`` at runtime rather than linked at link time with ``ld -l``. + Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here + will result in undefined behavior. + +``DIRECTORIES <directories>`` + List of additional directories to search for dependencies. On Linux + platforms, these directories are searched if the dependency is not found in + any of the other usual paths. If it is found in such a directory, a warning + is issued, because it means that the file is incomplete (it does not list all + of the directories that contain its dependencies). On Windows platforms, + these directories are searched if the dependency is not found in any of the + other search paths, but no warning is issued, because searching other paths + is a normal part of Windows dependency resolution. On Apple platforms, this + argument has no effect. + +``BUNDLE_EXECUTABLE <bundle_executable_file>`` + Executable to treat as the "bundle executable" when resolving libraries. On + Apple platforms, this argument determines the value of ``@executable_path`` + when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files. + It has no effect on ``EXECUTABLES`` files. On other platforms, it has no + effect. This is typically (but not always) one of the executables in the + ``EXECUTABLES`` argument which designates the "main" executable of the + package. + +The following arguments specify filters for including or excluding libraries to +be resolved. See below for a full description of how they work. + +``PRE_INCLUDE_REGEXES <regexes>`` + List of pre-include regexes through which to filter the names of + not-yet-resolved dependencies. + +``PRE_EXCLUDE_REGEXES <regexes>`` + List of pre-exclude regexes through which to filter the names of + not-yet-resolved dependencies. + +``POST_INCLUDE_REGEXES <regexes>`` + List of post-include regexes through which to filter the names of resolved + dependencies. + +``POST_EXCLUDE_REGEXES <regexes>`` + List of post-exclude regexes through which to filter the names of resolved + dependencies. + +These arguments can be used to blacklist unwanted system libraries when +resolving the dependencies, or to whitelist libraries from a specific +directory. The filtering works as follows: + +1. If the not-yet-resolved dependency matches any of the + ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency + resolution proceeds to step 4. +2. If the not-yet-resolved dependency matches any of the + ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency. +3. Otherwise, dependency resolution proceeds. +4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to + the linking rules of the platform (see below). +5. If the dependency is found, and its full path matches one of the + ``POST_INCLUDE_REGEXES``, the full path is added to the resolved + dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves + that library's own dependencies. Otherwise, resolution proceeds to step 6. +6. If the dependency is found, but its full path matches one of the + ``POST_EXCLUDE_REGEXES``, it is not added to the resolved dependencies, and + dependency resolution stops for that dependency. +7. If the dependency is found, and its full path does not match either + ``POST_INCLUDE_REGEXES`` or ``POST_EXCLUDE_REGEXES``, the full path is added + to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` + recursively resolves that library's own dependencies. + +Different platforms have different rules for how dependencies are resolved. +These specifics are described here. + +On Linux platforms, library resolution works as follows: + +1. If the depending file does not have any ``RUNPATH`` entries, and the library + exists in one of the depending file's ``RPATH`` entries, or its parents', in + that order, the dependency is resolved to that file. +2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the + library exists in one of those entries, the dependency is resolved to that + file. +3. Otherwise, if the library exists in one of the directories listed by + ``ldconfig``, the dependency is resolved to that file. +4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, the + dependency is resolved to that file. In this case, a warning is issued, + because finding a file in one of the ``DIRECTORIES`` means that the + depending file is not complete (it does not list all the directories from + which it pulls dependencies). +5. Otherwise, the dependency is unresolved. + +On Windows platforms, library resolution works as follows: + +1. The dependent DLL name is converted to lowercase. Windows DLL names are + case-insensitive, and some linkers mangle the case of the DLL dependency + names. However, this makes it more difficult for ``PRE_INCLUDE_REGEXES``, + ``PRE_EXCLUDE_REGEXES``, ``POST_INCLUDE_REGEXES``, and + ``POST_EXCLUDE_REGEXES`` to properly filter DLL names - every regex would + have to check for both uppercase and lowercase letters. For example: + + .. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$" + ) + + Converting the DLL name to lowercase allows the regexes to only match + lowercase names, thus simplifying the regex. For example: + + .. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^mylibrary\\.dll$" + ) + + This regex will match ``mylibrary.dll`` regardless of how it is cased, + either on disk or in the depending file. (For example, it will match + ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.) + + Please note that the directory portion of any resolved DLLs retains its + casing and is not converted to lowercase. Only the filename portion is + converted. + +2. (**Not yet implemented**) If the depending file is a Windows Store app, and + the dependency is listed as a dependency in the application's package + manifest, the dependency is resolved to that file. +3. Otherwise, if the library exists in the same directory as the depending + file, the dependency is resolved to that file. +4. Otherwise, if the library exists in either the operating system's + ``system32`` directory or the ``Windows`` directory, in that order, the + dependency is resolved to that file. +5. Otherwise, if the library exists in one of the directories specified by + ``DIRECTORIES``, in the order they are listed, the dependency is resolved to + that file. In this case, a warning is not issued, because searching other + directories is a normal part of Windows library resolution. +6. Otherwise, the dependency is unresolved. + +On Apple platforms, library resolution works as follows: + +1. If the dependency starts with ``@executable_path/``, and an ``EXECUTABLES`` + argument is in the process of being resolved, and replacing + ``@executable_path/`` with the directory of the executable yields an + existing file, the dependency is resolved to that file. +2. Otherwise, if the dependency starts with ``@executable_path/``, and there is + a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` with + the directory of the bundle executable yields an existing file, the + dependency is resolved to that file. +3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing + ``@loader_path/`` with the directory of the depending file yields an + existing file, the dependency is resolved to that file. +4. Otherwise, if the dependency starts with ``@rpath/``, and replacing + ``@rpath/`` with one of the ``RPATH`` entries of the depending file yields + an existing file, the dependency is resolved to that file. Note that + ``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/`` + also have these items replaced with the appropriate path. +5. Otherwise, if the dependency is an absolute file that exists, the dependency + is resolved to that file. +6. Otherwise, the dependency is unresolved. + +This function accepts several variables that determine which tool is used for +dependency resolution: + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM + + Determines which operating system and executable format the files are built + for. This could be one of several values: + + * ``linux+elf`` + * ``windows+pe`` + * ``macos+macho`` + + If this variable is not specified, it is determined automatically by system + introspection. + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL + + Determines the tool to use for dependency resolution. It could be one of + several values, depending on the value of + :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`: + + ================================================= ============================================= + ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL`` + ================================================= ============================================= + ``linux+elf`` ``objdump`` + ``windows+pe`` ``dumpbin`` + ``windows+pe`` ``objdump`` + ``macos+macho`` ``otool`` + ================================================= ============================================= + + If this variable is not specified, it is determined automatically by system + introspection. + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND + + Determines the path to the tool to use for dependency resolution. This is the + actual path to ``objdump``, ``dumpbin``, or ``otool``. + + If this variable is not specified, it is determined automatically by system + introspection. + +Writing +^^^^^^^ + +.. _WRITE: +.. _APPEND: + +.. code-block:: cmake + + file(WRITE <filename> <content>...) + file(APPEND <filename> <content>...) + +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. +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. + +.. _TOUCH: +.. _TOUCH_NOCREATE: + +.. code-block:: cmake + + file(TOUCH [<files>...]) + file(TOUCH_NOCREATE [<files>...]) + +Create a file with no content if it does not yet exist. If the file already +exists, its access and/or modification will be updated to the time when the +function call is executed. + +Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file +does not exist it will be silently ignored. + +With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be +modified. + +.. _GENERATE: + +.. code-block:: cmake + + file(GENERATE OUTPUT output-file + <INPUT input-file|CONTENT content> + [CONDITION expression]) + +Generate an output file for each build configuration supported by the current +:manual:`CMake Generator <cmake-generators(7)>`. Evaluate +:manual:`generator expressions <cmake-generator-expressions(7)>` +from the input content to produce the output content. The options are: + +``CONDITION <condition>`` + Generate the output file for a particular configuration only if + the condition is true. The condition must be either ``0`` or ``1`` + after evaluating generator expressions. + +``CONTENT <content>`` + Use the content given explicitly as input. + +``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 + such as ``$<CONFIG>`` to specify a configuration-specific output file + 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 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 +``file(GENERATE)`` command returns, it is written only after processing all +of a project's ``CMakeLists.txt`` files. + +Filesystem +^^^^^^^^^^ + +.. _GLOB: +.. _GLOB_RECURSE: + +.. code-block:: cmake + + file(GLOB <variable> + [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] + [<globbing-expressions>...]) + file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] + [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] + [<globbing-expressions>...]) + +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. The results will be ordered lexicographically. + +On Windows and macOS, globbing is case-insensitive even if the underlying +filesystem is case-sensitive (both filenames and globbing expressions are +converted to lowercase before matching). On other platforms, globbing is +case-sensitive. + +If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic +to the main build system check target to rerun the flagged ``GLOB`` commands +at build time. If any of the outputs change, CMake will regenerate the build +system. + +By default ``GLOB`` lists directories - directories are omitted in result if +``LIST_DIRECTORIES`` is set to false. + +.. note:: + We do not recommend using GLOB to collect a list of source files from + your source tree. If no CMakeLists.txt file changes when a source is + added or removed then the generated build system cannot know when to + ask CMake to regenerate. + The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or if + a new generator is added in the future that cannot support it, projects using + it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there is + still a cost to perform the check on every rebuild. + +Examples of globbing expressions include:: + + *.cxx - match all files with extension cxx + *.vt? - match all files with extension vta,...,vtz + f[3-5].txt - match files f3.txt, f4.txt, f5.txt + +The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the +matched directory and match the files. Subdirectories that are symlinks +are only traversed if ``FOLLOW_SYMLINKS`` is given or policy +:policy:`CMP0009` is not set to ``NEW``. + +By default ``GLOB_RECURSE`` omits directories from result list - setting +``LIST_DIRECTORIES`` to true adds directories to result list. +If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to +``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories. + +Examples of recursive globbing include:: + + /dir/*.py - match all python files in /dir and subdirectories + +.. _RENAME: + +.. code-block:: cmake + + file(RENAME <oldname> <newname>) + +Move a file or directory within a filesystem from ``<oldname>`` to +``<newname>``, replacing the destination atomically. + +.. _REMOVE: +.. _REMOVE_RECURSE: + +.. code-block:: cmake + + file(REMOVE [<files>...]) + file(REMOVE_RECURSE [<files>...]) + +Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given +files and directories, also non-empty directories. No error is emitted if a +given file does not exist. Relative input paths are evaluated with respect +to the current source directory. Empty input paths are ignored with a warning. + +.. _MAKE_DIRECTORY: + +.. code-block:: cmake + + file(MAKE_DIRECTORY [<directories>...]) + +Create the given directories and their parents as needed. + +.. _COPY: +.. _INSTALL: + +.. code-block:: cmake + + file(<COPY|INSTALL> <files>... DESTINATION <dir> + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...] + [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] + [FOLLOW_SYMLINK_CHAIN] + [FILES_MATCHING] + [[PATTERN <pattern> | REGEX <regex>] + [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) + +The ``COPY`` signature copies files, directories, and symlinks to a +destination folder. Relative input paths are evaluated with respect +to the current source directory, and a relative destination is +evaluated with respect to the current build directory. Copying +preserves input file timestamps, and optimizes out a file if it exists +at the destination with the same timestamp. Copying preserves input +permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` +are given (default is ``USE_SOURCE_PERMISSIONS``). + +If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve +the symlinks at the paths given until a real file is found, and install +a corresponding symlink in the destination for each symlink encountered. For +each symlink that is installed, the resolution is stripped of the directory, +leaving only the filename, meaning that the new symlink points to a file in +the same directory as the symlink. This feature is useful on some Unix systems, +where libraries are installed as a chain of symlinks with version numbers, with +less specific versions pointing to more specific versions. +``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and the library +itself into the destination directory. For example, if you have the following +directory structure: + +* ``/opt/foo/lib/libfoo.so.1.2.3`` +* ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3`` +* ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2`` +* ``/opt/foo/lib/libfoo.so -> libfoo.so.1`` + +and you do: + +.. code-block:: cmake + + file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN) + +This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into +``lib``. + +See the :command:`install(DIRECTORY)` command for documentation of +permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and +``EXCLUDE`` options. Copying directories preserves the structure +of their content even if options are used to select a subset of +files. + +The ``INSTALL`` signature differs slightly from ``COPY``: it prints +status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), +and ``NO_SOURCE_PERMISSIONS`` is default. +Installation scripts generated by the :command:`install` command +use this signature (with some undocumented options for internal use). + +.. _SIZE: + +.. code-block:: cmake + + file(SIZE <filename> <variable>) + +Determine the file size of the ``<filename>`` and put the result in +``<variable>`` variable. Requires that ``<filename>`` is a valid path +pointing to a file and is readable. + +.. _READ_SYMLINK: + +.. code-block:: cmake + + file(READ_SYMLINK <linkname> <variable>) + +This subcommand queries the symlink ``<linkname>`` and stores the path it +points to in the result ``<variable>``. If ``<linkname>`` does not exist or +is not a symlink, CMake issues a fatal error. + +Note that this command returns the raw symlink path and does not resolve +a relative path. The following is an example of how to ensure that an +absolute path is obtained: + +.. code-block:: cmake + + set(linkname "/path/to/foo.sym") + file(READ_SYMLINK "${linkname}" result) + if(NOT IS_ABSOLUTE "${result}") + get_filename_component(dir "${linkname}" DIRECTORY) + set(result "${dir}/${result}") + endif() + +.. _CREATE_LINK: + +.. code-block:: cmake + + file(CREATE_LINK <original> <linkname> + [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC]) + +Create a link ``<linkname>`` that points to ``<original>``. +It will be a hard link by default, but providing the ``SYMBOLIC`` option +results in a symbolic link instead. Hard links require that ``original`` +exists and is a file, not a directory. If ``<linkname>`` already exists, +it will be overwritten. + +The ``<result>`` variable, if specified, receives the status of the operation. +It is set to ``0`` upon success or an error message otherwise. If ``RESULT`` +is not specified and the operation fails, a fatal error is emitted. + +Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if +creating the link fails. It can be useful for handling situations such as +``<original>`` and ``<linkname>`` being on different drives or mount points, +which would make them unable to support a hard link. + +Path Conversion +^^^^^^^^^^^^^^^ + +.. _RELATIVE_PATH: + +.. code-block:: cmake + + file(RELATIVE_PATH <variable> <directory> <file>) + +Compute the relative path from a ``<directory>`` to a ``<file>`` and +store it in the ``<variable>``. + +.. _TO_CMAKE_PATH: +.. _TO_NATIVE_PATH: + +.. code-block:: cmake + + file(TO_CMAKE_PATH "<path>" <variable>) + file(TO_NATIVE_PATH "<path>" <variable>) + +The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style +path with forward-slashes (``/``). The input can be a single path or a +system search path like ``$ENV{PATH}``. A search path will be converted +to a cmake-style list separated by ``;`` characters. + +The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native +path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere). + +Always use double quotes around the ``<path>`` to be sure it is treated +as a single argument to this command. + +Transfer +^^^^^^^^ + +.. _DOWNLOAD: +.. _UPLOAD: + +.. code-block:: cmake + + file(DOWNLOAD <url> <file> [<options>...]) + file(UPLOAD <file> <url> [<options>...]) + +The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``. +The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``. + +Options to both ``DOWNLOAD`` and ``UPLOAD`` are: + +``INACTIVITY_TIMEOUT <seconds>`` + Terminate the operation after a period of inactivity. + +``LOG <variable>`` + Store a human-readable log of the operation in a variable. + +``SHOW_PROGRESS`` + Print progress information as status messages until the operation is + complete. + +``STATUS <variable>`` + Store the resulting status of the operation in a variable. + The status is a ``;`` separated list of length 2. + The first element is the numeric return value for the operation, + and the second element is a string value for the error. + A ``0`` numeric error means no error in the operation. + +``TIMEOUT <seconds>`` + Terminate the operation after a given total time has elapsed. + +``USERPWD <username>:<password>`` + Set username and password for operation. + +``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>`` + + Verify that the downloaded content hash matches the expected value, where + ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``. + If it does not match, the operation fails with an error. + +``EXPECTED_MD5 <value>`` + Historical short-hand for ``EXPECTED_HASH MD5=<value>``. + +``TLS_VERIFY <ON|OFF>`` + Specify whether to verify the server certificate for ``https://`` URLs. + The default is to *not* verify. + +``TLS_CAINFO <file>`` + Specify a custom Certificate Authority file for ``https://`` URLs. + +For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL`` +certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to +check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content. +If neither ``TLS`` option is given CMake will check variables +``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively. + +Locking +^^^^^^^ + +.. _LOCK: + +.. code-block:: cmake + + file(LOCK <path> [DIRECTORY] [RELEASE] + [GUARD <FUNCTION|FILE|PROCESS>] + [RESULT_VARIABLE <variable>] + [TIMEOUT <seconds>]) + +Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and file +``<path>/cmake.lock`` otherwise. File will be locked for scope defined by +``GUARD`` option (default value is ``PROCESS``). ``RELEASE`` option can be used +to unlock file explicitly. If option ``TIMEOUT`` is not specified CMake will +wait until lock succeed or until fatal error occurs. If ``TIMEOUT`` is set to +``0`` lock will be tried once and result will be reported immediately. If +``TIMEOUT`` is not ``0`` CMake will try to lock file for the period specified +by ``<seconds>`` value. Any errors will be interpreted as fatal if there is no +``RESULT_VARIABLE`` option. Otherwise result will be stored in ``<variable>`` +and will be ``0`` on success or error message on failure. + +Note that lock is advisory - there is no guarantee that other processes will +respect this lock, i.e. lock synchronize two or more CMake instances sharing +some modifiable resources. Similar logic applied to ``DIRECTORY`` option - +locking parent directory doesn't prevent other ``LOCK`` commands to lock any +child directory or file. + +Trying to lock file twice is not allowed. Any intermediate directories and +file itself will be created if they not exist. ``GUARD`` and ``TIMEOUT`` +options ignored on ``RELEASE`` operation. |