path: root/docbook/wsdg_src/WSDG_chapter_quick_setup.adoc

// WSDG Chapter Setup

[[ChapterSetup]]

== Quick Setup

[[ChSetupUNIX]]

=== UNIX: Installation

All the tools required are usually installed on a UNIX developer machine.

If a tool is not already installed on your system, you can usually install it
using the package in your distribution: aptitude, yum, Synaptic, etc.

If an install package is not available or you have a
reason not to use it (maybe because it’s simply too old), you
can install that tool from source code. The following sections
will provide you with the webpage addresses where you can get
these sources.

[[ChSetupWin32]]

=== Win32/64: Step-by-Step Guide

A quick setup guide for Win32 and Win64 with recommended
configuration.

[WARNING]
====
Unless you know exactly what you are doing, you
should strictly follow the recommendations below. They are known to work
and if the build breaks, please re-read this guide carefully.

Known traps are:

. Not using the correct (x86 or x64) version of the Visual Studio command prompt.

. Not using a supported version of Windows. Please check
  https://support.microsoft.com/en-gb/help/13853/windows-lifecycle-fact-sheet[here]
  that your installed version is supported and updated.

====

[[ChSetupChocolatey]]

==== Recommended: Install Chocolatey

https://chocolatey.org/[Chocolatey] is a native package manager for
Windows. There are https://chocolatey.org/packages[packages] for most of
the software listed below. Along with traditional Windows packages it
supports the Python Package Index.

Chocolatey tends to install packages into its own path (%ChocolateyInstall%),
although packages are free to use their own preferences (Python for example is
installed to `C:\Python37`). You can install Chocolatey packages using the
command `choco install` (or its shorthand, `cinst`), e.g.

[source,cmd]
----
> rem Flex and Bison are required.
> choco install -y winflexbison3
> rem Git, CMake, Perl, Python, etc are also required, but can be installed
> rem via their respective installation packages.
> choco install -y git cmake strawberryperl python3
----


[[ChSetupMSVC]]

==== Install Microsoft Visual Studio

https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=16[Download] and install “Microsoft Visual Studio 2019 Community Edition”.
This is a small utility that downloads all the other required parts (which are quite large).

Check the checkbox for “Desktop development with {cpp}” and then uncheck
all the optional components other than the “V{cpp} 2019” item with the
“latest ... tools”, the “Windows 10 SDK”, and the “Visual {cpp} tools for
CMake” (unless you want to use them for purposes other than Wireshark).

You can use Chocolatey to install Visual Studio, using the Visual Studio
Community and Native Desktop workload packages.

----
PS$> choco install -y visualstudio2019community visualstudio2019-workload-nativedesktop
----

You can use other Microsoft C compiler variants, but VS2019 is used to
build the development releases and is the preferred option. It’s
possible to compile Wireshark with a wide range of Microsoft C compiler
variants. For details see <<ChToolsMSChain>>.

You may have to do this as Administrator.

Compiling with gcc or Clang is not recommended and will
certainly not work (at least not without a lot of advanced
tweaking). For further details on this topic, see
<<ChToolsGNUChain>>. This may change in future as releases
of Visual Studio add more cross-platform support.

// XXX - mention the compiler and PSDK web installers -
// which significantly reduce download size - and find out the
// required components

Why is this recommended?
While this is a huge download, the Community Editions of Visual Studio are free (as in beer) and include the Visual Studio integrated debugger.
Visual Studio 2019 is also used to create official Wireshark builds, so it will likely have fewer development-related problems.

[[ChSetupQt]]

==== Install Qt

The main Wireshark application uses the Qt windowing toolkit. To install
Qt, go to the https://www.qt.io/download[“Download Qt” page], select “Go
open source”, download the *Qt Online Installer for Windows* from the Qt
Project and select, for the desired Qt version, a component that matches
your target system and compiler. For example, at the time of this
writing the Qt {qt-lts-version}.1 “msvc2017 64-bit” component is used to
build the official 64-bit packages. The “Qt Debug Information Files”
component contains PDB files which can be used for debugging. You can
deselect all of the other the components such as “Qt Charts” or “Android
xxxx” as they aren’t required.

