[apparmor] [patch 11/12] parser: add some developer documentation

[Seth Arnold]

On Tue, Dec 03, 2013 at 12:12:27PM -0800, Steve Beattie wrote:
> Signed-off-by: Steve Beattie <steve at nxnw.org>

This is fantastic.

Acked-by: Seth Arnold <seth.arnold at canonical.com>

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: Digital signature
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20131209/32ad25e7/attachment.pgp>