Signed-off-by: Steve Beattie <[email protected]> --- parser/README.devel | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+)
Index: b/parser/README.devel =================================================================== --- /dev/null +++ b/parser/README.devel @@ -0,0 +1,94 @@ +AppArmor parser development notes and tips +========================================== + +Debugging the build +------------------- +Adding V=1 as argument to make should result in build commands that are +normally quieter generating more verbose output. This can help diagnose +when something is going wrong at build time. + +Distribution vendors may wish to enable this option all the time to +assist debugging build failures in remote build environments. + +Building the parser with debugging information +---------------------------------------------- +Setting DEBUG=1 with make will enable debugging output in the parser +(i.e. PDEBUG statements will be emitted instead of dropped). Usually, +partial compilation between debug and non-debug will cause compilation +problems, so it's usually best to do something like + + make clean all DEBUG=1 + +Test Coverage +------------- +The parser can be built to generate test coverage information, by +setting the COVERAGE variable for make. As with debugging, partial +compilation is usually problematic, so it's recommended to do: + + make clean all COVERAGE=1 + +and then run whatever tests. Because the unit tests are built with the +make check target, in order to see what coverage they provide, they will +also need to be built with the COVERAGE flag set: + + make tests COVERAGE=1 + +or, if running the unit tests with all the other parser tests: + + make check COVERAGE=1 + +Coverage information will be written out in files in the source build +tree (*.gcno files *.gcda). The 'gcovr' utility is useful for reading +and summarizing the results; to do so, after running your tests, +do something like: + + gcovr -r /PATH/TO/YOUR/PARSER/BUILD/TREE + +Of course, having test coverage over a given line of code +won't indicate that the code is bug free; however, not having +coverage indicates that the tests do not exercise the given code at +all. That said, 100% coverage is unlikely to be possible in a testing +environment, given checks for things like error handling for failed +memory allocations. + +Finding memory leaks +-------------------- +The tst/ subdirectory has a python script for running the valgrind on +the parser over the test files in the simple_tests/ tree. This can take +over 24 hours to complete, so it is not part of the default tests; +however, it can be run manually or via the 'valgrind' make target. + +Valgrind reports some false positives for some additional checks it +makes; the script attempts to suppress those (read the valgrind +documentation for more details on suppressions). It can also emit the +suppressions via the --dump-suppressions argument, to be used for manual +valgrind runs. + +An example manual valgrind run could be something like: + + ./tst/valgrind_simply.py --dump-suppressions > /tmp/valgrind.suppression + valgrind --leak-check=full --suppressions=/tmp/valgrind.suppression ./apparmor_parser -QK /path/to/profile + +Profiling (for performance) the parser +-------------------------------------- + +# Using valgrind's callgrind tool + +Valgrind provides the callgrind tool to give some indication where +hot spots are in the parser. To do so, do: + + valgrind --tool=callgrind ./apparmor_parser PARSER_ARGS + +This will generate a data file that a tool like kcachegrind can read. + +# Using gprof + +This can be enabled by adding the -pg argument as a CFLAG [1] at build +time and then exercising the parser. A data file will be generated +that gprof(1) can then read to show where the parser is spending the +most time. + +[1] Unfortunately, only the DEBUG option in the Makefile does this, + which enables other debugging options that alters the parser in + ways that make it a less accurate representation of real world + performance. This needs to be fixed. -- AppArmor mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
