From d4fe805a51d5a8e9b39c1f4d51b132891c84169b Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Wed, 27 Feb 2019 16:29:31 +0100 Subject: [PATCH] rewriter: Added docs --- docs/markdown/Rewriter.md | 183 +++++++++++++++++++++++++++++ docs/markdown/snippets/rewriter.md | 18 +++ docs/sitemap.txt | 1 + 3 files changed, 202 insertions(+) create mode 100644 docs/markdown/Rewriter.md create mode 100644 docs/markdown/snippets/rewriter.md diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md new file mode 100644 index 000000000..89591fa36 --- /dev/null +++ b/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 {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} ... +``` + +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} ... +``` + +## 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 `. + +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`) diff --git a/docs/markdown/snippets/rewriter.md b/docs/markdown/snippets/rewriter.md new file mode 100644 index 000000000..7a4621deb --- /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. diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 69876416a..bea2a316c 100644 --- a/docs/sitemap.txt +++ b/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