forked from osmocom/wireshark
Migrate the build environment introduction to AsciiDoc.
svn path=/trunk/; revision=54971
This commit is contained in:
parent
e61a6533e7
commit
5344e2f2fc
|
@ -185,7 +185,7 @@ set(WSDG_FILES
|
|||
wsdg_src/WSDG_chapter_build_intro.xml
|
||||
wsdg_src/WSDG_chapter_capture.xml
|
||||
wsdg_src/WSDG_chapter_dissection.xml
|
||||
wsdg_src/WSDG_chapter_env_intro.xml
|
||||
wsdg_generated_src/WSDG_chapter_env_intro.xml
|
||||
wsdg_src/WSDG_chapter_libraries.xml
|
||||
wsdg_src/WSDG_chapter_quick_setup.xml
|
||||
wsdg_generated_src/WSDG_chapter_sources.xml
|
||||
|
@ -198,6 +198,7 @@ set(WSDG_FILES
|
|||
)
|
||||
|
||||
set(WSDG_ASCIIDOC_FILES
|
||||
wsdg_src/WSDG_chapter_env_intro.asciidoc
|
||||
wsdg_src/WSDG_chapter_sources.asciidoc
|
||||
wsdg_src/WSDG_preface.asciidoc
|
||||
)
|
||||
|
|
|
@ -162,18 +162,19 @@ WSDG_FILES = \
|
|||
wsdg_src/WSDG_chapter_build_intro.xml \
|
||||
wsdg_src/WSDG_chapter_capture.xml \
|
||||
wsdg_src/WSDG_chapter_dissection.xml \
|
||||
wsdg_src/WSDG_chapter_env_intro.xml \
|
||||
wsdg_src/WSDG_chapter_env_intro.asciidoc \
|
||||
wsdg_src/WSDG_chapter_libraries.xml \
|
||||
wsdg_src/WSDG_chapter_quick_setup.xml \
|
||||
wsdg_src/WSDG_chapter_sources.asciidoc \
|
||||
wsdg_src/WSDG_chapter_sources.asciidoc \
|
||||
wsdg_src/WSDG_chapter_tools.xml \
|
||||
wsdg_src/WSDG_chapter_userinterface.xml \
|
||||
wsdg_src/WSDG_chapter_works.xml \
|
||||
wsdg_src/WSDG_meta_info.xml \
|
||||
wsdg_src/WSDG_preface.asciidoc \
|
||||
wsdg_src/WSDG_preface.asciidoc \
|
||||
ws.css
|
||||
|
||||
WSDG_GENERATED_SOURCE = \
|
||||
wsdg_src/WSDG_chapter_env_intro.xml \
|
||||
wsdg_src/WSDG_chapter_sources.xml \
|
||||
wsdg_src/WSDG_preface.xml
|
||||
|
||||
|
|
|
@ -8,22 +8,28 @@
|
|||
wireshark-version:\[\]=1.11.3
|
||||
wireshark-major-minor-version:\[\]=1.11
|
||||
|
||||
wireshark-authors-url:\[\]=http://www.wireshark.org/about.html#authors
|
||||
wireshark-bugs-site:\[\]=https://bugs.wireshark.org/
|
||||
wireshark-code-browse-url:\[\]=https://code.wireshark.org/review/gitweb?p=wireshark.git
|
||||
wireshark-code-review-url:\[\]=https://code.wireshark.org/review
|
||||
wireshark-dev-list-email:\[\]=wireshark-dev[AT]wireshark.org
|
||||
wireshark-developers-guide-url:\[\]=http://www.wireshark.org/docs/
|
||||
wireshark-download-page:\[\]=http://www.wireshark.org/download/
|
||||
wireshark-faq-url:\[\]=http://www.wireshark.org/faq.html
|
||||
wireshark-git-anonhttp-url:\[\]=https://code.wireshark.org/review/wireshark
|
||||
wireshark-git-http-url:\[\]=https://your.username@code.wireshark.org/review/wireshark
|
||||
wireshark-git-ssh-url:\[\]=ssh://your.username@code.wireshark.org:29418/wireshark
|
||||
wireshark-code-review-url:\[\]=https://code.wireshark.org/review
|
||||
wireshark-code-browse-url:\[\]=https://code.wireshark.org/review/gitweb?p=wireshark.git
|
||||
wireshark-mailing-lists-url:\[\]=http://www.wireshark.org/lists/
|
||||
wireshark-qa-url:\[\]=http://ask.wireshark.org/
|
||||
wireshark-users-guide-url:\[\]=http://www.wireshark.org/docs/
|
||||
wireshark-developers-guide-url:\[\]=http://www.wireshark.org/docs/
|
||||
wireshark-web-site:\[\]=http://www.wireshark.org/
|
||||
wireshark-wiki-site:\[\]=http://wiki.wireshark.org/
|
||||
wireshark-dev-list-email:\[\]=wireshark-dev[AT]wireshark.org
|
||||
|
||||
# Make a document attribute after we fully convert to AsciiDoc
|
||||
wsdg-author-email:\[\]=ulf.lamping[AT]web.de
|
||||
|
||||
gpl-url:\[\]=http://www.gnu.org/licenses/gpl-2.0.html
|
||||
|
||||
[macros]
|
||||
|
||||
# bugs.wireshark.org link
|
||||
|
|
|
@ -0,0 +1,583 @@
|
|||
++++++++++++++++++++++++++++++++++++++
|
||||
<!-- WSDG Chapter Introduction -->
|
||||
++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
++++++++++++++++++++++++++++++++++++++
|
||||
<!-- $Id$ -->
|
||||
++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
[[ChapterIntroduction]]
|
||||
|
||||
== Introduction
|
||||
|
||||
[[ChIntroIntro]]
|
||||
|
||||
=== Introduction
|
||||
|
||||
This chapter will provide you with information about Wireshark
|
||||
development in general.
|
||||
|
||||
[[ChIntroWhatIs]]
|
||||
|
||||
=== What is Wireshark?
|
||||
|
||||
Well, if you want to start Wireshark development, you might already
|
||||
know what Wireshark is doing. If not, please have a look at the
|
||||
wireshark-users-guide-url:[][Wireshark User's Guide],
|
||||
which will provide a lot of general information about it.
|
||||
|
||||
[[ChIntroPlatforms]]
|
||||
|
||||
=== Supported Platforms
|
||||
|
||||
Wireshark currently runs on most UNIX platforms and various Windows
|
||||
platforms. It requires GTK+, GLib, libpcap and some other libraries in
|
||||
order to run.
|
||||
|
||||
As Wireshark is developed in a platform independent way and uses libraries
|
||||
(such as the GTK+ GUI library) which are available for a lot of different platforms,
|
||||
it's thus available on a wide variety of platforms.
|
||||
|
||||
If a binary package is not available for your platform, you should
|
||||
download the source and try to build it. Please report your experiences
|
||||
to mailto:wireshark-dev-list-email:[][wireshark-dev-list-email:[]].
|
||||
|
||||
Binary packages are available for at least the following platforms:
|
||||
|
||||
==== Unix
|
||||
|
||||
* Apple Mac OS X
|
||||
|
||||
* BeOS
|
||||
|
||||
* FreeBSD
|
||||
|
||||
* HP-UX
|
||||
|
||||
* IBM AIX
|
||||
|
||||
* NetBSD
|
||||
|
||||
* OpenBSD
|
||||
|
||||
* SCO UnixWare/OpenUnix
|
||||
|
||||
* SGI Irix
|
||||
|
||||
* Sun Solaris/Intel
|
||||
|
||||
* Sun Solaris/Sparc
|
||||
|
||||
* Tru64 UNIX (formerly Digital UNIX)
|
||||
|
||||
==== Linux
|
||||
|
||||
* Debian GNU/Linux
|
||||
|
||||
* Ubuntu
|
||||
|
||||
* Gentoo Linux
|
||||
|
||||
* IBM S/390 Linux (Red Hat)
|
||||
|
||||
* Mandrake Linux
|
||||
|
||||
* PLD Linux
|
||||
|
||||
* Red Hat Linux
|
||||
|
||||
* Rock Linux
|
||||
|
||||
* Slackware Linux
|
||||
|
||||
* Suse Linux
|
||||
|
||||
==== Microsoft Windows
|
||||
|
||||
Thanks to the Win32 API, development on all Windows platforms will be
|
||||
done in a very similar way. All Windows platforms referred to as Win32,
|
||||
Win or Windows may be used with the same meaning.
|
||||
Older Windows versions are no longer supported by Wireshark.
|
||||
As Windows CE differs a lot compared to the other Windows platforms
|
||||
mentioned, Wireshark will not run on Windows CE and there are no plans to
|
||||
support it.
|
||||
|
||||
Also the 64 bit Windows version are now supported by Wireshark. Although
|
||||
not all libraries are made 64 bit ready yet, basic operations are all
|
||||
available.
|
||||
|
||||
* Windows 8.1 / Windows Server 2012 R2
|
||||
|
||||
* Windows 8 / Windows Server 2012
|
||||
|
||||
* Windows 7 / Windows Server 2008 R2
|
||||
|
||||
* Windows Vista / Windows Server 2008
|
||||
|
||||
* Windows XP / Windows Server 2003
|
||||
|
||||
[[ChIntroDevelopment]]
|
||||
|
||||
=== Development and maintenance of Wireshark
|
||||
|
||||
Wireshark was initially developed by Gerald Combs. Ongoing development
|
||||
and maintenance of Wireshark is handled by the Wireshark core developers,
|
||||
a loose group of individuals who fix bugs and provide new functionality.
|
||||
|
||||
There have also been a large number of people who have contributed protocol
|
||||
dissectors and other improvements to Wireshark, and it is expected that this
|
||||
will continue. You can find a list of the people who have contributed code to
|
||||
Wireshark by checking the About dialog box of Wireshark, or have a look at the
|
||||
wireshark-authors-url:[] page on the Wireshark web site.
|
||||
|
||||
The communication between the developers is usually done through the developer
|
||||
mailing list, which can be joined by anyone interested in the development
|
||||
activities. At the time this document was written, more than 500 persons were
|
||||
subscribed to this mailing list!
|
||||
|
||||
It is strongly recommended to join the developer mailing list, if you are going
|
||||
to do any Wireshark development. See <<ChIntroMailingLists>> about the different
|
||||
Wireshark mailing lists available.
|
||||
|
||||
==== Programming languages used
|
||||
|
||||
Most of Wireshark is implemented in plain ANSI C. A notable exception is
|
||||
the code in 'ui/qt', which is written in $$C++$$.
|
||||
|
||||
The typical task for a new Wireshark developer is to extend an existing,
|
||||
or write a new dissector for a specific network protocol. As (almost) any
|
||||
dissector is written in plain old ANSI C, a good knowledge about ANSI C
|
||||
will be sufficient for Wireshark development in almost any case.
|
||||
|
||||
So unless you are going to change the build process of Wireshark
|
||||
itself, you won't come in touch with any other programming language than
|
||||
ANSI C (such as Perl or Python, which are used only in the Wireshark build
|
||||
process).
|
||||
|
||||
Beside the usual tools for developing a program in C (compiler, make, ...),
|
||||
the build process uses some additional helper tools (Perl, Python, Sed,
|
||||
...), which are needed for the build process when Wireshark
|
||||
is to be build and installed from the released source packages. If Wireshark
|
||||
is installed from a binary package, none of these helper tools are needed on
|
||||
the target system.
|
||||
|
||||
==== Open Source Software
|
||||
|
||||
Wireshark is an open source software (OSS) project, and is released under
|
||||
the gpl-url:[][GNU General Public License] (GPL).
|
||||
You can freely use Wireshark on any number of computers you like, without
|
||||
worrying about license keys or fees or such. In addition, all source
|
||||
code is freely available under the GPL. Because of that, it is very easy
|
||||
for people to add new protocols to Wireshark, either as plugins, or built
|
||||
into the source, and they often do!
|
||||
|
||||
You are welcome to modify Wireshark to suit your own needs, and it would be
|
||||
appreciated if you contribute your improvements back to the Wireshark community.
|
||||
|
||||
|
||||
You gain three benefits by contributing your improvements back to the
|
||||
community:
|
||||
|
||||
* 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 and other people.
|
||||
|
||||
* The developers of Wireshark might improve your changes even more, as there's
|
||||
always room for improvement. Or they may implement some advanced things on top
|
||||
of your code, which can be useful for yourself too.
|
||||
|
||||
* The maintainers and developers of Wireshark will maintain your code as well,
|
||||
fixing 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.
|
||||
|
||||
|
||||
The Wireshark source code and binary packages for some platforms are all
|
||||
available on the download page of the Wireshark website:
|
||||
wireshark-download-page:[].
|
||||
|
||||
|
||||
[[ChIntroReleases]]
|
||||
|
||||
=== Releases and distributions
|
||||
|
||||
The officially released files can be found at: wireshark-download-page:[]. A new Wireshark version is released after
|
||||
significant changes compared to the last release are completed or a
|
||||
serious security issue is encountered. The typical release schedule is
|
||||
about every 4-8 weeks (although this may vary).
|
||||
|
||||
There are two kinds of distributions: binary and source; both have their
|
||||
advantages and disadvantages.
|
||||
|
||||
[[ChIntroReleaseBinary]]
|
||||
|
||||
==== Binary distributions
|
||||
|
||||
Binary distributions are usually easy to install (as simply starting
|
||||
the appropriate file is usually the only thing to do). They are available
|
||||
for the following systems:
|
||||
|
||||
* Windows (.exe file). The typical Windows end user is used to get a setup.exe
|
||||
file which will install all the required things for him.
|
||||
|
||||
* Win32 PAF (.paf.exe file). Another Windows end user method is to get a
|
||||
portable application file which will install all the required things for him.
|
||||
|
||||
* Debian (.deb file). A user of a Debian Package Manager (DPKG) based system
|
||||
obtains a .deb file from which the package manager checks the dependencies and
|
||||
installs the software.
|
||||
|
||||
* Red Hat (.rpm file). A user of a Red Hat Package Manager (RPM) based system
|
||||
obtains an .rpm file from which the package manager checks the dependencies
|
||||
and installs the software.
|
||||
|
||||
* MAC OS X (.dmg file). The typical MAC OS X end user is used to get a .dmg file
|
||||
which will install all the required things for him. The other requirement is
|
||||
to have the X11.app installed.
|
||||
|
||||
* Solaris. A Solaris user obtains a file from which the package manager (PKG)
|
||||
checks the dependencies and installs the software.
|
||||
|
||||
However, if you want to start developing with Wireshark, the binary
|
||||
distributions won't be too helpful, as you need the source files, of
|
||||
course.
|
||||
|
||||
For details about how to build these binary distributions yourself,
|
||||
e.g. if you need a distribution for a special audience, see
|
||||
<<ChSrcBinary>>.
|
||||
|
||||
[[ChIntroReleaseSource]]
|
||||
|
||||
==== Source code distributions
|
||||
|
||||
It's still common for UNIX developers to give the end user a source
|
||||
tarball and let the user compile it on their target machine (configure,
|
||||
make, make install). However, for different UNIX (Linux) distributions
|
||||
it's becoming more common to release binary packages (e.g. .deb or .rpm
|
||||
files) these days.
|
||||
|
||||
You should use the released sources if you want to build Wireshark from
|
||||
source on your platform for productive use. However, if you going to
|
||||
develop changes to the Wireshark sources, it might be better to use the
|
||||
latest SVN sources. For details about the different ways to get the
|
||||
Wireshark source code see <<ChSrcObtain>>.
|
||||
|
||||
Before building Wireshark from a source distribution, make sure you have
|
||||
all the tools and libraries required to build. The following chapters will
|
||||
describe the required tools and libraries in detail.
|
||||
|
||||
[[ChIntroAutomated]]
|
||||
|
||||
=== Automated Builds (Buildbot)
|
||||
|
||||
The Wireshark Buildbot automatically rebuilds Wireshark on every
|
||||
change of the source code repository and indicates problematic changes.
|
||||
This frees the developers from repeating (and annoying) work, so time can
|
||||
be spent on more interesting tasks.
|
||||
|
||||
==== Advantages
|
||||
|
||||
* Recognizing (cross platform) build problems - early. Compilation problems can
|
||||
be narrowed down to a few commits, making a fix much easier.
|
||||
|
||||
* "Health status" overview of the sources. A quick look at:
|
||||
http://buildbot.wireshark.org/trunk/[] gives a good "feeling" if the sources
|
||||
are currently "well". On the other hand, if all is "red", an update of a
|
||||
personal source tree might better be done later ...
|
||||
|
||||
* "Up to date" binary packages are available. After a change was committed to
|
||||
the repository, a binary package / installer is usually available within a few
|
||||
hours at: http://www.wireshark.org/download/automated/[]. This can be quite
|
||||
helpful, e.g. a bug reporter can easily verify a bugfix by installing a recent
|
||||
build.
|
||||
|
||||
* Automated regression tests. In particular, the fuzz tests often indicate "real
|
||||
life" problems that are otherwise hard to find.
|
||||
|
||||
==== What does the Buildbot do?
|
||||
|
||||
The Buildbot will do the following (to a different degree on the different
|
||||
platforms):
|
||||
|
||||
* Check out from the source repository
|
||||
|
||||
* Build
|
||||
|
||||
* Create binary packages and installers
|
||||
|
||||
* Create source packages and run distribution checks
|
||||
|
||||
* Run regression tests
|
||||
|
||||
Each step is represented at the status page by a rectangle, green if it
|
||||
succeeded or red if it failed. Most steps provide a link to the corresponding
|
||||
console logfile, to get additional information.
|
||||
|
||||
The Buildbot runs on a platform collection that represents the different
|
||||
"platform specialties" quite well:
|
||||
|
||||
* Windows XP x86 (Win32, little endian, Visual Studion 2010)
|
||||
|
||||
* Windows 7 x86-64 (Win64, little endian, VS 2010)
|
||||
|
||||
* Ubuntu x86-64 (Linux, little endian, gcc)
|
||||
|
||||
* Solaris SPARC (Solaris, big endian, gcc)
|
||||
|
||||
* Mac OS-X PPC (BSD, big endian, gcc)
|
||||
|
||||
* Mac OS-X x86 (BSD, little endian, Clang)
|
||||
|
||||
* Mac OS-X x86-64 (BSD, little endian, Clang)
|
||||
|
||||
Each platform is represented at the status page by a single column, the
|
||||
most recent entries are at the top.
|
||||
|
||||
[[ChIntroHelp]]
|
||||
|
||||
|
||||
=== Reporting problems and getting help
|
||||
|
||||
If you have problems, or need help with Wireshark, there are several
|
||||
places that may be of interest to you (well, beside this guide of
|
||||
course).
|
||||
|
||||
[[ChIntroHomepage]]
|
||||
|
||||
==== Website
|
||||
|
||||
You will find lot's of useful information on the Wireshark homepage at
|
||||
wireshark-web-site:[].
|
||||
|
||||
|
||||
[[ChIntroWiki]]
|
||||
|
||||
|
||||
==== Wiki
|
||||
|
||||
The Wireshark Wiki at wireshark-wiki-site:[] provides a wide range
|
||||
of information related to Wireshark and packet capturing in general.
|
||||
You will find a lot of information not part of this developer's guide. For
|
||||
example, there is an explanation how to capture on a switched network,
|
||||
an ongoing effort to build a protocol reference and a lot more.
|
||||
|
||||
And best of all, if you would like to contribute your knowledge on a
|
||||
specific topic (maybe a network protocol you know well), you can edit the
|
||||
wiki pages by simply using your webbrowser.
|
||||
|
||||
[[ChIntroFAQ]]
|
||||
|
||||
|
||||
==== FAQ
|
||||
|
||||
The "Frequently Asked Questions" will list often asked questions and
|
||||
the corresponding answers.
|
||||
|
||||
Before sending any mail to the mailing lists below, be sure to read the
|
||||
FAQ, as it will often answer any questions you might have. This will save
|
||||
yourself and others a lot of time. Keep in mind that a lot of people are
|
||||
subscribed to the mailing lists.
|
||||
|
||||
You will find the FAQ inside Wireshark by clicking the menu item
|
||||
Help/Contents and selecting the FAQ page in the upcoming dialog.
|
||||
|
||||
An online version is available at the Wireshark website: wireshark-faq-url:[].
|
||||
You might prefer this online version as it's typically more up to date and the
|
||||
HTML format is easier to use.
|
||||
|
||||
[[ChIntroOtherSources]]
|
||||
|
||||
==== Other sources
|
||||
|
||||
If you don't find the information you need inside this book, there are
|
||||
various other sources of information:
|
||||
|
||||
* The file 'doc/README.developer' and all the other README.xxx files in the
|
||||
source code. These are various documentation files on different topics
|
||||
|
||||
[NOTE]
|
||||
.Read the README
|
||||
====
|
||||
'README.developer' is packed full with all kinds of details relevant
|
||||
to the developer of Wireshark source code. It advices you around common
|
||||
pitfalls, shows you basic layout of dissector code, shows details of the
|
||||
APIs available to the dissector developer, etc.
|
||||
====
|
||||
|
||||
* The Wireshark source code
|
||||
|
||||
* Tool documentation of the various tools used
|
||||
(e.g. manpages of sed, gcc, etc.)
|
||||
|
||||
* The different mailing lists. See <<ChIntroMailingLists>>
|
||||
|
||||
[[ChIntroMailingLists]]
|
||||
|
||||
==== Mailing Lists
|
||||
|
||||
There are several mailing lists available on specific Wireshark topics:
|
||||
|
||||
wireshark-announce:: This mailing list will inform you about new program
|
||||
releases, which usually appear about every 4-8 weeks.
|
||||
|
||||
wireshark-users:: This list is for users of Wireshark. People post
|
||||
questions about building and using Wireshark, others (hopefully)
|
||||
provide answers.
|
||||
|
||||
wireshark-dev:: This list is for Wireshark developers. People post questions about
|
||||
the development of Wireshark, others (hopefully) provide answers.
|
||||
If you want to start developing a protocol dissector, join this list.
|
||||
|
||||
wireshark-bugs:: This list is for Wireshark developers. Every time a change to the bug
|
||||
database occurs, a mail to this mailing list is generated.
|
||||
If you want to be notified about all the changes to the bug
|
||||
database, join this list. Details about the bug database can be
|
||||
found in <<ChIntroBugDatabase>>.
|
||||
|
||||
wireshark-commits:: This list is for Wireshark developers. Every time a change to the SVN
|
||||
repository is checked in, a mail to this mailing list is generated.
|
||||
If you want to be notified about all the changes to the SVN
|
||||
repository, join this list. Details about the SVN repository can be
|
||||
found in <<ChSrcGitRepository>>.
|
||||
|
||||
You can subscribe to each of these lists from the Wireshark web site:
|
||||
wireshark-mailing-lists-url:[]. From there, you can choose which mailing list you
|
||||
want to subscribe to by clicking on the Subscribe/Unsubscribe/Options button
|
||||
under the title of the relevant list. The links to the archives are included on
|
||||
that page as well.
|
||||
|
||||
[TIP]
|
||||
.The archives are searchable
|
||||
====
|
||||
You can search in the list archives to see if someone previously asked the same
|
||||
question and maybe already got an answer. That way you don't have to wait until
|
||||
someone answers your question.
|
||||
====
|
||||
|
||||
[[ChIntroBugDatabase]]
|
||||
|
||||
==== Bug database (Bugzilla)
|
||||
|
||||
The Wireshark community collects bug reports in a Bugzilla database at
|
||||
wireshark-bugs-site:[]. This database is filled with manually filed bug reports,
|
||||
usually after some discussion on wireshark-dev, and automatic bug reports from
|
||||
the buildbot tools.
|
||||
|
||||
[[ChIntroQA]]
|
||||
|
||||
==== Q&A Site
|
||||
|
||||
The Wireshark Q and A site at wireshark-qa-url:[] offers a resource where
|
||||
questions and answers come together. You have the option to search what
|
||||
questions were asked before and what answers were given by people who knew about
|
||||
the issue. Answers are graded, so you can pick out the best ones easily. If your
|
||||
issue isn't discussed before you can post one yourself.
|
||||
|
||||
[[ChIntroReportProblems]]
|
||||
|
||||
==== Reporting Problems
|
||||
|
||||
[NOTE]
|
||||
.Test with the latest version
|
||||
====
|
||||
Before reporting any problems, please make sure you have installed the
|
||||
latest version of Wireshark. Reports on older maintenance releases are
|
||||
usually met with an upgrade request.
|
||||
====
|
||||
|
||||
If you report problems, provide as much information as possible. In general,
|
||||
just think about what you would need to find that problem, if someone else sends
|
||||
you such a problem report. Also keep in mind that people compile/run Wireshark
|
||||
on a lot of different platforms.
|
||||
|
||||
When reporting problems with Wireshark, it is helpful if you supply the
|
||||
following information:
|
||||
|
||||
. The version number of Wireshark and the dependent libraries linked with
|
||||
it, e.g. Qt, GTK+, etc. You can obtain this with the command
|
||||
`wireshark -v`.
|
||||
|
||||
. Information about the platform you run Wireshark on.
|
||||
|
||||
. A detailed description of your problem.
|
||||
|
||||
. If you get an error/warning message, copy the text of that message (and
|
||||
also a few lines before and after it, if there are some), so others may
|
||||
find the build step where things go wrong.
|
||||
Please don't give something like: "I get a warning when compiling x"
|
||||
as this won't give any direction to look at.
|
||||
|
||||
[NOTE]
|
||||
.Don't send large files
|
||||
====
|
||||
Do not send large files (>100KB) to the mailing lists, just place a note
|
||||
that further data is available on request. Large files will only annoy a
|
||||
lot of people on the list who are not interested in your specific problem.
|
||||
If required, you will be asked for further data by the persons who really
|
||||
can help you.
|
||||
====
|
||||
|
||||
[WARNING]
|
||||
.Don't send confidential information
|
||||
====
|
||||
If you send captured data to the mailing lists, or add it to your bug report,
|
||||
be sure it doesn't contain any sensitive or confidential information,
|
||||
such as passwords. Visibility of such files can be limited to certain
|
||||
groups in the Bugzilla database though.
|
||||
====
|
||||
|
||||
==== Reporting Crashes on UNIX/Linux platforms
|
||||
|
||||
When reporting crashes with Wireshark, it is helpful if you supply the
|
||||
traceback information (besides the information mentioned in
|
||||
<<ChIntroReportProblems>>).
|
||||
|
||||
You can obtain this traceback information with the following commands:
|
||||
|
||||
----
|
||||
$ gdb `whereis wireshark | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
|
||||
backtrace
|
||||
^D
|
||||
$
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
.Using GDB
|
||||
====
|
||||
Type the characters in the first line verbatim. Those are
|
||||
back-tics there.
|
||||
|
||||
`backtrace` is a `gdb` command. You should
|
||||
enter it verbatim after the first line shown above, but it will not be
|
||||
echoed. The ^D
|
||||
(Control-D, that is, press the Control key and the D key
|
||||
together) will cause `gdb` to exit. This will
|
||||
leave you with a file called
|
||||
'bt.txt' in the current directory.
|
||||
Include the file with your bug report.
|
||||
|
||||
If you do not have `gdb` available, you
|
||||
will have to check out your operating system's debugger.
|
||||
====
|
||||
|
||||
You should mail the traceback to the
|
||||
mailto:wireshark-dev-list-email:[][wireshark-dev mailing list], or attach it to your bug report.
|
||||
|
||||
==== Reporting Crashes on Windows platforms
|
||||
|
||||
You can download Windows debugging symbol files (.pdb) from the following locations:
|
||||
|
||||
* 32-bit Windows: http://www.wireshark.org/download/win32/all-versions/
|
||||
|
||||
* 64-bit Windows: http://www.wireshark.org/download/win64/all-versions/
|
||||
|
||||
Files are named "Wireshark-pdb-win__bits__-_x_._y_._z_.zip" to match their
|
||||
corresponding "Wireshark-win__bits__-_x_._y_._z_.exe" installer packages.
|
||||
|
||||
// XXX Show how to use the Visual Studio debugger
|
||||
|
||||
++++++++++++++++++++++++++++++++++++++
|
||||
<!-- End of WSDG Chapter Introduction -->
|
||||
++++++++++++++++++++++++++++++++++++++
|
||||
|
|
@ -1,730 +0,0 @@
|
|||
<!-- WSDG Chapter Introduction -->
|
||||
<!-- $Id$ -->
|
||||
|
||||
<chapter id="ChapterIntroduction">
|
||||
<title>Introduction</title>
|
||||
|
||||
<section id="ChIntroIntro">
|
||||
<title>Introduction</title>
|
||||
<para>
|
||||
This chapter will provide you with information about Wireshark
|
||||
development in general.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="ChIntroWhatIs">
|
||||
<title>What is <application>Wireshark?</application></title>
|
||||
<para>
|
||||
Well, if you want to start Wireshark development, you might already
|
||||
know what Wireshark is doing. If not, please have a look at the
|
||||
<ulink url="&WiresharkUsersGuidePage;">Wireshark User's Guide</ulink>,
|
||||
which will provide a lot of general information about it.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section id="ChIntroPlatforms">
|
||||
<title>Platforms Wireshark runs on</title>
|
||||
<para>
|
||||
Wireshark currently runs on most UNIX platforms and various Windows
|
||||
platforms. It requires GTK+, GLib, libpcap and some other libraries in
|
||||
order to run.
|
||||
</para>
|
||||
<para>
|
||||
As Wireshark is developed in a platform independent way and uses libraries
|
||||
(such as the GTK+ GUI library) which are available for a lot of different platforms,
|
||||
it's thus available on a wide variety of platforms.
|
||||
</para>
|
||||
<para>
|
||||
If a binary package is not available for your platform, you should
|
||||
download the source and try to build it. Please report your experiences
|
||||
to <ulink url="mailto:&WiresharkDevMailList;">&WiresharkDevMailList;</ulink>.
|
||||
</para>
|
||||
<para>
|
||||
Binary packages are available for at least the following platforms:
|
||||
</para>
|
||||
|
||||
<section><title>Unix</title>
|
||||
<para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Apple Mac OS X</para></listitem>
|
||||
<listitem><para>BeOS</para></listitem>
|
||||
<listitem><para>FreeBSD</para></listitem>
|
||||
<listitem><para>HP-UX</para></listitem>
|
||||
<listitem><para>IBM AIX</para></listitem>
|
||||
<listitem><para>NetBSD</para></listitem>
|
||||
<listitem><para>OpenBSD</para></listitem>
|
||||
<listitem><para>SCO UnixWare/OpenUnix</para></listitem>
|
||||
<listitem><para>SGI Irix</para></listitem>
|
||||
<listitem><para>Sun Solaris/Intel</para></listitem>
|
||||
<listitem><para>Sun Solaris/Sparc</para></listitem>
|
||||
<listitem><para>Tru64 UNIX (formerly Digital UNIX)</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section><title>Linux</title>
|
||||
<para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Debian GNU/Linux</para></listitem>
|
||||
<listitem><para>Ubuntu</para></listitem>
|
||||
<listitem><para>Gentoo Linux</para></listitem>
|
||||
<listitem><para>IBM S/390 Linux (Red Hat)</para></listitem>
|
||||
<listitem><para>Mandrake Linux</para></listitem>
|
||||
<listitem><para>PLD Linux</para></listitem>
|
||||
<listitem><para>Red Hat Linux</para></listitem>
|
||||
<listitem><para>Rock Linux</para></listitem>
|
||||
<listitem><para>Slackware Linux</para></listitem>
|
||||
<listitem><para>Suse Linux</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section><title>Microsoft Windows</title>
|
||||
<para>
|
||||
Thanks to the Win32 API, development on all Windows platforms will be
|
||||
done in a very similar way. All Windows platforms referred to as Win32,
|
||||
Win or Windows may be used with the same meaning.
|
||||
Older Windows versions are no longer supported by Wireshark.
|
||||
As Windows CE differs a lot compared to the other Windows platforms
|
||||
mentioned, Wireshark will not run on Windows CE and there are no plans to
|
||||
support it.
|
||||
</para>
|
||||
<para>
|
||||
Also the 64 bit Windows version are now supported by Wireshark. Although
|
||||
not all libraries are made 64 bit ready yet, basic operations are all
|
||||
available.
|
||||
</para>
|
||||
<para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Windows Server 2000</para></listitem>
|
||||
<listitem><para>Windows XP</para></listitem>
|
||||
<listitem><para>Windows Server 2003</para></listitem>
|
||||
<listitem><para>Windows Vista</para></listitem>
|
||||
<listitem><para>Windows 7</para></listitem>
|
||||
<listitem><para>Windows Server 2008</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
</section>
|
||||
|
||||
<section id="ChIntroDevelopment">
|
||||
<title>
|
||||
Development and maintenance of <application>Wireshark</application>
|
||||
</title>
|
||||
<para>
|
||||
Wireshark was initially developed by Gerald Combs. Ongoing development
|
||||
and maintenance of Wireshark is handled by the Wireshark core developers,
|
||||
a loose group of individuals who fix bugs and provide new functionality.
|
||||
</para>
|
||||
<para>
|
||||
There have also been a large number of people who have contributed
|
||||
protocol dissectors and other improvements to Wireshark, and it is
|
||||
expected that this will continue. You can find a list of the people who
|
||||
have contributed code to Wireshark by checking the About dialog box of
|
||||
Wireshark, or have a look at the <ulink url="&WiresharkAuthorsPage;"/>
|
||||
page on the Wireshark web site.
|
||||
</para>
|
||||
<para>
|
||||
The
|
||||
communication between the developers is usually done through the developer
|
||||
mailing list, which can be joined by anyone interested in the development
|
||||
activities. At the time this document was written, more than 500 persons were
|
||||
subscribed to this mailing list!
|
||||
</para>
|
||||
<para>
|
||||
It is strongly recommended to join the developer mailing list, if you
|
||||
are going to do any Wireshark development. See
|
||||
<xref linkend="ChIntroMailingLists"/> about the different Wireshark
|
||||
mailing lists available.
|
||||
</para>
|
||||
|
||||
<section><title>Programming language(s) used</title>
|
||||
<para>
|
||||
Almost any part of Wireshark is implemented in plain ANSI C.
|
||||
</para>
|
||||
<para>
|
||||
The typical task for a new Wireshark developer is to extend an existing,
|
||||
or write a new dissector for a specific network protocol. As (almost) any
|
||||
dissector is written in plain old ANSI C, a good knowledge about ANSI C
|
||||
will be sufficient for Wireshark development in almost any case.
|
||||
</para>
|
||||
<para>
|
||||
So unless you are going to change the build process of Wireshark
|
||||
itself, you won't come in touch with any other programming language than
|
||||
ANSI C (such as Perl or Python, which are used only in the Wireshark build
|
||||
process).
|
||||
</para>
|
||||
<para>
|
||||
Beside the usual tools for developing a program in C (compiler, make, ...),
|
||||
the build process uses some additional helper tools (Perl, Python, Sed,
|
||||
...), which are needed for the build process when Wireshark
|
||||
is to be build and installed from the released source packages. If Wireshark
|
||||
is installed from a binary package, none of these helper tools are needed on
|
||||
the target system.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
|
||||
<section><title>Open Source Software</title>
|
||||
<para>
|
||||
Wireshark is an open source software (OSS) project, and is released under
|
||||
the <ulink url="&GPLWebsite;">GNU General Public License</ulink> (GPL).
|
||||
You can freely use Wireshark on any number of computers you like, without
|
||||
worrying about license keys or fees or such. In addition, all source
|
||||
code is freely available under the GPL. Because of that, it is very easy
|
||||
for people to add new protocols to Wireshark, either as plugins, or built
|
||||
into the source, and they often do!
|
||||
</para>
|
||||
<para>
|
||||
You are welcome to
|
||||
modify Wireshark to suit your own needs, and it would be appreciated
|
||||
if you contribute your improvements back to the Wireshark community.
|
||||
</para>
|
||||
<para>
|
||||
You gain three benefits by contributing your improvements back to the
|
||||
community:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
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 and other
|
||||
people.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
The developers of Wireshark might improve your changes even more,
|
||||
as there's always room for improvement. Or they may implement some
|
||||
advanced things on top of your code, which can be useful for yourself
|
||||
too.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
The maintainers and developers of Wireshark will maintain your
|
||||
code as well, fixing 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.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<para>
|
||||
The Wireshark source code and binary packages for some platforms are all
|
||||
available on the download page of the Wireshark website:
|
||||
<ulink url="&WiresharkDownloadPage;">&WiresharkDownloadPage;</ulink>.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
</section>
|
||||
|
||||
<section id="ChIntroReleases">
|
||||
<title>Releases and distributions</title>
|
||||
<para>
|
||||
The officially released files can be found at: <ulink
|
||||
url="&WiresharkDownloadPage;"/>. A new Wireshark version is released after
|
||||
significant changes compared to the last release are completed or a
|
||||
serious security issue is encountered. The typical release schedule is
|
||||
about every 4-8 weeks (although this may vary).
|
||||
</para>
|
||||
<para>
|
||||
There are two kinds of distributions: binary and source; both have their
|
||||
advantages and disadvantages.
|
||||
</para>
|
||||
|
||||
<section id="ChIntroReleaseBinary">
|
||||
<title>Binary distributions</title>
|
||||
<para>
|
||||
Binary distributions are usually easy to install (as simply starting
|
||||
the appropriate file is usually the only thing to do). They are available
|
||||
for the following systems:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Windows (.exe file). The typical Windows end user is used to get a setup.exe
|
||||
file which will install all the required things for him.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Win32 PAF (.paf.exe file). Another Windows end user method is to get a portable
|
||||
application file which will install all the required things for him.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Debian (.deb file). A user of a Debian Package Manager (DPKG) based system
|
||||
obtains a .deb file from which the package manager checks the
|
||||
dependencies and installs the software.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Red Hat (.rpm file). A user of a Red Hat Package Manager (RPM) based system
|
||||
obtains an .rpm file from which the package manager checks the
|
||||
dependencies and installs the software.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
MAC OS X (.dmg file). The typical MAC OS X end user is used to get a .dmg
|
||||
file which will install all the required things for him. The other
|
||||
requirement is to have the X11.app installed.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Solaris. A Solaris user obtains a file from which the package manager
|
||||
(PKG) checks the dependencies and installs the software.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
However, if you want to start developing with Wireshark, the binary
|
||||
distributions won't be too helpful, as you need the source files, of
|
||||
course.
|
||||
</para>
|
||||
<para>
|
||||
For details about how to build these binary distributions yourself,
|
||||
e.g. if you need a distribution for a special audience, see
|
||||
<xref linkend="ChSrcBinary"/>.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="ChIntroReleaseSource">
|
||||
<title>Source code distributions</title>
|
||||
<para>
|
||||
It's still common for UNIX developers to give the end user a source
|
||||
tarball and let the user compile it on their target machine (configure,
|
||||
make, make install). However, for different UNIX (Linux) distributions
|
||||
it's becoming more common to release binary packages (e.g. .deb or .rpm
|
||||
files) these days.
|
||||
</para>
|
||||
<para>
|
||||
You should use the released sources if you want to build Wireshark from
|
||||
source on your platform for productive use. However, if you going to
|
||||
develop changes to the Wireshark sources, it might be better to use the
|
||||
latest SVN sources. For details about the different ways to get the
|
||||
Wireshark source code see <xref linkend="ChSrcObtain"/>.
|
||||
</para>
|
||||
<para>
|
||||
Before building Wireshark from a source distribution, make sure you have
|
||||
all the tools and libraries required to build. The following chapters will
|
||||
describe the required tools and libraries in detail.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id="ChIntroAutomated">
|
||||
<title>Automated Builds (Buildbot)</title>
|
||||
<para>
|
||||
The Wireshark Buildbot automatically rebuilds Wireshark on every
|
||||
change of the source code repository and indicates problematic changes.
|
||||
This frees the developers from repeating (and annoying) work, so time can
|
||||
be spent on more interesting tasks.
|
||||
</para>
|
||||
<section>
|
||||
<title>Advantages</title>
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
Recognizing (cross platform) build problems - early. Compilation problems
|
||||
can be narrowed down to a few commits, making a fix much easier.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
"Health status" overview of the sources. A quick look at: <ulink
|
||||
url="http://buildbot.wireshark.org/trunk/" /> gives a good "feeling" if
|
||||
the sources are currently "well".
|
||||
On the other hand, if all is "red", an update of a personal source tree
|
||||
might better be done later ...
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
"Up to date" binary packages are available.
|
||||
After a change was committed to the repository, a binary package /
|
||||
installer is usually available within a few hours at: <ulink
|
||||
url="http://www.wireshark.org/download/automated/" />.
|
||||
This can be quite helpful, e.g. a bug reporter can easily verify a bugfix
|
||||
by installing a recent build.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Automated regression tests. In particular, the fuzz tests often indicate
|
||||
"real life" problems that are otherwise hard to find.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section>
|
||||
<title>What does the Buildbot do?</title>
|
||||
<para>
|
||||
The Buildbot will do the following (to a different degree on the different
|
||||
platforms):
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
checkout from the source repository
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
build
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
create binary package(s) / installer
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
create source package (and check completeness)
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
run regression tests
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
Each step is represented at the status page by a rectangle, green if it
|
||||
succeeded or red if it failed. Most steps provide a link to the corresponding
|
||||
console logfile, to get additional information.
|
||||
</para>
|
||||
<para>
|
||||
The Buildbot runs on a platform collection that represents the different
|
||||
"platform specialties" quite well:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
Windows XP x86 (Win32, little endian, VS 9)
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Windows XP x86-64 (Win64, little endian, VS 9)
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Ubuntu x86-64 (Linux, little endian, gcc)
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Solaris SPARC (Solaris, big endian, gcc)
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Mac OS-X PPC (BSD, big endian, gcc)
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Mac OS-X x86 (BSD, little endian, gcc)
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
Each platform is represented at the status page by a single column, the
|
||||
most recent entries are at the top.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id="ChIntroHelp">
|
||||
<title>Reporting problems and getting help</title>
|
||||
<para>
|
||||
If you have problems, or need help with Wireshark, there are several
|
||||
places that may be of interest to you (well, beside this guide of
|
||||
course).
|
||||
</para>
|
||||
|
||||
<section id="ChIntroHomepage"><title>Website</title>
|
||||
<para>
|
||||
You will find lot's of useful information on the Wireshark homepage at
|
||||
<ulink url="&WiresharkWebSite;">&WiresharkWebSite;</ulink>.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="ChIntroWiki"><title>Wiki</title>
|
||||
<para>
|
||||
The Wireshark Wiki at <ulink
|
||||
url="&WiresharkWikiSite;">&WiresharkWikiSite;</ulink> provides a wide range
|
||||
of information related to Wireshark and packet capturing in general.
|
||||
You will find a lot of information not part of this developer's guide. For
|
||||
example, there is an explanation how to capture on a switched network,
|
||||
an ongoing effort to build a protocol reference and a lot more.
|
||||
</para>
|
||||
<para>
|
||||
And best of all, if you would like to contribute your knowledge on a
|
||||
specific topic (maybe a network protocol you know well), you can edit the
|
||||
wiki pages by simply using your webbrowser.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="ChIntroFAQ"><title>FAQ</title>
|
||||
<para>
|
||||
The "Frequently Asked Questions" will list often asked questions and
|
||||
the corresponding answers.
|
||||
</para>
|
||||
<para>
|
||||
Before sending any mail to the mailing lists below, be sure to read the
|
||||
FAQ, as it will often answer the question(s) you might have. This will save
|
||||
yourself and others a lot of time (keep in mind that a lot of people are
|
||||
subscribed to the mailing lists).
|
||||
</para>
|
||||
<para>
|
||||
You will find the FAQ inside Wireshark by clicking the menu item
|
||||
Help/Contents and selecting the FAQ page in the upcoming dialog.
|
||||
</para>
|
||||
<para>
|
||||
An online version is available at the Wireshark website:
|
||||
<ulink url="&WiresharkFAQPage;">&WiresharkFAQPage;</ulink>. You might
|
||||
prefer this online version, as it's typically more up to date and the HTML
|
||||
format is easier to use.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="ChIntroOtherSources"><title>Other sources</title>
|
||||
<para>
|
||||
If you don't find the information you need inside this book, there are
|
||||
various other sources of information:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
the file <filename>doc/README.developer</filename> and
|
||||
all the other README.xxx files in the source code - these are various
|
||||
documentation files on different topics
|
||||
</para>
|
||||
<note><title>Read the README!</title>
|
||||
<para>
|
||||
The README.developer is packed full with all kinds of details relevant
|
||||
to the developer of Wireshark source code. It advices you around common
|
||||
pitfalls, shows you basic layout of dissector code, shows details of the
|
||||
API's available to the dissector developer, etc.
|
||||
</para>
|
||||
</note>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
the Wireshark source code
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
tool documentation of the various tools used
|
||||
(e.g. manpages of sed, gcc, ...)
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
the different mailing lists: see <xref linkend="ChIntroMailingLists"/>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
...
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="ChIntroMailingLists"><title>Mailing Lists</title>
|
||||
<para>
|
||||
There are several mailing lists available on specific Wireshark topics:
|
||||
<variablelist>
|
||||
<varlistentry><term><command>wireshark-announce</command></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This mailing list will inform you about new program
|
||||
releases, which usually appear about every 4-8 weeks.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><command>wireshark-users</command></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This list is for users of Wireshark. People post
|
||||
questions about building and using Wireshark, others (hopefully)
|
||||
provide answers.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><command>wireshark-dev</command></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This list is for Wireshark developers. People post questions about
|
||||
the development of Wireshark, others (hopefully) provide answers.
|
||||
If you want to start developing a protocol dissector, join this list.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><command>wireshark-bugs</command></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This list is for Wireshark developers. Every time a change to the bug
|
||||
database occurs, a mail to this mailing list is generated.
|
||||
If you want to be notified about all the changes to the bug
|
||||
database, join this list. Details about the bug database can be
|
||||
found in <xref linkend="ChIntroBugDatabase"/>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><command>wireshark-commits</command></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This list is for Wireshark developers. Every time a change to the SVN
|
||||
repository is checked in, a mail to this mailing list is generated.
|
||||
If you want to be notified about all the changes to the SVN
|
||||
repository, join this list. Details about the SVN repository can be
|
||||
found in <xref linkend="ChSrcGitRepository"/>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
You can subscribe to each of these lists from the Wireshark web site:
|
||||
<ulink url="&WiresharkListsPage;">&WiresharkListsPage;</ulink>.
|
||||
From there, you can choose which mailing list you want to subscribe to
|
||||
by clicking on the Subscribe/Unsubscribe/Options button under the title
|
||||
of the relevant list. The links to the archives are included on that
|
||||
page as well.
|
||||
|
||||
<tip><title>Tip!</title>
|
||||
<para>
|
||||
You can search in the list archives to see if someone previously asked the same
|
||||
question and maybe already got an answer. That way you
|
||||
don't have to wait until someone answers your question.
|
||||
</para>
|
||||
</tip>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="ChIntroBugDatabase"><title>Bug database (Bugzilla)</title>
|
||||
<para>
|
||||
The Wireshark community collects bug reports in a Bugzilla database at
|
||||
<ulink url="&WiresharkBugsSite;">&WiresharkBugsSite;</ulink>.
|
||||
This database is filled with manually filed bug reports, usually after some
|
||||
discussion on wireshark-dev, and automatic bug reports from the buildbot tools.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="ChIntroQA"><title>Q&A Forum</title>
|
||||
<para>
|
||||
The Wireshark Q and A forum at
|
||||
<ulink url="&WiresharkQASite;">&WiresharkQASite;</ulink> offers a resource
|
||||
where questions and answers come together. You have the option to search
|
||||
what questions were asked before and what answers were given by people who
|
||||
knew about the issue. Answers are graded, so you can pick out the best ones
|
||||
easily. If your issue isn't discussed before you can post one yourself.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="ChIntroReportProblems"><title>Reporting Problems</title>
|
||||
<note><title>Note!</title>
|
||||
<para>
|
||||
Before reporting any problems, please make sure you have installed the
|
||||
latest version of Wireshark. Reports on older maintenance releases are
|
||||
usually met with an upgrade request.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
If you report problems, provide as much
|
||||
information as possible. In general, just think about what
|
||||
you would need to find that problem, if someone else sends you such a
|
||||
problem report. Also keep in mind that people compile/run Wireshark on a lot of different
|
||||
platforms.
|
||||
</para>
|
||||
<para>
|
||||
When reporting problems with Wireshark, it is helpful if you supply the
|
||||
following information:
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
The version number of Wireshark and the dependent libraries linked with
|
||||
it, e.g. GTK+, etc. You can obtain this with the command
|
||||
<command>wireshark -v</command>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Information about the platform you run Wireshark on.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
A detailed description of your problem.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
If you get an error/warning message, copy the text of that message (and
|
||||
also a few lines before and after it, if there are some), so others may
|
||||
find the build step where things go wrong.
|
||||
Please don't give something like: "I get a warning when compiling x"
|
||||
as this won't give any direction to look at.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
<note><title>Don't send large files!</title>
|
||||
<para>
|
||||
Do not send large files (>100KB) to the mailing lists, just place a note
|
||||
that further data is available on request. Large files will only annoy a
|
||||
lot of people on the list who are not interested in your specific problem.
|
||||
If required, you will be asked for further data by the persons who really
|
||||
can help you.
|
||||
</para>
|
||||
</note>
|
||||
<note><title>Don't send confidential information!</title>
|
||||
<para>
|
||||
If you send captured data to the mailing lists, or add it to your bug report,
|
||||
be sure it doesn't contain any sensitive or confidential information,
|
||||
such as passwords. Visibility of such files can be limited to certain
|
||||
groups in the Bugzilla database though.
|
||||
</para>
|
||||
</note>
|
||||
</section>
|
||||
|
||||
<section><title>Reporting Crashes on UNIX/Linux platforms</title>
|
||||
<para>
|
||||
When reporting crashes with Wireshark, it is helpful if you supply the
|
||||
traceback information (besides the information mentioned in
|
||||
<xref linkend="ChIntroReportProblems"/>).
|
||||
</para>
|
||||
<para>
|
||||
You can obtain this traceback information with the following commands:
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
$ gdb `whereis wireshark | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
|
||||
backtrace
|
||||
^D
|
||||
$
|
||||
]]>
|
||||
</programlisting>
|
||||
<note>
|
||||
<para>
|
||||
Type the characters in the first line verbatim! Those are
|
||||
back-tics there!
|
||||
</para>
|
||||
</note>
|
||||
<note>
|
||||
<para>
|
||||
backtrace is a <command>gdb</command> command. You should
|
||||
enter it verbatim after the first line shown above, but it will not be
|
||||
echoed. The ^D
|
||||
(Control-D, that is, press the Control key and the D key
|
||||
together) will cause <command>gdb</command> to exit. This will
|
||||
leave you with a file called
|
||||
<filename>bt.txt</filename> in the current directory.
|
||||
Include the file with your bug report.
|
||||
</para>
|
||||
</note>
|
||||
<note>
|
||||
<para>
|
||||
If you do not have <command>gdb</command> available, you
|
||||
will have to check out your operating system's debugger.
|
||||
</para>
|
||||
</note>
|
||||
</para>
|
||||
<para>
|
||||
You should mail the traceback to the
|
||||
<ulink url="mailto:&WiresharkDevMailList;">&WiresharkDevMailList;</ulink>
|
||||
mailing list, or attach it to your bug report.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section><title>Reporting Crashes on Windows platforms</title>
|
||||
<para>
|
||||
The Windows distributions don't contain the symbol files (.pdb), because
|
||||
they are very large. For this reason it's not possible to create
|
||||
a meaningful backtrace file from it. You should report your crash just
|
||||
like other problems, using the mechanism from
|
||||
<xref linkend="ChIntroReportProblems"/>.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
<!-- End of WSDG Chapter Introduction -->
|
Loading…
Reference in New Issue