cmake/gmxCustomCommandUtilities.cmake

   1 #
   2 # This file is part of the GROMACS molecular simulation package.
   3 #
   4 # Copyright (c) 2014,2016, by the GROMACS development team, led by
   5 # Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6 # and including many others, as listed in the AUTHORS file in the
   7 # top-level source directory and at http://www.gromacs.org.
   8 #
   9 # GROMACS is free software; you can redistribute it and/or
  10 # modify it under the terms of the GNU Lesser General Public License
  11 # as published by the Free Software Foundation; either version 2.1
  12 # of the License, or (at your option) any later version.
  13 #
  14 # GROMACS is distributed in the hope that it will be useful,
  15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 # Lesser General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU Lesser General Public
  20 # License along with GROMACS; if not, see
  21 # http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23 #
  24 # If you want to redistribute modifications to GROMACS, please
  25 # consider that scientific software is very special. Version
  26 # control is crucial - bugs must be traceable. We will be happy to
  27 # consider code for inclusion in the official distribution, but
  28 # derived work must not be called official GROMACS. Details are found
  29 # in the README & COPYING files - if they are missing, get the
  30 # official version at http://www.gromacs.org.
  31 #
  32 # To help us fund GROMACS development, we humbly ask that you cite
  33 # the research papers on the package. Check out http://www.gromacs.org.
  34
  35 # Helper functions for creating custom commands
  36 #
  37 # CMake semantics of add_custom_command() and add_custom_target() are not
  38 # always very convenient or intuitive for creating commands that do not always
  39 # run.  This file provides a gmx_add_custom_output_target() to simplify the
  40 # task.  The function also provides some convenience features to remove code
  41 # duplication in some parts of the GROMACS build system.
  42 #
  43 # Additionally, gmx_get_stamp_filename() and gmx_get_files_with_gitattribute()
  44 # are provided independently to help in creating custom commands.
  45
  46 # Helper function to create a stamp file name for a target.
  47 #
  48 # Usage:
  49 #   gmx_get_stamp_filename(<variable> <targetname>)
  50 #
  51 #   <variable>   - name of variable to receive the stamp name
  52 #   <targetname> - name of target for which to generate the stamp name
  53 #
  54 # This is used internally by gmx_add_custom_target(... OUTPUT STAMP ...), but
  55 # can also be called directly to create uniform stamp file names throughout the
  56 # build system.
  57 # <targetname> can be any string that is a part of a valid file name; it does
  58 # not need to name an existing or to-be-created target.
  59 function (gmx_get_stamp_filename variable targetname)
  60     set(_filename "${targetname}")
  61     if (NOT "${targetname}" MATCHES "stamp$")
  62         set(_filename "${targetname}-timestamp")
  63     endif()
  64     set(${variable} "${CMAKE_CURRENT_BINARY_DIR}/${_filename}.txt"
  65         PARENT_SCOPE)
  66 endfunction()
  67
  68 # Helper function to tell gmx_add_custom_output_target() the name of an output
  69 # file for a custom target.
  70 #
  71 # Usage:
  72 #   gmx_set_custom_target_output(<targetname> <output>)
  73 #
  74 #   <targetname> - name of an existing custom target
  75 #   <output>     - path to the output file produced by the custom target
  76 #
  77 # This is used internally by gmx_add_custom_output_target(), but can also be
  78 # called for targets created with add_custom_target() to make them work with
  79 # the dependency resolution mechanism in gmx_add_custom_output_target() if
  80 # those targets for some reason cannot be created with that command.
  81 function (gmx_set_custom_target_output targetname output)
  82     # Store the output file name in a custom property to be used in dependency
  83     # resolution later.
  84     if (NOT IS_ABSOLUTE ${output})
  85         set(output ${CMAKE_CURRENT_BINARY_DIR}/${output})
  86     endif()
  87     set_property(TARGET ${targetname}
  88         PROPERTY GMX_CUSTOM_TARGET_OUTPUT_FILE ${output})
  89 endfunction()
  90
  91 # More flexible alternative to add_custom_command() and add_custom_target()
  92 # for dependent custom commands.  It adds a few convenience features:
  93 #   - Adds file-level dependencies between custom targets added with this
  94 #     command such that if there is a target-level dependency, it also implies
  95 #     that the custom command should always be run if the output file of the
  96 #     dependency has been updated.
  97 #   - Support for creating custom targets that produce stamp files whenever
  98 #     they run successfully, so that other targets can depend on those stamp
  99 #     files.
 100 #
 101 # Usage:
 102 #   gmx_add_custom_output_target(<target> [RUN_ALWAYS] [ADD_FAST_TARGET]
 103 #                                OUTPUT <STAMP | <output> >
 104 #                                [COMMAND <command1> [<args1...>]]
 105 #                                [COMMAND <command2> [<args2...>]]
 106 #                                [WORKING_DIRECTORY <dir>]
 107 #                                [DEPENDS <deps...>]
 108 #                                [DEPENDS_FILE_LIST <list>]
 109 #                                [COMMENT <comment>] [USES_TERMINAL])
 110 #
 111 #   <target>
 112 #     - Name of the custom target to create.
 113 #   RUN_ALWAYS
 114 #     - Create the command such that it always runs, and may update the output
 115 #       file in the process.
 116 #       The dependencies listed with DEPENDS are ignored in this case.
 117 #   ADD_FAST_TARGET
 118 #     - In addition to creating <target>, create a secondary target
 119 #       <target>-fast that always runs the same commands, but does not have
 120 #       any dependencies.  Desired dependencies can be added separately using
 121 #       add_dependencies().  This supports cases where some of the dependencies
 122 #       are time-consuming to build, and it is possible to build the target
 123 #       even without up-to-date dependencies for testing only that part of the
 124 #       build.
 125 #   OUTPUT
 126 #     - Sets the name of the output file from this custom target.
 127 #       Can be set to STAMP, in which case a stamp file name is automatically
 128 #       generated and commands to touch that stamp whenever the target is made
 129 #       are added.
 130 #   COMMAND
 131 #     - Passed to add_custom_command()/add_custom_target().
 132 #       If OUTPUT STAMP is used, then a command to touch the stamp is
 133 #       automatically added.  In this case, it is allowed to not specify any
 134 #       commands explicitly.
 135 #   WORKING_DIRECTORY
 136 #     - Passed to add_custom_command()/add_custom_target()
 137 #   COMMENT
 138 #     - Passed to add_custom_command()/add_custom_target()
 139 #   USES_TERMINAL
 140 #     - Passed to add_custom_command()/add_custom_target()
 141 #   DEPENDS
 142 #     - Dependencies passed to add_custom_command().  Any targets in this list
 143 #       that have been created with gmx_add_custom_output_target() are
 144 #       automatically expanded such that the custom command always runs if the
 145 #       output of the dependent target changes.  It is not necessary to list
 146 #       those output files here explicitly.
 147 #   DEPENDS_FILE_LIST
 148 #     - Names of variables from which dependencies are added verbatim.
 149 #       The target expansion described above is not performed for these
 150 #       dependencies, and the value passed to the function is the name of a
 151 #       list variable, not the list itself.  This provides much better
 152 #       performance if the dependency list is a long list of source files.
 153 #
 154 # This function does not need a VERBATIM argument; that is always used when
 155 # creating the underlying custom commands/targets.
 156 function (gmx_add_custom_output_target targetname)
 157     # Parse the arguments
 158     # CMakeParseArguments is not suitable, since it does not support the use of
 159     # multiple COMMAND parameters that add_custom_target/command() supports.
 160     set(_option "")
 161     set(_command_args "")
 162     set(_deps "")
 163     set(_output "")
 164     set(_stamp OFF)
 165     set(_always OFF)
 166     set(_add_fast OFF)
 167     foreach (_arg ${ARGN})
 168         if ("x${_arg}" STREQUAL "xRUN_ALWAYS")
 169             set(_always ON)
 170         elseif ("x${_arg}" STREQUAL "xADD_FAST_TARGET")
 171             set(_add_fast ON)
 172         elseif ("x${_arg}" MATCHES "^x(OUTPUT|DEPENDS|DEPENDS_FILE_LIST)$")
 173             set(_option ${_arg})
 174         elseif ("x${_arg}" MATCHES "^x(COMMAND|COMMENT|WORKING_DIRECTORY|USES_TERMINAL)$")
 175             set(_option "PASS")
 176             list(APPEND _command_args "${_arg}")
 177         elseif ("x${_option}" STREQUAL "xDEPENDS")
 178             list(APPEND _deps "${_arg}")
 179             # If the dependency is a target created with this command, also add
 180             # the output file as a dependency.
 181             if (TARGET "${_arg}")
 182                 get_property(_target_output
 183                     TARGET "${_arg}" PROPERTY GMX_CUSTOM_TARGET_OUTPUT_FILE)
 184                 if (_target_output)
 185                     list(APPEND _deps ${_target_output})
 186                 endif()
 187             endif()
 188         elseif ("x${_option}" STREQUAL "xPASS")
 189             list(APPEND _command_args "${_arg}")
 190         elseif ("x${_option}" STREQUAL "xDEPENDS_FILE_LIST")
 191             list(APPEND _deps ${${_arg}})
 192         elseif ("x${_option}" STREQUAL "xOUTPUT")
 193             if (_output)
 194                 message(FATAL_ERROR "Multiple OUTPUTs not supported")
 195             endif()
 196             if ("x${_arg}" STREQUAL "xSTAMP")
 197                 gmx_get_stamp_filename(_output ${targetname})
 198                 set(_stamp ON)
 199             else()
 200                 set(_output ${_arg})
 201             endif()
 202         else()
 203             message(FATAL_ERROR "Unknown option ${_arg}")
 204         endif()
 205     endforeach()
 206     # Add automatically a command to update the stamp if requested
 207     if (_stamp)
 208         list(APPEND _command_args COMMAND ${CMAKE_COMMAND} -E touch ${_output})
 209     endif()
 210     # Create the actual command as requested.
 211     if (NOT _always)
 212         add_custom_command(OUTPUT ${_output}
 213             ${_command_args} DEPENDS ${_deps} VERBATIM)
 214         add_custom_target(${targetname} DEPENDS ${_output})
 215     else()
 216         add_custom_target(${targetname} BYPRODUCTS ${_output}
 217             ${_command_args} VERBATIM)
 218     endif()
 219     # Store the output file name in a custom property to be used in dependency
 220     # resolution later.
 221     gmx_set_custom_target_output(${targetname} ${_output})
 222     # Create the fast target if requested.
 223     if (_add_fast)
 224         add_custom_target(${targetname}-fast ${_command_args} VERBATIM)
 225     endif()
 226 endfunction()
 227
 228 # Gets list of files in the source tree with the given git attribute set
 229 #
 230 # Usage:
 231 #   gmx_get_files_with_gitattribute(<variable> <attribute>)
 232 #
 233 #   <variable>  - name of variable to receive the file list
 234 #   <attribute> - name of git attribute to use
 235 #
 236 # This is useful to generate a list of dependencies for custom commands when
 237 # there is a long list of files that cannot be easily just globbed.
 238 # Using git attributes allows keeping complicated logic out of the build
 239 # system, as expressing such logic in a CMake script that would be reasonably
 240 # fast to evaluate for a long file list is convenient or easy.
 241 function (gmx_get_files_with_gitattribute variable attribute)
 242     execute_process(
 243         COMMAND ${GIT_EXECUTABLE} ls-files
 244         COMMAND ${GIT_EXECUTABLE} check-attr ${attribute} --stdin
 245         WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
 246         OUTPUT_VARIABLE _files)
 247     string(REGEX MATCHALL "[^\n]*: ${attribute}: set\n"
 248            _files_with_attr "${_files}")
 249     string(REGEX REPLACE "([^;]*): ${attribute}: set\n" "${PROJECT_SOURCE_DIR}/\\1"
 250            _files "${_files_with_attr}")
 251     set(${variable} ${_files} PARENT_SCOPE)
 252 endfunction()