← Back to branch summary

~apparmor-dev/apparmor/apparmor-ubuntu-citrain-trusty

« back to all changes in this revision

Viewing changes to parser/README.devel

  • Committer: Seth Arnold
  • Date: 2014-03-12 02:05:16 UTC
  • mto: This revision was merged to the branch mainline in revision 1496.
  • Revision ID: seth.arnold@canonical.com-20140312020516-zjike3pmw6hi861h
[ Jamie Strandboge ]
 * debian/debhelper/dh_apparmor: exit with error if aa-easyprof does not
   exist
 * debian/control: drop Depends on apparmor-easyprof to Suggests for
   dh-apparmor
[ Seth Arnold, Jamie Strandboge, Steve Beattie, John Johansen, Tyler Hicks ]
* New upstream snapshot (LP: #1278702, #1061693, #1285653) dropping very
  large Ubuntu delta and fixing the following bugs:
  - Adjust fonts abstraction for libthai (LP: #1278702)
  - Support translated XDG user directories (LP: #1061693)
  - Adjust abstractions/web-data to include /var/www/html (LP: #1285653)
    Refresh 0002-add-debian-integration-to-lighttpd.patch to include
    /etc/lighttpd/conf-available/*.conf
  - Adjust debian/libapparmor1.symbols to reflect new upstream versioning
    for the aa_query_label() function
  - Raise exceptions in Python bindings when something fails
* ship new Python replacements for previous Perl-based tools
  - debian/apparmor-utils.install: remove usr/share/perl5/Immunix/*.pm and add
    usr/sbin/aa-autodep, usr/sbin/aa-cleanprof and usr/sbin/aa-mergeprof
  - debian/control:
    + remove various Perl dependencies
    + add python-apparmor and python3-apparmor
    + python3-apparmor Breaks: apparmor-easyprof to move the file since it
      ships dist-packages/apparmor/__init__.py now
  - debian/apparmor-utils.manpages: ship new manpages for aa-cleanprof and
    aa-mergeprof
  - debian/rules: build and install Python tools
* debian/apparmor.install:
  - install apparmorfs, dovecot, kernelvars, securityfs, sys,
    and xdg-user-dirs tunables and xdg-user-dirs.d directory
* debian/apparmor.dirs:
  - install /etc/apparmor.d/tunables/xdg-user-dirs.d
* debian/apparmor.postinst: create xdg-user-dirs.d
* debian/apparmor.postrm: remove xdg-user-dirs.d
* Remaining patches:
  - 0001-add-chromium-browser.patch
  - 0002-add-debian-integration-to-lighttpd.patch
  - 0003-ubuntu-manpage-updates.patch
  - 0004-libapparmor-layout-deb.patch (renamed from 0008)
  - 0005-libapparmor-mention-dbus-method-in-getcon-man.patch (renamed from
    0068)
  - 0006-etc-writable.patch (renamed from 0070)
  - 0007-aa-utils_are_bilingual.patch (renamed from 0077)
  - 0008-remove-ptrace.patch
  - 0009-convert-to-rules.patch
  - 0010-list-fns.patch
  - 0011-parse-mode.patch
  - 0012-add-decimal-interp.patch
  - 0013-policy_mediates.patch
  - 0014-fix-failpath.patch
  - 0015-feature_file.patch
  - 0016-fix-network.patch
  - 0017-aare-to-class.patch
  - 0018-add-mediation-unix.patch
  - 0019-parser_version.patch
  - 0020-caching.patch
  - 0021-label-class.patch
  - 0022-signal.patch
  - 0023-fix-lexer-debug.patch
  - 0024-ptrace.patch
  - 0025-use-diff-encode.patch
  - 0026-fix-serialize.patch
  - 0027-fix-af.patch
  - 0028-opt_arg.patch
  - 0029-tests-cond-dbus.patch
  - 0030-tests.diff
* Move manpages from libapparmor1 to libapparmor-dev
  - debian/libapparmor-dev.manpages: install aa_change_hat.2,
    aa_change_profile.2, aa_find_mountpoint.2, aa_getcon.2
  - debian/control: libapparmor-dev Replaces: and Breaks: libapparmor1
* Move /usr/lib/python3/dist-packages/apparmor/__init__.py from
  apparmor-easyprof to python3-apparmor
  - debian/control: python3-apparmor Breaks: apparmor-easyprof
  - debian/apparmor-easyprof.install: remove
    usr/lib/python*.*/site-packages/apparmor*
* New profiles and abstractions:
  - debian/apparmor.install: tunables/dovecot, tunables/kernelvars,
    tunables/xdg-user-dirs, tunables/xdg-user-dirs.d
* Test merge from upstream new pyutils branch (rev 2385)

Show diffs side-by-side

added added

removed removed

Lines of Context:
parser/README.devel
 
1
AppArmor parser development notes and tips
 
2
==========================================
 
3
 
 
4
Debugging the build
 
5
-------------------
 
6
Adding V=1 as argument to make should result in build commands that are
 
7
normally quieter generating more verbose output. This can help diagnose
 
8
when something is going wrong at build time.
 
9
 
 
10
Distribution vendors may wish to enable this option all
 
11
the time to assist debugging build failures in remote build
 
12
environments. Generally, they should not need to enable any other
 
13
build flags/options.
 
14
 
 
15
Building the parser with debugging information
 
16
----------------------------------------------
 
17
Setting DEBUG=1 with make will enable debugging output in the parser
 
18
(i.e. PDEBUG statements will be emitted instead of dropped). Usually,
 
19
partial compilation between debug and non-debug will cause compilation
 
20
problems, so it's usually best to do something like
 
21
 
 
22
  make clean all DEBUG=1
 
23
 
 
24
Test Coverage
 
25
-------------
 
26
The parser can be built to generate test coverage information, by
 
27
setting the COVERAGE variable for make. As with debugging, partial
 
28
compilation is usually problematic, so it's recommended to do:
 
29
 
 
30
  make clean all COVERAGE=1
 
31
 
 
32
and then run whatever tests. Because the unit tests are built with the
 
33
make check target, in order to see what coverage they provide, they will
 
34
also need to be built with the COVERAGE flag set:
 
35
 
 
36
  make tests COVERAGE=1
 
37
 
 
38
or, if running the unit tests with all the other parser tests:
 
39
 
 
40
  make check COVERAGE=1
 
41
 
 
42
Coverage information will be written out in files in the source build
 
43
tree (*.gcno and *.gcda files). The 'gcovr' utility is useful for
 
44
reading and summarizing the results; to do so, after running your
 
45
tests, do something like:
 
46
 
 
47
  gcovr -r /PATH/TO/YOUR/PARSER/BUILD/TREE
 
48
 
 
49
Of course, having test coverage over a given line of code
 
50
won't indicate that the code is bug free; however, not having
 
51
coverage indicates that the tests do not exercise the given code at
 
52
all. That said, 100% coverage is unlikely to be possible in a testing
 
53
environment, given checks for things like error handling for failed
 
54
memory allocations.
 
55
 
 
56
Finding memory leaks
 
57
--------------------
 
58
The tst/ subdirectory has a python script for running valgrind on the
 
59
parser over the test files in the simple_tests/ tree. This can take
 
60
over 24 hours to complete, so it is not part of the default tests;
 
61
however, it can be run manually or via the 'valgrind' make target.
 
62
 
 
63
Valgrind reports some false positives for some additional checks it
 
64
makes; the script attempts to suppress those (read the valgrind
 
65
documentation for more details on suppressions). It can also emit the
 
66
suppressions via the --dump-suppressions argument, to be used for manual
 
67
valgrind runs.
 
68
 
 
69
An example manual valgrind run could be something like:
 
70
 
 
71
  ./tst/valgrind_simply.py --dump-suppressions > /tmp/valgrind.suppression
 
72
  valgrind --leak-check=full --suppressions=/tmp/valgrind.suppression ./apparmor_parser -QK /path/to/profile
 
73
 
 
74
Profiling (for performance) the parser
 
75
--------------------------------------
 
76
 
 
77
# Using valgrind's callgrind tool
 
78
 
 
79
Valgrind provides the callgrind tool to give some indication where
 
80
hot spots are in the parser. To do so, do:
 
81
 
 
82
  valgrind --tool=callgrind ./apparmor_parser PARSER_ARGS
 
83
 
 
84
This will generate a data file that a tool like kcachegrind can read.
 
85
 
 
86
# Using gprof
 
87
 
 
88
This can be enabled by adding the -pg argument as a CFLAG [1] at build
 
89
time and then exercising the parser. A data file will be generated
 
90
that gprof(1) can then read to show where the parser is spending the
 
91
most time.
 
92
 
 
93
[1] Unfortunately, only the DEBUG option in the Makefile does this,
 
94
    which enables other debugging options that alters the parser in
 
95
    ways that make it a less accurate representation of real world
 
96
    performance. This needs to be fixed.