From b27554b93d855972c0b8484226fab1253d1472e3 Mon Sep 17 00:00:00 2001 From: Mark Wielaard Date: Thu, 7 Aug 2008 12:43:39 +0200 Subject: Add meta file tag descriptions to systemtap.examples/README. --- testsuite/systemtap.examples/README | 52 +++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) (limited to 'testsuite/systemtap.examples') diff --git a/testsuite/systemtap.examples/README b/testsuite/systemtap.examples/README index 6718a55a..e505bdfb 100644 --- a/testsuite/systemtap.examples/README +++ b/testsuite/systemtap.examples/README @@ -5,5 +5,53 @@ Each script should be checked in as executable. The first line should be #! /usr/bin/env stap -There should be an accompanying ".txt" file describing what the -script does and how to use it. +There should be an accompanying ".meta" file describing what the +script does and how to use it, and how the testsuite should compile +and run it. The meta files are also used to create a txt and html +index (by keyword and subsystem) of all the examples by the +examples-index-gen.pl script. + +The meta file contains the following elements. Each element (key and +value) are on one line. If a key can have a list of values, the list +elements are separated by spaces. + +title: Descriptive title for the script (required) +name: the file name for the script, e.g. iotime.stp (required) +version: versioning if any fixes and developed can be identified (required) +author: name of author(s), "anonymous" if unknown (required) +exclusivearch: Stated if the script can only run on some arches + this concept borrowed from rpm, matches types for rpm: + x86 i386 x86_64 ppc ppc64, s390 (optional) +requires: Some scripts may require software to be available. In some cases + may need version numbering, e.g. kernel >= 2.6 + Can have multiple "requires:" tags. (optional) +keywords: List of likely words to categorize the script (required) + keywords are separated by spaces. + #FIXME have list of keyword +subsystem: List what part of the kernel the instrumentation probes (required) + audit cpu blockio file filesystem locking memory numa network + process scheduler or user-space (probes are in the user-space) +application: when user-space probing becomes available (optional) + a script might probe a particular application + this tag indicates the applicaton +status: describes the state of development for the script (required) + proposed just an idea + experimental an implemented idea, but use at own risk + alpha + beta + production should be safe to use +exit: how long do the script run? (required) + fixed exits in a fixed amount of time + user-controlled exits with "cntrl-c" + event-ended exits with some arbitrary event +output: what kind of output does the script generate? (required) + trace histogram graph sorted batch timed +scope: How much of the processes on the machine does the script watch? + system-wide or pid +arg_[0-9]+: Describe what the arguments into the script are. (optional) +description: A text description what the script does. (required) +test_check: How to check that the example compiles. + (e.g. stap -p4 iotime.stp) +test_installcheck: How to check that the example runs. + (e.g. stap iotime.stp -c "sleep 1") + -- cgit From ea667a9f0d42dad0652563e7b76ce1527ebb9fc3 Mon Sep 17 00:00:00 2001 From: Mark Wielaard Date: Thu, 7 Aug 2008 14:24:51 +0200 Subject: Correct futexes.meta name: entry. --- testsuite/systemtap.examples/ChangeLog | 4 ++++ testsuite/systemtap.examples/futexes.meta | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) (limited to 'testsuite/systemtap.examples') diff --git a/testsuite/systemtap.examples/ChangeLog b/testsuite/systemtap.examples/ChangeLog index 7cb39fb9..ca2ffbdd 100644 --- a/testsuite/systemtap.examples/ChangeLog +++ b/testsuite/systemtap.examples/ChangeLog @@ -1,3 +1,7 @@ +2008-08-07 Mark Wielaard + + * futexes.meta: Correct name: entry. + 2008-08-01 William Cohen * helloworld.meta, traceio2.meta: Tweak test_installcheck. diff --git a/testsuite/systemtap.examples/futexes.meta b/testsuite/systemtap.examples/futexes.meta index 0a34b2d8..ff303122 100644 --- a/testsuite/systemtap.examples/futexes.meta +++ b/testsuite/systemtap.examples/futexes.meta @@ -1,5 +1,5 @@ title: System-Wide Futex Contention -name: futex.stp +name: futexes.stp version: 1.0 author: anonymous keywords: syscall locking futex -- cgit From 1cfd2143ecabdf664b2d61f6d46bfab6fdd77816 Mon Sep 17 00:00:00 2001 From: Mark Wielaard Date: Thu, 7 Aug 2008 15:18:14 +0200 Subject: Add new examples-index-gen.pl script and support files. --- testsuite/systemtap.examples/ChangeLog | 10 + testsuite/systemtap.examples/examples-index-gen.pl | 290 +++++++++++++++++++++ testsuite/systemtap.examples/html_footer.tmpl | 14 + testsuite/systemtap.examples/html_header.tmpl | 41 +++ testsuite/systemtap.examples/systemtap.css | 164 ++++++++++++ testsuite/systemtap.examples/systemtapcorner.gif | Bin 0 -> 970 bytes testsuite/systemtap.examples/systemtaplogo.png | Bin 0 -> 1860 bytes 7 files changed, 519 insertions(+) create mode 100644 testsuite/systemtap.examples/examples-index-gen.pl create mode 100644 testsuite/systemtap.examples/html_footer.tmpl create mode 100644 testsuite/systemtap.examples/html_header.tmpl create mode 100644 testsuite/systemtap.examples/systemtap.css create mode 100644 testsuite/systemtap.examples/systemtapcorner.gif create mode 100644 testsuite/systemtap.examples/systemtaplogo.png (limited to 'testsuite/systemtap.examples') diff --git a/testsuite/systemtap.examples/ChangeLog b/testsuite/systemtap.examples/ChangeLog index ca2ffbdd..fa6a3aa3 100644 --- a/testsuite/systemtap.examples/ChangeLog +++ b/testsuite/systemtap.examples/ChangeLog @@ -1,3 +1,13 @@ +2008-08-07 Mark Wielaard + + * examples-index-gen.pl: New file. + * systemtap.css: Likewise. + * systemtapcorner.gif: Likewise. + * systemtaplogo.png: Likewise. + * html_footer.tmpl: Likewise. + * html_header.tmpl: Likewise. + * Makefile.am (EXTRA_DIST): Add new support files. + 2008-08-07 Mark Wielaard * futexes.meta: Correct name: entry. diff --git a/testsuite/systemtap.examples/examples-index-gen.pl b/testsuite/systemtap.examples/examples-index-gen.pl new file mode 100644 index 00000000..bc12577e --- /dev/null +++ b/testsuite/systemtap.examples/examples-index-gen.pl @@ -0,0 +1,290 @@ +# Generates index files from examples .meta file info. +# Copyright (C) 2008 Red Hat Inc. +# +# This file is part of systemtap, and is free software. You can +# redistribute it and/or modify it under the terms of the GNU General +# Public License (GPL); either version 2, or (at your option) any +# later version. + +use strict; +use warnings; + +use File::Copy; +use File::Find; +use File::Path; +use Text::Wrap; + +my $inputdir; +if ($#ARGV >= 0) { + $inputdir = $ARGV[0]; +} else { + $inputdir = "."; +} + +my $outputdir; +if ($#ARGV >= 1) { + $outputdir = $ARGV[1]; +} else { + $outputdir = $inputdir; +} + +my %scripts = (); +print "Parsing .meta files in $inputdir...\n"; +find(\&parse_meta_files, $inputdir); + +my $meta; +my $subsystem; +my %subsystems; +my $keyword; +my %keywords; + +# Adds a formatted meta entry to a given file handle as text. +sub add_meta_txt(*;$) { + my($file,$meta) = @_; + + print $file "$scripts{$meta}{name} - $scripts{$meta}{title}\n"; + + print $file "output: $scripts{$meta}{output}, "; + print $file "exits: $scripts{$meta}{exit}, "; + print $file "status: $scripts{$meta}{status}\n"; + + print $file "subsystem: $scripts{$meta}{subsystem}, "; + print $file "keywords: $scripts{$meta}{keywords}\n\n"; + + $Text::Wrap::columns = 72; + my $description = wrap(' ', ' ', $scripts{$meta}{description}); + print $file "$description\n\n\n"; +} + +# Adds a formatted meta entry to a given file handle as text. +sub add_meta_html(*;$) { + my($file,$meta) = @_; + + my $name = $scripts{$meta}{name}; + print $file "
  • $name "; + print $file "- $scripts{$meta}{title}
    \n"; + + print $file "output: $scripts{$meta}{output}, "; + print $file "exits: $scripts{$meta}{exit}, "; + print $file "status: $scripts{$meta}{status}
    \n"; + + print $file "subsystem: $scripts{$meta}{subsystem}, "; + print $file "keywords: $scripts{$meta}{keywords}
    \n"; + + print $file "

    $scripts{$meta}{description}"; + print $file "

  • \n"; +} + +my $HEADER = "SYSTEMTAP EXAMPLES INDEX\n" + . "(see also subsystem-index.txt, keyword-index.txt)\n\n"; + +my $header_tmpl = "$inputdir/html_header.tmpl"; +open(TEMPLATE, "<$header_tmpl") + || die "couldn't open $header_tmpl, $!"; +my $HTMLHEADER = do { local $/;