| 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 |
|