Merge pull request #2764 from mesonbuild/generatorpath

Generator outputs can have path segments

2 files changed, 31 insertions, 3 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index a231ed4..a3e1ef0 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1705,11 +1705,18 @@ This object is returned by [`generator()`](#generator) and contains a
 generator that is used to transform files from one type to another by
 an executable (e.g. `idl` files into source code and headers).
 
-* `process(list_of_files)` takes a list of files, causes them to be
-  processed and returns an object containing the result which can
+* `process(list_of_files, ...)` takes a list of files, causes them to
+  be processed and returns an object containing the result which can
   then, for example, be passed into a build target definition. The
   keyword argument `extra_args`, if specified, will be used to replace
-  an entry `@EXTRA_ARGS@` in the argument list.
+  an entry `@EXTRA_ARGS@` in the argument list. The keyword argument
+  `preserve_path_from`, if given, specifies that the output files need
+  to maintain their directory structure inside the target temporary
+  directory. The most common value for this is
+  `meson.current_source_dir()`. With this value when a file called
+  `subdir/one.input` is processed it generates a file `<target private
+  directory>/subdir/one.out` as opposed to `<target private
+  directory>/one.out`.
 
 ### `subproject` object
 
diff --git a/docs/markdown/snippets/gen-subdirs.md b/docs/markdown/snippets/gen-subdirs.md
new file mode 100644
index 0000000..fdb5945
--- /dev/null
+++ b/docs/markdown/snippets/gen-subdirs.md
@@ -0,0 +1,21 @@
+## Generator outputs can preserve directory structure
+
+Normally when generating files with a generator, Meson flattens the
+input files so they all go in the same directory. Some code
+generators, such as Protocol Buffers, require that the generated files
+have the same directory layout as the input files used to generate
+them. This can now be achieved like this:
+
+```meson
+g = generator(...) # Compiles protobuf sources
+generated = gen.process('com/mesonbuild/one.proto',
+  'com/mesonbuild/two.proto',
+  preserve_path_from : meson.current_source_dir())
+
+This would cause the following files to be generated inside the target
+private directory:
+
+    com/mesonbuild/one.pb.h
+    com/mesonbuild/one.pb.cc
+    com/mesonbuild/two.pb.h
+    com/mesonbuild/two.pb.cc