4.7. Documentation Toolchain

Wireshark’s documentation is split across two directories. The doc directory contains man pages written in Perl’s POD (Plain Old Documentation) format. The docbook directory contains the User’s Guide, Developer’s Guide, and the release notes, which are written in Asciidoctor markup.

Our various output formats are generated using the following tools. Intermediate formats are in italics.

Guide HTML
Asciidoctor → DocBook XML → xsltproc + DocBook XSL
Guide PDF
Asciidoctor
Guide HTML Help
Asciidoctor → DocBook XML → xsltproc + DocBook XSL → HHC
Release notes HTML
Asciidoctor
Release notes text
Asciidoctor → HTML → html2text.py

4.7.1. Asciidoctor

Asciidoctor comes in several flavors: a Ruby gem (Asciidoctor), a Java bundle (AsciidoctorJ), and transpiled JavaScript (Asciidoctor.js). Only the Asciidoctor and AsciidoctorJ flavors are supported for building the Wireshark documentation and AsciidoctorJ is recommended.

The guides and release notes were originally written in DocBook (hence the directory name). They were later converted to AsciiDoc and then migrated to Asciidoctor. compat-mode is currently enabled for the guides, but we are steadily migrating to Asciidoctor’s modern (>= 1.5.0) syntax.

PDF output requires Asciidoctor PDF. It is included with AsciidoctorJ but not with Asciidoctor.

4.7.2. Xsltproc And DocBook

The single HTML, chunked HTML, and HTML Help guides are generated using DocBook XSL stylesheets. They in turn require an XSLT processor. We use xsltproc.

4.7.3. HTML Help

HTML Help is used to create the User’s and Developer’s Guide in .chm format. The User’s Guide .chm file is included with the NSIS and WiX installers and is used as Wireshark’s built-in help on Windows.

This compiler is used to generate a .chm file from a bunch of HTML files — in our case to generate the User’s and Developer’s Guide in .chm format.

The compiler is only available as the free (as in beer) "HTML Help Workshop" download. If you want to compile the guides yourself, you need to download and install this. If you don’t install it into the default directory, you may also have a look at the HHC_DIR setting in the file docbook/Makefile.

The files htmlhelp.c and htmlhelp.lib are required to be able to open .chm files from Wireshark and show the online help. Both files are part of the SDK (standalone (P)SDK or MSVC since 2002).

4.7.4. Debugger

Using a good debugger can save you a lot of development time.

The debugger you use must match the C compiler Wireshark was compiled with, otherwise the debugger will simply fail or you will only see a lot of garbage.

4.7.4.1. Visual Studio integrated debugger

You can use the integrated debugger of Visual Studio if your toolchain includes it. Open the solution in your build directory and build and debug as normal with a Visual Studio solution.

To set the correct paths for Visual Studio when running Wireshark under the debugger, add the build output directory to the path before opening Visual Studio from the same command prompt, e.g.

C:\Development\wsbuild32>set PATH="%PATH%;C:\Development\wsbuild32\run\RelwithDebInfo"
C:\Development\wsbuild32>wireshark.sln

for PowerShell use

PS C:\Development\wsbuild32>$env:PATH += ";$(Convert-Path run\RelWithDebInfo)"
PS C:\Development\wsbuild32>wireshark.sln

When Visual Studio has finished loading the solution, set the executable to be run in the debugger, e.g. Executables\Wireshark, by right clicking it in the Solution Explorer window and selecting "Set as StartUp Project". Also set the Solution Configuration (usually RelWithDebInfo) from the droplist on the toolbar.

[Note]Note

Currently Visual Studio regards a command line build as incomplete, so will report that some items need to be built when starting the debugger. These can either be rebuilt or ignored as you wish.

The normal build is an optimised release version so debugging can be a bit difficult as variables are optimised out into registers and the execution order of statements can jump around.

If you require a non-optimised version, then build using a debug configuration.

4.7.4.2. Debugging Tools for Windows

You can also use the Microsoft Debugging Tools for Windows toolkit, which is a standalone GUI debugger. Although it’s not that comfortable compared to debugging with the Visual Studio integrated debugger it can be helpful if you have to debug on a machine where an integrated debugger is not available.

You can get it free of charge from Microsoft in several ways, see the Debugging tools for Windows page.

You can also use Chocolatey to install WinDbg:

PS:\> choco install windbg

To debug Wireshark using WinDbg, open the built copy of Wireshark using the File → Open Executable…​ menu, i.e. C:\Development\wsbuild32\run\RelWithDebInfo\Wireshark.exe. To set a breakpoint open the required source file using the File → Open Source File…​ menu and then click on the required line and press F9. To run the program, press F5.

If you require a non-optimised version, then build using a debug configuration, e.g. msbuild /m /p:Configuration=Debug Wireshark.sln. The build products will be found in C:\Development\wsbuild32\run\Debug\.