Debian Codegraph @

EXAMPLES/README

raw
1 This text describes contribution procedures for adding scripts to
2 systemtap.examples directory. Please read before submitting SystemTap
3 examples. Discussions take place on the <[email protected]> list.
4
5 - general
6
7 The script should do something that normal users of SystemTap might
8 like to do, such as show which processes have system calls that time
9 out or show which memory accesses cause page faults. Scripts that
10 check that some aspect of SystemTap operates correctly, but would
11 never be used by a regular user should go in one of the other
12 testsuite directories.
13
14 - copyright
15
16 You must designate the appropriate copyright holder for your
17 contribution. The copyright holder is assumed to agree with the
18 general licensing terms (GPLv2+).
19
20 - coding style
21
22 Abide by the general formatting of the code for SystemTap. The
23 code base generally follows the GNU standards in usermode code and
24 the Linux kernel standards in runtime code.
25
26 - Try to keep the lines shorter than 80 characters long.
27 - Make use of SystemTap functions to factor out common idioms in code.
28 - Use tapset probe points rather than raw function names.
29 - Make scripts portable by avoiding probes by file and line number.
30 - Avoid unnecessary use of guru mode (-g) in the examples.
31 - Make the file executable and use the following line at the
32 beginning of the script to select the proper interpreter:
33
34 #! /usr/bin/env stap
35
36
37 - Describe the example
38
39 Each example script has a description in a .meta file that provide
40 an easy-to-parse format that describes various aspect of the example
41 script. The .meta file has the same base name as the example script.
42 The .meta file is parsed to generate a web page listing all the
43 available examples; the webpage is available at:
44 http://sourceware.org/systemtap/examples/. The .meta file also
45 describes how to run the compiled example script for testing. This
46 ensures that the example is frequently run to verify it works on a
47 wide range of platforms.
48
49 The meta file may contain the following elements. Each element (key
50 and value) are on one line. If a key can have a list of values, the
51 list elements are separated by spaces. Only fields marked with "@"
52 below are meaningful enough and used by the index-generator, so
53 a .meta file can be quite small. The generator script
54 perl examples-index-gen.pl
55 should be run whenever .meta/.txt files are modified. Note, this
56 will require perl DBI.
57
58
59 +---- @ means required
60 |
61 v
62
63 @ title: Descriptive title for the script (required)
64 @ name: the file name for the script, e.g. iotime.stp (required)
65 version: versioning if any fixes and developed can be identified
66 (optional)
67 author: name of author(s), if known (optional)
68 exclusivearch: Stated if the script can only run on some arches
69 this concept borrowed from rpm, matches types for
70 rpm: x86 i386 x86_64 ppc ppc64, s390 (optional)
71 requires: Some scripts may require software to be available. In some
72 cases may need version numbering, e.g. kernel >= 2.6
73 Can have multiple "requires:" tags. (optional)
74 @ keywords: List of likely words to categorize the script (required)
75 keywords are separated by spaces. Please don't be
76 unnecessarily innovative with keywords. Tag really good
77 examples with the "_best" keyword for highlighting in indexes.
78 subsystem: List what part of the kernel the instrumentation probes
79 (optional), similar to keywords
80 application: when user-space probing becomes available (optional)
81 a script might probe a particular application
82 this tag indicates the applicaton
83 status: describes the state of development for the script (optional)
84 proposed just an idea
85 experimental an implemented idea, but use at own risk
86 alpha
87 beta
88 production should be safe to use
89 exit: how long does the script run? (optional)
90 fixed exits in a fixed amount of time
91 user-controlled exits with "cntrl-c"
92 event-ended exits with some arbitrary event
93 output: what kind of output does the script generate? (optional)
94 trace histogram graph sorted-list batch timed on-exit
95 scope: How much of the processes on the machine does the script
96 watch? (required) system-wide, process or per-socket
97 arg_[0-9]+: Describe what the arguments into the script are.
98 (optional)
99 @ description: A text description what the script does. (required)
100 test_support: How to check that the example is applicable. Run by
101 'sh -c COMMAND'. (e.g. stap -l needed.probe)
102 test_check: How to check that the example compiles. Run by
103 'sh -c COMMAND'. (e.g. stap -p4 iotime.stp)
104 test_installcheck: How to check that the example runs. Run by
105 'sh -c COMMAND'.
106 (e.g. stap iotime.stp -T 1)
107 @ usage: A sample invocation of the script, if more informative than
108 the test_* ones.
109 @ As an alternative, a SAMPLE.txt file beside the .meta/.stp
110 files can be used to give longer freeform usage examples
111 for the script.
112
113
114 - Testing of the example script
115
116 To enable automated testing, include the "test_support", "test_check",
117 and/or "test_installcheck" fields in the meta file. Run the examples
118 subset of the testsuite with
119 % make check RUNTESTFLAGS=check.exp
120 and/or
121 # make installcheck RUNTESTFLAGS=check.exp
122
123 Note that the check.exp test script checks for an optional tcl file
124 that can check to see if the example is applicable to the system,
125 somewhat analogous to the 'test_support' key mentioned above.
126
127
128 - Review, revision, and submission of the example script
129
130 When you have a SystemTap script that should be included as an
131 example, submit it to the SystemTap mailing list,
132 [email protected] for review. Even if the script is not
133 ready for submission as an example, feel free to ask questions or
134 discuss the work-in-progress script with other people working with
135 SystemTap.
136