CMakeFile命令之file

1. file:文件操作命令.

   file(WRITE filename "message towrite"... )

   WRITE 将一则信息写入文件’filename’中，如果该文件存在，它会覆盖它，如果不存在，它会创建该文件。

   file(APPEND filename "message to write"... )

   APPEND 如同WRITE，区别在于它将信息内容追加到文件末尾。

   file(READ filename variable [LIMIT numBytes] [OFFSEToffset] [HEX])

   READ 会读取文件的内容并将其存入到变量中。它会在给定的偏移量处开始读取最多numBytes个字节。如果指定了HEX参数，二进制数据将会被转换成十进制表示形式并存储到变量中。

   file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filenamevariable)

   MD5, SHA1, SHA224, SHA256, SHA384, 和SHA512 会计算出文件内容对应的加密散列。

   file(STRINGS filename variable [LIMIT_COUNT num]
        [LIMIT_INPUT numBytes] [LIMIT_OUTPUTnumBytes]
        [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUMnumBytes]
        [NEWLINE_CONSUME] [REGEX regex]
        [NO_HEX_CONVERSION])

   STRINGS 从文件中解析出ASCII字符串列表并存储在变量中。文件中的二进制数据将被忽略。回车符(CR)也会被忽略。也能解析Intel Hex和Motorola S-record文件，这两种文件在读取是会自动转换为二进制格式，可以使用参数NO_HEX_CONVERSION 禁用这种自动转换。LIMIT_COUNT设置可返回的最大数量的字符串。LIMIT_INPUT 设置从输入文件中可读取的最大字节数。LIMIT_OUTPUT设置了存储在输出变量中最大的字节数。 LENGTH_MINIMUM设置了返回的字符串的最小长度。小于这个长度的字符串将被忽略。 LENGTH_MAXIMUM 设置返回的字符串的最大长度。大于这个长度的字符串将被切分为长度不大于于最大长度值的子字符串。NEWLINE_CONSUME 允许换行符包含进字符串中而不是截断它们。REGEX 指定了返回的字符串必须匹配的正则表达式的模式。典型用法

   file(STRINGS myfile.txt myfile)， 将输入文件的每行内容存储在变量"myfile"中。

   file(GLOB variable [RELATIVE path] [globbingexpressions]...)

   GLOB 会产生一个由所有匹配globbing表达式的文件组成的列表，并将其保存到变量中。Globbing 表达式与正则表达式类似，但更简单。如果指定了RELATIVE 标记，返回的结果将是与指定的路径相对的路径构成的列表。 (通常不推荐使用GLOB命令来从源码树中收集源文件列表。原因是：如果CMakeLists.txt文件没有改变，即便在该源码树中添加或删除文件，产生的构建系统也不会知道何时该要求CMake重新产生构建文件。globbing 表达式包括：

   *.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

   file(GLOB_RECURSE variable [RELATIVE path] 
        [FOLLOW_SYMLINKS] [globbingexpressions]...)

   GLOB_RECURSE 与GLOB类似，区别在于它会遍历匹配目录的所有文件以及子目录下面的文件。对于属于符号链接的子目录，只有FOLLOW_SYMLINKS指定一或者cmake策略CMP0009没有设置为NEW时，才会遍历这些目录。

   Examples of recursive globbing include:

   /dir/*.py - match all Python files in /dir and subdirectories

   file(RENAME <oldname> <newname>)

   RENAME 将文件系统中的文件或目录移动到目标位置，并自动替换目标位置处的文件或目录。

   file(REMOVE [file1 ...])

   REMOVE 会删除指定的文件以及子目录下的文件。

   file(REMOVE_RECURSE [file1 ...])

   REMOVE_RECURSE 会删除指定的文件及子目录，包括非空目录。

   file(MAKE_DIRECTORY [directory1 directory2 ...])

   MAKE_DIRECTORY在指定目录处创建子目录，如果它们的父目录不存在，也会创建它们的父目录。

   file(RELATIVE_PATH variable directory file)

   RELATIVE_PAT推断出指定文件相对于特定目录的路径。

   file(TO_CMAKE_PATH path result)

   TO_CMAKE_PATH会将路径转换成cmake风格的路径表达形式。

   file(TO_NATIVE_PATH path result)

   TO_NATIVE_PATH与TO_CMAKE_PATH类似，但执行反向操作，将cmake风格的路径转换为操作系统特定风格的路径表式形式。

   file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout]
        [TIMEOUT timeout] [STATUS status] [LOGlog] [SHOW_PROGRESS]
        [EXPECTED_MD5 sum])

   DOWNLOAD下载指定URL的资源到指定的文件上。如果指定了LOG 参数，将会把下载的日志保存到相应的变量中。如果指定了STATUS变量，操作的状态信息就会保存在相应的变量中。返回的状态是一个长度为2的列表。第一个元素是操作的返回值。0表示操作过程中无错误发生。如果指定了TIMEOUT，单位于秒，且必须为整数，那么在指定的时间后，操作将会超时，INACTIVITY_TIMEOUT指定了操作在处于活动状态超过指定的秒数后，应该停止。如果指定了EXPECTED_MD5，如果操作会检验下载后的文件的实际md5校验和是否与预期的匹配，如果不匹配，操作将会失败，并返回相应的错误码。如果指定了 SHOW_PROGRESS，那么进度的信息将会被打印成状态信息直到操作完成。

   file(UPLOADfilename url [INACTIVITY_TIMEOUT timeout]
        [TIMEOUT timeout] [STATUS status][LOG log] [SHOW_PROGRESS])

   UPLOAD与DOWNLOAD类似，它执行的是一个上传操作。参数含义与DOWNLOAD 一致。

   file(<COPY|INSTALL> files... DESTINATION<dir>
        [FILE_PERMISSIONS permissions...]
        [DIRECTORY_PERMISSIONSpermissions...]
        [NO_SOURCE_PERMISSIONS][USE_SOURCE_PERMISSIONS]
        [FILES_MATCHING]
        [[PATTERN <pattern> | REGEX<regex>]
        [EXCLUDE] [PERMISSIONSpermissions...]] [...])

   COPY表示复制文件，目录以及符号链接到一个目标文件夹中。输入路径将视为相对于当前源码目录的路径。目标路径则是相对于当前的构建目录。复制保留输入文件的一些权限属性，

   除非显式指定了NO_SOURCE_PERMISSIONS（默认是USE_SOURCE_PERMISSIONS），关于文件权限，PATTERN,REGX和EXCLUDE等相关选项可参考install(DIRECTORY)命令的文档。

   INSTALL 与COPY略微有点不同：它打印状态信息，并且默认情况下指定了 NO_SOURCE_PERMISSIONS。

   测试例子：

   1. message(STATUS "current dir: ${CMAKE_CURRENT_SOURCE_DIR}")
   2. file(WRITE test1.txt "Some messages to Write\n" )
   3. file(APPEND test1.txt "Another message to write\n")
   4. file(READ test1.txt CONTENTS LIMIT 4 OFFSET 12)
   5. message(STATUS "contents of test1.txt is: \n ${CONTENTS}")
   6. file(MD5 ${CMAKE_CURRENT_SOURCE_DIR}/test1.txt HASH_CONTENTS)
   7. message(STATUS "hash contents of test1.txt is: \n ${HASH_CONTENTS}")
   8. file(STRINGS test1.txt PARSED_STRINGS)
   9. message(STATUS "\n strings of test1.txt is: \n ${PARSED_STRINGS}")
   10. file(GLOB files RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} "*.*")
   11. FILE(GLOB SOURCES "*.cu" "*.cpp" "*.c" "*.h")
   12. message(STATUS  "files: ${files}")
   13. file(MAKE_DIRECTORY dir1 dir2)
   14. file(RENAME dir2 dir3)
   15. file(REMOVE dir3)
   16. file(REMOVE_RECURSE dir3)
   17. file(RELATIVE_PATH relative_path ${PROJECT_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/test1.txt)
   18. message(STATUS "relative path : ${relative_path}")
   19. file(TO_CMAKE_PATH "$ENV{PATH}" cmake_path)
   20. message(STATUS "cmake path: ${cmake_path}")
   21. file(TO_NATIVE_PATH "/usr/local/sbin;/usr/local/bin" native_path)
   22. message(STATUS "native path: ${native_path}")
   23. file(DOWNLOAD "http://www.baidu.com" ${CMAKE_CURRENT_SOURCE_DIR}/index.html SHOW_PROGRESS)
   24. file(COPY test1.txt DESTINATION ${CMAKE_CURRENT_SOURCE_DIR}/dir1)
   25. file(INSTALL test1.txt DESTINATION ${CMAKE_CURRENT_SOURCE_DIR}/dir1)

    
   

源码解释　　　　

FILE

File manipulation command.

file(WRITE filename "message to write"... )
file(APPEND filename "message to write"... )
file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filename variable)
file(STRINGS filename variable [LIMIT_COUNT num]
     [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
     [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
     [NEWLINE_CONSUME] [REGEX regex]
     [NO_HEX_CONVERSION])
file(GLOB variable [RELATIVE path] [globbing expressions]...)
file(GLOB_RECURSE variable [RELATIVE path]
     [FOLLOW_SYMLINKS] [globbing expressions]...)
file(RENAME <oldname> <newname>)
file(REMOVE [file1 ...])
file(REMOVE_RECURSE [file1 ...])
file(MAKE_DIRECTORY [directory1 directory2 ...])
file(RELATIVE_PATH variable directory file)
file(TO_CMAKE_PATH path result)
file(TO_NATIVE_PATH path result)
file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout]
     [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]
     [EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum]
     [TLS_VERIFY on|off] [TLS_CAINFO file])
file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout]
     [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])
file(TIMESTAMP filename variable [<format string>] [UTC])
file(GENERATE OUTPUT output_file
     <INPUT input_file|CONTENT input_content>
     [CONDITION expression])

WRITE will write a message into a file called ‘filename’. It overwrites the file if it already exists, and creates the file if it does not exist. (If the file is a build input, use configure_file to update the file only when its content changes.)

APPEND will write a message into a file same as WRITE, except it will append it to the end of the file

READ will read the content of a file and store it into the variable. It will start at the given offset and read up to numBytes. If the argument HEX is given, the binary data will be converted to hexadecimal representation and this will be stored in the variable.

MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a cryptographic hash of the content of a file.

STRINGS will parse a list of ASCII strings from a file and store it in a variable. Binary data in the file are ignored. Carriage return (CR) characters are ignored. It works also for Intel Hex and Motorola S-record files, which are automatically converted to binary format when reading them. Disable this using NO_HEX_CONVERSION.

LIMIT_COUNT sets the maximum number of strings to return. LIMIT_INPUT sets the maximum number of bytes to read from the input file. LIMIT_OUTPUT sets the maximum number of bytes to store in the output variable. LENGTH_MINIMUM sets the minimum length of a string to return. Shorter strings are ignored. LENGTH_MAXIMUM sets the maximum length of a string to return. Longer strings are split into strings no longer than the maximum length. NEWLINE_CONSUME allows newlines to be included in strings instead of terminating them.

REGEX specifies a regular expression that a string must match to be returned. Typical usage

file(STRINGS myfile.txt myfile)

stores a list in the variable “myfile” in which each item is a line from the input file.

GLOB will generate a list of all 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 for an expression, the results will be returned as a relative path to the given path. (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.)

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

GLOB_RECURSE will generate a list similar to the regular GLOB, except it 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 cmake policy CMP0009 is not set to NEW. See cmake –help-policy CMP0009 for more information.

Examples of recursive globbing include:

/dir/*.py  - match all python files in /dir and subdirectories

MAKE_DIRECTORY will create the given directories, also if their parent directories don’t exist yet

RENAME moves a file or directory within a filesystem, replacing the destination atomically.

REMOVE will remove the given files, also in subdirectories

REMOVE_RECURSE will remove the given files and directories, also non-empty directories

RELATIVE_PATH will determine relative path from directory to the given file.

TO_CMAKE_PATH will convert path into a cmake style path with unix /. The input can be a single path or a system path like “$ENV{PATH}”. Note the double quotes around the ENV call TO_CMAKE_PATH only takes one argument. This command will also convert the native list delimiters for a list of paths like the PATH environment variable.

TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert from a cmake style path into the native path style for windows and / for UNIX.

DOWNLOAD will download the given URL to the given file. If LOG var is specified a log of the download will be put in var. If STATUS var is specified the status of the operation will be put in var. The status is returned in a 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. If TIMEOUT time is specified, the operation will timeout after time seconds, time should be specified as an integer. The INACTIVITY_TIMEOUT specifies an integer number of seconds of inactivity after which the operation should terminate. If EXPECTED_HASH ALGO=value is specified, the operation will verify that the downloaded file’s actual hash matches the expected value, where ALGO is one of MD5, SHA1, SHA224, SHA256, SHA384, or SHA512. If it does not match, the operation fails with an error. (“EXPECTED_MD5 sum” is short-hand for “EXPECTED_HASH MD5=sum”.) If SHOW_PROGRESS is specified, progress information will be printed as status messages until the operation is complete. For https URLs CMake must be built with OpenSSL. 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. Set TLS_CAINFO to specify a custom Certificate Authority file. If either TLS option is not given CMake will check variables CMAKE_TLS_VERIFY and CMAKE_TLS_CAINFO, respectively.

UPLOAD will upload the given file to the given URL. If LOG var is specified a log of the upload will be put in var. If STATUS var is specified the status of the operation will be put in var. The status is returned in a 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. If TIMEOUT time is specified, the operation will timeout after time seconds, time should be specified as an integer. The INACTIVITY_TIMEOUT specifies an integer number of seconds of inactivity after which the operation should terminate. If SHOW_PROGRESS is specified, progress information will be printed as status messages until the operation is complete.

TIMESTAMP will write a string representation of the modification time of filename to variable.

Should the command be unable to obtain a timestamp variable will be set to the empty string “”.

See documentation of the string TIMESTAMP sub-command for more details.

The file() command also provides COPY and INSTALL signatures:

file(<COPY|INSTALL> files... DESTINATION <dir>
     [FILE_PERMISSIONS permissions...]
     [DIRECTORY_PERMISSIONS permissions...]
     [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
     [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). See the install(DIRECTORY) command for documentation of permissions, PATTERN, REGEX, and EXCLUDE options.

The INSTALL signature differs slightly from COPY: it prints status messages, and NO_SOURCE_PERMISSIONS is default. Installation scripts generated by the install() command use this signature (with some undocumented options for internal use).

GENERATE will write an <output_file> with content from an <input_file>, or from <input_content>. The output is generated conditionally based on the content of the <condition>. The file is written at CMake generate-time and the input may contain generator expressions. The <condition>, <output_file> and <input_file> may also contain generator expressions. The <condition> must evaluate to either ‘0’ or ‘1’. The <output_file> must evaluate to a unique name among all configurations and among all invocations of file(GENERATE).