rewriter: Added docs

docs/markdown/Rewriter.md

@@ -0,0 +1,183 @@
+---
+short-description: Automatic modification of the build system files
+...
+
+# Meson file rewriter
+
+Since version 0.50.0, meson has the functionality to perform some basic
+modification on the `meson.build` files from the command line. The currently
+supported operations are:
+
+- For build targets:
+  - Add/Remove source files
+  - Add/Remove targets
+  - Modify a select set of kwargs
+  - Print some JSON information
+- For dependencies:
+  - Modify a select set of kwargs
+- For the project function:
+  - Modify a select set of kwargs
+  - Modify the default options list
+
+The rewriter has both, a normal command line interface and a "script mode". The
+normal CLI is mostly designed for everyday use. The "script mode", on the
+other hand, is meant to be used by external programs (IDEs, graphical
+frontends, etc.)
+
+## Using the rewriter
+
+All rewriter functions are accessed via `meson rewrite` (or the rewriter alias
+`meson rw`). The meson rewriter assumes that it is run inside the project root
+directory. If this isn't the case, use `--sourcedir` to specify the actual
+project source directory.
+
+### Adding and removing sources
+
+The most common operations will probably be the adding and removing of source
+files to a build target. This can be easily done with:
+
+```bash
+meson rewrite target <target name/id> {add/rm} [list of sources]
+```
+
+For instance, given the following example
+
+```meson
+src = ['main.cpp', 'fileA.cpp']
+
+exe1 = executable('testExe', src)
+```
+
+the source `fileB.cpp` can be added with:
+
+```bash
+meson rewrite target testExe add fileB.cpp
+```
+
+After executing this command, the new `meson.build` will look like this:
+
+```meson
+src = ['main.cpp', 'fileA.cpp', 'fileB.cpp']
+
+exe1 = executable('testExe', src)
+```
+
+In this case, `exe1` could also have been used for the target name, since the
+rewriter also takes assignments and internal meson IDs into consideration when
+searching for the target in the `meson.build` files.
+
+For more information see the help output of the rewriter target command.
+
+### Setting the project version
+
+It is also possible to set kwargs of specific functions with the rewriter. The
+general command for setting or removing kwargs is:
+
+```bash
+meson rewriter kwargs {set/delete} <function type> <function ID> <key1> <value1> <key2> <value2> ...
+```
+
+For instance, setting the project version can be achieved with this command:
+
+```bash
+meson rewriter kwargs set project '' version 1.0.0
+```
+
+Currently, only the following function types are supported:
+
+- dependency
+- target (any build target, the function ID is the target name/ID)
+- project (the function ID can be anything since project() can only be called once)
+
+For more information see the help output of the rewriter kwargs command.
+
+### Setting the project default options
+
+For setting and deleting default options, use the following command:
+
+```bash
+meson rewrite default-options {set/delete} <opt1> <value1> <opt2> <value2> ...
+```
+
+## Using the "script mode"
+
+The "script mode" should be the preferred API for party programs, since it
+offers more flexibility and higher API stability. The "scripts" are stored
+in JSON format and executed with `meson rewrite command <JSON file or string>`.
+
+The JSON format is defined as follows:
+
+```json
+[
+  {
+    "type": "function to execute",
+    ...
+  }, {
+    "type": "other function",
+    ...
+  },
+  ...
+]
+```
+
+Each object in the main array must have a `type` entry which specifies which
+function should be executed.
+
+Currently, the following functions are supported:
+
+- target
+- kwargs
+- default_options
+
+### Target modification format
+
+The format for the type `target` is defined as follows:
+
+```json
+{
+  "type": "target",
+  "target": "target ID/name/assignment variable",
+  "operation": "one of ['src_add', 'src_rm', 'tgt_rm', 'tgt_add', 'info']",
+  "sources": ["list", "of", "source", "files", "to", "add, remove"],
+  "subdir": "subdir where the new target should be added (only has an effect for operation 'tgt_add')",
+  "target_type": "function name of the new target -- same as in the CLI (only has an effect for operation 'tgt_add')"
+}
+```
+
+The keys `sources`, `subdir` and `target_type` are optional.
+
+### kwargs modification format
+
+The format for the type `target` is defined as follows:
+
+```json
+{
+  "type": "kwargs",
+  "function": "one of ['dependency', 'target', 'project']",
+  "id": "function ID",
+  "operation": "one of ['set', 'delete', 'add', 'remove', 'remove_regex', 'info']",
+  "kwargs": {
+    "key1": "value1",
+    "key2": "value2",
+    ...
+  }
+}
+```
+
+### Default options modification format
+
+The format for the type `default_options` is defined as follows:
+
+```json
+{
+  "type": "default_options",
+  "operation": "one of ['set', 'delete']",
+  "options": {
+    "opt1": "value1",
+    "opt2": "value2",
+    ...
+  }
+}
+```
+
+For operation `delete`, the values of the `options` can be anything (including `null`)

docs/markdown/snippets/rewriter.md

@@ -0,0 +1,18 @@
+## Meson file rewriter
+
+This release adds the functionality to perform some basic modification
+on the `meson.build` files from the command line. The currently
+supported operations are:
+
+- For build targets:
+  - Add/Remove source files
+  - Add/Remove targets
+  - Modify a select set of kwargs
+  - Print some JSON information
+- For dependencies:
+  - Modify a select set of kwargs
+- For the project function:
+  - Modify a select set of kwargs
+  - Modify the default options list
+
+For more information see the rewriter documentation.

docs/sitemap.txt

@@ -60,6 +60,7 @@ index.md
 	Reference-manual.md
 	Reference-tables.md
 	Style-guide.md
+	Rewriter.md
 	FAQ.md
 	Reproducible-builds.md
 	howtox.md