Re: Draft: SystemTap Instrumentation Script Cataloging and Archiving

[fche at redhat dot com (Frank Ch. Eigler)]

wcohen wrote:

> SystemTap Instrumentation Script Cataloging and Archiving
> Version 0.1

It's a good start.  Here are some simple specifics I suggest:


> Packaging Scripts

- Scripts should be placed under examples/CLASS/ in the following form:
  - main script body: SAMPLE.stp
  - runnable demo driver: SAMPLE.sh, which presumably includes a
    call to "stap STAMPLE.stp ..."
  - documentation: SAMPLE.txt, in a stylized form TBD,
    including headers such as "Keyword: foo", "Summary: bar"
  - preferably, no other files, so extra stuff like C code
    would need to be stored within SAMPLE.sh
- examples/CATALOG should be a text file mechanically produced
  by grepping for headers in the */*.txt stylized documentation files.

> Vetting Scripts

- Scripts be offered for review on the mailing list, so that
  they can demonstrate good function and style.
- Scripts should be at least buildok-tested by the dejagnu "make check".
  This can be done by a generic .exp file that runs "stap -p4" on all
  .stp files matching examples/*/*.stp, except those that require
  command line arguments ($1 or @1).
- Scripts should be runok-tested by the dejagnu "make installcheck".
  This can be done by a generic .exp file that runs each of the
  examples/*/*.sh scripts, perhaps amended by per-sample tcl code.

> Document Scripts

- Need to propose a documentation template.  As mentioned above, I
  suggest a simple .txt file with a few standard headers that
  we can extract for the catalog file.  One could start from the
  wiki WarStories template.
- IMO, it is not necessary that this stuff be literally part of the
  .stp file.  It would make them hard to read (much longer) and use as
  a basis for experimentation.

> Organize and Catalog Scripts

- Need to propose a set of CLASS subdirectories for examples/;
  perhaps language/, profiling/, monitoring/
- Need to enumerate all the places where potential samples
  currently reside (src/examples, src/testsuite/*, warstories,
  tutorial, langref, mailing lists, "systemtap help" bugzillas).
- Need to actually collect them.
- Need to retire the old copies if possible, so as to make the
  src/examples/ the sole copy.
- Need to post the samples back to the web for search engine
  and casual onlooker visibility.  It may be enough to link to
  <http://sourceware.org/git/?p=systemtap.git;a=tree;f=examples>.


- FChE