forked from osmocom/wireshark
561 lines
19 KiB
Plaintext
561 lines
19 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]]
|
||
|
||
==== 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 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]]
|
||
|
||
==== Optional: 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.
|
||
|
||
Over time the Wireshark development toolchain has been migrating away from Cygwin
|
||
toward native tools and we hope to eliminate it as a requirement someday.
|
||
|
||
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/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 [...] -source cygwin
|
||
|
||
Chocolatey installs Cygwin in _C:\tools\cygwin_ by default.
|
||
|
||
You can directly download packages via `cyg-get`
|
||
|
||
----
|
||
PS$>cyg-get 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.
|
||
|
||
[[ChSetupAsciidoctor]]
|
||
|
||
==== Install Asciidoctor, Xsltproc, And DocBook
|
||
|
||
http://asciidoctor.org/[Asciidoctor] can be run directly as a Ruby
|
||
script or via a Java wrapper (AsciidoctorJ). It is used in conjuntion
|
||
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 asciidoctorj xsltproc docbook-bundle
|
||
----
|
||
|
||
Chocolatey ensures that asciidoctorj.exe and xsltproc.exe is on your
|
||
path and that xsltproc uses the DocBook catalog.
|
||
|
||
==== 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 -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.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.
|
||
|
||
. 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. 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”.
|