Default to first interface from pcap_findalldevs()

[tcpdump] / CONTRIBUTING

Some informations for Contributors
----------------------------------
Your want to contribute to Tcpdump, Thanks!
Please, read these lines.

1) Fork the Tcpdump repository on GitHub from
   https://github.com/the-tcpdump-group/tcpdump
   (See https://help.github.com/articles/fork-a-repo/)

2) Setup an optionnal Travis-CI build
   You can setup a travis build for your fork. So, your can test your changes
   on Linux and OSX before sending pull requests.
   (See http://docs.travis-ci.com/user/getting-started/)

3) Clone your repository
   git clone https://github.com/<username>/tcpdump.git

4) Do a 'touch .devel' in your working directory.
   Currently, the effect is
   a) add (via configure, in Makefile) some warnings options ( -Wall
   -Wmissing-prototypes -Wstrict-prototypes, ...) to the compiler if it
   supports these options,
   b) have the Makefile support "make depend" and the configure script run it.

5) Configure and build
   ./configure && make -s && make check

6) Add/update sample.pcap files
   We use tests directory to do regression tests on the dissection of captured
   packets, by running tcpdump against a savefile sample.pcap, created with -w
   option and comparing the results with a text file sample.out giving the
   expected results.

   Any new/updated fields in a dissector must be present in a sample.pcap file
   and the corresponding output file.

   Configuration is set in tests/TESTLIST.
   Each line in this file has the following format:
   test-name   sample.pcap   sample.out   tcpdump-options

   the sample.out file can be build by:
   (cd tests && ../tcpdump -n -r sample.pcap tcpdump-options > sample.out)

   It is often useful to have test outputs with different verbosity levels
   (none, -v, -vv, -vvv, etc.) depending on the code.

7) Test with 'make check'
   Don't send a pull request if 'make check' gives failed tests.

8) Rebase your commits against upstream/master
   (To keep linearity)

9) Initiate and send a pull request
   (See https://help.github.com/articles/using-pull-requests/)

Some remarks
------------
- A thorough reading of some other printers code is usefull.

- Put the the normative reference if any as comments (RFC, etc.).

- Put the the format of packets/headers/options as comments.

- The printer may receive incomplete packet in the buffer, truncated at any
  random position, for example by capturing with '-s size' option.
  Thus use ND_TTEST, ND_TTEST2, ND_TCHECK or ND_TCHECK2 for bound checking.
  For ND_TCHECK2:
    Define : static const char tstr[] = " [|protocol]";
    Define a label: trunc
    Print with: ND_PRINT((ndo, "%s", tstr));
  You can test the code via:
    sudo ./tcpdump -s snaplen [-v][v][...] -i lo # in a terminal
    sudo tcpreplay -i lo sample.pcap             # in another terminal
  You should try several values for snaplen to do various truncation.

- Do invalid packet checks in code: Think that your code can receive in input
  not only a valid packet but any arbitrary random sequence of octets (packet
  corrupted in transit or built by a fuzz tester).

- Use 'struct tok' for indexed strings and print them with
  tok2str() or bittok2str() (for flags).

- Avoid empty lines in output of printers.

- A commit message must have:
  First line: Capitalized short summary in the imperative (70 chars or less)

  Body: Detailed explanatory text, if necessary.  Fold up it to approximately
  72 characters. There must be an empty line separating the summary from
  the body.

- Avoid non-ASCII characters in code and commit messages.

- Use the style of the modified sources.

- Don't mix declarations and code

- Don't use // for comments
  Not all C compilers accept C++/C99 comments by default.

- Avoid trailing tabs/spaces