From Nagios Wiki

Overview

This document will document the information required to develop on Nagios in the central repository on Sourceforge.

Patches

If the patch is a small change, these should be first raised on mantis.

TODO: Ethan to change Mantis to send all tracker item changes to nagios-devel list.

Larger should changes should be discussed on mailing list first.

Source code management

Currently, the source code for Nagios is held in CVS in Sourceforge.

We will probably switch to git in the future.

Checkout

To access the nagios code with developer read/write access, run this:

export CVS_RSH=ssh
cvs -z3 -d:ext:USERNAME@nagios.cvs.sourceforge.net:/cvsroot/nagios checkout nagios

This will create a subdirectory called nagios for editing.

Changes

When making any changes, update the Changelog at the top level with a summary of the change. Keep to present tense when writing. Include author in comments. Update THANKS file.

Changelog to be categorised by:

 * Enhancements
 * Fixes
 * Warnings

Order chronologically.

Keep commits minimal.

Write detailed changelog (what? why?). Put detailed comments on how in the code.

Add Mantis bug number if appropriate.

Code style

Remain in "Ethan style" until TBD (change delayed for now).

When indent style is changed, use GNU Indent (or some other program) to re-indent for future release. TODO: Update instructions here about running indent program before submitting patches.

Credit

Credit 3rd party patches in the commit message. Update the THANKS file with their full name.

Testing

Ideally, add a test for each change you make. At the very least, check that existing tests still pass before committing.

Add perl test files into t/. These will get run with a make test-perl. These are good for configuration tests, end-to-end tests and CGI output tests.

Add C unit tests into t-tap/. These will get run with a make test-tap. These are good for controlled testing.

Running tests

From a tar distribution, run ./configure --enable-libtap && make nagios && make cgis && make test.

(From CVS, you may need to run autoconf first.)

This should return last few lines like:

$ make test
make test-perl
prove t/*.t
t/615cgierror...........ok                                                   
t/616cginotification....ok                                                   
t/620history............ok                                                   
t/621extinfo............ok                                                   
t/705nagiostats.........ok                                                   
t/900-configparsing.....ok                                                   
t/910-noservice.........ok                                                   
All tests successful.
Files=7, Tests=32,  1 wallclock secs ( 0.67 cusr +  0.26 csys =  0.93 CPU)
make test-tap
HARNESS_PERL=./test_each.t perl -MTest::Harness -e '$Test::Harness::switches=""; runtests(@ARGV)' test_logging
test_logging...ok                                                            
All tests successful.
Files=1, Tests=14,  1 wallclock secs ( 0.06 cusr +  0.03 csys =  0.09 CPU)

This means all the tests passed successfully.

Configuration file tests

The t/900configparsing.t test will take the configuration from t/etc/nagios.cfg (which in turn reads t/etc/minimal.cfg) and runs a nagios -v against it to validate it. It will also run a nagios -vp against it to create the objects.precache file and test this against an expected file. This proves that the configuration file can be parsed as expected.

If you are doing changes around configuration parsing, these are the steps to include the test:

• don't update nagios code yet
• confirm that perl t/900configparsing.t returns OK
• update t/etc/minimal.cfg with relevant entries
• run perl t/900configparsing.t. This should fail (you've made changes to the config!) with output like:

not ok 2 - Nagios precached objects discrepency!!!

• run the diff command specified in the output. This will show the differences between the expected and the generated objects.precache file. Update the objects.precache.expected file with the desired result
• make the changes to nagios
• run the test again
• when happy, commit code changes with test changes

The idea is that you have a test failure before your code changes (that highlights the bug or new feature), but the test passes after the code changes are made.

CGI tests

It is possible to invoke the CGIs as if you were a web server, thus allowing you to check for expected strings in the output.

See t/616cginotification.t for an example.

References

See http://search.cpan.org/dist/Test-Simple/lib/Test/More.pm for general information about perl's testing toolkit.

Tinderbox tests

See Tinderbox page.

TODO: Include run of package creation

Release process

TODO: Ethan to document steps for release (include button for latest release number)

Documentation

Update documentation in main repository as you go.

Profiling

Some notes on profiling CGIs (from Jonathan Kames):

Build CGI with -pg (profiling) compiler flag, figured out correct environment variables to set to run profiling version of status.cgi from the shell and produce gmon.out, and ran gprof on profiling version of cgi and gmon.out to produce execution profile

TODO: add more instructions when more profiling work done