mirror of
https://gitlab.com/apparmor/apparmor.git
synced 2025-03-04 16:35:02 +01:00
f0cfec62cd
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 <steve@nxnw.org>
Acked-by: Seth Arnold <seth.arnold@canonical.com>
96 lines
3.7 KiB
Text
96 lines
3.7 KiB
Text
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.
|