forked from osmocom/wireshark
466 lines
18 KiB
XML
466 lines
18 KiB
XML
<?xml version='1.0' encoding='utf-8'?>
|
|
<chapter id="ChapterSetup">
|
|
<title>Quick Setup</title>
|
|
<section id="ChSetupUNIX">
|
|
<title>UNIX: Installation</title>
|
|
<para>All the tools required are usually installed on a UNIX
|
|
developer machine.</para>
|
|
<para>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: aptitude, yum,
|
|
synaptics, ...).</para>
|
|
<para>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.</para>
|
|
</section>
|
|
<section id="ChSetupWin32">
|
|
<title>Win32: Step-by-Step Guide</title>
|
|
<para>A quick setup guide for Win32 with recommended
|
|
configuration.</para>
|
|
<warning>
|
|
<title>Warning!</title>
|
|
<para>
|
|
<command>Unless you know exactly what you are doing, you
|
|
should strictly follow the recommendations!</command>
|
|
</para>
|
|
</warning>
|
|
<section id="ChSetupMSVC">
|
|
<title>Install Microsoft C compiler and Platform SDK</title>
|
|
<para>You need to install:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>C compiler:
|
|
<ulink url="http://msdn.microsoft.com/vstudio/express/visualc/download/">
|
|
Download</ulink>(474MB) and install "Visual C++ 2005
|
|
Express Edition"</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Platform SDK :
|
|
<ulink url="http://www.microsoft.com/downloads/details.aspx?familyid=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en">
|
|
Download</ulink>(420MB) and install Platform SDK Server
|
|
2003 R2</para>
|
|
</listitem>
|
|
</orderedlist></para>
|
|
<para>Install MSVC the usual way. Don't forget to install
|
|
vcvars32.bat or call it manually before building Wireshark.
|
|
vcvars32.bat will set some required environment (e.g. the
|
|
PATH) settings.</para>
|
|
<tip>
|
|
<title>Other Microsoft C compiler variants
|
|
possible!</title>
|
|
<para>It's possible to compile Wireshark with a wide range
|
|
of Microsoft C compiler variants, for details see
|
|
<xref linkend="ChToolsMSChain" />!</para>
|
|
</tip>
|
|
<warning>
|
|
<title>Don't use cygwin's gcc!</title>
|
|
<para>Using cygwin's gcc is not recommended and will
|
|
certainly not work (at least without a lot of advanced
|
|
tweaking). For further details on this topic, see
|
|
<xref linkend="ChToolsGNUChain" />.</para>
|
|
</warning>
|
|
<para>XXX - mention the compiler and PSDK web installers -
|
|
which significantly reduce download size - and find out the
|
|
required components</para>
|
|
<para>XXX - how to get the right PATH settings?</para>
|
|
<para>Why this is recommended: While this is a huge download,
|
|
the 2005 express edition is the only free (as in beer)
|
|
version that includes the Visual Studio integrated
|
|
debugger.</para>
|
|
</section>
|
|
<section id="ChSetupCygwin">
|
|
<title>Install Cygwin</title>
|
|
<para>
|
|
<ulink url="http://www.cygwin.com/setup.exe">
|
|
Download</ulink> the cygwin installer and start it.</para>
|
|
<para>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:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Archive/unzip</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Devel/bison</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Devel/flex</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Interpreters/perl</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Utils/patch</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Web/wget</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
<para>After clicking the Next button several times, the setup
|
|
will then download and install the selected packages (this
|
|
may take a while).</para>
|
|
<para>Why this is recommended: Cygwin's bash version is
|
|
required, as no native Win32 version is available. As
|
|
additional packages can easily be added, the perl and alike
|
|
packages are also used.</para>
|
|
</section>
|
|
<section id="ChSetupPython">
|
|
<title>Install Python</title>
|
|
<para>Get the python 2.4 installer from:
|
|
<ulink url="http://python.org/download/" /> and install python
|
|
into the default location (currently: C:/Python24).</para>
|
|
<para>Beware: python 2.5 won't work without
|
|
modifications.</para>
|
|
<para>Why this is recommended: Cygwin's python package
|
|
doesn't work on some machines, so the Win32 native package is
|
|
recommended.</para>
|
|
</section>
|
|
<section id="ChSetupsubversion">
|
|
<title>Install Subversion Client</title>
|
|
<para>Please note that the following is not required to build
|
|
Wireshark, but can be quite helpful when working with the
|
|
sources.</para>
|
|
<para>Why this is recommended: updating a personal source
|
|
tree is significantly easier to do with Subversion than
|
|
downloading a zip file and merging new sources into a
|
|
personal source tree "by hand".</para>
|
|
<section>
|
|
<title>Subversion</title>
|
|
<para>If you want to work with the Wireshark Subversion
|
|
source repositories (which is highly recommended, see
|
|
<xref linkend="ChSrcObtain" />), it's recommended to
|
|
install Subversion. This makes the first time setup easy
|
|
and enables the Wireshark build process to determine your
|
|
current source code revision. You can download the setup
|
|
from
|
|
<ulink url="http://subversion.tigris.org/" /> and simply
|
|
install it.</para>
|
|
</section>
|
|
<section>
|
|
<title>TortoiseSVN</title>
|
|
<para>If you want to work with the Wireshark Subversion
|
|
source repositories (which is highly recommended, see
|
|
<xref linkend="ChSrcObtain" />), it's recommended to use
|
|
TortoiseSVN for your everyday work. You can download the
|
|
setup from
|
|
<ulink url="http://tortoisesvn.tigris.org/" /> and simply
|
|
install it.</para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Install and Prepare Sources</title>
|
|
<para>
|
|
<tip> <title>Tip</title>
|
|
<para>It's a good idea to successfully compile and run
|
|
Wireshark at least once before you start hacking the
|
|
Wireshark sources for your own project! </para>
|
|
</tip>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Download sources : Download Wireshark sources into:
|
|
C:\wireshark using TortoiseSVN</para>
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>right click on the C:\ drive in Windows
|
|
Explorer</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>in the upcoming context menu select "SVN
|
|
checkout..." and then set:</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>URL of repository: "
|
|
<literal>
|
|
http://anonsvn.wireshark.org/wireshark/trunk/</literal>"</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Checkout directory:
|
|
"C:\wireshark"</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>TortoiseSVN might ask you to create this
|
|
directory - say yes</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>TortoiseSVN starts downloading the
|
|
sources</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>if the download fails you may be behind a
|
|
restrictive firewall, see
|
|
<xref linkend="ChSrcObtain" />for alternative
|
|
download methods</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Edit config.nmake: edit the settings in
|
|
C:\wireshark\config.nmake, especially:</para>
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>VERSION_EXTRA : give Wireshark your "private"
|
|
version info, e.g.: -myprotocol123 - to distinguish
|
|
it from an official release!</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>PROGRAM_FILES : where your programs reside,
|
|
usually just keep the default: C:/Program Files
|
|
<superscript>2</superscript></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>MSVC_VARIANT : search for the line:
|
|
#MSVC_VARIANT=MSVC2005EE and remove the tailing #
|
|
comment char from this line
|
|
<superscript>1</superscript></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<superscript>1</superscript>Compiler dependent: This step
|
|
depends on the compiler variant used, for other variants than
|
|
the recommended Visual C++ 2005 Express Edition see the table
|
|
at
|
|
<xref linkend="ChToolsMSChain" />!</para>
|
|
<para>
|
|
<superscript>2</superscript>International Windows might use
|
|
different values here, e.g. a german version uses
|
|
C:/Programme - take this also in account where C:\Program
|
|
Files appears elsewhere</para>
|
|
</section>
|
|
<section id="ChSetupPrepareCommandCom">
|
|
<title>Prepare cmd.exe</title>
|
|
<para>Prepare cmd.exe - set environment and current dir.
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>start cmd.exe</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>call "C:\Program Files\Microsoft Platform SDK for
|
|
Windows Server 2003 R2\SetEnv.Cmd" to set environment
|
|
variables of Platform SDK Server 2003 R2
|
|
<superscript>1,2</superscript></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>call "C:\Program Files\Microsoft Visual Studio
|
|
8\VC\bin\vcvars32.bat" to set environment variables of
|
|
Visual C++ 2005 Express Edition
|
|
<superscript>1,2</superscript></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>cd C:\wireshark to jump into the source
|
|
directory</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<superscript>1</superscript>Compiler dependent: This step
|
|
depends on the compiler variant used, for other variants than
|
|
the recommended Visual C++ 2005 Express Edition see the table
|
|
at
|
|
<xref linkend="ChToolsMSChain" />!</para>
|
|
<para>
|
|
<superscript>2</superscript>International Windows might use
|
|
different values here, e.g. a german version uses
|
|
C:/Programme - take this also in account where C:\Program
|
|
Files appears elsewhereNote: You need to repeat steps 1 - 4
|
|
each time you open a new cmd.exe!</para>
|
|
</section>
|
|
<section id="ChToolsWin32Verify">
|
|
<title>Verify installed tools</title>
|
|
<para>After you've installed the Wireshark sources (see
|
|
<xref linkend="ChSrcObtain" />), you can check the correct
|
|
installation of all tools by using the verify_tools target of
|
|
the
|
|
<filename>Makefile.nmake</filename> from the source
|
|
package.</para>
|
|
<warning>
|
|
<title>Warning!</title>
|
|
<para>You will need the Wireshark sources and some tools
|
|
(nmake, bash) installed, before this verification is able
|
|
to work.</para>
|
|
</warning>
|
|
<para>Enter at the command line (cmd.exe, not Cygwin's
|
|
bash!):</para>
|
|
<para>
|
|
<prompt>></prompt>
|
|
<userinput>nmake -f Makefile.nmake verify_tools</userinput>
|
|
</para>
|
|
<para>This will check for the various tools needed to build
|
|
Wireshark:</para>
|
|
<para>
|
|
<programlisting>
|
|
<![CDATA[Checking for required applications:
|
|
cl: /cygdrive/c/Programme/Microsoft Visual Studio 8/VC/BIN/cl
|
|
link: /cygdrive/c/Programme/Microsoft Visual Studio 8/VC/BIN/link
|
|
nmake: /cygdrive/c/Programme/Microsoft Visual Studio 8/VC/BIN/nmake
|
|
bash: /usr/bin/bash
|
|
bison: /usr/bin/bison
|
|
flex: /usr/bin/flex
|
|
env: /usr/bin/env
|
|
grep: /usr/bin/grep
|
|
/usr/bin/find: /usr/bin/find
|
|
perl: /usr/bin/perl
|
|
env: /usr/bin/env
|
|
C:/python24/python.exe: /cygdrive/c/python24/python.exe
|
|
sed: /usr/bin/sed
|
|
unzip: /usr/bin/unzip
|
|
wget: /usr/bin/wget]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>If you have problems with all the first three items (cl, link, nmake),
|
|
check if you called vcvars32/SetEnv as mentioned in
|
|
<xref linkend="ChSetupPrepareCommandCom" /> (which will "fix"
|
|
your PATH settings). However, the exact text will be slightly
|
|
different depending on the MSVC version used.</para>
|
|
<para>Unfortunately, the link command is defined both in
|
|
cygwin and in MSVC each with completely different functionality;
|
|
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 rename the
|
|
link.exe in cygwin. If you rename it, make sure to remember
|
|
that a cygwin update may provide a new version of it.</para>
|
|
</section>
|
|
<section>
|
|
<title>Install Libraries</title>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>If you've closed cmd.exe in the meantime, prepare
|
|
cmd.exe again</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>nmake -f Makefile.nmake setup downloads libraries
|
|
using wget and installs them - this may take a while
|
|
...</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If the download fails you may be behind a
|
|
restrictive firewall, see the wget manual for ways to use
|
|
a proxy</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
<section>
|
|
<title>Distclean Sources</title>
|
|
<para>The released Wireshark sources contain files that are
|
|
prepared for a UNIX build (e.g. config.h).</para>
|
|
<para>You must distclean your sources before building the
|
|
first time!
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>If you've closed cmd.exe in the meantime, prepare
|
|
cmd.exe again</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>nmake -f Makefile.nmake distclean to cleanup the
|
|
Wireshark sources</para>
|
|
</listitem>
|
|
</orderedlist></para>
|
|
</section>
|
|
<section>
|
|
<title>Build Wireshark</title>
|
|
<para>Now it's time to build Wireshark ...
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>If you've closed cmd.exe in the meantime, prepare
|
|
cmd.exe again</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>nmake -f Makefile.nmake all to build
|
|
Wireshark</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>wait for Wireshark to compile - this may take a
|
|
while!</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>run C:\wireshark\wireshark-gtk2\wireshark.exe and
|
|
check if it starts</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>check Help/About if it shows your "private" program
|
|
version, e.g.: Version 0.99.4-myprotocol123 - you might
|
|
run a release version previously installed!</para>
|
|
</listitem>
|
|
</orderedlist>Tip: If compilation fails for suspicious
|
|
reasons after you changed some source files try to distclean
|
|
the sources and make "all" again</para>
|
|
</section>
|
|
<section>
|
|
<title>Debug Environment Setup (XXX)</title>
|
|
<para>XXX - debug needs to be written, e.g. an idea is the
|
|
create a simple MSVC 6 workspace/project(s) to ease Visual
|
|
Studio debugging</para>
|
|
</section>
|
|
<section>
|
|
<title>Optional: Create User's and Developer's Guide</title>
|
|
<para>Detailed information to build these guides can be found
|
|
in the file docbook/README.txt in the Wireshark
|
|
sources.</para>
|
|
</section>
|
|
<section>
|
|
<title>Optional: Create a Wireshark Installer</title>
|
|
<para>Note: You should have successfully built Wireshark
|
|
before doing the following!</para>
|
|
<para>If you want to build your own wireshark-setup.exe,
|
|
you'll need NSIS.
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>NSIS:
|
|
<ulink url="http://nsis.sourceforge.net">
|
|
Download</ulink> and install NSIS</para>
|
|
<para>You may check the MAKENSIS setting in the file
|
|
<filename>config.nmake</filename> of the Wireshark
|
|
sources.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>vcredist_x86.exe :
|
|
<ulink url="http://www.microsoft.com/downloads/details.aspx?FamilyId=32BC1BEE-A3F9-4C13-9C99-220B62A191EE&displaylang=en">
|
|
Download</ulink> the C-Runtime redistributable for Visual
|
|
C++ 2005 Express Edition (vcredist_x86.exe) and copy it
|
|
into C:\wireshark-win32-libs
|
|
<superscript>1</superscript>
|
|
<warning>
|
|
<title>Beware of Visual Studio Service Packs!</title>
|
|
<para>If you have installed the Visual Studio Service
|
|
Pack 1, you need a different vcredist_x86.exe version!
|
|
See
|
|
<xref linkend="ChToolsMSChain" />for details!</para>
|
|
</warning></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you've closed cmd.exe in the meantime, prepare
|
|
cmd.exe again</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>nmake -f Makefile.nmake packaging build Wireshark
|
|
installer</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>run
|
|
C:\wireshark\packaging\nsis\wireshark-setup-<version>.exe
|
|
and test it - it's a good idea to test also on a
|
|
different machine than the developer machine.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<superscript>1</superscript>Compiler dependent: This step
|
|
depends on the compiler variant used, for other variants than
|
|
the recommended Visual C++ 2005 Express Edition see the table
|
|
at
|
|
<xref linkend="ChToolsMSChain" />!</para>
|
|
</section>
|
|
</section>
|
|
</chapter>
|