-
Notifications
You must be signed in to change notification settings - Fork 0
/
HACKING
188 lines (148 loc) · 8.1 KB
/
HACKING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
This text describes contribution procedures to systemtap. Please read
and understand them before jumping in. Discussions take place on
the <[email protected]> mailing list.
- general
Submissions should be in an easy-to-read diff/patch form, unless
this is inappropriate due to size, relevance, or fraction of novel
content. They should be accompanied by an explanation. The
relevant test suites should be run before and after your changes,
and regressions avoided, explained, or corrected.
Established contributors may be considered for direct GIT write
access. Other contributors should simply pack up the goods into a
plain text email message to the mailing list.
It is not necessary to include machine-generated files like
autoconf*, sample-script indexes, etc. in patches posted for
review.
- obvious changes
Trivial, obvious patches may be posted or committed without other
formalities.
- copyright
You must designate the appropriate copyright holder for your
contribution. If not already there, this name should be added by
your patch to the copyright header in the affected files. The
copyright holder is assumed to agree with the general licensing
terms (GPLv2+).
- coding style
Abide by the general formatting of the code you are modifying. The
code base generally follows the GNU standards in usermode code and
the Linux kernel standards in runtime code.
- commit messages
In the git commit message, make the first line a brief (<=50 char)
summary of the patch, and leave the second line blank. If you have
trouble coming up with a concise summary, consider whether your
patch might be better broken into smaller commits.
For trivial changes, the summary alone may be sufficient, but most
commits should include a paragraph or two giving more details about
what the change is and why it is needed. Extra information like
bugzilla numbers and mailing-list discussion links are appreciated
as a supplement, but they are not a replacement for a real
description.
- test suites
As far as practicable, changes should be accompanied by test cases
to prevent future regressions. Tests should be run on at least
x86, and ideally also on some 64-bit platform. The test suite is
located under /src/testsuite and is based on dejagnu. "make check"
runs unprivileged tests only against an uninstalled build tree.
"make installcheck" runs all tests against an installed tree.
Tests that don't require probe execution should go into new or
modified files under the *{ok,ko} directories, which are scanned
by corresponding systemtap.pass1-4/*.exp files. The "ko" tests are
for expected (deliberate) errors.
Tests that execute probes (pass 5) should include their own .exp/.stp
files under any other appropriate systemtap.* testsuite subdirectory.
To run a particular test or set of tests, do:
cd testsuite
make check RUNTESTFLAGS=testname.exp
or
make installcheck RUNTESTFLAGS=testname.exp
To disambiguate among multiple tests with the same name, specify
the directory as well -- for example:
make installcheck RUNTESTFLAGS=systemtap.base/print.exp
- translator
Translator changes can easily invalidate tapsets and user script
code. One must tread carefully and run regression tests rigorously.
Both positive and negative polarity (expect-pass / expect-fail) test
cases may need to be written to assert a bug fix. Script language
changes should be documented in the stap.1 man page and emphasized
in the NEWS file.
- tapsets
Tapset script files should demonstrate effective economy, and avoid
conflicts with user and other tapset code.
It may be necessary to prefix symbols with the tapset name to ensure
systemtap-wide uniqueness. All "external interfaces" expected to be
used by user scripts (or perhaps other tapsets) should be documented
-- either in stapprobes.3stap if they are built into the language or
otherwise somehow essential; or in kernel-doc style comments if they
are defined in a tapset (see almost any existing tapset for an
example of how this is done); any new tapset should be mentioned in
doc/SystemTap_Tapset_Reference/tapsets.tmpl. Major or incompatible
changes should be mentioned in the NEWS file; see also the
deprecation section below.
Internal function, variable, probe identifiers should be prefixed
with "_" for extra uniqueness, and not documented in the man pages.
Tapsets should come with a tests cases that provide good test
coverage. Every alias definition should be tested for pass-2
correctness. Every embedded-C routine should be tested for pass-4
buildability. As they are a security hazard, every tapset
embedded-C routine should be pass-5 stress-tested for response to
erroneous inputs. This applies doubly to /* unprivileged */ ones.
The platforms/architectures against which the tapset was tested
should be published, and ideally asserted by code.
Embedded-C code should avoid making references to the runtime or
other code possibly generated by the translator. Embedded-C code that
dereferences pointers should use deref() type functions to check each
individual operation if there exists a possibility that the function may
be called with invalid pointers or pointer chains.
- deprecation
Try to remain compatible with existing valid scripts, with respect
to changes in the script language or the tapset. Where this is not
practicable, preserve the old functionality using the %( systemtap_v %)
preprocessor conditional in the tapset and systemtap_session.compatible
in the translator. If needed, after several major releases,
deprecated functionality may be dropped outright. Note both pending
and final deprecation in NEWS and the permanent DEPRECATION section
in stap.1. The intent is to protect old scripts for a year or longer.
Tapset functions to be deprecated should be kept for at least one
major release. For example, if we're in development between versions
1.2 and 1.3, wrap to-be-deprecated tapset functions or probes in
%( systemtap_v <= "1.3" %? function foo() {} %)
so as to preserve the tapset function during the life of the 1.3 release.
Script language changes that cause earlier valid scripts to become
invalid should be opt-in (requiring --compatible=NEWVERSION) for at
least one major release before becoming default. For example, test
strverscmp(s.compatible.c_str(), "1.4") >= 0
in the 1.3 release sources in order to activate the change.
- runtime
Changes to the runtime can cause problems on different architectures
or kernel versions. Luckily, many code mistakes show up easily in
the pass-4 tests.
- i18n
We use the zanata [1] system for managing translations of runtime
strings. If interested, create yourself a zanata account, and help
translate online! In addition, you can ship systemtap sources
to/from zanata by installing the zanata-cli and getting a
$HOME/.config/zanata.ini file, thereafter following the advice [2][3]
of "make update-po" (invoked from the top of the build tree).
[1] https://translate.zanata.org/zanata/iteration/view/systemtap/master
[2] http://zanata.org/help/cli/cli-push
[3] http://zanata.org/help/cli/cli-pull
- meta
Proposed changes to these guidelines should be discussed on the
mailing list.
- git basics
git clone ssh://sourceware.org/git/systemtap.git
# OR: use git://sourceware.org/git/systemtap.git then add to .git/config:
# [remote "origin"]
# pushurl=ssh://sourceware.org/git/systemtap.git
# build ; hack hack hack; test
git add FILE1 FILE2 # enumerate all modified or new files
git status # to confirm that needed local changes are "staged"
git commit # to your local repository, add nice commit message
git show # to check that the last commit included all changes
git pull # to make sure your copy is up to date & merged
# last minute rebuild; retest
git rebase origin/master # clean git commit of merge history
git diff origin/master # final visual check
git push # to the central one, if you have access
OR git format-patch -s origin/master..
then email the resulting files to the mailing list