forked from osmocom/wireshark
698 lines
25 KiB
Plaintext
698 lines
25 KiB
Plaintext
// WSDG Chapter Setup
|
||
|
||
[#ChapterSetup]
|
||
|
||
== Quick Setup
|
||
|
||
[#ChSetupUNIX]
|
||
|
||
=== UNIX: Installation and Build Instructions
|
||
|
||
[#ChSetupUNIXBuildEnvironmentSetup]
|
||
|
||
==== Build environment setup
|
||
|
||
The following must be installed in order to build Wireshark:
|
||
|
||
* a C compiler and a C++ compiler;
|
||
* the Flex lexical analyzer;
|
||
* Python 3;
|
||
* CMake;
|
||
* several required libraries.
|
||
|
||
Either make or Ninja can be used to build Wireshark; at least one of
|
||
those must be installed.
|
||
|
||
To build the manual pages, Developer's Guide and User's Guide, Asciidoctor, Xsltproc, and DocBook must be installed.
|
||
|
||
Perl is required to generate some code and run some code analysis checks.
|
||
|
||
Some features of Wireshark require additional libraries to be installed.
|
||
|
||
For Debian, and for Linux distributions based on Debian, such as Ubuntu,
|
||
the script `tools/debian-setup.sh` will install the packages and
|
||
libraries required to build Wireshark. It supports the command-line
|
||
options:
|
||
|
||
* `--install-optional` to install additional tools and to install
|
||
libraries required for all Wireshark features;
|
||
* `--install-deb-deps` to install packages required to build a .deb file
|
||
for Wireshark;
|
||
* `--install-test-deps` to install packages required to run all tests.
|
||
|
||
For RPM-based Linux distributions such as Red Hat, Centos, Fedora, and
|
||
openSUSE, the script `tools/rpm-setup.sh` will install the packages and
|
||
libraries required to build Wireshark. It supports the command-line
|
||
options:
|
||
|
||
* `--install-optional` to install additional tools and to install
|
||
libraries required for all Wireshark features;
|
||
* `--install-rpm-deps` to install packages required to build a .rpm file
|
||
for Wireshark.
|
||
|
||
For Alpine Linux, the script `tools/alpine-setup.sh` will install the
|
||
packages and libraries required to build Wireshark. It supports the
|
||
`--install-optional` command-line option to install additional tools and
|
||
to install libraries required for all Wireshark features.
|
||
|
||
For FreeBSD, NetBSD, OpenBSD, and DragonFly BSD, the script
|
||
`tools/bsd-setup.sh` will install the packages and libraries required to
|
||
build Wireshark. It supports the `--install-optional` command-line
|
||
option to install additional tools and to install libraries required for
|
||
all Wireshark features.
|
||
|
||
For macOS, you must first install Xcode. After installing Xcode, the
|
||
script `tools/macos-setup.sh` will install the rest of the tools and
|
||
libraries required to build Wireshark, as well as the additional tools
|
||
required to build the documentation and the libraries required for all
|
||
Wireshark features. If you're using Homebrew, the script
|
||
`tools/macos-setup-brew.sh` will intall the same tools and libraries
|
||
from Homebrew.
|
||
|
||
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.
|
||
|
||
[#ChSetupUNIXBuild]
|
||
|
||
==== Building
|
||
|
||
The recommended (and fastest) way to build Wireshark is with CMake
|
||
and Ninja. Building with make took nearly 2x time as Ninja in one
|
||
experiment.
|
||
|
||
CMake builds are best done in a separate build directory, such as a
|
||
`build` subdirectory of the top-level source directory. If that
|
||
directory is a subdirectory of the top-level source directory, to
|
||
generate the build files, change to the build directory and enter the
|
||
following command:
|
||
|
||
----
|
||
$ cmake ..
|
||
----
|
||
|
||
to use make as the build tool or
|
||
|
||
----
|
||
$ cmake -G Ninja ..
|
||
----
|
||
|
||
to use Ninja as the build tool. If you create the build tool in the
|
||
same directory that contains the top-level Wireshark source directory,
|
||
to generate the build files, change to the build directory and enter the
|
||
following command:
|
||
|
||
----
|
||
$ cmake ../{source directory}
|
||
----
|
||
|
||
to use make as the build tool or
|
||
|
||
----
|
||
$ cmake -G Ninja ../{source directory}
|
||
----
|
||
|
||
to use Ninja as the build tool. `{source directory}` is the name of the
|
||
top-level Wireshark source directory.
|
||
|
||
If you need to build with a non-standard configuration, you can run
|
||
|
||
[source,sh]
|
||
----
|
||
$ cmake -LH ../{source directory}
|
||
----
|
||
|
||
to see what options you have.
|
||
|
||
You can then run Ninja or make to build Wireshark.
|
||
|
||
----
|
||
$ ninja
|
||
$ # or
|
||
$ make
|
||
----
|
||
|
||
Once you have build Wireshark with `ninja` or `make` above, you should be able to test it
|
||
by entering `run/wireshark`.
|
||
|
||
==== Optional: Install
|
||
|
||
Install Wireshark in its final destination:
|
||
|
||
----
|
||
make install
|
||
----
|
||
|
||
Once you have installed Wireshark with `make install` above, you should be able
|
||
to run it by entering `wireshark`.
|
||
|
||
==== Optional: Create User’s and Developer’s Guide
|
||
|
||
To build the Wireshark User's Guide and the Wireshark Developer's Guide,
|
||
build the `all_guides` target, e.g. `make all_guides` or `ninja
|
||
all_guides`. Detailed information to build these guides can be found in
|
||
the file _docbook/README.adoc_ in the Wireshark sources.
|
||
|
||
==== Optional: Create an installable or source code package
|
||
|
||
You can create packages using the following build targets and commands:
|
||
|
||
Source code tarball::
|
||
Build the `dist` target.
|
||
|
||
deb (Debian) package::
|
||
Create a symlink in the top-level source directory to _packaging/debian_, then run `dpkg-buildpackage`.
|
||
|
||
RPM package::
|
||
Build the `wireshark_rpm` target.
|
||
|
||
https://appimage.org[AppImage] package::
|
||
Build the `wireshark_appimage` target.
|
||
|
||
macOS .dmg package containing an application bundle::
|
||
Build the `wireshark_dmg` or `logray_dmg` targets.
|
||
|
||
Installable packages typically require building Wireshark first.
|
||
|
||
==== Troubleshooting during the build and install on Unix
|
||
|
||
A number of errors can occur during the build and installation process.
|
||
Some hints on solving these are provided here.
|
||
|
||
If the `cmake` stage fails you will need to find out why. You can check the
|
||
file `CMakeOutput.log` and `CMakeError.log` in the build directory to find
|
||
out what failed. The last few lines of this file should help in determining the
|
||
problem.
|
||
|
||
The standard problems are that you do not have a required development package on
|
||
your system or that the development package isn’t new enough. Note that
|
||
installing a library package isn’t enough. You need to install its development
|
||
package as well.
|
||
|
||
If you cannot determine what the problems are, send an email to the
|
||
_wireshark-dev_ mailing list explaining your problem. Include the output from
|
||
`cmake` and anything else you think is relevant such as a trace of the
|
||
`make` stage.
|
||
|
||
|
||
// Retain ChSetupWin32 for backward compatibility
|
||
[#ChSetupWindows]
|
||
=== Windows: Step-by-Step Guide[[ChSetupWin32]]
|
||
|
||
A quick setup guide for Windows development with recommended configurations.
|
||
|
||
[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 (x64 or x86) 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.
|
||
You can install Chocolatey packages using the command `choco install` (or its shorthand, `cinst`), e.g.
|
||
|
||
[source,cmd]
|
||
----
|
||
> rem Flex is required.
|
||
> choco install -y winflexbison3
|
||
> rem Git, CMake, Python, etc are also required, but can be installed
|
||
> rem via their respective installation packages.
|
||
> choco install -y git cmake python3
|
||
----
|
||
|
||
|
||
[#ChSetupMSVC]
|
||
|
||
==== Install Microsoft Visual Studio
|
||
|
||
Download and install https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=16[“Microsoft Visual Studio 2019 Community Edition”].
|
||
If you prefer you can instead download and install https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=17[“Microsoft Visual Studio 2022 Community Edition”].
|
||
These are small utilities that download 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” or “V{cpp} 2022” 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 alternatively use Chocolatey to install Visual Studio, using the Visual Studio Community and Native Desktop workload packages.
|
||
Note that this includes Visual Studio’s CMake component.
|
||
|
||
----
|
||
PS$> choco install -y visualstudio2019community visualstudio2019-workload-nativedesktop
|
||
PS$> # OR
|
||
PS$> choco install -y visualstudio2022community visualstudio2022-workload-nativedesktop
|
||
----
|
||
|
||
// winget has basic VS 2022 and 2019 packages, but no native desktop workload packages.
|
||
// https://github.com/microsoft/winget-pkgs/tree/master/manifests/m/Microsoft/VisualStudio
|
||
|
||
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}.2 “msvc2019 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 64 bit and 32 bit builds, e.g. “msvc2019 64-bit” and “msvc2019 32-bit”.
|
||
The components are forward compatible; you can build Wireshark using Qt’s “msvc2019 64-bit” and Visual {cpp} 2022.
|
||
The environment variable `https://doc.qt.io/qt-5/cmake-get-started.html[CMAKE_PREFIX_PATH]` should be set as appropriate for your environment and should point to the Qt installation directory, e.g. _C:\Qt{backslash}{qt-lts-version}.2\msvc2019_64_
|
||
|
||
Wireshark has experimental support for Qt 6.
|
||
If you would like to build Wireshark with Qt 6 you must install it along with the “Qt5 Compatibility Module” component and and pass `-DUSE_qt6=ON` to cmake.
|
||
You can optionally set the `WIRESHARK_QT6_PREFIX_PATH` environment variable to your Qt 6 installation directory instead of `CMAKE_PREFIX_PATH`.
|
||
|
||
The Qt maintenance tool (_C:\Qt\MaintenanceTool.exe_) can be used to upgrade Qt to newer versions.
|
||
|
||
[#ChSetupPython]
|
||
|
||
==== Install Python
|
||
|
||
Get a Python 3 installer from https://python.org/download/[] and install Python.
|
||
Its installation location varies depending on the options selected in the installer and on the version of Python that you are installing.
|
||
At the time of this writing the latest version of Python is 3.10, and common installation directories are
|
||
_C:\Users{backslash}**username**\AppData\Local\Programs\Python\Python310_, _C:\Program Files\Python310_, and _C:\Python310_.
|
||
|
||
Alternatively you can install Python using Chocolatey:
|
||
|
||
----
|
||
PS$> choco install -y python3
|
||
----
|
||
|
||
// Not sure how to document Chocolatey's installation location other than "could be anywhere, LOL"
|
||
// https://community.chocolatey.org/packages/python3/#discussion
|
||
Chocolatey will likely install Python in one of the locations above, or possibly in _C:\Tools\Python3_.
|
||
|
||
// winget has Python 3 packages.
|
||
// https://github.com/microsoft/winget-pkgs/tree/master/manifests/p/Python/Python/3
|
||
|
||
[#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
|
||
----
|
||
|
||
// winget has git.
|
||
// https://github.com/microsoft/winget-pkgs/tree/master/manifests/g/Git/Git
|
||
|
||
===== Others
|
||
|
||
A list of other GUI interfaces for Git can be found at
|
||
https://git-scm.com/downloads/guis
|
||
|
||
|
||
[#ChSetupCMake]
|
||
|
||
==== Install CMake
|
||
|
||
While CMake is required to build Wireshark, it might have been installed as a component of either Visual Studio or Qt.
|
||
If that’s the case you can skip this step.
|
||
If you do want or need to install CMake, you can get it from https://cmake.org/download/[].
|
||
Installing CMake into the default location is recommended.
|
||
Ensure the directory containing cmake.exe is added to your path.
|
||
|
||
Alternatively you can install it using Chocolatey:
|
||
|
||
----
|
||
PS$> choco install -y cmake
|
||
----
|
||
|
||
// winget has CMake.
|
||
// https://github.com/microsoft/winget-pkgs/tree/master/manifests/k/Kitware/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).
|
||
The JavaScript flavor (Asciidoctor.js) isn’t yet supported.
|
||
It is used in conjunction with Xsltproc and DocBook to generate the documentation you're reading and the User’s Guide.
|
||
|
||
You can install AsciidoctorJ, Xsltproc, and DocBook using Chocolatey.
|
||
AsciidoctorJ requires a Java runtime and there are https://en.wikipedia.org/wiki/List_of_Java_virtual_machines[many to choose from].
|
||
Chocolatey doesn't support alternative package dependencies at the present time, including dependencies on Java.
|
||
As a result, installing the asciidoctorj package won't automatically install a Java runtime -- you must install one separately.
|
||
|
||
----
|
||
PS$> choco install -y <your favorite Java runtime>
|
||
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.
|
||
|
||
// winget has no Asciidoctor, xsltproc, or DocBook packages.
|
||
|
||
==== 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 is on your path.
|
||
|
||
Alternatively you can install Winflexbison using Chocolatey:
|
||
|
||
----
|
||
PS$> choco install -y winflexbison3
|
||
----
|
||
|
||
Chocolatey ensures win_flex.exe is on your path.
|
||
|
||
// winget has no bison package.
|
||
|
||
==== Optional: Install Perl
|
||
|
||
If needed you can 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
|
||
----
|
||
|
||
// winget has StrawberryPerl.
|
||
// https://github.com/microsoft/winget-pkgs/tree/master/manifests/s/StrawberryPerl/StrawberryPerl
|
||
|
||
==== 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.
|
||
====
|
||
|
||
*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://gitlab.com/wireshark/wireshark.git
|
||
----
|
||
|
||
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://gitlab.com/wireshark/wireshark.git`*
|
||
+
|
||
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 CMAKE_PREFIX_PATH=C:\Qt{backslash}{qt-lts-version}.2\msvc2019_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 from the source tree, leaving the source tree in a pristine state.
|
||
64 and 32 bit builds require a separate build directory.
|
||
Create (if required) and change to the appropriate build directory.
|
||
+
|
||
--
|
||
// XXX Our CI builds are in-tree in <src dir>/build.
|
||
----
|
||
> 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 <<ChWindowsGenerate>>.
|
||
--
|
||
|
||
[#ChWindowsGenerate]
|
||
|
||
==== 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 17 2022" -A x64 ..\wireshark
|
||
> : or
|
||
> cmake -G "Visual Studio 16 2019" -A x64 ..\wireshark
|
||
----
|
||
|
||
Adjusting the path to the Wireshark source tree as required.
|
||
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.
|
||
32-bit builds are no longer supported.
|
||
|
||
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 environment 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 `CMAKE_PREFIX_PATH`.
|
||
|
||
[#ChWindowsBuild]
|
||
|
||
==== 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
|
||
|
||
To build the Wireshark User's Guide and the Wireshark Developer's Guide,
|
||
build the `all_guides` target, e.g. `msbuild all_guides.vcxproj`.
|
||
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-win64-{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 64-bit and 32-bit versions of Wireshark.
|
||
NSIS version 3 is required.
|
||
|
||
If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again.
|
||
|
||
Run
|
||
|
||
----
|
||
> msbuild /m /p:Configuration=RelWithDebInfo wireshark_nsis_prep.vcxproj
|
||
> msbuild /m /p:Configuration=RelWithDebInfo wireshark_nsis.vcxproj
|
||
----
|
||
|
||
to build a Wireshark installer.
|
||
If you sign your executables you should do so between the “wireshark_nsis_prep” and “wireshark_nsis” 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.
|