Note that installation of separate Qt components are required for 32 bit
and 64 bit builds, e.g. “msvc2017 32-bit” and “msvc2017 64-bit”. The
environment variable `QT5_BASE_DIR` should be set as appropriate for your
environment and should point to the Qt directory that contains the bin
directory, e.g. _C:\Qt{backslash}{qt-lts-version}.5\msvc2017_64_

The Qt maintenance tool (_C:\Qt\MaintenanceTool.exe_) can be used to
upgrade Qt to newer versions.

[[ChSetupPython]]

==== Install Python

Get a Python 3.x installer from https://python.org/download/[] and
install Python into the default location (_C:\Python37_).

Alternatively you can install Python using Chocolatey:

----
PS$> choco install -y python3
----

Chocolatey installs Python in _C:\Python37_ by default.

==== Install Perl

Get a Perl installer from http://strawberryperl.com/ or
https://www.activestate.com/ and install Perl into the default location.

Alternatively you can install Perl using Chocolatey:

----
PS$> choco install -y strawberryperl
# ...or...
PS$> choco install -y activeperl
----

[[ChSetupGit]]

==== Install Git

Please note that the following is not required to build Wireshark but can be
quite helpful when working with the sources.

Working with the Git source repositories is highly recommended, as described in
<<ChSrcObtain>>. It is much easier to update a personal source tree (local repository) with Git
rather than downloading a zip file and merging new sources into a personal
source tree by hand. It also makes first-time setup easy and enables the
Wireshark build process to determine your current source code revision.

There are several ways in which Git can be installed. Most packages are
available at the URLs below or via https://chocolatey.org/[Chocolatey].
Note that many of the GUI interfaces depend on the command line version.

If installing the Windows version of git select the
_Use Git from the Windows Command Prompt_ (in chocolatey the _/GitOnlyOnPath_
option).  Do *not* select the _Use Git and optional Unix tools from the Windows Command Prompt_
option (in chocolatey the _/GitAndUnixToolsOnPath_ option).

===== The Official Windows Installer

The official command-line installer is available at https://git-scm.com/download/win.

===== Git Extensions

Git Extensions is a native Windows graphical Git client for
Windows.  You can download the installer from
https://github.com/gitextensions/gitextensions/releases/latest.

===== TortoiseGit

TortoiseGit is a native Windows graphical Git
similar to TortoiseSVN. You can download the installer from
https://tortoisegit.org/download/.

===== Command Line client via Chocolatey

The command line client can be installed (and updated) using Chocolatey:
----
PS$> choco install -y git
----

===== Others

A list of other GUI interfaces for Git can be found at
https://git-scm.com/downloads/guis


[[ChSetupCMake]]

==== Install CMake

Get the CMake installer from https://cmake.org/download/[] and install CMake into
the default location.  Ensure the directory containing cmake.exe is added to your path.

Alternatively you can install CMake using Chocolatey:

----
PS$> choco install -y cmake
----

Chocolatey ensures cmake.exe is on your path.

[[ChSetupAsciidoctor]]

==== Install Asciidoctor, Xsltproc, And DocBook

https://asciidoctor.org/[Asciidoctor] can be run directly as a Ruby
script or via a Java wrapper (AsciidoctorJ). It is used in conjunction
with Xsltproc and DocBook to generate the documenation you're reading
and the User’s Guide.

The easiest way to install them on Windows is via Chocolatey:

----
PS$> choco install -y asciidoctorj xsltproc docbook-bundle
----

Chocolatey ensures that asciidoctorj.exe and xsltproc.exe is on your
path and that xsltproc uses the DocBook catalog.

