From 68fb1572a8352f5229009285202afc3df692642f Mon Sep 17 00:00:00 2001 From: Matthew Woehlke Date: Fri, 10 Mar 2023 15:22:51 -0500 Subject: Help: Convert signatures of file command Convert `file` command to use new `signature` directive. Use '' rather than 'HASH' for relevant signature targets, as this is arguably more correct, results in less need to specify explicit targets, but still produces '#hash' as the HTML anchor. Although actual textual changes to `file` are fairly minimal, large portions of the content have been re-indented and in many cases, re-flowed. Some tabular content in literal text blocks has also been converted to actual tables. --- Help/command/file.rst | 1820 +++++++++++++++---------------- Help/command/get_filename_component.rst | 6 +- Help/command/string.rst | 4 +- 3 files changed, 899 insertions(+), 931 deletions(-) diff --git a/Help/command/file.rst b/Help/command/file.rst index 6ab7421..5c41f0d 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -26,7 +26,7 @@ Synopsis `Reading`_ file(`READ`_ [...]) file(`STRINGS`_ [...]) - file(`\ `_ ) + file(`\`_ ) file(`TIMESTAMP`_ [...]) file(`GET_RUNTIME_DEPENDENCIES`_ [...]) @@ -68,1209 +68,1177 @@ Synopsis Reading ^^^^^^^ -.. _READ: - -.. code-block:: cmake - +.. signature:: file(READ [OFFSET ] [LIMIT ] [HEX]) -Read content from a file called ```` and store it in a -````. Optionally start from the given ```` and -read at most ```` bytes. The ``HEX`` option causes data to -be converted to a hexadecimal representation (useful for binary data). If the -``HEX`` option is specified, letters in the output (``a`` through ``f``) are in -lowercase. - -.. _STRINGS: - -.. code-block:: cmake + Read content from a file called ```` and store it in a + ````. Optionally start from the given ```` and + read at most ```` bytes. The ``HEX`` option causes data to + be converted to a hexadecimal representation (useful for binary data). + If the ``HEX`` option is specified, letters in the output + (``a`` through ``f``) are in lowercase. +.. signature:: file(STRINGS [...]) -Parse a list of ASCII strings from ```` and store it in -````. Binary data in the file are ignored. Carriage return -(``\r``, CR) characters are ignored. The options are: + Parse a list of ASCII strings from ```` and store it in + ````. Binary data in the file are ignored. Carriage return + (``\r``, CR) characters are ignored. The options are: -``LENGTH_MAXIMUM `` - Consider only strings of at most a given length. + ``LENGTH_MAXIMUM `` + Consider only strings of at most a given length. -``LENGTH_MINIMUM `` - Consider only strings of at least a given length. + ``LENGTH_MINIMUM `` + Consider only strings of at least a given length. -``LIMIT_COUNT `` - Limit the number of distinct strings to be extracted. + ``LIMIT_COUNT `` + Limit the number of distinct strings to be extracted. -``LIMIT_INPUT `` - Limit the number of input bytes to read from the file. + ``LIMIT_INPUT `` + Limit the number of input bytes to read from the file. -``LIMIT_OUTPUT `` - Limit the number of total bytes to store in the ````. + ``LIMIT_OUTPUT `` + Limit the number of total bytes to store in the ````. -``NEWLINE_CONSUME`` - Treat newline characters (``\n``, LF) as part of string content - instead of terminating at them. + ``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. + ``NO_HEX_CONVERSION`` + Intel Hex and Motorola S-record files are automatically converted to + binary while reading unless this option is given. -``REGEX `` - Consider only strings that match the given regular expression, - as described under :ref:`string(REGEX) `. + ``REGEX `` + Consider only strings that match the given regular expression, + as described under :ref:`string(REGEX) `. -``ENCODING `` - .. versionadded:: 3.1 + ``ENCODING `` + .. versionadded:: 3.1 - 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. + 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. - .. versionadded:: 3.2 - Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings. + .. versionadded:: 3.2 + Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings. -For example, the code + For example, the code -.. code-block:: cmake + .. code-block:: cmake - file(STRINGS myfile.txt myfile) + file(STRINGS myfile.txt myfile) -stores a list in the variable ``myfile`` in which each item is a line -from the input file. + stores a list in the variable ``myfile`` in which each item is a line + from the input file. -.. _HASH: +.. signature:: + file( ) + :target: -.. code-block:: cmake + Compute a cryptographic hash of the content of ```` and + store it in a ````. The supported ```` algorithm names + are those listed by the :command:`string()` command. - file( ) +.. signature:: + file(TIMESTAMP [] [UTC]) -Compute a cryptographic hash of the content of ```` and -store it in a ````. The supported ```` algorithm names -are those listed by the :ref:`string(\) ` -command. + Compute a string representation of the modification time of ```` + and store it in ````. Should the command be unable to obtain a + timestamp variable will be set to the empty string (""). -.. _TIMESTAMP: + See the :command:`string(TIMESTAMP)` command for documentation of + the ```` and ``UTC`` options. -.. code-block:: cmake +.. signature:: + file(GET_RUNTIME_DEPENDENCIES [...]) - file(TIMESTAMP [] [UTC]) + .. versionadded:: 3.16 -Compute a string representation of the modification time of ```` -and store it in ````. Should the command be unable to obtain a -timestamp variable will be set to the empty string (""). + Recursively get the list of libraries depended on by the given files: -See the :command:`string(TIMESTAMP)` command for documentation of -the ```` and ``UTC`` options. + .. code-block:: cmake -.. _GET_RUNTIME_DEPENDENCIES: + file(GET_RUNTIME_DEPENDENCIES + [RESOLVED_DEPENDENCIES_VAR ] + [UNRESOLVED_DEPENDENCIES_VAR ] + [CONFLICTING_DEPENDENCIES_PREFIX ] + [EXECUTABLES [...]] + [LIBRARIES [...]] + [MODULES [...]] + [DIRECTORIES [...]] + [BUNDLE_EXECUTABLE ] + [PRE_INCLUDE_REGEXES [...]] + [PRE_EXCLUDE_REGEXES [...]] + [POST_INCLUDE_REGEXES [...]] + [POST_EXCLUDE_REGEXES [...]] + [POST_INCLUDE_FILES [...]] + [POST_EXCLUDE_FILES [...]] + ) -.. code-block:: cmake + Please note that this sub-command is not intended to be used in project mode. + It is intended for use at install time, either from code generated by the + :command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by + the project via :command:`install(CODE)` or :command:`install(SCRIPT)`. + For example: - file(GET_RUNTIME_DEPENDENCIES - [RESOLVED_DEPENDENCIES_VAR ] - [UNRESOLVED_DEPENDENCIES_VAR ] - [CONFLICTING_DEPENDENCIES_PREFIX ] - [EXECUTABLES [...]] - [LIBRARIES [...]] - [MODULES [...]] - [DIRECTORIES [...]] - [BUNDLE_EXECUTABLE ] - [PRE_INCLUDE_REGEXES [...]] - [PRE_EXCLUDE_REGEXES [...]] - [POST_INCLUDE_REGEXES [...]] - [POST_EXCLUDE_REGEXES [...]] - [POST_INCLUDE_FILES [...]] - [POST_EXCLUDE_FILES [...]] - ) + .. code-block:: cmake -.. versionadded:: 3.16 + install(CODE [[ + file(GET_RUNTIME_DEPENDENCIES + # ... + ) + ]]) + + The arguments are as follows: + + ``RESOLVED_DEPENDENCIES_VAR `` + Name of the variable in which to store the list of resolved dependencies. + + ``UNRESOLVED_DEPENDENCIES_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 `` + 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 ``_FILENAMES``. For each filename, the list + of paths that were found for that filename are stored in + ``_``. + + ``EXECUTABLES `` + 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 `` + 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 `` + 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 `` + 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 `` + 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 `` + List of pre-include regexes through which to filter the names of + not-yet-resolved dependencies. + + ``PRE_EXCLUDE_REGEXES `` + List of pre-exclude regexes through which to filter the names of + not-yet-resolved dependencies. + + ``POST_INCLUDE_REGEXES `` + List of post-include regexes through which to filter the names of + resolved dependencies. + + ``POST_EXCLUDE_REGEXES `` + List of post-exclude regexes through which to filter the names of + resolved dependencies. + + ``POST_INCLUDE_FILES `` + .. versionadded:: 3.21 + + List of post-include filenames through which to filter the names of + resolved dependencies. Symlinks are resolved when attempting to match + these filenames. + + ``POST_EXCLUDE_FILES `` + .. versionadded:: 3.21 + + List of post-exclude filenames through which to filter the names of + resolved dependencies. Symlinks are resolved when attempting to match + these filenames. + + These arguments can be used to exclude unwanted system libraries when + resolving the dependencies, or to include 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`` or ``POST_INCLUDE_FILES``, 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`` or ``POST_EXCLUDE_FILES``, 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``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``, + or ``POST_EXCLUDE_FILES``, 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). -Recursively get the list of libraries depended on by the given files. + 5. Otherwise, the dependency is unresolved. -Please note that this sub-command is not intended to be used in project mode. -It is intended for use at install time, either from code generated by the -:command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by -the project via :command:`install(CODE)` or :command:`install(SCRIPT)`. -For example: + On Windows platforms, library resolution works as follows: -.. code-block:: cmake + 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: - install(CODE [[ - file(GET_RUNTIME_DEPENDENCIES - # ... - ) - ]]) - -The arguments are as follows: - -``RESOLVED_DEPENDENCIES_VAR `` - Name of the variable in which to store the list of resolved dependencies. - -``UNRESOLVED_DEPENDENCIES_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 `` - 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 - ``_FILENAMES``. For each filename, the list of paths - that were found for that filename are stored in - ``_``. - -``EXECUTABLES `` - 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 `` - 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 `` - 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 `` - 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 `` - 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 `` - List of pre-include regexes through which to filter the names of - not-yet-resolved dependencies. - -``PRE_EXCLUDE_REGEXES `` - List of pre-exclude regexes through which to filter the names of - not-yet-resolved dependencies. - -``POST_INCLUDE_REGEXES `` - List of post-include regexes through which to filter the names of resolved - dependencies. - -``POST_EXCLUDE_REGEXES `` - List of post-exclude regexes through which to filter the names of resolved - dependencies. - -``POST_INCLUDE_FILES `` - .. versionadded:: 3.21 + .. code-block:: cmake - List of post-include filenames through which to filter the names of resolved - dependencies. Symlinks are resolved when attempting to match these filenames. + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$" + ) -``POST_EXCLUDE_FILES `` - .. versionadded:: 3.21 + Converting the DLL name to lowercase allows the regexes to only match + lowercase names, thus simplifying the regex. For example: - List of post-exclude filenames through which to filter the names of resolved - dependencies. Symlinks are resolved when attempting to match these filenames. - -These arguments can be used to exclude unwanted system libraries when -resolving the dependencies, or to include 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`` or ``POST_INCLUDE_FILES``, 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`` or ``POST_EXCLUDE_FILES``, 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``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``, - or ``POST_EXCLUDE_FILES``, 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 by the value of - ``CMAKE_OBJDUMP`` if set, else by system introspection. + .. code-block:: cmake - .. versionadded:: 3.18 - Use ``CMAKE_OBJDUMP`` if set. + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^mylibrary\\.dll$" + ) -Writing -^^^^^^^ + 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``.) -.. _WRITE: -.. _APPEND: + 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. -.. code-block:: cmake + 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. - file(WRITE ...) - file(APPEND ...) + 3. Otherwise, if the library exists in the same directory as the depending + file, the dependency is resolved to that file. -Write ```` into a file called ````. 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 ```` that do not -exist will be created. + 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. -If the file is a build input, use the :command:`configure_file` command -to update the file only when its content changes. + 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. -.. _TOUCH: -.. _TOUCH_NOCREATE: + 6. Otherwise, the dependency is unresolved. -.. code-block:: cmake + On Apple platforms, library resolution works as follows: - file(TOUCH [...]) - file(TOUCH_NOCREATE [...]) + 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. -.. versionadded:: 3.12 + 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. -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. + 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. -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. + 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. -With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be -modified. + 5. Otherwise, if the dependency is an absolute file that exists, + the dependency is resolved to that file. -.. _GENERATE: + 6. Otherwise, the dependency is unresolved. -.. code-block:: cmake + This function accepts several variables that determine which tool is used for + dependency resolution: - file(GENERATE OUTPUT output-file - - [CONDITION expression] [TARGET target] - [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | - FILE_PERMISSIONS ...] - [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) + .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM -Generate an output file for each build configuration supported by the current -:manual:`CMake Generator `. Evaluate -:manual:`generator expressions ` -from the input content to produce the output content. The options are: + Determines which operating system and executable format the files are built + for. This could be one of several values: -``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. + * ``linux+elf`` + * ``windows+pe`` + * ``macos+macho`` -``CONTENT `` - Use the content given explicitly as input. + If this variable is not specified, it is determined automatically by system + introspection. -``INPUT `` - Use the content from a given file as input. + .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL - .. versionchanged:: 3.10 - A relative path is treated with respect to the value of - :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. + 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`: -``OUTPUT `` - Specify the output file name to generate. Use generator expressions - such as :genex:`$` 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 - ```` must evaluate to an unique name for each configuration. + ================================================= ============================================= + ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL`` + ================================================= ============================================= + ``linux+elf`` ``objdump`` + ``windows+pe`` ``objdump`` or ``dumpbin`` + ``macos+macho`` ``otool`` + ================================================= ============================================= - .. versionchanged:: 3.10 - A relative path (after evaluating generator expressions) is treated - with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. - See policy :policy:`CMP0070`. + If this variable is not specified, it is determined automatically by system + introspection. -``TARGET `` - .. versionadded:: 3.19 + .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND - Specify which target to use when evaluating generator expressions that - require a target for evaluation (e.g. - :genex:`$`, - :genex:`$`). + Determines the path to the tool to use for dependency resolution. This is + the actual path to ``objdump``, ``dumpbin``, or ``otool``. -``NO_SOURCE_PERMISSIONS`` - .. versionadded:: 3.20 + If this variable is not specified, it is determined by the value of + ``CMAKE_OBJDUMP`` if set, else by system introspection. - The generated file permissions default to the standard 644 value - (-rw-r--r--). + .. versionadded:: 3.18 + Use ``CMAKE_OBJDUMP`` if set. -``USE_SOURCE_PERMISSIONS`` - .. versionadded:: 3.20 +Writing +^^^^^^^ - Transfer the file permissions of the ``INPUT`` file to the generated file. - This is already the default behavior if none of the three permissions-related - keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS`` - or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly - serves as a way of making the intended behavior clearer at the call site. - It is an error to specify this option without ``INPUT``. +.. signature:: + file(WRITE ...) + file(APPEND ...) -``FILE_PERMISSIONS ...`` - .. versionadded:: 3.20 + Write ```` into a file called ````. 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 ```` that do not + exist will be created. - Use the specified permissions for the generated file. + If the file is a build input, use the :command:`configure_file` command + to update the file only when its content changes. -``NEWLINE_STYLE