{"id":13645776,"url":"https://github.com/GrammaTech/clang-mutate","last_synced_at":"2025-04-21T17:31:23.580Z","repository":{"id":104961643,"uuid":"112793214","full_name":"GrammaTech/clang-mutate","owner":"GrammaTech","description":"Manipulate C-family ASTs with Clang","archived":false,"fork":false,"pushed_at":"2018-10-22T23:47:00.000Z","size":2278,"stargazers_count":64,"open_issues_count":1,"forks_count":6,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-11-09T19:39:30.392Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GrammaTech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-12-01T22:31:41.000Z","updated_at":"2024-08-13T22:48:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"73c86d84-cb40-4750-9e3d-f5a871471189","html_url":"https://github.com/GrammaTech/clang-mutate","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrammaTech%2Fclang-mutate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrammaTech%2Fclang-mutate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrammaTech%2Fclang-mutate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrammaTech%2Fclang-mutate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GrammaTech","download_url":"https://codeload.github.com/GrammaTech/clang-mutate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250100391,"owners_count":21374932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T01:02:41.531Z","updated_at":"2025-04-21T17:31:23.034Z","avatar_url":"https://github.com/GrammaTech.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# clang-mutate: Manipulate C-family ASTs with Clang\n\nThis tool provides an interface for performing operations on C and C++\nsource files.  Using the\n[clang LibTooling interface](http://clang.llvm.org/docs/LibTooling.html),\nit obtains an abstract syntax tree (AST) representation of the source\nand provides enables the inspection or alteration the source ASTs.\n\n## Installation\n\n`clang-mutate` is dependent on\n[clang/llvm version 6.0.X](http://releases.llvm.org/download.html).\nPrecompiled binaries may be downloaded for the platform of your choice;\nonce downloaded, ensure `clang` is on your $PATH.\n\nBeyond clang, we use `zlib` and `tinfo`.  Additionally, we use\n`pandoc` to generate documentation.  These\ntools may be installed via the package manager of your choice.\nOn Debian systems, `sudo apt-get install libtinfo-dev zlib1g-dev pandoc`\nwill install these dependencies.\n\n## Inspection operations\n\n`clang-mutate` can output the ASTs for input source file(s) formatted\neither as JSON or S-expressions.  Output ASTs provide source\ninformation to enable subsequent source rewriting by external tools.\nAlternatively, it can be launched in interactive mode, and ASTs can be\nexplored in a plain text format more similar to source code.\n\nSome of the inspection operations are:\n\n`-annotate`\n:   Display the source, annotating statements with their IDs\n    and AST classes\n\n`-ids`\n:   Display the number of statements in the source\n\n`-list`\n:   List every statement's ID, AST class, and range\n\n`-number`\n:   Display the source, annotating statements with their IDs\n\n`-number-full`\n:   Display the source, annotating full statements with their IDs\n\n`-cfg`\n:   Include control-flow information in ASTs\n\nRefer to the [manual](man/clang-mutate.template.md) for complete\ndocumentation of available commands.\n\n\n## Mutation operands\n\nIn `clang-mutate`, the mutation operands and operators are specified\nas separate flags.  The `stmt1` and `stmt2` operands are used to\nspecify a numeric AST ID to which an operator will be applied. The\n`value1` and `value2` operands are strings, and the `file1` and\n`file2` operands may be used to specify a file whose contents will be\nused as the strings for `value1` and `value2`, repectively.\n\n\n## Mutation operations\n\nSome of the mutation operations that are available include:\n\n`-cut`\n:   Cut `stmt1` from the source\n\n`-insert`\n:   Insert `value1` before `stmt1`\n\n`-set`\n:   Set the text of `stmt1` to `value1`\n\n`-swap`\n:   Swap `stmt1` and `stmt2` in the source\n\nRefer to the [manual](man/clang-mutate.template.md) for complete\ndocumentation of available mutation commands.\n\n\n## Installation\n\nAs mentioned above, `clang-mutate` uses the clang LibTooling\ninterface, which means that the `clang-mutate` executable works best\nwhen run from the same directory as clang. Run \"make install\" to build\nand install.\n\nA PKGBUILD file is provided for installation on Arch Linux systems.\n\n`clang-mutate` has only been tested on Linux, although we don't know\nof any reason it should not work in other OSes.  If you encounter\nissues running in a different OS, please let us know by filing an\nissue report or a merge request.  We're happy to incorporate changes\nthat will enable more general execution.\n\n\n## Examples\n\nA running example using the file `etc/hello.c`. Here is the source:\n\n    $ cat etc/hello.c\n    #include \u003cstdio.h\u003e\n    int main(int argc, char *argv[])\n    {\n      puts(\"hello\");\n      return 0;\n    }\n\nCount the number of statements:\n\n    $ clang-mutate -ids etc/hello.c --\n    12\n\nPrint the source, annotated with statement IDs:\n\n    $ clang-mutate -number etc/hello.c --\n    #include \u003cstdio.h\u003e\n    /* 0.1[ */int main(/* 0.2[ */int argc,/* ]0.2 */ /* 0.3[ */char *argv[]/* ]0.3 */)\n    /* 0.4[ */{\n      /* 0.5[ *//* 0.6[ *//* 0.7[ */puts/* ]0.7 *//* ]0.6 */(/* 0.8[ *//* 0.9[ *//* 0.10[ */\"hello\"/* ]0.10 *//* ]0.9 *//* ]0.8 */);/* ]0.5 */\n      /* 0.11[ */return /* 0.12[ */0/* ]0.12 */;/* ]0.11 */\n    }/* ]0.4 */\n    /* ]0.1 */\n\nCut the return statement:\n\n    $ clang-mutate -cut -stmt1=11 etc/hello.c --\n    #include \u003cstdio.h\u003e\n    int main(int argc, char *argv[])\n    {\n      puts(\"hello\");\n\n    }\n\nReplace the string \"hello\" with the string \"good bye\":\n\n    $ clang-mutate -set -stmt1=9 -value1='\"good bye\"' etc/hello.c --\n    #include \u003cstdio.h\u003e\n    int main(int argc, char *argv[])\n    {\n      puts(\"good bye\");\n      return 0;\n    }\n\nUse the `tools/perforate-loops` script to halve the number of loop iterations by\nreplacing `++` or `--` with `+=2` or `-=2`, respectively:\n\n    $ make etc/loop\n    cc     etc/loop.c   -o etc/loop\n    $ ./etc/loop\n    hello 0 10\n    hello 1 9\n    hello 2 8\n    hello 3 7\n    hello 4 6\n    hello 5 5\n    hello 6 4\n    hello 7 3\n    hello 8 2\n    hello 9 1\n\n    $ ./tools/perforate-loops etc/loop.c \u003e /tmp/faster.c\n    $ make /tmp/faster\n    cc     /tmp/faster.c   -o /tmp/faster\n    $ /tmp/faster\n    hello 0 10\n    hello 2 8\n    hello 4 6\n    hello 6 4\n    hello 8 2\n\nUse the `tools/strings-to` script to replace string literals:\n\n    $ ./tools/strings-to etc/hello.c foo\n    #include \u003cstdio.h\u003e\n    int main(int argc, char *argv[])\n    {\n      puts(\"foo\");\n      return 0;\n    }\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGrammaTech%2Fclang-mutate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGrammaTech%2Fclang-mutate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGrammaTech%2Fclang-mutate/lists"}