-++++++++++++++++++++++++++++++++++++++
-<!-- WSDG Chapter Introduction -->
-++++++++++++++++++++++++++++++++++++++
+// WSDG Chapter Introduction
[[ChapterIntroduction]]
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],
+link:{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
+Wireshark currently runs on most UNIX-like platforms and various Windows
platforms. It requires Qt, 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 Qt GUI library) which are available for many different platforms,
-it's thus available on a wide variety of 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:[]].
+to mailto:{wireshark-dev-list-email}[].
Binary packages are available for the following platforms along with many
others:
-==== Unix
+==== Unix and Unix-like platforms
-* Apple Mac OS X
+* Apple macOS
* FreeBSD
* Oracle Solaris
-==== Linux
+===== Linux
* Debian GNU/Linux
* Ubuntu
+* Fedora
+
* Gentoo Linux
* IBM S/390 Linux (Red Hat)
==== 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.
+Wireshark supports Windows natively via the
+https://en.wikipedia.org/wiki/Windows_API[Windows API]. Note that in
+this documentation and elsewhere we tend to use the terms
+“Win32”, “Win”, and “Windows” interchangeably to refer to the
+Windows API. Wireshark runs on and can be compiled on the following
+platforms:
-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 10 / Windows Server 2016
* Windows 8.1 / Windows Server 2012 R2
* Windows 7 / Windows Server 2008 R2
-* Windows Vista / Windows Server 2008
-
-* Windows XP / Windows Server 2003
+Development on Windows Vista, Server 2008, and older versions may be possible but
+is not supported.
[[ChIntroDevelopment]]
-=== Development and maintenance of Wireshark
+=== 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.
+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
==== 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 code in _ui/qt_, which is written in {cpp}.
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
==== Open Source Software
Wireshark is an open source software (OSS) project, and is released under
-the gpl-url:[][GNU General Public License] (GPL).
+the link:{gplv2-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
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
+* 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 Wireshark source code and binary packages for some platforms are all
available on the download page of the Wireshark website:
-wireshark-download-page:[].
+{wireshark-download-url}.
[[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.
+The officially released files can be found at {wireshark-download-url}.
+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]]
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.
+* Windows (.exe file). The typical Windows end user is used to getting
+ 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.
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
+* Red Hat (.rpm file). A user of a RPM 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.
+* macOS (.dmg file). The typical macOS end user is used to getting a .dmg file
+ which will install all the required things for him.
* Solaris. A Solaris user obtains a file from which the package manager (PKG)
checks the dependencies and installs the software.
==== 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.
+It's still common for developers for UNIX-like platforms 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
+and UNIX-like systems, such as 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 GIT sources. For details about the different ways to get the
+latest Git 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
be narrowed down to a few commits, making a fix much easier.
* "Health status" overview of the sources. A quick look at:
- https://buildbot.wireshark.org/trunk/[] gives a good "feeling" if the sources
+ https://buildbot.wireshark.org/wireshark-master/[] 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 ...
The Buildbot runs on a platform collection that represents the different
"platform specialties" quite well:
-* Windows 8.1 x86 (Win32, little endian, Visual Studion 2013)
-
-* Windows 7 x86-64 (Win64, little endian, VS 2013)
-
-* Ubuntu x86-64 (Linux, little endian, gcc)
+* Windows 8.1 x86 (Win32, little endian, Visual Studio 2013)
-* Solaris SPARC (Solaris, big endian, gcc)
+* Windows Server 2012 R2 x86-64 (Win64, little endian, Visual Studio 2013)
-* Mac OS-X x86 (BSD, little endian, Clang)
+* Ubuntu x86-64 (Linux, little endian, gcc, Clang)
-* Mac OS-X x86-64 (BSD, little endian, Clang)
+* macOS x86-64 (BSD, little endian, Clang)
and two buildslaves that run static code analysis to help spot coding issues:
==== Website
You will find lots of useful information on the Wireshark homepage at
-wireshark-web-site:[].
+{wireshark-main-url}.
[[ChIntroWiki]]
==== Wiki
-The Wireshark Wiki at wireshark-wiki-site:[] provides a wide range
+The Wireshark Wiki at {wireshark-wiki-url} 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
+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.
+Wiki pages by simply using your webbrowser.
[[ChIntroFAQ]]
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.
+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]]
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
+* 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
+_README.developer_ is packed full with all kinds of details relevant
to the developer of Wireshark source code. Its companion file
-'README.dissector' advises you around common
+_README.dissector_ advises you around common
pitfalls, shows you basic layout of dissector code, shows details of the
APIs available to the dissector developer, etc.
====
* The different mailing lists. See <<ChIntroMailingLists>>
+[[ChIntroQA]]
+
+==== Q&A Site
+
+The Wireshark Q&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.
+
[[ChIntroMailingLists]]
==== Mailing Lists
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 GIT
+wireshark-commits:: This list is for Wireshark developers. Every time a change to the Git
repository is checked in, a mail to this mailing list is generated.
-If you want to be notified about all the changes to the GIT
-repository, join this list. Details about the GIT repository can be
+If you want to be notified about all the changes to the Git
+repository, join this list. Details about the Git 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.
+{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
==== 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.
+{wireshark-bugs-url}. This database is filled with manually filed bug
+reports, usually after some discussion on wireshark-dev, and automatic
+bug reports from the Buildbot tools.
[[ChIntroReportProblems]]
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
+it, e.g. Qt, GLib, etc. You can obtain this with the command
`wireshark -v`.
. Information about the platform you run Wireshark on.
[NOTE]
.Don't send large files
====
-Do not send large files (>100KB) to the mailing lists, just place a note
+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
groups in the Bugzilla database though.
====
-==== Reporting Crashes on UNIX/Linux platforms
+==== Reporting Crashes on UNIX-like platforms
When reporting crashes with Wireshark, it is helpful if you supply the
traceback information (besides the information mentioned in
(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.
+_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.
+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.
+You should mail the traceback to mailto:{wireshark-dev-list-email}[] or attach it
+to your bug report.
==== Reporting Crashes on Windows platforms
// XXX Show how to use the Visual Studio debugger
-++++++++++++++++++++++++++++++++++++++
-<!-- End of WSDG Chapter Introduction -->
-++++++++++++++++++++++++++++++++++++++
+// End of WSDG Chapter Introduction
git.samba.org / metze / wireshark / wip.git / blobdiff