This tool provides an interface for performing operations on C and C++ source files. Using the clang LibTooling interface, it obtains an abstract syntax tree (AST) representation of the source and provides enables the inspection or alteration the source ASTs.

clang-mutate can output the ASTs for input source file(s) formatted either as JSON or S-expressions. Output ASTs provide source information to enable subsequent source rewriting by external tools. Alternatively, it can be launched in interactive mode, and ASTs can be explored in a plain text format more similar to source code.

Some of the inspection operations are:

-annotate : Display the source, annotating statements with their IDs and AST classes

-ids : Display the number of statements in the source

-list : List every statement's ID, AST class, and range

-number : Display the source, annotating statements with their IDs

-number-full : Display the source, annotating full statements with their IDs

-cfg : Include control-flow information in ASTs

Refer to the manual for complete documentation of available commands.

In clang-mutate, the mutation operands and operators are specified as separate flags. The stmt1 and stmt2 operands are used to specify a numeric AST ID to which an operator will be applied. The value1 and value2 operands are strings, and the file1 and file2 operands may be used to specify a file whose contents will be used as the strings for value1 and value2, repectively.

Some of the mutation operations that are available include:

-cut : Cut stmt1 from the source

-insert : Insert value1 before stmt1

-set : Set the text of stmt1 to value1

-swap : Swap stmt1 and stmt2 in the source

Refer to the manual for complete documentation of available mutation commands.

As mentioned above, clang-mutate uses the clang LibTooling interface, which means that the clang-mutate executable works best when run from the same directory as clang. Run "make install" to build and install.

A PKGBUILD file is provided for installation on Arch Linux systems.

clang-mutate has only been tested on Linux, although we don't know of any reason it should not work in other OSes. If you encounter issues running in a different OS, please let us know by filing an issue report or a merge request. We're happy to incorporate changes that will enable more general execution.

A running example using the file etc/hello.c. Here is the source:

$ cat etc/hello.c
#include <stdio.h>
int main(int argc, char *argv[])
{
  puts("hello");
  return 0;
}

Count the number of statements:

$ clang-mutate -ids etc/hello.c --
12

Print the source, annotated with statement IDs:

$ clang-mutate -number etc/hello.c --
#include <stdio.h>
/* 0.1[ */int main(/* 0.2[ */int argc,/* ]0.2 */ /* 0.3[ */char *argv[]/* ]0.3 */)
/* 0.4[ */{
  /* 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 */
  /* 0.11[ */return /* 0.12[ */0/* ]0.12 */;/* ]0.11 */
}/* ]0.4 */
/* ]0.1 */

Cut the return statement:

$ clang-mutate -cut -stmt1=11 etc/hello.c --
#include <stdio.h>
int main(int argc, char *argv[])
{
  puts("hello");

}

Replace the string "hello" with the string "good bye":

$ clang-mutate -set -stmt1=9 -value1='"good bye"' etc/hello.c --
#include <stdio.h>
int main(int argc, char *argv[])
{
  puts("good bye");
  return 0;
}

Use the tools/perforate-loops script to halve the number of loop iterations by replacing ++ or -- with +=2 or -=2, respectively:

$ make etc/loop
cc     etc/loop.c   -o etc/loop
$ ./etc/loop
hello 0 10
hello 1 9
hello 2 8
hello 3 7
hello 4 6
hello 5 5
hello 6 4
hello 7 3
hello 8 2
hello 9 1

$ ./tools/perforate-loops etc/loop.c > /tmp/faster.c
$ make /tmp/faster
cc     /tmp/faster.c   -o /tmp/faster
$ /tmp/faster
hello 0 10
hello 2 8
hello 4 6
hello 6 4
hello 8 2

Use the tools/strings-to script to replace string literals:

$ ./tools/strings-to etc/hello.c foo
#include <stdio.h>
int main(int argc, char *argv[])
{
  puts("foo");
  return 0;
}