From c785b540d3a0b94badfaf0a1a99f08b3d31d735e Mon Sep 17 00:00:00 2001
From: Duncan Ogilvie <mr.exodia.tpodt@gmail.com>
Date: Wed, 8 Mar 2023 09:01:39 +0100
Subject: [PATCH] Document target templates

---
 docs/cmake-toml.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/cmake-toml.md b/docs/cmake-toml.md
index 47e5c6f..593f1ed 100644
--- a/docs/cmake-toml.md
+++ b/docs/cmake-toml.md
@@ -212,6 +212,29 @@ CXX_STANDARD_REQUIRED = true
 FOLDER = "MyFolder"
 ```
 
+## Templates
+
+To avoid repeating yourself you can create your own target type and use it in your targets:
+
+```toml
+[template.example]
+condition = "MYPROJECT_BUILD_EXAMPLES"
+type = "executable"
+link-libraries = ["myproject::mylib"]
+add-function = ""
+pass-sources = false
+
+# Properties from the template are merged with the ones here
+[target.myexample]
+type = "example"
+sources = ["src/myexample.cpp"]
+```
+
+The properties declared on a `template` are the same as the ones you use for targets. The only exceptions are:
+
+- `add-function`: Specifies a custom add function. Projects like [pybind11](https://pybind11.readthedocs.io/en/stable/cmake/index.html#new-findpython-mode) have their own `add_xxx` function, which you can specify here.
+- `pass-sources`: Pass sources directly to the add function instead of using `target_sources`.
+
 ## Tests and installation (unfinished)
 
 **Note**: The `[[test]]` and `[[install]]` are unfinished features and will likely change in a future release.