From 7458e762a3cb44e3cae6f96e2ee811535c576fef Mon Sep 17 00:00:00 2001
From: Dylan Baker <dylan@pnwbakers.com>
Date: Fri, 26 Oct 2018 09:24:51 -0700
Subject: [PATCH] docs: Add documentation to custom_targets for codegen [skip
 ci]

Including the following that has come up several times recent:
 - How to use codegen for headers (that each target that uses the header
   needs the object in it's sources)
 - Using custom_targets with multiple outputs
---
 docs/markdown/Custom-build-targets.md |  2 +
 docs/markdown/Generating-sources.md   | 71 ++++++++++++++++++++++++++-
 2 files changed, 72 insertions(+), 1 deletion(-)

diff --git a/docs/markdown/Custom-build-targets.md b/docs/markdown/Custom-build-targets.md
index 30a16e344..9a0f2a15b 100644
--- a/docs/markdown/Custom-build-targets.md
+++ b/docs/markdown/Custom-build-targets.md
@@ -27,6 +27,8 @@ This would generate the binary `output.bin` and install it to
 `${prefix}/subdir/output.bin`. Variable substitution works just like
 it does for source generation.
 
+See [Generating Sources](Generating-sources.md) for more information on this topic.
+
 ## Details on compiler invocations
 
 Meson only permits you to specify one command to run. This is by
diff --git a/docs/markdown/Generating-sources.md b/docs/markdown/Generating-sources.md
index cbe6c0d1f..4d474619b 100644
--- a/docs/markdown/Generating-sources.md
+++ b/docs/markdown/Generating-sources.md
@@ -46,10 +46,79 @@ file individually by index.
 
 Then you just put that in your program and you're done.
 
+### Generating headers
+
+Adding a generated header to a source list will ensure that the header is
+generated and that the proper include paths are created for the target:
+
 ```meson
-executable('program', 'main.c', gen_src)
+prog_python = import('python').find_installation('python3')
+
+foo_c = custom_target(
+	'foo.c',
+	output : 'foo.c',
+	input : 'my_gen.py',
+	command : [prog_python, '@INPUT@', '--code', '@OUTPUT@'],
+]
+
+foo_h = custom_target(
+	'foo.h',
+	output : 'foo.h',
+	input : 'my_gen.py',
+	command : [prog_python, '@INPUT@', '--header', '@OUTPUT@'],
+]
+
+libfoo = static_library('foo', [foo_c, foo_h])
+
+executable('myexe', ['main.c', foo_h], link_with : libfoo)
 ```
 
+Each target that depends on a generated header should add that header to it's sources,
+as seen above with `libfoo` and `myexe`. This is because there is no way for
+meson or the backend to know that `myexe` depends on `foo.h` just because
+`libfoo` does, it could be a private header.
+
+### Generating multiple files at a time
+
+Sometimes it makes sense for a single generator to create two or more files at
+a time, (perhaps a header and source file), meson has this case covered as
+well. `custom_target`s can be indexed like a list to get each output file
+separately. The order is the same as the order of the output argument to
+`custom_target`
+
+```meson
+prog_python = import('python').find_installation('python3')
+
+foo_ch = custom_target(
+	'foo.[ch]',
+	output : ['foo.c', 'foo.h'],
+	input : 'my_gen.py',
+	command : [prog_python, '@INPUT@', '@OUTPUT@'],
+]
+
+libfoo = static_library('foo', [foo_ch])
+
+executable('myexe', ['main.c', foo_ch[1]], link_with : libfoo)
+```
+
+In this case `libfoo` depends on both `foo.c` and `foo.h` but `myexe` only
+depends on `foo.h`, the second output.
+
+### Using dependencies to manage generated resources
+
+In some cases it might be easier to use `declare_dependency` to "bundle" the header
+and library dependency, especially if there are many generated headers:
+
+```meson
+idep_foo = declare_dependency(
+	sources : [foo_h, bar_h],
+	link_with : [libfoo],
+)
+```
+
+See [dependencies](Dependencies.md#declaring-your-own), and
+[reference](Reference-manual.md#decalre_dependency) for more information.
+
 ## Using generator()
 
 Generators are similar to custom targets, except that we define a