If you have finished changing the Wireshark sources to suit your needs,
you might want to contribute your changes back to the Wireshark
community. You gain the following benefits by contributing your improvements:
It's the right thing to do. Other people who find your contributions
useful will appreciate them, and you will know that you have helped
people in the same way that the developers of Wireshark have helped
you.
You get free enhancements. By making your code public, other developers
have a chance to make improvements, as there's always room for
improvements. In addition someone may implement advanced features on top of
your code, which can be useful for yourself too.
You save time and effort. The maintainers and developers of Wireshark
will maintain your code as well, updating it when API changes or other
changes are made, and generally keeping it in tune with what is
happening with Wireshark. So if Wireshark is updated (which is done
often), you can get a new Wireshark version from the website and your
changes will already be included without any effort for you.
There's no direct way to commit changes to the SVN repository. Only a few
people are authorised to actually
make changes to the source code (check-in changed files). If you want
to submit your changes, you should make a diff file (a patch) and upload it to the bug tracker.
3.9.1. What is a diff file (a patch)?
A diff file
is a plain text file containing the differences between a pair of files
(or a multiple of such file pairs).
Tip!
A diff file is often also called a patch,
as it can be used to patch an existing source file or tree with changes
from somewhere else.
The Wireshark community is using patches to transfer source code changes
between the authors.
A patch is both readable by humans and (as it is specially formatted) by
some dedicated tools.
Here is a small example of a patch for file.h that
makes the second argument in cf_continue_tail()volatile. It was created using svn diff, described below:
Index: file.h
===================================================================
--- file.h (revision 21134)
+++ file.h (revision 22401)
@@ -142,7 +142,7 @@
* @param err the error code, if an error had occurred
* @return one of cf_read_status_t
*/
-cf_read_status_t cf_continue_tail(capture_file *cf, int to_read, int *err);
+cf_read_status_t cf_continue_tail(capture_file *cf, volatile int to_read, int *err);
/**
* Finish reading from "end" of a capture file.
The plus sign at the start of a line indicates an added line, a minus
sign indicates a deleted line compared to the original sources.
We prefer to use so called "unified" diff files in Wireshark development,
three unchanged lines before and after the actual changed parts are
included. This makes it much easier for a merge/patch tool to find
the right place(s) to change in the existing sources.
3.9.2. Generate a patch
There are several ways to generate patches. The preferred way is to
generate them from an updated Subversion tree, since it avoids
unnecessary integration work.
3.9.2.1. Using the svn command-line client
svn diff [changed_files] > svn.diff
Use the command line svn client to generate a patch in the required format
from the changes you've made to your working copy. If you leave out the
name of the changed file the svn client searches for all changes in the
working copy and usually produces a patch containing more than just the
change you want to send. Therefore you should always check the produced
patch file.
If you've added a new file, e.g.
packet-myprotocol.c, you can use svn
add to add it to your local tree before generating the patch.
Similarly, you can use svn rm for files that should
be removed.
3.9.2.2. Using the diff feature of the GUI Subversion clients
Most (if not all) of the GUI Subversion clients (RapidSVN, TortoiseSVN, ...)
have a built-in "diff" feature.
If you use TortoiseSVN:
TortoiseSVN (to be precise Subversion) keeps track of the files you have
changed in the directories it controls, and will generate for you a
unified diff file compiling the differences. To do so - after updating
your sources from the SVN repository if needed - just right-click on the
highest level directory and choose "TortoiseSVN" -> "Create patch...".
You will be asked for a name and then the diff file will be created. The
names of the files in the patch will be relative to the directory you have
right-clicked on, so it will need to be applied on that level too.
When you create the diff file, it will include any difference TortoiseSVN
finds in files in and under the directory you have right-clicked on, and
nothing else. This means that changes you might have made for your
specific configuration - like modifying "config.nmake" so that it uses
your lib directory - will also be included, and you will need to remove
these lines from the diff file. It also means that only changes will be
recorded, i.e. if you have created new files -say, a new packet-xxx for a
new protocol dissector- it will not be included in the diff, you need to
add it separately. And, of course, if you have been working separately in
two different patches, the .diff file will include both topics, which is
probably not a good idea.
3.9.2.3. Using the diff tool
A diff file is generated, by comparing two files or directories between
your own working copy and the "official" source tree. So to be able to
do a diff, you should
have two source trees on your computer, one with your working copy
(containing your changes), and one with the "official" source tree
(hopefully the latest SVN files) from www.wireshark.org.
If you have only changed a single file, you could type something like
this:
It's a good idea to do a make distclean before the
actual diff call, as this will remove a lot
of temporary files which might be otherwise included in the diff. After
doing the diff, you should edit the foo.diff
file and remove unnecessary things, like your private changes to the
config.nmake file.
Table 3.1. Some useful diff options
Option
Purpose
-N
Add new files when used in conjunction with -r.
-r
Recursively compare any subdirectories found.
-u
Output unified context.
--strip-trailing-cr
Strip trailing carriage return on input. This is useful for Win32
-x PAT
Exclude files that match PAT.
This could be something like -x *.obj to exclude all win32 object files.
The diff tool has a lot options; they can be listed with:
diff --help
3.9.3. Some tips for a good patch
Some tips that will make the merging of your changes into the
SVN tree much more likely (and you want exactly that, don't you :-):
Use the latest SVN sources, or alike.
It's a good idea to work with the same sources that are used by the
other developer's, this makes it usually much easier to apply your
patch. For information about the different ways to get the sources,
see Section 3.3, “Obtain the Wireshark sources”.
Update your SVN sources just before making a patch.
For the same reasons as the previous point.
Do a "make clean" before generating the patch.
This removes a lot of unneeded intermediate files (like object files)
which can confuse the diff tool generating a lot of unneeded stuff which
you have to remove by hand from the patch again.
Find a good descriptive filename for your patch.
Think a moment to find a proper name for your patch file. Often a
filename like wireshark.diff is used, which isn't
really helpful if keeping several of these files and find the right
one later. For example: If you want to commit changes to the datatypes
of dissector foo, a good filename might be:
packet-foo-datatypes.diff.
Don't put unrelated things into one large patch.
A few smaller patches are usually easier to apply (but also
don't put every changed line into a separate patch :-).
Remove any parts of the patch not related to the
changes you want to submit. You can use a text editor for this.
A common example for win32 developers are the differences in your private
config.nmake file.
In general: making it easier to understand and apply your patch by one
of the maintainers will make it much more likely (and faster) that it
will actually be applied.
Please remember: you don't pay the person "on the
other side of the mail" for his/her effort applying your patch!
3.9.4. Code Requirements
The core maintainers have done a lot of work fixing bugs and making code
compile on the various platforms Wireshark supports.
To ensure Wireshark's source code quality, and to reduce the workload of
the core maintainers, there are some things you should
think about before submitting a patch.
Warn!
Ignoring the code requirements will make it very likely
that your patch will be rejected!
Follow the Wireshark source code style guide.
Just because something compiles on your platform, that doesn't
mean it'll compile on all of the other platforms for which Wireshark is
built.
Wireshark runs on many platforms, and can be compiled with a number of
different compilers. See Section 7.2, “Coding styleguides” for details.
Submit dissectors as build-in whenever possible.
Developing a new dissector as a plugin is a good idea because compiling is
quicker, but it's best to convert dissectors to the build-in style before
submitting for checkin. This reduces the number of files that must be installed
with Wireshark and ensures your dissector will be available on all platforms.
This is no hard-n-fast rule though. Many dissectors are straightforward so they
can easily be put into 'the big pile', while some are ASN.1 based which takes a
different approach, and some multiple sourcefile dissectors are more suitable to
be placed separate as plugin.
Verify that your dissector code does not use prohibited or deprecated APIs
This can be done as follows:
Fuzz test your changes! Fuzz testing is a very
effective way to automatically find a lot of dissector related bugs.
You'll take a capture file containing packets affecting your dissector
and the fuzz test will randomly change bytes in this file, so that unusual
code paths in your dissector are checked. There are tools available to
automatically do this on any number of input files, see:
https://wiki.wireshark.org/FuzzTesting for details.
3.9.5. Sending your patch for inclusion
After generating a patch of your changes, you might want to have your
changes included into the SVN repository.
Set the Product, Priority, and Severity as needed.
Add a Summary and Description, and create a bug using the
Commit button. If your code has passed fuzz
testing, please say so in the description.
Once the bug has been created, select Create a New Attachment
and upload your patch or patches. Set the review_for_checkin flag to ?.
If possible and applicable, attach a capture file that demonstrates
your new feature or protocol.
Tip!
Setting the review_for_checkin is important.
Without it, your patch won't show up in the pending
patch request queue.
You might get one of the following responses to your patch request:
Your patch is checked into the SVN repository. Congratulations!
You are asked to provide additional information, capture files, or
other material. If you haven't fuzzed your code, you may be asked
to do so.
Your patch is rejected. You should get a response with the reason
for rejection. Common reasons include not following the style
guide, buggy or insecure code, and code that won't compile on other
platforms. In each case you'll have to fix each problem and upload
another patch.
You don't get any response to your patch (even after a few days or so).
Possible reason: your patch might simply get lost, as all core
maintainers were busy at that time and forgot to look at your patch.
Simply send a mail asking if the patch was forgotten or if someone is
still looking at it.
Published under the terms fo the GNU General Public License
![[Tip]](wsdg_graphics/tip.png)
![[Warning]](wsdg_graphics/warning.png)
