544 lines
18 KiB
Plaintext
544 lines
18 KiB
Plaintext
++++++++++++++++++++++++++++++++++++++
|
|
<!-- 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 copying/downloading the correct version of vcredist_xYY.exe.
|
|
|
|
====
|
|
|
|
[[ChSetupChocolatey]]
|
|
|
|
==== Optional: 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 Cygwin and
|
|
the Python Package Index.
|
|
|
|
// ...such as:
|
|
// - Active Perl and/or StrawberryPerl
|
|
// - Devbox-UnZip and/or 7zip and/or peazip
|
|
// - Wget
|
|
// - Git (a native win32 (MSYS) version)
|
|
|
|
[[ChSetupMSVC]]
|
|
|
|
==== Install Microsoft C compiler and SDK
|
|
|
|
You need to install, in exactly this order:
|
|
|
|
. C compiler:
|
|
https://go.microsoft.com/fwlink/?LinkId=532606&clcid=0x409[Download]
|
|
and install "Microsoft Visual Studio 2015 Community Edition." This is a small
|
|
download that then downloads all the other required parts (which are quite large).
|
|
|
|
Select the "Custom" install and then uncheck all the optional components other
|
|
than "Common Tools for Visual C++ 2015" (unless you want to use them for purposes
|
|
other than Wireshark).
|
|
|
|
You can use Chocolatey to install Visual Studio, to correctly configure the
|
|
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
|
|
and pass the path the file to the chocolatey install command:
|
|
|
|
----
|
|
PS$>choco install VisualStudio2015Community --timeout 0 -package-parameters "--AdminFile path\to\msvc2015AdminDeployment.xml"
|
|
----
|
|
|
|
You can use other Microsoft C compiler variants, but VS2015 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,
|
|
Visual Studio 2015 Community Edition is the only free (as in beer)
|
|
versions that includes the Visual Studio integrated
|
|
debugger. Visual Studio 2015 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 download the *Qt Online Installer for Windows* from the Qt Project
|
|
https://www.qt.io/download-open-source/["Download Open Source" page] and
|
|
select a component that matches your target system and compiler. For
|
|
example, the ``msvc2015 64-bit'' component is used to build the official
|
|
64-bit packages. You can deselect all the Qt xxxx (e.g. Qt Charts)
|
|
components as they aren't required.
|
|
|
|
Note that installation of separate Qt components are required for 32 bit
|
|
and 64 bit builds, e.g. ``msvc2015 32-bit'' and ``msvc2015 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\5.9.1\msvc2015_64'
|
|
|
|
The Qt maintenance tool ('C:\Qt\MaintenanceTool.exe') can be used to
|
|
upgrade Qt to newer versions.
|
|
|
|
[[ChSetupCygwin]]
|
|
|
|
==== Install Cygwin
|
|
|
|
On 32-bit Windows, http://www.cygwin.com/setup-x86.exe[download the
|
|
32-bit Cygwin installer] and start it. On 64-bit Windows,
|
|
http://www.cygwin.com/setup-x86_64.exe[download the 64-bit Cygwin
|
|
installer] and start it.
|
|
|
|
At the "Select Packages" page, you'll need to select
|
|
some additional packages which are not installed by default.
|
|
Navigate to the required Category/Package row and, if the package
|
|
has a "Skip" item in the "New" column, click on the "Skip" item
|
|
so it shows a version number for:
|
|
|
|
* Devel/bison (or install Win flex-bison - see Chocolatey below)
|
|
|
|
* Devel/flex (or install Win flex-bison - see Chocolatey below)
|
|
|
|
* Devel/git (recommended - see discussion about using Git below)
|
|
|
|
* Interpreters/perl
|
|
|
|
* Utils/patch (only if needed) (may be Devel/patch instead)
|
|
|
|
* Web/wget (not needed if using CMake)
|
|
|
|
* Text/asciidoc
|
|
|
|
* Text/docbook-xml45
|
|
|
|
// Also need: bash/sh, sed
|
|
|
|
You might also have to install
|
|
|
|
* Interpreters/m4
|
|
|
|
if installing Devel/bison doesn't provide a working version of Bison. If
|
|
m4 is missing bison will fail.
|
|
|
|
After clicking the btn:[Next] button several times, the setup
|
|
will then download and install the selected packages (this
|
|
may take a while).
|
|
|
|
Alternatively you can install Cygwin and its packages using Chocolatey:
|
|
|
|
----
|
|
PS$>choco install cygwin
|
|
PS$>choco install cyg-get
|
|
----
|
|
//PS$>choco install sed asciidoc [...] -source cygwin
|
|
|
|
Chocolatey installs Cygwin in 'C:\tools\cygwin' by default.
|
|
|
|
You can directly download packages via `cyg-get`
|
|
|
|
----
|
|
PS$>cyg-get asciidoc patch docbook-xml45 [...]
|
|
----
|
|
|
|
You can use Chocolatey's Win flex-bison packages rather than the Cygwin
|
|
Bison and Flex package:
|
|
|
|
----
|
|
PS$>choco install winflexbison
|
|
----
|
|
|
|
[[ChSetupPython]]
|
|
|
|
==== Install Python
|
|
|
|
Get the Python 3.5 or 2.7 installer from http://python.org/download/[] and
|
|
install Python into the default location ('C:\Python35' or 'C:\Python27').
|
|
|
|
Why is this recommended? Cygwin's '/usr/bin/python' is a Cygwin-specific
|
|
symbolic link which cannot be run from Windows. The native package is faster
|
|
as well.
|
|
|
|
Alternatively you can install Python using Chocolatey:
|
|
|
|
----
|
|
PS$>choco install python3
|
|
----
|
|
|
|
or
|
|
|
|
----
|
|
PS$>choco install python2
|
|
----
|
|
|
|
Chocolatey installs Python in 'C:\tools\python3' and 'C:\tools\python2' by default.
|
|
|
|
[[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, see
|
|
<<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 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 cmake.portable
|
|
----
|
|
|
|
Chocolatey ensures cmake.exe is 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
|
|
2015' folder and choose the Command Prompt appropriate for
|
|
the build you wish to make, e.g. `VS2015 x64 Native Tools Command
|
|
Prompt' for a 64-bit version or `VS2015 x86 Native Tools Command Prompt'
|
|
for a 32-bit version. Depending on your version of Windows the Command
|
|
Prompt list might be directly under `Visual Studio 2015' or you might
|
|
have to dig for it under multiple folders, e.g. `Visual Studio 2015 ->
|
|
Visual Studio Tools -> Windows Desktop Command Prompts'.
|
|
|
|
[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:
|
|
|
|
----
|
|
> 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\5.9.1\msvc2015_64
|
|
> rem Append a custom string to the package version. Optional.
|
|
> set WIRESHARK_VERSION_EXTRA=-YourExtraVersionInfo
|
|
----
|
|
|
|
If your Cygwin installation path is not automatically detected by CMake,
|
|
you can explicitly specify it with the following environment variable:
|
|
|
|
----
|
|
> rem Chocolatey installs Cygwin in an odd location
|
|
> set WIRESHARK_CYGWIN_INSTALL_PATH=C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin
|
|
----
|
|
|
|
If you are using a version of Visual Studio earlier than VS2012 then you must set an additional env var,
|
|
e.g. for VS2010 set the following:
|
|
----
|
|
> set VisualStudioVersion=10.0
|
|
----
|
|
|
|
Setting these variables could be added to a batch file to be run after you open
|
|
the Visual Studio Tools Command Prompt.
|
|
|
|
[TIP]
|
|
====
|
|
Qt 5.9 is a "long term support" branch of Qt5. We recommend using it to
|
|
compile Wireshark on Windows.
|
|
====
|
|
|
|
--
|
|
|
|
. 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\wsbuild32
|
|
> cd C:\Development\wsbuild32
|
|
----
|
|
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 -DENABLE_CHM_GUIDES=on -G "Visual Studio 14 2015" ..\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, the `-G` parameter must have a Win64 suffix,
|
|
e.g. `-G "Visual Studio 14 2015 Win64"`:
|
|
|
|
----
|
|
> cmake -DENABLE_CHM_GUIDES=on -G "Visual Studio 14 2015 Win64" ..\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/wsbuild32
|
|
----
|
|
|
|
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\wsbuild32\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.txt' 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.
|
|
|
|
. NSIS:
|
|
http://nsis.sourceforge.net[Download] and install NSIS
|
|
+
|
|
Note that the 32-bit version of NSIS will work for both 32-bit and
|
|
64-bit versions of Wireshark. NSIS v3 is recommended and may be required
|
|
in the future.
|
|
|
|
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.
|
|
|
|
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').
|
|
|
|
The files can be located in the Visual Studio install directory for non-Express edition builds, or downloaded from Microsoft for Expresss edition builds.
|
|
|
|
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.
|
|
|
|
. 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.
|
|
--
|
|
|
|
. Run
|
|
+
|
|
--
|
|
----
|
|
> C:\Development\wireshark\packaging\nsis\wireshark-win32-{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 x64 version, the installer will be named accordingly.
|
|
--
|