==== Install winflexbison

Get the winFlexBison installer from https://sourceforge.net/projects/winflexbison/
and install into the default location. Ensure the directory containing win_flex.exe
and win_bison.exe is on your path.

Alternatively you can install Winflexbison using Chocolatey:

----
PS$> choco install -y winflexbison3
----

Chocolatey ensures win_flex.exe and win_bison.exe are on your path.

==== Install and Prepare Sources

[TIP]
.Make sure everything works
====
It’s a good idea to make sure Wireshark compiles and runs at least once before
you start hacking the Wireshark sources for your own project. This example uses
Git Extensions but any other Git client should work as well.
====

// XXX -

*Download sources* Download Wireshark sources into
_C:\Development\wireshark_ using either the command line or Git Extensions:

Using the command line:

----
>cd C:\Development
>git clone https://code.wireshark.org/review/wireshark
----

Using Git extensions:

. Open the Git Extensions application. By default Git Extensions
   will show a validation checklist at startup. If anything needs to
   be fixed do so now. You can bring up the checklist at any time
   via menu:Tools[Settings].

. In the main screen select _Clone repository_. Fill in the following:
+
Repository to clone: *`https://code.wireshark.org/review/wireshark`*
+
Destination: Your top-level development directory, e.g. _C:\Development_.
+
Subdirectory to create: Anything you’d like. Usually _wireshark_.
+
[TIP]
.Check your paths
====
Make sure your repository path doesn't contain spaces.
====

. Click the btn:[Clone] button. Git Extensions should start cloning the
  Wireshark repository.

[[ChSetupPrepareCommandCom]]

==== Open a Visual Studio Command Prompt

From the Start Menu (or Start Screen), navigate to the “Visual Studio 2019” folder and choose the https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#developer_command_prompt_shortcuts[Command Prompt] appropriate for the build you wish to make, e.g. “x64 Native Tools Command Prompt for VS 2019” for a 64-bit version or “x86 Native Tools Command Prompt for VS 2019” for a 32-bit version.
Depending on your version of Windows the Command Prompt list might be directly under “Visual Studio 2019” or you might have to dig for it under multiple folders, e.g. menu:Visual Studio 2019[Visual Studio Tools,Windows Desktop Command Prompts].

You can set up a build environment in your own command prompt by running the appropriate `vcvars__ARCHITECTURE__.bat` command.
See https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#use-the-developer-tools-in-an-existing-command-window[Use the Microsoft C++ toolset from the command line] for details.

[TIP]
.Pin the items to the Task Bar
====
Pin the Command Prompt you use to the Task Bar for easy access.
====

All subsequent operations take place in this Command Prompt window.

. Set environment variables to control the build.
+
--
Set the following environment variables, using paths and values suitable for your installation:

[subs="attributes+"]
----
> rem Let CMake determine the library download directory name under
> rem WIRESHARK_BASE_DIR or set it explicitly by using WIRESHARK_LIB_DIR.
> rem Set *one* of these.
> set WIRESHARK_BASE_DIR=C:\Development
> rem set WIRESHARK_LIB_DIR=c:\wireshark-win64-libs
> rem Set the Qt installation directory
> set QT5_BASE_DIR=C:\Qt{backslash}{qt-lts-version}.5\msvc2017_64
> rem Append a custom string to the package version. Optional.
> set WIRESHARK_VERSION_EXTRA=-YourExtraVersionInfo
----

Setting these variables could be added to a batch file to be run after you open
the Visual Studio Tools Command Prompt.

[TIP]
.Use Qt’s LTS branch
====
We recommend using the most recent “long term support” branch of Qt5 to
compile Wireshark on Windows. At the time of writing this is Qt
{qt-lts-version}.
====

--

