From d4fe805a51d5a8e9b39c1f4d51b132891c84169b Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Wed, 27 Feb 2019 16:29:31 +0100 Subject: rewriter: Added docs --- docs/markdown/Rewriter.md | 183 +++++++++++++++++++++++++++++++++++++ docs/markdown/snippets/rewriter.md | 18 ++++ 2 files changed, 201 insertions(+) create mode 100644 docs/markdown/Rewriter.md create mode 100644 docs/markdown/snippets/rewriter.md (limited to 'docs/markdown') diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md new file mode 100644 index 0000000..89591fa --- /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 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. -- cgit v1.1 From eabc35340dc0fd63d70058f93c94674bc7782c19 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sat, 2 Mar 2019 11:18:13 +0100 Subject: rewriter: Enforce an empty project ID string --- docs/markdown/Rewriter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index 89591fa..4550170 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -87,7 +87,7 @@ 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) +- project (the function ID must be an empty string since project() can only be called once) For more information see the help output of the rewriter kwargs command. -- cgit v1.1 From c98987c19efabac06296c0e65692b7822db95a72 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sat, 2 Mar 2019 11:45:26 +0100 Subject: rewriter: Fixed docs. --- docs/markdown/Rewriter.md | 42 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index 4550170..46b117e 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -99,10 +99,48 @@ For setting and deleting default options, use the following command: meson rewrite default-options {set/delete} ... ``` +## 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 party programs, since it -offers more flexibility and higher API stability. The "scripts" are stored +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 `. The JSON format is defined as follows: -- cgit v1.1 From 1290330894f5c2ad77684b1b3985a7ba17114ccb Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sat, 2 Mar 2019 12:29:54 +0100 Subject: rewriter: Renamed tgt_{add,rm} --> target_{add,rm} --- docs/markdown/Rewriter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index 46b117e..332c9f7 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -175,7 +175,7 @@ The format for the type `target` is defined as follows: { "type": "target", "target": "target ID/name/assignment variable", - "operation": "one of ['src_add', 'src_rm', 'tgt_rm', 'tgt_add', 'info']", + "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')" -- cgit v1.1 From 90b557e38af2df9e68f72c96d0f22f0e7bc37e91 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sat, 2 Mar 2019 12:40:31 +0100 Subject: rewriter: Remove command alias --- docs/markdown/Rewriter.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index 332c9f7..ce769d4 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -26,10 +26,9 @@ 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. +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 -- cgit v1.1 From ff5e7eb104d015c462fdae2de76c967bf00c27ad Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sat, 2 Mar 2019 17:03:51 +0100 Subject: rewriter: Updated docs --- docs/markdown/Rewriter.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index ce769d4..b88b4a8 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -61,9 +61,9 @@ 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. +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. For more information see the help output of the rewriter target command. -- cgit v1.1 From e724fd5438a20836be1b270c1f851502ac97fdd4 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sat, 2 Mar 2019 17:41:25 +0100 Subject: rewriter: Handle duplicate target --- docs/markdown/Rewriter.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index b88b4a8..8d46597 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -63,7 +63,8 @@ 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. +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. -- cgit v1.1 From dd5791309e7dcd0a156063784a60245d8088da14 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 3 Mar 2019 09:18:48 +0100 Subject: rewriter: Document info operation --- docs/markdown/Rewriter.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/markdown') diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index 8d46597..30e0bc1 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -219,3 +219,13 @@ The format for the type `default_options` is defined as follows: ``` 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 guaranteed to be backwards compatible, but new keys may be +added in the future. -- cgit v1.1 From 0a3b91c1c9f8ae6d8db6a20e25c862766ea09f2c Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 3 Mar 2019 10:53:36 +0100 Subject: rewriter: Mark the info output as experimental --- docs/markdown/Rewriter.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index 30e0bc1..f143ac0 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -227,5 +227,4 @@ 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 guaranteed to be backwards compatible, but new keys may be -added in the future. +The output format is currently experimental and may change in the future. -- cgit v1.1 From 976c136ab6897809ba94bd1ada1a8cd831236cfa Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 3 Mar 2019 11:13:11 +0100 Subject: rewriter: Mark the CLI as experimental --- docs/markdown/Rewriter.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/markdown') diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index f143ac0..73611e9 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -24,6 +24,12 @@ 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 -- cgit v1.1 From 594bf678c7aaf676ce02d7d8a7d33e04c42c6b39 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 3 Mar 2019 14:58:36 +0100 Subject: rewriter: Require '/' for the project ID --- docs/markdown/Rewriter.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index 73611e9..b6301d6 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -86,14 +86,14 @@ 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 +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 an empty string since project() can only be called once) +- 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. -- cgit v1.1