How can I add a step to the build phase in cmake?

I am trying to convert our installation process to use cmake instead of our old custom build that we have today. In the project we do have a few perl files that sometimes change that we want to include in the built product. In these perl files we want to set the shebang (#!/path/to/perl) during installation, so it can run on the system where cmake is run.

Usually I would use configure_file(), but due to the nature of configure_file() any @Unidentified-sequence@ will default to an empty string, when using configure_file() with any other option than COPYONLY (https://gitlab.kitware.com/cmake/cmake/-/issues/22740). This becomes inconvenient for perl scripts, as @ is used to define an array.

The workaround I have today is to read the file into cmake and use string replace,

file(READ "${srcDir}/${file}"  FILE_CONTENTS)
#I have full control over the files. Thus adding a custom variable, such as @PERLPATH@, instead of a REGEX, is possible
string(REGEX REPLACE "#!/[/A-Za-z_0-9.-]+/perl" "#!${PERL_PATH}" FILE_CONTENTS "${FILE_CONTENTS}")
file(GENERATE OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/${destDir}/${file}" CONTENT "${FILE_CONTENTS}")

This works, but any changes to the perl files requires cmake -B /path/to/build -S /path/to/source to be rerun. Also, it will rerun this for any file and not only the changed files.

I would like it to automatically update the files when doing cmake --build. Further, I would also prefer to have a check whether the files are changed or not and only update them then (which requires old change data to be saved and thus cannot be done during configure, cmake -B /path/to/build -S /path/to/source).

I would appreciate if someone had a standardized solution to this, but as I understand it, this use case is not exactly supported in CMake. Thus I would consider it good enough with a workaround. Getting the change date is easy enough with stat -c %y.

Is there any way to force cmake to run some particular cmake code snippet during cmake --build, lets say the above example?

1. use find_program() to find perl and define e.g., PERL_EXECUTABLE
2. if perl is not found (dunno how critical it's for you) set PERL_EXECUTABLE to a default value, e.g., /usr/bin/perl, so configure_file() will always substitute #!@PERL_EXECUTABLE@ in shebang to smth not empty
3. use add_custom_command(<fixed-shebang>.perl...) to run cmake -P <your-script-with-configure_file>.cmake [<input-files>] to produce the perl file(s) to install from their "templates"
4. use install(<FILES|PROGRAMS> ${CMAKE_BINARY_DIR}/<fixed-shebang>.perl) command to install 'em to a desired location

This way edit files will "rebuild" 'em on cmake --build … and install fixed shebang versions on cmake --install.

Update:

According to the substitution problem, I can't reproduce:

1. I pick a random Perl module from my system (e.g., Storable.pm where @ symbols exist) and copy it to a test directory as Storable.pm.in
2. add #!@PERL_EXECUTABLE@ as the very first line in it
3. added a subst.cmake to the test directory with the following content:

message(STATUS "PERL_EXECUTABLE=${PERL_EXECUTABLE}")
configure_file(Storable.pm.in Storable.pm @ONLY)

3. run cmake -DPERL_EXECUTABLE=/usr/bin/perl -P subst.cmake
4. and then diff Storable.pm.in Storable.pm:

--- Storable.pm.in      2023-02-24 15:10:18.630116604 +0400
+++ Storable.pm 2023-02-24 15:12:00.587358711 +0400
@@ -1,4 +1,4 @@
-#!@PERL_EXECUTABLE@
+#!/usr/bin/perl
 #
 #  Copyright (c) 1995-2001, Raphael Manfredi
 #  Copyright (c) 2002-2014 by the Perl 5 Porters

If the output file of this procedure is needed as a source file for any targets, use add_custom_command. Otherwise, use add_custom_target.

Since you've already written some CMake to perform the task, just put that CMake in its own .cmake file and run it in the custom command/target using "${CMAKE_COMMAND}" -P <path to that script file>. (see docs on -P here).

In the DEPENDS field, specify the path to the CMake script and the path to any input files that are required by the CMake script. You will need to pass the value of CMAKE_CURRENT_BINARY_DIR to the CMake script in the command field with "-DCMAKE_CURRENT_BINARY_DIR=${CMAKE_CURRENT_BINARY_DIR}", since the script will not automatically have the same variables as the project that calls it (see docs on script-mode's -D flag here).

If the output file is needed as a source file for any targets (the add_custom_command route), then specify its path in the OUTPUT field, and then the custom command will be run as needed any time a target that needs that output file gets built. In the add_custom_target route, custom targets are always run, so if you want to have fancy logic that skips running if the input files haven't changed, I think you'll need to implement that in the script file itself, which you can do by using the if(file1 IS_NEWER_THAN file2) command, and file(TOUCH) to create a file with the timestamp of when the custom target body was last run (so if the touch file is newer than all the input files, just return).