diff options
Diffstat (limited to 'doc/developer-guidelines.sgml')
-rw-r--r-- | doc/developer-guidelines.sgml | 92 |
1 files changed, 79 insertions, 13 deletions
diff --git a/doc/developer-guidelines.sgml b/doc/developer-guidelines.sgml index 42ad8964..3edca6b8 100644 --- a/doc/developer-guidelines.sgml +++ b/doc/developer-guidelines.sgml | |||
@@ -109,7 +109,42 @@ | |||
109 | when it notifies contacts about potential problems. If you print | 109 | when it notifies contacts about potential problems. If you print |
110 | multiple lines, you're out of luck. Remember, keep it short and | 110 | multiple lines, you're out of luck. Remember, keep it short and |
111 | to the point.</para> | 111 | to the point.</para> |
112 | </section> | 112 | </section> |
113 | |||
114 | <section><title>Verbose output</title> | ||
115 | <para>Use the -v flag for verbose output. You should allow multiple | ||
116 | -v options for additional verbosity, up to a maximum of 3. The standard | ||
117 | type of output should be:</para> | ||
118 | |||
119 | <table id="verbose_levels"><title>Verbose output levels</title> | ||
120 | <tgroup cols="2"> | ||
121 | <thead> | ||
122 | <row> | ||
123 | <entry><para>Verbosity level</para></entry> | ||
124 | <entry><para>Type of output</para></entry> | ||
125 | </row> | ||
126 | </thead> | ||
127 | <tbody> | ||
128 | <row> | ||
129 | <entry align=center><para>0</para></entry> | ||
130 | <entry><para>Single line, minimal output. Summary</para></entry> | ||
131 | </row> | ||
132 | <row> | ||
133 | <entry align=center><para>1</para></entry> | ||
134 | <entry><para>Single line, additional information (eg list processes that fail)</para></entry> | ||
135 | </row> | ||
136 | <row> | ||
137 | <entry align=center><para>2</para></entry> | ||
138 | <entry><para>Multi line, configuration debug output (eg ps command used)</para></entry> | ||
139 | </row> | ||
140 | <row> | ||
141 | <entry align=center><para>3</para></entry> | ||
142 | <entry><para>Lots of detail for plugin problem diagnosis</para></entry> | ||
143 | </row> | ||
144 | </tbody> | ||
145 | </tgroup> | ||
146 | </table> | ||
147 | </section> | ||
113 | 148 | ||
114 | <section><title>Screen Output</title> | 149 | <section><title>Screen Output</title> |
115 | <para>The plug-in should print the diagnostic and just the | 150 | <para>The plug-in should print the diagnostic and just the |
@@ -345,9 +380,8 @@ | |||
345 | <section><title>Option Processing</title> | 380 | <section><title>Option Processing</title> |
346 | 381 | ||
347 | <para>For plugins written in C, we recommend the C standard | 382 | <para>For plugins written in C, we recommend the C standard |
348 | getopt library for short options. If using getopt_long, check to | 383 | getopt library for short options. Getopt_long is always available. |
349 | be sure that HAVE_GETOPT_H is defined (configure checks this and | 384 | </para> |
350 | sets the #define in common/config.h).</para> | ||
351 | 385 | ||
352 | <para>For plugins written in Perl, we recommend Getopt::Long module.</para> | 386 | <para>For plugins written in Perl, we recommend Getopt::Long module.</para> |
353 | 387 | ||
@@ -363,6 +397,7 @@ | |||
363 | -w warning threshold (--warning) | 397 | -w warning threshold (--warning) |
364 | -c critical threshold (--critical) | 398 | -c critical threshold (--critical) |
365 | -H hostname (--hostname) | 399 | -H hostname (--hostname) |
400 | -v verbose (--verbose) | ||
366 | </literallayout> | 401 | </literallayout> |
367 | 402 | ||
368 | <para>In addition to the reserved options above, some other standard options are:</para> | 403 | <para>In addition to the reserved options above, some other standard options are:</para> |
@@ -397,6 +432,9 @@ | |||
397 | help. Help text should fit on an 80-character width display, but | 432 | help. Help text should fit on an 80-character width display, but |
398 | may run as many lines as needed.</para> | 433 | may run as many lines as needed.</para> |
399 | 434 | ||
435 | <para>The option -v or --verbose should be present in all plugins. | ||
436 | The user should be allowed to specify -v multiple times to increase | ||
437 | the verbosity level, as described in <xref linkend="verbose_levels">.</para> | ||
400 | </section> | 438 | </section> |
401 | 439 | ||
402 | <section> | 440 | <section> |
@@ -405,7 +443,7 @@ | |||
405 | 443 | ||
406 | <para>Old style was to do things like -ct for critical time and | 444 | <para>Old style was to do things like -ct for critical time and |
407 | -cv for critical value. That goes out the window with POSIX | 445 | -cv for critical value. That goes out the window with POSIX |
408 | getopt. The allowable alternatves are:</para> | 446 | getopt. The allowable alternatives are:</para> |
409 | 447 | ||
410 | <orderedlist> | 448 | <orderedlist> |
411 | <listitem> | 449 | <listitem> |
@@ -449,23 +487,51 @@ | |||
449 | 487 | ||
450 | <para>As always, comments are welcome - making this consistent | 488 | <para>As always, comments are welcome - making this consistent |
451 | without a host of long options was quite a hassle, and I would | 489 | without a host of long options was quite a hassle, and I would |
452 | suspect that there are flaws in this strategy. Perhaps clear | 490 | suspect that there are flaws in this strategy. |
453 | long-options is the most important of the above choices, but not | 491 | </para> |
454 | all POSIX systems have C libraries for long options, so the | ||
455 | short forms must exist as well.</para> | ||
456 | </section> | 492 | </section> |
457 | </section> | 493 | </section> |
458 | 494 | ||
495 | <section id="CodingGuidelines"><title>Coding guidelines</title> | ||
496 | <para>See <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU | ||
497 | Coding standards</ulink> for general guidelines.</para> | ||
498 | <section><title>Comments</title> | ||
499 | <para>You should use /* */ for comments and not // as some compilers | ||
500 | do not handle the latter form</para> | ||
501 | </section> | ||
502 | </section> | ||
503 | |||
459 | <section id="SubmittingChanges"><title>New submissions and patches</title> | 504 | <section id="SubmittingChanges"><title>New submissions and patches</title> |
460 | 505 | ||
461 | <para>If you would like other to use your plugins and have it included in | 506 | <para>If you would like others to use your plugins and have it included in |
462 | the standard distribution, please include patches for the relavant | 507 | the standard distribution, please include patches for the relevant |
463 | configuration files, in particular "configure.in" Otherwise submitted | 508 | configuration files, in particular "configure.in". Otherwise submitted |
464 | plugins will be included in the contrib directory.</para> | 509 | plugins will be included in the contrib directory.</para> |
465 | 510 | ||
466 | <para>Plugins in the contrib directory are going to be migrated to the | 511 | <para>Plugins in the contrib directory are going to be migrated to the |
467 | standard plugins/plugin-scripts directory as time permits and per user | 512 | standard plugins/plugin-scripts directory as time permits and per user |
468 | requests</para> | 513 | requests. The minimum requirements are:</para> |
514 | |||
515 | <orderedlist> | ||
516 | <listitem> | ||
517 | <para>The standard command options are supported (--help, --version, | ||
518 | --timeout, --warning, --critical)</para> | ||
519 | </listitem> | ||
520 | <listitem> | ||
521 | <para>It is determined to be not redundant (for instance, we would not | ||
522 | add a new version of check_disk just because someone had provide | ||
523 | a plugin that had perf checking - we would incorporate the features | ||
524 | into an exisiting plugin)</para> | ||
525 | </listitem> | ||
526 | <listitem> | ||
527 | <para>One of the developers has had the time to audit the code and declare | ||
528 | it ready for core</para> | ||
529 | </listitem> | ||
530 | <listitem> | ||
531 | <para>It should also follow code format guidelines, and use functions from | ||
532 | utils (perl or c or sh) rather than cooking it's own</para> | ||
533 | </listitem> | ||
534 | </orderedlist> | ||
469 | 535 | ||
470 | <para>Patches should be submitted via the SourceForge and be announced to | 536 | <para>Patches should be submitted via the SourceForge and be announced to |
471 | the mailing list.</para> | 537 | the mailing list.</para> |