ToolsIntroduction
This chapter will provide you with information how to install
the various tools needed for Wireshark development.
None of the tools mentioned in this chapter is needed to run Ethereal,
they are only needed to build it.
All these tools have
their roots on UNIX like platforms, but Win32 ports are also
available. Therefore the tools are available in different "flavours":
UNIX (or Win32 Cygwin): as described above, the tools should be commonly
available on the supported UNIX platforms, and for Win32 platforms by the
Cygwin UNIX emulation
Win32 native: some tools are available as native Win32 tools, no
emulation is required (however, as the installation can be complicated,
using the Cygwin tools is recommended)
General instructions to install the tools are given in:
and
.
The following sections give a very brief description of
what the particular tool is doing, how it is used in the Wireshark project
and how it can be installed and tested.
Don't expect a lot of documentation regarding these tools in this
document. If you need further documentation of a specific tool, you
should find lot's of useful information on the web, as these tools are
commonly used. As all of the tools are command line tools, you can try
to get help with toolname --help or read
the manpage man toolname.
You will find explanations of the tool usage for some of the specific
development tasks in .
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 will typically use
the installation package from your distribution (by your favourite package
manager: apt, yum, synaptics, ...).
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.
Win32: Installation
The tool installation on Win32 can be quite confusing as there are several
ways to do so.
The following will give you a step-by-step guide to install the
development tools in the recommended way.
Warning!Unless you know exactly what you are doing, you should strictly
follow the recommendations!Recommendations (Cygwin vs. Win32 native)
Cygwin provides a lot of UNIX based tools on the Win32 platform. It uses
a UNIX emulation layer which might be a bit slower compared to the native
Win32 tools, but at an acceptable level.
The installation and update is pretty easy and done through a single
(web based) setup.exe.
The native Win32 tools will typically be a bit faster, but more
complicated to install.
You will have to download the tools from different webpages,
and install them in different ways, tweaking the PATH and alike.
Note!
As there's no Win32 native bash version available, at least a basic
installation of cygwin is required in any case.
For all these reasons, the following recommends to use Cygwin tools where
appropriate.
The recommended toolsToolCygwin (Category/Package)Win32 nativeRemark-cl.exe (MSVC V6)-integrated debugger (MSVC V6)-nmake.exe (MSVC V6)Base/bash-No Win32 native version available!Base/sed-Interpreters/python-Interpreters/perl-Devel/bison-Devel/flex-Web/wget-Archive/unzip--TortoiseSVNOnly needed if you access the Wireshark sources using
the subversion repository (the recommended way).-NSISOnly needed if you want to build your own
wireshark-setup.exe.
Don't get confused by the (optional) marker at some of the items in the
"Tool" column.
Although these tools are not required to build
Ethereal they can make development life much easier and some are even
required by the following installation procedure.
Install Microsoft Visual Studio Version 6
Install MSVC the usual way. Don't forget to install vcvars32.bat or call
it manually before building Ethereal. vcvars32.bat will set some required
environment settings.
Warning!
Using any other MSVC version is not recommended and will certainly not
work (at least without a lot of advanced tweaking).
For further details on this topic, see .
Install Cygwin
Although Cygwin consists of several seperate packages, the installation
and update is done through a single setup.exe, which acts similar to other
web based installers.
All tools will be installed into one base folder, the default is
C:\cygwin.
You will find this network based setup.exe at: . Click on one of the "Install Cygwin now"
appearances to download the setup.exe.
After the download completed, start this setup.exe
on your machine.
The setup will ask you for some settings, the defaults should usually
work well for a first start.
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 click on the "Skip"
item in the "New" column so it shows a version number for:
Archive/unzip
Devel/bison
Devel/flex
Interpreters/perl
Interpreters/python
Utils/patch
Web/wget
After clicking the Next button several times, the setup will then
download and install the selected packages (this may take a while).
Under: "Start -> Programs -> Cygwin -> Cygwin Bash Shell" you
should now be able to start a new Cygwin bash shell, which is similar to
the command line (command.exe/cmd.exe) in Win32, but much more powerful.
Add/Update/Remove Cygwin Packages
If you want to add additional, update installed or remove packages later,
you have to start the setup.exe again.
At the "Select Packages" page, the entry in the "New" column will control
what is done (or not) with the package. If a new version of a package is
available, the new version number will be displayed, so it will be
automatically updated.
You can change the current setting by simply clicking at it, it will
change between:
a specific version number - this different package version will be
installed
Skip - not installed, no changes
Keep - already installed, no changes
Uninstall - uninstall this package
Reinstall - reinstall this package
Install Additional Tools
Depending on your actual task the following tools are recommended.
Please note that they are not required to build Ethereal but can be
quite helpful.
TortoiseSVN
If you want to work with the Wireshark subversion source repositories
(which is highly recommended, see ),
it's recommended to use TortoiseSVN. You can download the setup from
and simply install it.
Nullsoft Scriptable Install System (NSIS)
If you want to build your own wireshark-setup.exe, you'll need NSIS.
You can download the NSIS setup from
and simply install it.
You may check the MAKENSIS setting in the file
config.nmake of the Wireshark sources.
Verify installed tools
After you've installed the Wireshark sources (see ), you can check the correct installation of
all tools by using the verify_tools target of the
Makefile.nmake from the source package.
Warning!
You will need the Wireshark sources and some tools (nmake, bash) installed,
before this verification is able to work.
Enter at the command line (cmd.exe, not Cygwin's bash!):
>nmake -f Makefile.nmake verify_tools
This will check for the various tools needed to build Ethereal:
If you have problems with all the first three ones, check if you called
...\Microsoft Visual Studio\VC98\Bin\vcvars32.bat before
(which will "fix" your PATH settings).
Unfortunately, the link command is defined both from cygwin and from MSVC
with completely different purpose, you'll need the MSVC link.
If your link command looks something like: /usr/bin/link, the link command
of cygwin takes precedence over the MSVC one. To fix this, you can change
your PATH environment setting or simply renaming the link.exe in cygwin.
If you rename it, make sure to remember that a cygwin update may provide
a new version of it.
C compilerUNIX or Win32 Cygwin: GCC (GNU compiler collection)Win32 Note!
Although some effort is currently made to use gcc from the Cygwin
environment, the mainline for several reasons is still using Microsoft
Visual Studio's C compiler.
The GCC C compiler is available for most of the UNIX-like platforms and
as the Devel/gcc package from the Cygwin setup.
If GCC isn't already installed and also not available as a package
for your platform, you can get it at:
.
After correct installation, typing inside the bash:
$gcc --version
should result in something like:
However, the version string may vary.
Win32 native: Microsoft Visual Studio version 6 C compilerNote!
The Microsoft Visual Studio is not free software.
This is a tool you have to buy before you use it!
The mainline for generating Ethereal on the windows platform, is using
the compiler cl.exe from the Microsoft Visual Studio version 6 (and it's
nmake, as described below).
After correct installation, typing inside the command line (cmd.exe):
>cl
should result in something like:
However, the version string may vary.
Win32 native: Microsoft Visual Studio .NET (and alike) C compilers
Warning!
The recent "Microsoft Visual Studio .NET" C compiler(s) currently cannot
be used to compile Ethereal!!!
The following is a problem summary for:
Microsoft Visual Studio .NET
Microsoft Visual C++ .NET
Microsoft Visual C++ Toolkit 2003, freely available at:
All containing version 7 or later of Microsoft's C compiler.
It is reported that this compiler requires to ship a MSVCRT70.dll together
with the compiled exe, which contains the C runtime library. This
conflicts, as all required libraries currently compiled with (and uses)
MSVCRT.dll (the older version 6 one).
Example why this hurts: A dependant library might try to open a file using
functions in MSVCRT.dll which creates an internal file handle and keeps
information about that file. When Ethereal tries to read data from that
file, it uses the functions from MSVCRT70.dll, which doesn't know anything
about that previously opened file and returns an error code.
There where also attempts to bring the compiler to use only the old
MSVCRT.dll but they seemed to fail :-(
It's also still unsure, if shipping the MSVCRT70.dll together with Ethereal
is compatible with the GPL license at all.
Note!
This isn't an Ethereal specific problem. Any software project trying to use
the version 7 C compiler will have the problems described above!
XXX - what about the legal issue, as the MSVCRT70.dll had to be shipped
with Ethereal.
Debugger
Well, using a good debugger can save you a lot of development time. However
some people still think it's use is optional.
The debugger you use must match the C compiler Ethereal was compiled with,
otherwise the debugger will simply fail or you will only see a lot of
garbage.
UNIX or Win32 Cygwin: GDB (GNU project debugger)
GDB is the debugger for the GCC compiler. It is available for many (if
not all) UNIX-like platforms and as the Devel/gdb
package from the Cygwin setup
If you don't like debugging using the command line, there are some GUI
frontends for it available, most notably GNU DDD.
If gdb isn't already installed and also not available as a package for
your platform, you can get it at:
.
After correct installation:
$gdb --version
should result in something like:
However, the version string may vary.
UNIX: DDD (GNU Data Display Debugger)
The GNU Data Display Debugger is a good GUI frontend for GDB (and a lot of
other command line debuggers), so you have to install GDB first. It is
available for many UNIX-like platforms and as the
ddd package from the Cygwin setup.
If GNU DDD isn't already installed and also not available as a package for
your platform, you can get it at:
.
Win32 native: Microsoft Visual Studio debugger
You can use the integrated debugger of Visual Studio.
However, setting up
the environment is a bit tricky, as the Win32 build process is using
makefiles instead of the .dsp/.dsw files usually used.
XXX - add instructions how to do it.
Win32 native: Microsoft Debugging Tools for Windows
You could also use the Microsoft debugging tools, which is a GUI debugger.
As it's not that comfortable compared to debugging in Visual Studio, it
can be helpful if you have to debug on a different machine.
You can get it free of charge at: (as
links to microsoft pages changes from time to time, search for
"Debugging Tools" at their page if this link should be outdated).
makeUNIX or Win32 Cygwin: GNU MakeWin32 Note!
Although some effort is made to use make from the Cygwin environment,
the mainline is still using Microsoft Visual Studio's nmake.
GNU Make is available for most of the UNIX-like platforms and
also as the Devel/make package from the Cygwin setup.
If GNU Make isn't already installed and also not available as a package
for your platform, you can get it at:
.
After correct installation:
$make --version
should result in something like:
However, the version string may vary.
Win32 native: nmake from MSVC
nmake is part of the Microsoft Visual Studio suite, see comment above.
Instead of using the the workspace (.dsw) and projects (.dsp) files,
the traditional nmake makefiles are used. This has one main reason: it
makes it much easier to maintain changes simultaneous with the GCC
toolchain makefile.am files as both file formats are similar. However, as
no Visual Studio workspace/project files are available, this makes it
hard to use the Visual Studio IDE e.g. for using the integrated
debugging feature.
After correct installation, typing inside the command line (cmd.exe):
>nmake
should result in something like:
However, the version string may vary.
Win32 native: nmake from microsoft.comWarning!
It is recommended to use the Microsoft Visual Studio version 6 to compile
Ethereal for Win32, see . Don't follow the
instructions in this section, until you now what you are doing.
NMAKE 1.5 can be downloaded from Microsoft.com if you search for
"KB132084". Unpack the archive by running it, and drop the 3 extracted
files in the MSVC++ Toolkit "bin" directory.
You will also need win32.mak, which you can get from
the MS Win Platform SDK by browsing to
where you select the "Core SDK" and only tick the "Build Environment"
(31MB) option. After a while, this SDK will be installed.
From the start menu, choose "Programs"
-> "Microsoft Platform SDK February 2003"
-> "Open build environment window"
-> (choose your OS Win2K/WinXP/Win2003)
bash
The bash shell is needed to run several shell scripts.
UNIX or Win32 Cygwin: GNU bash
The bash is available for most of the UNIX-like platforms and as the
bash package from the Cygwin setup.
If the bash isn't already installed and also not available as a package
for your platform, you can get it at:
.
After correct installation, typing inside any shell:
$bash --version
should result in something like:
However, the version string may vary.
Win32 native: -
The authors don't know of any working Win32 native bash implementation.
python
Python is an interpreter based programming language. The homepage of
the python project is: .
Python is used to generate some source files.
Python version 2.2 and above should be working fine.
UNIX or Win32 Cygwin: python
Python is available for most of the UNIX-like platforms and as the
python package from the Cygwin setup
If Python isn't already installed and also not available as a package
for your platform, you can get it at:
.
After correct installation, typing inside the bash:
$ python -V
should result in something like:
Python 2.3.3
However, the version string may vary.
Win32 native: python
Have a look at
to download the latest stable release. You can download a setup there,
which will install the python system typically into
C:\python23 or similiar.
perl
Perl is an interpreter based programming language. The homepage of the
perl project is: .
Perl is used to convert various text files into usable source code.
Perl version 5.6 and above should be working fine.
UNIX or Win32 Cygwin: perl
Perl is available for most of the UNIX-like platforms and as the
perl package from the Cygwin setup.
If perl isn't already installed and also not available as a package
for your platform, you can get it at:
.
After correct installation, typing inside the bash:
$perl --version
should result in something like:
However, the version string may vary.
Win32 native: perl
A native Win32 perl package can be obtained from
. The
installation should be straightforward.
After correct installation, typing inside the command line (cmd.exe):
>perl -v
should result in something like:
However, the version string may vary.
sed
Sed it the streaming editor. It makes it easy for example to replace
specially marked texts inside a source code file. The Wireshark build
process uses this to stamp version strings into various places.
UNIX or Win32 Cygwin: sed
Sed is available for most of the UNIX-like platforms and as the
sed package from the Cygwin setup.
If sed isn't already installed and also not available as a package
for your platform, you can get it at:
After correct installation, typing inside the bash:
$sed --version
should result in something like:
However, the version string may vary.
Win32 native: sed
A native Win32 sed package can be obtained from
. The
installation should be straightforward.
yacc (bison)
Bison is a free implementation of yacc.
UNIX or Win32 Cygwin: bison
Bison is available for most of the UNIX-like platforms and as the
bison package from the Cygwin setup.
If GNU Bison isn't already installed and also not available as a package
for your platform, you can get it at:
.
After correct installation, typing inside the bash:
$bison --version
should result in something like:
However, the version string may vary.
Win32 native: bison
A native Win32 yacc/bison package can be obtained from
. The
installation should be straightforward.
lexx (flex)
Flex is a free implementation of lexx.
UNIX or Win32 Cygwin: flex
Flex is available for most of the UNIX-like platforms and as the
flex package from the Cygwin setup.
If GNU flex isn't already installed and also not available as a package
for your platform, you can get it at:
.
After correct installation, typing inside the bash:
$flex --version
should result in something like:
However, the version string may vary.
Win32 native: flex
A native Win32 lexx/flex package can be obtained from
. The
installation should be straightforward.
Subversion (SVN) client (optional)
The Wireshark project uses it's own subversion (or short SVN) server to keep
track of all the changes done to the source code. Details about the usage
of subversion in the Wireshark project can be found in .
If you want to work with the source code and planning to commit your
changes back to the Wireshark community, it is recommended to use a SVN
client to get the latest source files. For detailed information about the
different ways to obtain the Wireshark sources, see
.
Along with the traditional command-line client, several GUI clients are
available for a number of platforms, see
.
You will find more instructions in how to
use the subversion client.
UNIX or Win32 Cygwin: svn (subversion)
SVN is available for most of the UNIX-like platforms and as the
Devel/subversion package from the Cygwin setup
If Subversion isn't already installed and also not available as a package
for your platform, you can get it at:
(together with the server
software).
After correct installation, typing inside the bash:
$svn --version
should result in something like:
However, the version string may vary.
Win32 native: TortoiseSVN
A good subversion client for Win32 can be found at:
. It will nicely integrate
into the Windows Explorer window.
diff (optional)
Diff is used to get a file of all differences between two source
files/trees (sometimes called a patch). The diff tool isn't needed for
building Ethereal, but it's needed if you are going to commit your changes
back to the Wireshark community.
Note!
The recommended way to build patches is using the subversion client,
see for details.
You will find more instructions in how to
use the diff tool.
UNIX or Win32 Cygwin: GNU diff
Diff is available for most of the UNIX-like platforms and as the
diffutils package from the Cygwin setup.
If GNU diff isn't already installed and also not available as a package
for your platform, you can get it at:
.
After correct installation, typing inside the bash:
$diff --version
should result in something like:
However, the version string may vary.
Win32 native: diff
A native Win32 diff package can be obtained from
. The
installation should be straightforward.
The subversion client TortoiseSVN has a build in diff feature, see
. If this can be used to create diff
files in the required format, so other persons can use them, is currently
unknown.
patch (optional)
The patch utility is used to merge a diff file into your own source
tree. This tool is only needed, if you want to apply a patch (diff file)
from someone else (probably from the developer mailing list) to try out
in your own private source tree.
Tip!
Unless you are in the rare case needing to apply a patch to your private
source tree, you won't need the patch tool installed.
You will find more instructions in how
to use the patch tool.
UNIX or Win32 Cygwin: patch
Patch is available for most of the UNIX-like platforms and as the
patch package from the Cygwin setup.
If GNU patch isn't already installed and also not available as a package
for your platform, you can get it at:
.
After correct installation, typing inside the bash:
$patch --version
should result in something like:
However, the version string may vary.
Win32 native: patch
A native Win32 patch package can be obtained from
. The
installation should be straightforward.
The subversion client TortoiseSVN has a build in patch feature, see
. The last time tested (Version 1.1.0),
this feature failed to apply patches known to be ok.
Win32: GNU wget (optional)
GNU wget is used to download files from the internet using the command line.
GNU wget is available for most of the UNIX-like platforms and as the
wget package from the Cygwin setup.
You will only need wget, if you want to use the Win32 automated library
download, see for details.
If GNU wget isn't already installed and also not available as a package
for your platform (well, for Win32 it is available as a Cygwin package),
you can get it at:
.
If wget is trying to download files but fails to do so, your internet
connection might use a HTTP proxy. Some Internet providers using such a
proxy and it is common for company networks today. In this case, you
must set the environment variable
http_proxy before using wget. For example, if you are behind proxy.com
which is listening on port 8080, you have to set it to something like:
set HTTP_PROXY=http://proxy.com:8080/
If you are unsure about the settings, you might ask your system
administrator.
Win32: GNU unzip (optional)
GNU unzip is used to, well, unzip the zip files downloaded using the wget
tool.
GNU wget is available for most of the UNIX-like platforms and as the
unzip package from the Cygwin setup.
You will only need unzip, if you want to use the Win32 automated library
download, see for details.
If GNU unzip isn't already installed and also not available as a package
for your platform (well, for Win32 it is available as a Cygwin package),
you can get it at:
.
Win32: NSIS (optional)
The NSIS (Nullsoft Scriptable Install System) is used to generate a
setup.exe from all the files needed to be installed, including all
required DLL's and such.
To install it, simply download the latest released version (currently: 2.0
final) from
and start the downloaded installer. You will need NSIS version 2 final
or higher.
You will find more instructions in how to
use the NSIS tool.
Obsolete: CVS client
Some time ago, the Wireshark project was using CVS to keep track of all
the source code changes. As now subversion (SVN) is used, a CVS client
is no longer helpful, see for details
about subversion clients.