11 All the tools required are usually installed on a UNIX developer machine.
13 If a tool is not already installed on your system, you can usually install it
14 using the package in your distribution: aptitude, yum, Synaptic, etc.
16 If an install package is not available or you have a
17 reason not to use it (maybe because it’s simply too old), you
18 can install that tool from source code. The following sections
19 will provide you with the webpage addresses where you can get
24 === Win32/64: Step-by-Step Guide
26 A quick setup guide for Win32 and Win64 with recommended
31 Unless you know exactly what you are doing, you
32 should strictly follow the recommendations below. They are known to work
33 and if the build breaks, please re-read this guide carefully.
37 . Not using the correct (x86 or x64) version of the Visual Studio command prompt.
39 . Not copying/downloading the correct version of vcredist_xYY.exe.
45 ==== Install Microsoft C compiler and SDK
47 You need to install, in exactly this order:
50 https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=15[Download]
51 and install ``Microsoft Visual Studio 2017 Community Edition.'' This is a small
52 download that then downloads all the other required parts (which are quite large).
54 Check the checkbox for "Desktop development with C++" and then uncheck
55 all the optional components other than the "VC++ 2017" item with the
56 "latest ... tools", the "Windows 10 SDK", and the "Visual C++ tools for
57 CMake" (unless you want to use them for purposes other than Wireshark).
59 You can use Chocolatey to install Visual Studio, to correctly configure the
60 installation, copy the deployment XML file https://code.wireshark.org/review/gitweb?p=wireshark.git;a=blob_plain;f=tools/msvc2015AdminDeployment.xml;hb=HEAD[msvc2015AdminDeployment.xml] from the source code tools directory
61 and pass the path the file to the chocolatey install command:
64 PS$>choco install -y VisualStudio2015Community --timeout 0 -package-parameters "--AdminFile path\to\msvc2015AdminDeployment.xml"
67 You can use other Microsoft C compiler variants, but VS2017 is used to
68 build the development releases and is the preferred option. It’s
69 possible to compile Wireshark with a wide range of Microsoft C compiler
70 variants. For details see <<ChToolsMSChain>>.
72 You may have to do this as Administrator.
74 Compiling with gcc or Clang is not recommended and will
75 certainly not work (at least not without a lot of advanced
76 tweaking). For further details on this topic, see
77 <<ChToolsGNUChain>>. This may change in future as releases
78 of Visual Studio add more cross-platform support.
80 // XXX - mention the compiler and PSDK web installers -
81 // which significantly reduce download size - and find out the
82 // required components
84 Why is this recommended? While this is a huge download,
85 Visual Studio 2017 Community Edition is the only free (as in beer)
86 versions that includes the Visual Studio integrated
87 debugger. Visual Studio 2017 is also used to create official
88 Wireshark builds, so it will likely have fewer development-related
95 The main Wireshark application uses the Qt windowing toolkit. To
96 install Qt, go to the https://www.qt.io/download["Download Qt" page],
97 select "Go open source", download the *Qt Online Installer for Windows*
98 from the Qt Project and select, for the desired Qt version, a component
99 that matches your target system and compiler. For example, the Qt 5.9.5
100 ``msvc2017 64-bit'' component is used to build the official 64-bit
101 packages. You can deselect all the Qt xxxx (e.g. Qt Charts) components
102 as they aren't required.
104 Note that installation of separate Qt components are required for 32 bit
105 and 64 bit builds, e.g. ``msvc2017 32-bit'' and ``msvc2017 64-bit''. The
106 environment variable `QT5_BASE_DIR` should be set as appropriate for your
107 environment and should point to the Qt directory that contains the bin
108 directory, e.g. _C:\Qt\5.9.5\msvc2017_64_
110 The Qt maintenance tool (_C:\Qt\MaintenanceTool.exe_) can be used to
111 upgrade Qt to newer versions.
113 [[ChSetupChocolatey]]
115 ==== Recommended: Install Chocolatey
117 https://chocolatey.org/[Chocolatey] is a native package manager for
118 Windows. There are https://chocolatey.org/packages[packages] for most of
119 the software listed below. Along with traditional Windows packages it
120 supports the Python Package Index and Cygwin.
122 Chocolatey tends to install packages into its own path (%ChocolateyInstall%).
123 In most cases this is OK, but in some instances (Python in particular)
124 this might not be what you want. You can install Chocolatey packages
125 using the command `choco install`.
129 > rem Flex and Bison are required.
130 > choco install -y winflexbison
131 > rem Git, CMake, Perl, Python, etc are also required, but can be installed
132 > rem via their respective installation packages.
133 > choco install -y git cmake
134 > rem Choose one of Strawberry...
135 > choco install -y strawberryperl
136 > rem ...or ActiveState Perl
137 > choco install -y activeperl
138 > rem This will likely install Python in a non-standard location, but
139 > rem should otherwise work.
140 > choco install -y python3
145 ==== Optional: Install Cygwin
147 On 32-bit Windows, http://www.cygwin.com/setup-x86.exe[download the
148 32-bit Cygwin installer] and start it. On 64-bit Windows,
149 http://www.cygwin.com/setup-x86_64.exe[download the 64-bit Cygwin
150 installer] and start it.
153 .Cygwin is no longer required
155 In the past the Wireshark development toolchain depended on Cygwin, but
156 it it no longer required. Although you can often use the Cygwin version
157 of a particular tool for Wireshark development that's not always the
161 At the "Select Packages" page, you'll need to select
162 some additional packages which are not installed by default.
163 Navigate to the required Category/Package row and, if the package
164 has a "Skip" item in the "New" column, click on the "Skip" item
165 so it shows a version number for:
167 * Devel/bison (or install Win flex-bison -- see Chocolatey above)
169 * Devel/flex (or install Win flex-bison -- see Chocolatey above)
171 * Devel/git (recommended, but it's also available via Chocolatey -- see the Git discussion below)
175 * Utils/patch (only if needed) (may be Devel/patch instead)
177 * Text/docbook-xml45 (only needed if you're building the documenation)
179 // Also need: bash/sh, sed
181 You might also have to install
185 if installing Devel/bison doesn't provide a working version of Bison. If
186 m4 is missing bison will fail.
188 After clicking the btn:[Next] button several times, the setup
189 will then download and install the selected packages (this
192 Alternatively you can install Cygwin and its packages using Chocolatey:
195 PS$>choco install -y cygwin
196 PS$>choco install -y cyg-get
198 //PS$>choco install sed [...] -source cygwin
200 Chocolatey installs Cygwin in _C:\tools\cygwin_ by default.
202 You can directly download packages via `cyg-get`
205 PS$>cyg-get docbook-xml45 [...]
212 Get a Python 3.x installer from https://python.org/download/[] and
213 install Python into the default location (_C:\Python37_).
215 Why is this recommended? Cygwin’s _/usr/bin/python_ is a Cygwin-specific
216 symbolic link which cannot be run from Windows. The native package is faster
219 Alternatively you can install Python using Chocolatey:
222 PS$>choco install -y python3
225 Chocolatey installs Python in _C:\Python37_ by default.
231 Please note that the following is not required to build Wireshark but can be
232 quite helpful when working with the sources.
234 Working with the Git source repositories is highly recommended, as described in
235 <<ChSrcObtain>>. It is much easier to update a personal source tree (local repository) with Git
236 rather than downloading a zip file and merging new sources into a personal
237 source tree by hand. It also makes first-time setup easy and enables the
238 Wireshark build process to determine your current source code revision.
240 There are several ways in which Git can be installed. Most packages are
241 available at the URLs below or via https://chocolatey.org/[Chocolatey].
242 Note that many of the GUI interfaces depend on the command line version.
244 If installing the Windows version of git select the
245 _Use Git from the Windows Command Prompt_ (in chocolatey the _/GitOnlyOnPath_
246 option). Do *not* select the _Use Git and optional Unix tools from the Windows Command Prompt_
247 option (in chocolatey the _/GitAndUnixToolsOnPath_ option).
249 ===== The Official Windows Installer
251 The official command-line installer is available at https://git-scm.com/download/win.
255 Git Extensions is a native Windows graphical Git client for
256 Windows. You can download the installer from
257 https://github.com/gitextensions/gitextensions/releases/latest.
261 TortoiseGit is a native Windows graphical Git
262 similar to TortoiseSVN. You can download the installer from
263 https://tortoisegit.org/download/.
265 ===== Command Line client via Chocolatey
267 The command line client can be installed (and updated) using Chocolatey:
269 PS$> choco install -y git
274 A list of other GUI interfaces for Git can be found at
275 https://git-scm.com/downloads/guis
282 Get the CMake installer from https://cmake.org/download/[] and install CMake into
283 the default location. Ensure the directory containing cmake.exe is added to your path.
285 Alternatively you can install CMake using Chocolatey:
288 PS$>choco install -y cmake
291 Chocolatey ensures cmake.exe is on your path.
293 [[ChSetupAsciidoctor]]
295 ==== Install Asciidoctor, Xsltproc, And DocBook
297 http://asciidoctor.org/[Asciidoctor] can be run directly as a Ruby
298 script or via a Java wrapper (AsciidoctorJ). It is used in conjunction
299 with Xsltproc and DocBook to generate the documenation you're reading
300 and the User’s Guide.
302 The easiest way to install them on Windows is via Chocolatey:
305 PS$>choco install -y asciidoctorj xsltproc docbook-bundle
308 Chocolatey ensures that asciidoctorj.exe and xsltproc.exe is on your
309 path and that xsltproc uses the DocBook catalog.
311 ==== Install and Prepare Sources
314 .Make sure everything works
316 It’s a good idea to make sure Wireshark compiles and runs at least once before
317 you start hacking the Wireshark sources for your own project. This example uses
318 Git Extensions but any other Git client should work as well.
323 *Download sources* Download Wireshark sources into
324 _C:\Development\wireshark_ using either the command line or Git Extensions:
326 Using the command line:
330 >git clone https://code.wireshark.org/review/wireshark
333 Using Git extensions:
335 . Open the Git Extensions application. By default Git Extensions
336 will show a validation checklist at startup. If anything needs to
337 be fixed do so now. You can bring up the checklist at any time
338 via menu:Tools[Settings].
340 . In the main screen select _Clone repository_. Fill in the following:
342 Repository to clone: *`https://code.wireshark.org/review/wireshark`*
344 Destination: Your top-level development directory, e.g. _C:\Development_.
346 Subdirectory to create: Anything you’d like. Usually _wireshark_.
351 Make sure your repository path doesn't contain spaces.
354 . Click the btn:[Clone] button. Git Extensions should start cloning the
355 Wireshark repository.
357 [[ChSetupPrepareCommandCom]]
359 ==== Open a Visual Studio Command Prompt
361 From the Start Menu (or Start Screen), navigate to the `Visual Studio
362 2017' folder and choose the Command Prompt appropriate for the build you
363 wish to make, e.g. `x64 Native Tools Command Prompt for VS 2017' for a
364 64-bit version or `x86 Native Tools Command Prompt for VS 2017' for a
365 32-bit version. Depending on your version of Windows the Command Prompt
366 list might be directly under `Visual Studio 2017' or you might have to
367 dig for it under multiple folders, e.g. `Visual Studio 2017 -> Visual
368 Studio Tools -> Windows Desktop Command Prompts'.
371 .Pin the items to the Task Bar
373 Pin the Command Prompt you use to the Task Bar for easy access.
376 All subsequent operations take place in this Command Prompt window.
378 . Set environment variables to control the build.
381 Set the following environment variables, using paths and values suitable for your installation:
384 > rem Let CMake determine the library download directory name under
385 > rem WIRESHARK_BASE_DIR or set it explicitly by using WIRESHARK_LIB_DIR.
386 > rem Set *one* of these.
387 > set WIRESHARK_BASE_DIR=C:\Development
388 > rem set WIRESHARK_LIB_DIR=c:\wireshark-win64-libs
389 > rem Set the Qt installation directory
390 > set QT5_BASE_DIR=C:\Qt\5.9.5\msvc2017_64
391 > rem Append a custom string to the package version. Optional.
392 > set WIRESHARK_VERSION_EXTRA=-YourExtraVersionInfo
395 If your Cygwin installation path is not automatically detected by CMake,
396 you can explicitly specify it with the following environment variable:
399 > rem Chocolatey installs Cygwin in an odd location
400 > set WIRESHARK_CYGWIN_INSTALL_PATH=C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin
403 If you are using a version of Visual Studio earlier than VS2017 then you must set an additional env var,
404 e.g. for VS2019 set the following:
406 > set VisualStudioVersion=10.0
409 Setting these variables could be added to a batch file to be run after you open
410 the Visual Studio Tools Command Prompt.
414 Qt 5.9 is a "long term support" branch of Qt5. We recommend using it to
415 compile Wireshark on Windows.
420 . Create and change to the correct build directory. CMake is best used in an out-of-tree build configuration
421 where the build is done in a separate directory to the source tree, leaving the source tree in a pristine
422 state. 32 and 64 bit builds require a separate build directory. Create (if required) and change to the appropriate
427 > mkdir C:\Development\wsbuild32
428 > cd C:\Development\wsbuild32
430 to create and jump into the build directory.
432 The build directory can be deleted at any time and the build files regenerated as detailed in <<ChWin32Generate>>.
437 ==== Generate the build files
439 CMake is used to process the CMakeLists.txt files in the source tree and produce build files appropriate
442 You can generate Visual Studio solution files to build either from within Visual Studio, or from the command
443 line with MSBuild. CMake can also generate other build types but they aren't supported.
445 The initial generation step is only required the first time a build directory is created. Subsequent
446 builds will regenerate the build files as required.
448 If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again.
450 To generate the build files enter the following at the Visual Studio command prompt:
452 > cmake -G "Visual Studio 15 2017" ..\wireshark
455 Adjusting the paths as required to Python and the wireshark source tree.
456 To use a different generator modify the `-G` parameter. `cmake -G` lists
457 all the CMake supported generators, but only Visual Studio is supported
458 for Wireshark builds.
460 To build an x64 version, the `-G` parameter must have a Win64 suffix,
461 e.g. `-G "Visual Studio 15 2017 Win64"`:
464 > cmake -G "Visual Studio 15 2017 Win64" ..\wireshark
467 The CMake generation process will download the required 3rd party libraries (apart from Qt)
468 as required, then test each library for usability before generating the build files.
470 At the end of the CMake generation process the following should be displayed:
474 -- Build files have been written to: C:/Development/wsbuild32
477 If you get any other output, there is an issue in your envirnment that must be rectified before building.
478 Check the parameters passed to CMake, especially the `-G` option and the path to the Wireshark sources and
479 the environment variables `WIRESHARK_BASE_DIR` and `QT5_BASE_DIR`.
485 Now it’s time to build Wireshark!
487 . If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again.
493 > msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln
498 . Wait for Wireshark to compile. This will take a while, and there will be a lot of text output in the command prompt window
500 . Run _C:\Development\wsbuild32\run\RelWithDebInfo\Wireshark.exe_ and make sure it starts.
502 . Open menu:Help[About]. If it shows your "private" program
503 version, e.g.: Version {wireshark-version}-myprotocol123
504 congratulations! You have compiled your own version of Wireshark!
506 You may also open the Wireshark solution file (_Wireshark.sln_) in the Visual Studio IDE and build there.
508 TIP: If compilation fails for suspicious reasons after you changed some source
509 files try to clean the build files by running `msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln /t:Clean`
510 and then building the solution again.
512 The build files produced by CMake will regenerate themselves if required by changes in the source tree.
514 ==== Debug Environment Setup
516 You can debug using the Visual Studio Debugger or WinDbg. See the section
517 on using the <<ChToolsDebugger, Debugger Tools>>.
519 ==== Optional: Create User’s and Developer’s Guide
521 Detailed information to build these guides can be found in the file
522 _docbook\README.adoc_ in the Wireshark sources.
524 ==== Optional: Create a Wireshark Installer
526 Note: You should have successfully built Wireshark
527 before doing the following.
529 If you want to build your own
530 _Wireshark-win32-{wireshark-version}-myprotocol123.exe_, you'll need
531 NSIS. You can download it from http://nsis.sourceforge.net[].
533 Note that the 32-bit version of NSIS will work for both 32-bit and
534 64-bit versions of Wireshark. NSIS v3 is required.
536 Note: If you do not yet have a copy of vcredist_x86.exe or vcredist_x64.exe in _./wireshark-win**XX**-libs_ (where *_XX_* is 32 or 64) you will need to download the appropriate file and place it in _./wireshark-win**XX**-libs_ before starting this step.
538 If building an x86 version using a Visual Studio “Express” edition or an x64 version with any edition, then you must have the appropriate vcredist file for your compiler in the support libraries directory (_vcredist_x86.exe_ in _wireshark-32-libs_ or _vcredist_x64.exe_ in _wireshark-win64-libs_).
540 The files can be located in the Visual Studio install directory for non-Express edition builds, or downloaded from Microsoft for Expresss edition builds.
542 Note you must use the correct version of vcredist for your compiler, unfortunately they all have the same name (_vcredist_x86.exe_ or _vcredist_x64.exe_). You can use Windows Explorer and examine the `Properties -> Details' tab for a vcredist file to determine which compiler version the file is for use with.
544 If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again.
549 > msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
550 > msbuild /m /p:Configuration=RelWithDebInfo nsis_package.vcxproj
553 to build a Wireshark installer. If you sign your executables you should do
554 so between the “nsis_package_prep” and “nsis_package” steps.
559 > packaging\nsis\wireshark-win64-{wireshark-version}-myprotocol123.exe
562 to test your new installer. It’s a good idea to test on a different
563 machine than the developer machine. Note that if you've built an x86
564 version, the installer name will contain “win32”.