From 311d5d6ce07bd44c3aa9c468a96bdfbf6ededdc8 Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Mon, 2 Mar 2015 11:26:19 -0500 Subject: [PATCH] examples README: clarify index-generation Mention .txt files, _best keyword, and index-generator, to which only a few .meta fields are important. --- testsuite/systemtap.examples/README | 36 +++++++++++++++++------------ 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/testsuite/systemtap.examples/README b/testsuite/systemtap.examples/README index f106f1975..32deb0030 100644 --- a/testsuite/systemtap.examples/README +++ b/testsuite/systemtap.examples/README @@ -49,12 +49,16 @@ examples. Discussions take place on the ensures that the example is frequently run to verify it works on a wide range of platforms. - 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) + The meta file may contain 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. Only fields marked with @ + below are meaningful enough and used by the index-generator, so + a .meta file can be quite small. The generator script + perl examples-index-gen.pl + should be run whenever .meta/.txt files are modified. + +@ 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) @@ -64,14 +68,10 @@ examples. Discussions take place on the 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. - autofs backtrace callgraph cpu device disk file filesystem - format function futex interrupt io kvm limits locking - memory monitoring nanosleep network nfs numa process - profiling qemu scheduler scsi security signals simple slab - socket statistics syscall tcp thread time trace tracepoint - traffic tty utilization virtualization watchdog watchpoint +@ keywords: List of likely words to categorize the script (required) + keywords are separated by spaces. Please don't be + unnecessarily innovative with keywords. Tag really good + examples with the "_best" keyword for highlighting in indexes. subsystem: List what part of the kernel the instrumentation probes (required) any none audit cpu blockio file filesystem locking memory numa network process scheduler syscall or @@ -95,7 +95,7 @@ examples. Discussions take place on the watch? (required) system-wide, process or per-socket arg_[0-9]+: Describe what the arguments into the script are. (optional) - description: A text description what the script does. (required) +@ description: A text description what the script does. (required) test_support: How to check that the example is applicable. Run by 'sh -c COMMAND'. (e.g. stap -l needed.probe) test_check: How to check that the example compiles. Run by @@ -103,6 +103,12 @@ examples. Discussions take place on the test_installcheck: How to check that the example runs. Run by 'sh -c COMMAND'. (e.g. stap iotime.stp -c "sleep 1") +@ usage: A sample invocation of the script, if more informative than + the test_* ones. +@ As an alternative, a SAMPLE.txt file beside the .meta/.stp + files can be used to give longer freeform usage examples + for the script. + - Review, revision, and submission of the example script -- 2.43.5