Merge pull request #4992 from mensinda/rwCLI

rewriter: Add a CLI and docs

2 files changed, 254 insertions, 0 deletions

diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md
new file mode 100644
index 0000000..b6301d6
--- /dev/null
+++ b/docs/markdown/Rewriter.md
@@ -0,0 +1,236 @@
+---
+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.)
+
+The rewriter itself is considered stable, however the user interface and the
+"script mode" API might change in the future. These changes may also break
+backwards comaptibility to older releases.
+
+We are also open to suggestions for API improvements.
+
+## Using the rewriter
+
+All rewriter functions are accessed via `meson rewrite`. 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. This is
+possible because the rewriter also searches for assignments and unique meson
+IDs, which can be acquired with introspection. If there are multiple targets
+with the same name, meson will do nothing and print an error message.
+
+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 must be `/` 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> ...
+```
+
+## Limitations
+
+Rewriting a meson file is not guranteed to keep the indentation of the modified
+functions. Additionally, comments inside a modified statement will be removed.
+Furthermore, all source files will be sorted alphabetically.
+
+For instance adding `e.c` to srcs in the following code
+
+```meson
+# Important comment
+
+srcs = [
+'a.c', 'c.c', 'f.c',
+# something important about b
+       'b.c', 'd.c', 'g.c'
+]
+
+# COMMENT
+```
+
+would result in the following code:
+
+```meson
+# Important comment
+
+srcs = [
+  'a.c',
+  'b.c',
+  'c.c',
+  'd.c',
+  'e.c',
+  'f.c',
+  'g.c'
+]
+
+# COMMENT
+```
+
+## Using the "script mode"
+
+The "script mode" should be the preferred API for third 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', 'target_rm', 'target_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`)
+
+## Extracting information
+
+The rewriter also offers operation `info` for the types `target` and `kwargs`.
+When this operation is used, meson will print a JSON dump to stderr, containing
+all available information to the rewriter about the build target / function
+kwargs in question.
+
+The output format is currently experimental and may change in the future.
diff --git a/docs/markdown/snippets/rewriter.md b/docs/markdown/snippets/rewriter.md
new file mode 100644
index 0000000..7a4621d
--- /dev/null
+++ b/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.