modules/fs: Replace configure_file(copy:) with fs.copyfile

`configure_file` is both an extremely complicated implementation, and
a strange place for copying. It's a bit of a historical artifact, since
the fs module didn't yet exist. It makes more sense to move this to the
fs module and deprecate this `configure_file` version.

This new version works at build time rather than configure time, which
has the disadvantage it can't be passed to `run_command`, but with the
advantage that changes to the input don't require a full reconfigure.

2 files changed, 44 insertions, 0 deletions

diff --git a/docs/markdown/Fs-module.md b/docs/markdown/Fs-module.md
index 663aba41b..139355192 100644
--- a/docs/markdown/Fs-module.md
+++ b/docs/markdown/Fs-module.md
@@ -215,3 +215,30 @@ fs.stem('foo/bar/baz.dll.a')  # baz.dll
    specified by `path` changes, this will trigger Meson to reconfigure the
    project. If the file specified by `path` is a `files()` object it
    cannot refer to a built file.
+
+
+### copyfile
+
+*Since 0.64.0*
+
+Copy a file from the source directory to the build directory at build time
+
+Has the following positional arguments:
+   - src `File | str`: the file to copy
+
+Has the following optional arguments:
+   - dest `str`: the name of the output file. If unset will be the basename of
+     the src argument
+
+Has the following keyword arguments:
+   - install `bool`: Whether to install the copied file, defaults to false
+   - install_dir `str`: Where to install the file to
+   - install_tag: `str`: the install tag to assign to this target
+   - install_mode `array[str | int]`: the mode to install the file with
+
+returns:
+   - a [[custom_target]] object
+
+```meson
+copy = fs.copyfile('input-file', 'output-file')
+```
diff --git a/docs/markdown/snippets/fs_copyfile.md b/docs/markdown/snippets/fs_copyfile.md
new file mode 100644
index 000000000..dfb5d8985
--- /dev/null
+++ b/docs/markdown/snippets/fs_copyfile.md
@@ -0,0 +1,17 @@
+## `fs.copyfile` to replace `configure_file(copy : true)`
+
+A new method has been added to the `fs` module, `copyfile`. This method replaces
+`configure_file(copy : true)`, but only copies files. Unlike `configure_file()`
+it runs at build time, and the output name is optional defaulting to the
+filename without paths of the input if unset:
+
+```meson
+fs.copyfile('src/file.txt')
+```
+Will create a file in the current build directory called `file.txt`
+
+
+```meson
+fs.copyfile('file.txt', 'outfile.txt')
+```
+Will create a copy renamed to `outfile.txt`