forked from osmocom/wireshark
482 lines
20 KiB
XML
482 lines
20 KiB
XML
<!-- WSDG Chapter Setup -->
|
|
<!-- $Id$ -->
|
|
|
|
<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://www.microsoft.com/express/Downloads/#Visual_Studio_2008_Express_Downloads">
|
|
Download</ulink> and install "Microsoft Visual C++
|
|
2008 Express Edition SP1." (This is a very large download.)</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 "Microsoft Platform
|
|
SDK Server 2003 R2"</para>
|
|
</listitem>
|
|
-->
|
|
</orderedlist></para>
|
|
<para>Install MSVC the usual way. Don't forget to install
|
|
<filename>vcvars32.bat</filename> or call it manually before building Wireshark.
|
|
<filename>vcvars32.bat</filename> will set some required environment (e.g. the
|
|
<varname>PATH</varname>) settings.</para>
|
|
<tip>
|
|
<title>You can use other Microsoft C compiler variants!</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>Wireshark development depends on several environment variables,
|
|
particularly <varname>PATH</varname>. You can use a batch script to fill
|
|
these in, for example
|
|
|
|
<programlisting>
|
|
<![CDATA[@echo off
|
|
echo Adding things to the path...
|
|
set PATH=%PATH%;.
|
|
set PATH=%PATH%;c:\cygwin\bin
|
|
|
|
echo Setting up Visual Studio environment...
|
|
call "c:\Program Files\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat"
|
|
|
|
title Command Prompt (VC++ 2008)]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>Why is this recommended? While this is a huge download,
|
|
the 2008 Express Edition is the only free (as in beer)
|
|
version that includes the Visual Studio integrated
|
|
debugger. Visual C++ 2008 is also used to create official
|
|
Wireshark builds, so it will likely have fewer development-related
|
|
problems.</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.6 installer from:
|
|
<ulink url="http://python.org/download/" /> and install Python
|
|
into the default location (C:\Python26).</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:
|
|
<filename>C:\wireshark</filename> 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:
|
|
<filename>C:\wireshark</filename></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
|
|
<filename>C:\wireshark\config.nmake</filename>, especially:</para>
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><varname>VERSION_EXTRA</varname> : Give Wireshark your "private"
|
|
version info, e.g.: -myprotocol123 - to distinguish
|
|
it from an official release!</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><varname>PROGRAM_FILES</varname> : Where your programs reside,
|
|
usually just keep the default: <filename>C:\Program Files</filename>
|
|
<superscript>2</superscript></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><varname>MSVC_VARIANT</varname> : Make sure the variant for
|
|
your compiler is
|
|
uncommented, and that all others are commented out. For example,
|
|
if you're using Visual C++ 2008 Express Edition, find the line
|
|
<programlisting>
|
|
<![CDATA[#MSVC_VARIANT=MSVC2008EE]]>
|
|
</programlisting>
|
|
and remove the comment character (#)
|
|
from the beginning of the line. Then, find the line
|
|
<programlisting>
|
|
<![CDATA[MSVC_VARIANT=MSVC2008]]>
|
|
</programlisting>
|
|
and comment it out, by prefixing a hash (#).
|
|
<superscript>1</superscript></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<superscript>1</superscript>Compiler dependent: This step
|
|
depends on the compiler you are using. For compilers other than
|
|
Visual C++ 2008, 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
|
|
<filename>C:\Programme</filename> - take this also in account where
|
|
<filename>C:\Program Files</filename> appears elsewhere.</para>
|
|
</section>
|
|
<section id="ChSetupPrepareCommandCom">
|
|
<title>Prepare cmd.exe</title>
|
|
<para>Prepare <filename>cmd.exe</filename> - set environment and current dir.
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>start <command>cmd.exe</command></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 <command>C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat</command>
|
|
to set environment variables of Visual C++ 2008 Express Edition.
|
|
<superscript>1,2</superscript></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>cd C:\wireshark</command> 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++ 2008 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
|
|
<filename>C:\Programme</filename> - take this also in account where
|
|
<filename>C:\Program Files</filename> appears elsewhere. Note: 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 <parameter>verify_tools</parameter>
|
|
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:/python26/python.exe: /cygdrive/c/python26/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 <literal>vcvars32/SetEnv</literal> as mentioned in
|
|
<xref linkend="ChSetupPrepareCommandCom" /> (which will "fix"
|
|
your <varname>PATH</varname> 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: <command>/usr/bin/link</command>, the link command of Cygwin
|
|
takes precedence over the MSVC one. To fix this, you can
|
|
change your <varname>PATH</varname> environment setting or simply rename the
|
|
<filename>link.exe</filename> 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 <command>cmd.exe</command> in the meantime,
|
|
prepare <command>cmd.exe</command> again.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>nmake -f Makefile.nmake setup</command> downloads libraries
|
|
using <command>wget</command> 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 proxy comment in
|
|
<xref linkend="ChToolsWget"/>.</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. <filename>config.h</filename>).</para>
|
|
<para>You must distclean your sources before building the
|
|
first time!
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>If you've closed <command>cmd.exe</command> in the meantime,
|
|
prepare <command>cmd.exe</command> again</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>nmake -f Makefile.nmake distclean</command>
|
|
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 <command>cmd.exe</command> in the meantime,
|
|
prepare <command>cmd.exe</command> again</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>nmake -f Makefile.nmake all</command>
|
|
to build Wireshark</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>wait for Wireshark to compile - this may take a
|
|
while!</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>run <command>C:\wireshark\wireshark-gtk2\wireshark.exe</command>
|
|
and check if it starts</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>check Help/About if it shows your "private" program
|
|
version, e.g.: Version &WiresharkCurrentVersion;.x-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 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
|
|
<filename>docbook/README.txt</filename> 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
|
|
<filename>wireshark-win32-&WiresharkCurrentVersion;.x-myprotocol123.exe</filename>,
|
|
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 <varname>MAKENSIS</varname> setting in the file
|
|
<filename>config.nmake</filename> of the Wireshark sources.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>vcredist_x86.exe</filename> :
|
|
<ulink url="http://www.microsoft.com/DOWNLOADS/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2&displaylang=en">
|
|
Download</ulink> the C-Runtime redistributable for Visual
|
|
C++ 2008 Express Edition SP1 (<filename>vcredist_x86.exe</filename>)
|
|
and copy it into <filename>C:\wireshark-win32-libs</filename>
|
|
<superscript>1</superscript>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you've closed <command>cmd.exe</command> in the meantime,
|
|
prepare <command>cmd.exe</command> again</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>nmake -f Makefile.nmake packaging</command>
|
|
build Wireshark installer</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>run
|
|
<command>C:\wireshark\packaging\nsis\wireshark-win32-&WiresharkCurrentVersion;.x-myprotocol123.exe</command>
|
|
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++ 2008 Express Edition SP1 see the table
|
|
at <xref linkend="ChToolsMSChain" />!</para>
|
|
</section>
|
|
</section>
|
|
</chapter>
|