Home | History | Annotate | Download | only in tcpdump
      1 Some Information for Contributors
      2 ---------------------------------
      3 You want to contribute to Tcpdump, Thanks!
      4 Please, read these lines.
      5 
      6 1) Fork the Tcpdump repository on GitHub from
      7    https://github.com/the-tcpdump-group/tcpdump
      8    (See https://help.github.com/articles/fork-a-repo/)
      9 
     10 2) Setup an optional Travis-CI build
     11    You can setup a travis build for your fork. So, you can test your changes
     12    on Linux and OSX before sending pull requests.
     13    (See http://docs.travis-ci.com/user/getting-started/)
     14 
     15 3) Clone your repository
     16    git clone https://github.com/<username>/tcpdump.git
     17 
     18 4) Do a 'touch .devel' in your working directory.
     19    Currently, the effect is
     20    a) add (via configure, in Makefile) some warnings options ( -Wall
     21    -Wmissing-prototypes -Wstrict-prototypes, ...) to the compiler if it
     22    supports these options,
     23    b) have the Makefile support "make depend" and the configure script run it.
     24 
     25 5) Configure and build
     26    ./configure && make -s && make check
     27 
     28 6) Add/update sample.pcap files
     29    We use tests directory to do regression tests on the dissection of captured
     30    packets, by running tcpdump against a savefile sample.pcap, created with -w
     31    option and comparing the results with a text file sample.out giving the
     32    expected results.
     33 
     34    Any new/updated fields in a dissector must be present in a sample.pcap file
     35    and the corresponding output file.
     36 
     37    Configuration is set in tests/TESTLIST.
     38    Each line in this file has the following format:
     39    test-name   sample.pcap   sample.out   tcpdump-options
     40 
     41    the sample.out file can be build by:
     42    (cd tests && ../tcpdump -n -r sample.pcap tcpdump-options > sample.out)
     43 
     44    It is often useful to have test outputs with different verbosity levels
     45    (none, -v, -vv, -vvv, etc.) depending on the code.
     46 
     47 7) Test with 'make check'
     48    Don't send a pull request if 'make check' gives failed tests.
     49 
     50 8) Rebase your commits against upstream/master
     51    (To keep linearity)
     52 
     53 9) Initiate and send a pull request
     54    (See https://help.github.com/articles/using-pull-requests/)
     55 
     56 Some remarks
     57 ------------
     58 a) A thorough reading of some other printers code is useful.
     59 
     60 b) Put the normative reference if any as comments (RFC, etc.).
     61 
     62 c) Put the format of packets/headers/options as comments.
     63 
     64 d) The printer may receive incomplete packet in the buffer, truncated at any
     65    random position, for example by capturing with '-s size' option.
     66    Thus use ND_TTEST, ND_TTEST2, ND_TCHECK or ND_TCHECK2 for bound checking.
     67    For ND_TCHECK2:
     68      Define : static const char tstr[] = " [|protocol]";
     69      Define a label: trunc
     70      Print with: ND_PRINT((ndo, "%s", tstr));
     71    You can test the code via:
     72      sudo ./tcpdump -s snaplen [-v][v][...] -i lo # in a terminal
     73      sudo tcpreplay -i lo sample.pcap             # in another terminal
     74    You should try several values for snaplen to do various truncation.
     75 
     76 e) Do invalid packet checks in code: Think that your code can receive in input
     77    not only a valid packet but any arbitrary random sequence of octets (packet
     78    - built malformed originally by the sender or by a fuzz tester,
     79    - became corrupted in transit).
     80    Print with: ND_PRINT((ndo, "%s", istr));	/* to print " (invalid)" */
     81 
     82 f) Use 'struct tok' for indexed strings and print them with
     83    tok2str() or bittok2str() (for flags).
     84 
     85 g) Avoid empty lines in output of printers.
     86 
     87 h) A commit message must have:
     88    First line: Capitalized short summary in the imperative (70 chars or less)
     89 
     90    Body: Detailed explanatory text, if necessary. Fold it to approximately
     91    72 characters. There must be an empty line separating the summary from
     92    the body.
     93 
     94 i) Avoid non-ASCII characters in code and commit messages.
     95 
     96 j) Use the style of the modified sources.
     97 
     98 k) Don't mix declarations and code
     99 
    100 l) Don't use // for comments
    101    Not all C compilers accept C++/C99 comments by default.
    102 
    103 m) Avoid trailing tabs/spaces
    104