This is the mail archive of the systemtap@sourceware.org mailing list for the systemtap project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]