This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Write-up on submitting systemtap examples
- From: William Cohen <wcohen at redhat dot com>
- To: SystemTAP <systemtap at sources dot redhat dot com>
- Date: Mon, 11 May 2009 10:43:47 -0400
- Subject: Write-up on submitting systemtap examples
Hi All,
Trying to streamline the process of people submitting systemtap examples. Below
is a writeup trying to cover what to do for submitting examples. Comments on it
would be appreciated. Expect that this text would go in the
testsuite/systemtap.examples directory and be like the HACKING file in the root
of systemtap source code.
-Will
The text describes contribution procedures for added scripts to
systemtap.examples. Please read before submitting Systemtap examples.
Discussions take place on the <systemtap@sources.redhat.com> mailing
list.
- general
The script should do something that a normal users of SystemTap might
like to do, such as show which processes have systemcalls that timeout
or show which memory accesses cause page faults. Scripts that check
that check some aspect of systemtap operates correctly, but would
never be used by a regular user should go in one of the other test
directories.
- 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.
- Try to keep the lines shorter than 80 characters long
- Make use of systemtap functions to factor out common idoms in code
- Use tapset probe points rather than raw function names
- No probes by file and line number allowed in examples
- Avoid using guru mode (-g) in the examples
- Minimize use of globals variables:
All associative arrays must be global in SystemTap
Variables used only for the duration of a probe should be local
- Make the file executable and use the following line at the
beginning of the script to select the proper interpreter:
#! /usr/bin/env stap
- Describe the example
Each example script has a description in a .meta file that provide
an easy-to-parse format that describes various aspect of the example
script. The .meta file has the same base name as the example script.
The .meta file is parsed to generate an webpage listing all the
available examples; the webpage is available at:
http://sourceware.org/systemtap/examples/. The .meta file also
describe how to run the compile example script for testing. This
ensures that the example is frequently run to verified it works on a
wide range fo platforms.
Each line in the .meta file has a tag indicate what the line is.
You can look at the meta files for the existing systemtap examples
in the SystemTap source code repository. For more information about
the tags refer to the email thread archived at:
http://sourceware.org/ml/systemtap/2008-q2/msg00045.html
- Review, revision, and submission of the example script
When you have a SystemTap script that should be included as an
example, submit it to the SystemTap mailing list,
systemtap@sources.redhat.com for review. Even if the script is not
ready for submission as an example, feel free to ask questions or
discuss the work-in-progress script with other people working with
SystemTap.