$Id: HACKING,v 1.10 2008/10/14 19:20:43 jayrfink Exp $

NetWard HACKING
---------------
Information for potential hackers.

Source is provided to Netward because we believe users have a
right to know exactly what a program is going to do before they run
it.  This also allows you to audit the software for security holes
(none have been found so far).

Source code also allows you to port NetWard to new platforms, fix bugs,
and add new features.  You are highly encouraged to send your changes
to jay.fink@gmail.com for possible incorporation into the main
distribution.  By sending these changes it is assumed that you are
offering the unlimited, non-exclusive right to reuse, modify,
and relicense the code.  This is important because the inability to
relicense code has caused devastating problems for other Free Software
projects (such as KDE and NASM).  NetWard will always be available Open
Source.  If you wish to specify special license conditions of your
contributions, just say so when you send them.

NetWard is a community project and stands to benefit from contributions.
Bugfixes, and portability changes will almost always be accepted.  
Even if you do not have time to track
down and patch a problem, bug reports are always welcome.

Hackers interested in something more major, such as a new feature, are
encouraged to send a mail describing their plans to
jay.fink@gmail.com .  This is a good way to solicit feedback on
your proposals.  

Working with -current
---------------------
NetWard is under constant development. The easiest way to keep up and hack
is to track the main repository and flip on the debug compile time option.

1. Checkout the code:
  cvs -d:pserver:anonymous@systhread.cvs.sourceforge.net:/cvsroot/systhread \
       login 
  cvs -z3 -d:pserver:anonymous@systhread.cvs.sourceforge.net:/cvsroot/systhread \
       co -P netward

2. Compile with the -debug  or -gdb option:

 2a. -debug
  On Linux kernel based systems:
    cd /path/to/netward
    make linux-debug

  On FreeBSD systems:
    cd /path/to/netward
    make freebsd-debug

  On MAC OSX systems:
    cd /path/to/netward
    make darwin-debug
 
 2b. -gdb .... NOTE: This enables DEBUG prints as well ....
  On Linux kernel based systems:
    cd /path/to/netward
    make linux-gdb

  On FreeBSD systems:
    cd /path/to/netward
    make freebsd-gdb

  On MAC OSX systems:
    cd /path/to/netward
    make darwin-gdb
 
How to make code contributions
------------------------------
The preferred mechanism for submitted changes is unified diffs against
the the HEAD of the CVS repository and submit them to jay.fink@gmail.com:

To make a unified diff, please follow these instructions:

1. Remove temporary files:
    make clean

2. Rename your source tree:
    cd ..
    mv netward netward-mystuff

3. Check out the latest version or unpack your tarball:

  cvs -d:pserver:anonymous@systhread.cvs.sourceforge.net:/cvsroot/systhread \
       login 
  cvs -z3 -d:pserver:anonymous@systhread.cvs.sourceforge.net:/cvsroot/systhread \
       co -P netward

      or
    tar xzf netward-x.x.tar.gz

4. Generate the diffs:
   diff -urNb netward[-x.x]  netward-mystuff > netward.patch

5. Check the patch and remove any unnecessary patches from the file.

6. If you've added several features, it's best to send them as
   several independent patches if you can.

If you have just patched one or two files, then making patches is even
easier. For each file, just do:

  cp file.c file.c.orig
  [Make changes to file.c ...]
  diff -u file.c.orig file.c > file.c.patch

and just send us the patch: file.c.patch.

Style
-----
netward currently uses lkm style or -linux with indent or if that profile is
not avaiable in the src directory:

	for n in *.c ; do gindent -kr  -i8 $n ; done

which is pretty close.

Credits
-------
I got the idea for this HACKING file from Nmap
(http://www.nmap.org/) who got it from Gnet
(http://www.gnetlibrary.org/) and followed the
general structure of their HACKING files.
