On Tue, Dec 03, 2013 at 12:12:27PM -0800, Steve Beattie wrote: > Signed-off-by: Steve Beattie <[email protected]>
This is fantastic. Acked-by: Seth Arnold <[email protected]> Small comments inline: > --- > 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. I'd say that all the other options should probably be off for distribution vendors; would it be worth saying so? > + > +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 ^^^^^^^^^^^^^^^^^^^^^ probably meant "and" > +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 valgrind" :) > +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. > Thanks
signature.asc
Description: Digital signature
-- AppArmor mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
