From f0cfec62cdc1967ed10eb718f5da0f0468437805 Mon Sep 17 00:00:00 2001 From: Steve Beattie Date: Tue, 10 Dec 2013 14:15:02 -0800 Subject: [PATCH] parser: add some developer documentation Patch history: v1: initial version v2: based on feedback from cboltz and sarnold: - fix bad grammar when mentioning *.gcno and *.gcda files - mention that distros generally don't need other options besides verbose builds - fix 'the valgrind' grammar messup. Signed-off-by: Steve Beattie Acked-by: Seth Arnold --- parser/README.devel | 96 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 parser/README.devel diff --git a/parser/README.devel b/parser/README.devel new file mode 100644 index 000000000..406667eb0 --- /dev/null +++ b/parser/README.devel @@ -0,0 +1,96 @@ +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. Generally, they should not need to enable any other +build flags/options. + +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 and *.gcda files). 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 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.