From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 12544 invoked by alias); 11 May 2009 16:21:51 -0000 Received: (qmail 12537 invoked by uid 22791); 11 May 2009 16:21:50 -0000 X-SWARE-Spam-Status: No, hits=-2.1 required=5.0 tests=AWL,BAYES_00,SPF_PASS X-Spam-Check-By: sourceware.org Received: from e35.co.us.ibm.com (HELO e35.co.us.ibm.com) (32.97.110.153) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 11 May 2009 16:21:44 +0000 Received: from d03relay04.boulder.ibm.com (d03relay04.boulder.ibm.com [9.17.195.106]) by e35.co.us.ibm.com (8.13.1/8.13.1) with ESMTP id n4BGFeaA022390 for ; Mon, 11 May 2009 10:15:40 -0600 Received: from d03av02.boulder.ibm.com (d03av02.boulder.ibm.com [9.17.195.168]) by d03relay04.boulder.ibm.com (8.13.8/8.13.8/NCO v9.2) with ESMTP id n4BGLfWD160064 for ; Mon, 11 May 2009 10:21:41 -0600 Received: from d03av02.boulder.ibm.com (loopback [127.0.0.1]) by d03av02.boulder.ibm.com (8.12.11.20060308/8.13.3) with ESMTP id n4BGLfEr007213 for ; Mon, 11 May 2009 10:21:41 -0600 Received: from [9.47.18.94] (dyn9047018094.beaverton.ibm.com [9.47.18.94]) by d03av02.boulder.ibm.com (8.12.11.20060308/8.12.11) with ESMTP id n4BGLeXm007164; Mon, 11 May 2009 10:21:40 -0600 Subject: Re: Write-up on submitting systemtap examples From: Jim Keniston To: William Cohen Cc: SystemTAP In-Reply-To: <4A0839A3.9070804@redhat.com> References: <4A0839A3.9070804@redhat.com> Content-Type: text/plain Date: Mon, 11 May 2009 16:21:00 -0000 Message-Id: <1242058894.3432.12.camel@dyn9047018094.beaverton.ibm.com> Mime-Version: 1.0 Content-Transfer-Encoding: 7bit X-IsSubscribed: yes Mailing-List: contact systemtap-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Post: List-Help: , Sender: systemtap-owner@sourceware.org X-SW-Source: 2009-q2/txt/msg00549.txt.bz2 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 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. >