You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
103 lines
3.8 KiB
103 lines
3.8 KiB
Some Information for Contributors |
|
--------------------------------- |
|
You 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 optional Travis-CI build |
|
You can setup a travis build for your fork. So, you 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) A thorough reading of some other printers code is useful. |
|
|
|
b) Put the normative reference if any as comments (RFC, etc.). |
|
|
|
c) Put the format of packets/headers/options as comments. |
|
|
|
d) 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. |
|
|
|
e) 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 |
|
- built malformed originally by the sender or by a fuzz tester, |
|
- became corrupted in transit). |
|
Print with: ND_PRINT((ndo, "%s", istr)); /* to print " (invalid)" */ |
|
|
|
f) Use 'struct tok' for indexed strings and print them with |
|
tok2str() or bittok2str() (for flags). |
|
|
|
g) Avoid empty lines in output of printers. |
|
|
|
h) A commit message must have: |
|
First line: Capitalized short summary in the imperative (70 chars or less) |
|
|
|
Body: Detailed explanatory text, if necessary. Fold it to approximately |
|
72 characters. There must be an empty line separating the summary from |
|
the body. |
|
|
|
i) Avoid non-ASCII characters in code and commit messages. |
|
|
|
j) Use the style of the modified sources. |
|
|
|
k) Don't mix declarations and code |
|
|
|
l) Don't use // for comments |
|
Not all C compilers accept C++/C99 comments by default. |
|
|
|
m) Avoid trailing tabs/spaces
|
|
|