From 34c03719a304bbbf684ad99110f49c18c99d9542 Mon Sep 17 00:00:00 2001 From: Jussi Pakkanen Date: Mon, 18 Dec 2017 21:10:14 +0200 Subject: [PATCH] Added documentation. --- docs/markdown/Reference-manual.md | 13 ++++++++++--- docs/markdown/snippets/gen-subdirs.md | 21 +++++++++++++++++++++ 2 files changed, 31 insertions(+), 3 deletions(-) create mode 100644 docs/markdown/snippets/gen-subdirs.md diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 03660f55a..7e8f7eeeb 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -1688,11 +1688,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 `/subdir/one.out` as opposed to `/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 000000000..fdb59457b --- /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