From c56ffe2b1cc78e9f063f695a18b5533862181eb4 Mon Sep 17 00:00:00 2001 From: bloodstalker Date: Sat, 14 Jan 2017 07:15:20 +0330 Subject: updated for the help section on action files. --- README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 62 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 87e5248..e6d98a6 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,17 @@ Here are some samples from the `mutator-lvl0`, the Misra-C checker Reports:
``` +##mutator + +`mutator` is a C code mutator,Misra-C checker and code transformation tool written using the Clang frontend(LibTooling) as a stand-alone in C++. It consists of three(well so far) executables and a UI written in bash. You can run executables like any other CLI tool or just run them through the UI which again acts like a CLI tool. `mutator` also accepts action files that tell it what to do.
+ +
+**mutator-lvl0** will run the Misra-C checks.
+**mutator** will run the level-1 implementers and mutators.
+**mutator-lvl2** will run the level-2 implementers and mutators.
+Mutation levels have nothing to do with the order of mutants.
+
+ ### Dev Status All the as-of-yet implemented features of the project are very much buildable and usable at all times, even during the dev phase.
* **`mutator-lvl0`** is the executable responsible for the Misra-C rule checks. Currently it can check for 130 out of the 141 Misra-C:2004 rules. For a more accurate list please check out `misrac.ods` under `docs` in project's root.
@@ -100,6 +111,7 @@ To run the executables with the mutator UI, you can use `mutator.sh`. For a list * `-v, --version` prints out the version.
* `-i, --input, -input` lets you choose the input file(or a white-space-separated list of files) that is going to be passed to the mutator executable(s).
* `-o, --output, -output` lets you choose where to put the mutant.
+* `-pp, --print-pretty`, prints the output in a pretty format in a new file. The new file has the same name with a "-pretty" added to the name in the same directory.
* `-t, --test`, runs the tests on the built executables. It should be followed by an executable name and the test to run on it. The accepted options are: tdd,valgrind. For example: `-test mutator-lvl0 valgrind`.
* `-opts --options, pass options to the executable(s). The executables support all the clang options. please enclose all the options in double quatation. This is basically a pass-through option. Everything appearing inside will be passed through to the executable.`
* `-copts --customoptions`, just like `-opts` but passes the custom options defined for each executable. it is pass-through. Example: `-copts "-MainOnly=false -SysHeader"`.
@@ -131,12 +143,56 @@ Do note that if your file has included standard header libraries, you do need to ./mutator.sh -c misrac -i ./test/testFuncs2.c ./test/testFuncs1.c -opts "-Wall -I/lib/gcc/x86_64-redhat-linux/5.3.1/include/" ``` -
-**mutator-lvl0** will run the Misra-C:2004 checks.
-**mutator** will run the level-1 implementers.
-**mutator-lvl2** will run the level-2 implementers.
-The levels have nothing to do with mutation orders.
-
+ +Here's the command I use to run the TDD tests:
+```bash + +/mutator.sh -c misrac -i ./test/testFuncs1.c ./test/testFuncs2.c -pp -opts "-std=c90 -I/lib/gcc/x86_64-redhat-linux/5.3.1/include" -copts "-SysHeader=false -MainOnly=true" 2> /dev/null + +``` + +####The Action File +`mutator` can accept a file which tells it what to do. Currently this feature is only supporte for `mutator-lvl0`. You can find a sample under `./samples` named `action_file.mutator`. + +```bash + +action_name:my_action1 +executable_name:mutator-lvl0 +#these are the options specific to the executable +exec_opts:-SysHeader=false -MainOnly=true +in_files:./test/testFuncs1.c ./test/testFuncs2.c ./test/testFuncs3.c +#clang options +libtooling_options:-std=c90 -I/lib/gcc/x86_64-redhat-linux/5.3.1/include +#the output file +out_files:./test/misra-log +#the log file +log_files: +print_pretty:true +end_action:run + +``` +Here's the explanation for the fields: +* `action_name` lets you specify a name for the action to run. Marks the start of an action.
+* `executable_name` is used for detemining which executable to run.
+* `exec_opts` is the field used for passing the executable-specific options.
+* `in_files` is a list of the input files to pass to the executable.
+* `libtooling_options` is used for passin the clang options.
+* `out_files` is used to pass the result file to mutator. For `mutator-lvl0`, this field detemines the Misra-C check results.
+* `log_files` is used to pass the file to hold the log. Mostly meant to be used with `mutator` and `mutator-lvl2`.
+* `print_pretty` is a boolean switch. Used for running `ReportPrintPretty.sh`.
+* `end_action` is used to tell `mutator.sh` what action to do. Currently the only supported options are "run" and "stop". "run" will run the action and "stop" will not run it.
+* Lines starting with a hash(`#`) are considered comments.
+Field names shall not have preceeding whitespace or tab. The `:` character shall immeidately follow the field name with options appearing after it.
+ +You can run the sample action file with this:
+ +```bash + +./mutator.sh --file samples/action_file.mutator + + +``` + Currently, the mutation-only features(mutation for the sake of mutation, technically implementing Misra-C is also a form of mutation) are turned off in **mutator** and **mutator-lvl2** though some automatic code refactoring features work in both executables. Just run a sample code through **mutator** and then **mutator-lvl2** for a demo.

If your code needs a compilation database for clang to understand it and you don't have one,you can use [Bear](https://github.com/rizsotto/Bear). Please note that bear will capture what the make runs, not what is in the makefile. So run `make clean` before invoking `bear make target`.
-- cgit v1.2.3