--- /dev/null
+++++++++++++++++++++++++++++++++++++++
+<!-- 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 -->
+++++++++++++++++++++++++++++++++++++++
+
+++ /dev/null
-<!-- 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 -->
git.samba.org / metze / wireshark / wip.git / commitdiff