From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 27414 invoked by alias); 11 May 2009 14:44:07 -0000 Received: (qmail 27403 invoked by uid 22791); 11 May 2009 14:44:05 -0000 X-SWARE-Spam-Status: No, hits=-2.3 required=5.0 tests=AWL,BAYES_00,SPF_HELO_PASS,SPF_PASS X-Spam-Check-By: sourceware.org Received: from mx1.redhat.com (HELO mx1.redhat.com) (66.187.233.31) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 11 May 2009 14:43:56 +0000 Received: from int-mx1.corp.redhat.com (int-mx1.corp.redhat.com [172.16.52.254]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id n4BEhshj020202 for ; Mon, 11 May 2009 10:43:54 -0400 Received: from ns3.rdu.redhat.com (ns3.rdu.redhat.com [10.11.255.199]) by int-mx1.corp.redhat.com (8.13.1/8.13.1) with ESMTP id n4BEhmrn013897 for ; Mon, 11 May 2009 10:43:49 -0400 Received: from [10.11.231.126] (dhcp231-126.rdu.redhat.com [10.11.231.126]) by ns3.rdu.redhat.com (8.13.8/8.13.8) with ESMTP id n4BEhlpu022945 for ; Mon, 11 May 2009 10:43:47 -0400 Message-ID: <4A0839A3.9070804@redhat.com> Date: Mon, 11 May 2009 14:44:00 -0000 From: William Cohen User-Agent: Thunderbird 2.0.0.21 (X11/20090320) MIME-Version: 1.0 To: SystemTAP Subject: Write-up on submitting systemtap examples Content-Type: text/plain; charset=ISO-8859-1 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/msg00542.txt.bz2 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 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.