. Create and change to the correct build directory.  CMake is best used in an out-of-tree build configuration
where the build is done in a separate directory to the source tree, leaving the source tree in a pristine
state.  32 and 64 bit builds require a separate build directory.  Create (if required) and change to the appropriate
build directory.
+
--
----
> mkdir C:\Development\wsbuild64
> cd C:\Development\wsbuild64
----
to create and jump into the build directory.

The build directory can be deleted at any time and the build files regenerated as detailed in <<ChWin32Generate>>.
--

[[ChWin32Generate]]

==== Generate the build files

CMake is used to process the CMakeLists.txt files in the source tree and produce build files appropriate
for your system.

You can generate Visual Studio solution files to build either from within Visual Studio, or from the command
line with MSBuild.  CMake can also generate other build types but they aren't supported.

The initial generation step is only required the first time a build directory is created.  Subsequent
builds will regenerate the build files as required.

If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again.

To generate the build files enter the following at the Visual Studio command prompt:
----
> cmake -G "Visual Studio 16 2019" -A Win32 ..\wireshark
----

Adjusting the paths as required to Python and the Wireshark source tree.
To use a different generator modify the `-G` parameter. `cmake -G` lists
all the CMake supported generators, but only Visual Studio is supported
for Wireshark builds.

To build an x64 version, specify it as the architecture,
e.g. `-G "Visual Studio 16 2019" -A x64`:

----
> cmake -G "Visual Studio 16 2019" -A x64 ..\wireshark
----

The CMake generation process will download the required 3rd party libraries (apart from Qt)
as required, then test each library for usability before generating the build files.

At the end of the CMake generation process the following should be displayed:
----
-- Configuring done
-- Generating done
-- Build files have been written to: C:/Development/wsbuild64
----

If you get any other output, there is an issue in your envirnment that must be rectified before building.
Check the parameters passed to CMake, especially the `-G` option and the path to the Wireshark sources and
the environment variables `WIRESHARK_BASE_DIR` and `QT5_BASE_DIR`.

[[ChWin32Build]]

==== Build Wireshark

Now it’s time to build Wireshark!

. If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again.

. Run
+
--
----
> msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln
----
to build Wireshark.
--

. Wait for Wireshark to compile. This will take a while, and there will be a lot of text output in the command prompt window

. Run _C:\Development\wsbuild64\run\RelWithDebInfo\Wireshark.exe_ and make sure it starts.

. Open menu:Help[About]. If it shows your "private" program
version, e.g.: Version {wireshark-version}-myprotocol123
congratulations! You have compiled your own version of Wireshark!

You may also open the Wireshark solution file (_Wireshark.sln_) in the Visual Studio IDE and build there.

TIP: If compilation fails for suspicious reasons after you changed some source
files try to clean the build files by running `msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln /t:Clean`
and then building the solution again.

The build files produced by CMake will regenerate themselves if required by changes in the source tree.

==== Debug Environment Setup

You can debug using the Visual Studio Debugger or WinDbg.  See the section
on using the <<ChToolsDebugger, Debugger Tools>>.

==== Optional: Create User’s and Developer’s Guide

Detailed information to build these guides can be found in the file
_docbook\README.adoc_ in the Wireshark sources.

==== Optional: Create a Wireshark Installer

Note: You should have successfully built Wireshark
before doing the following.

If you want to build your own
_Wireshark-win32-{wireshark-version}-myprotocol123.exe_, you'll need
NSIS. You can download it from http://nsis.sourceforge.net[].

Note that the 32-bit version of NSIS will work for both 32-bit and
64-bit versions of Wireshark. NSIS v3 is required.

If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again.

Run

----
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package.vcxproj
----

to build a Wireshark installer. If you sign your executables you should do
so between the “nsis_package_prep” and “nsis_package” steps.

Run

----
> packaging\nsis\wireshark-win64-{wireshark-version}-myprotocol123.exe
----

to test your new installer. It’s a good idea to test on a different
machine than the developer machine. Note that if you've built an x86
version, the installer name will contain “win32”.