This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: Write-up on submitting systemtap examples
- From: Jim Keniston <jkenisto at us dot ibm dot com>
- To: William Cohen <wcohen at redhat dot com>
- Cc: SystemTAP <systemtap at sources dot redhat dot com>
- Date: Mon, 11 May 2009 09:21:34 -0700
- Subject: Re: Write-up on submitting systemtap examples
- References: <4A0839A3.9070804@redhat.com>
On Mon, 2009-05-11 at 10:43 -0400, William Cohen wrote:
> 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
Looks good. See below for suggested tweaks. Thanks for your work on
this.
Jim
>
>
> The text describes contribution procedures for added scripts to
s/added/adding/ ?
> 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
Fix "a normal users".
> like to do, such as show which processes have systemcalls that timeout
s/systemcalls/system calls/
s/timeout/time out/ -- since it's a verb here
> or show which memory accesses cause page faults. Scripts that check
> that check some aspect of systemtap operates correctly, but would
s/that check that check/that check that/
> 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
I'm not sure what you mean by "this name".
> 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
These are complete sentences, so append periods.
> - Make use of systemtap functions to factor out common idoms in code
s/idoms/idioms/
> - 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
s/an webpage/a web page/
> 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
s/describe/describes/
s/compile/compiled/
> 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.
s/tag indicate/tag to indicate/
> You can look at the meta files for the existing systemtap examples
s/meta/.meta/ to match elsewhere?
Capitalization of SystemTap is inconsistent.
> 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.
>