2008-02-18 22:39:03 +00:00
<!-- WSDG Chapter Setup -->
<!-- $Id$ -->
2007-01-21 04:48:49 +00:00
<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
2007-06-17 11:18:29 +00:00
distribution (by your favourite package manager: aptitude, yum,
2007-01-21 04:48:49 +00:00
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>
2008-01-20 18:53:38 +00:00
<para > You need to install:
2007-01-21 04:48:49 +00:00
<orderedlist >
<listitem >
2008-01-20 18:53:38 +00:00
<para > C compiler:
2008-10-24 21:00:35 +00:00
<ulink url= "http://www.microsoft.com/express/vc/" >
Download</ulink> and install "Microsoft Visual C++
2008 Express Edition." (This is a very large download.)</para>
2007-01-21 04:48:49 +00:00
</listitem>
2008-10-24 21:00:35 +00:00
<!--
2007-01-21 04:48:49 +00:00
<listitem >
2008-01-20 18:53:38 +00:00
<para > Platform SDK :
2007-01-21 04:48:49 +00:00
<ulink url= "http://www.microsoft.com/downloads/details.aspx?familyid=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en" >
2008-10-23 00:38:34 +00:00
Download</ulink> (420MB) and install "Microsoft Platform
2008-08-17 22:33:53 +00:00
SDK Server 2003 R2"</para>
2007-01-21 04:48:49 +00:00
</listitem>
2008-10-24 21:00:35 +00:00
-->
2007-01-21 04:48:49 +00:00
</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 >
2008-10-24 21:00:35 +00:00
<title > You can use other Microsoft C compiler variants!</title>
2007-08-29 00:15:15 +00:00
<para > It's possible to compile Wireshark with a wide range
2008-10-24 21:00:35 +00:00
of Microsoft C compiler variants. For details see
2007-01-21 04:48:49 +00:00
<xref linkend= "ChToolsMSChain" /> !</para>
</tip>
<warning >
2008-10-24 21:00:35 +00:00
<title > Don't use Cygwin's gcc!</title>
2007-01-21 04:48:49 +00:00
<para > Using cygwin's gcc is not recommended and will
certainly not work (at least without a lot of advanced
2008-01-20 18:53:38 +00:00
tweaking). For further details on this topic, see
2007-01-21 04:48:49 +00:00
<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>
2008-10-24 21:00:35 +00:00
<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)
2007-01-21 04:48:49 +00:00
version that includes the Visual Studio integrated
2008-10-24 21:00:35 +00:00
debugger. Visual C++ 2008 is also used to create official
Wireshark builds, so it will likely have fewer development-related
problems.</para>
2007-01-21 04:48:49 +00:00
</section>
<section id= "ChSetupCygwin" >
<title > Install Cygwin</title>
<para >
<ulink url= "http://www.cygwin.com/setup.exe" >
2007-09-10 17:10:42 +00:00
Download</ulink> the cygwin installer and start it.</para>
2007-01-21 04:48:49 +00:00
<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
2008-01-20 18:53:38 +00:00
number for:
2007-01-21 04:48:49 +00:00
<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>
2008-10-23 00:38:34 +00:00
<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
2007-01-21 04:48:49 +00:00
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
2007-09-10 17:10:42 +00:00
tree is significantly easier to do with Subversion than
2007-01-21 04:48:49 +00:00
downloading a zip file and merging new sources into a
personal source tree "by hand".</para>
<section >
<title > Subversion</title>
2007-09-10 17:10:42 +00:00
<para > If you want to work with the Wireshark Subversion
2008-01-20 18:53:38 +00:00
source repositories (which is highly recommended, see
2007-01-21 04:48:49 +00:00
<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
2008-01-20 18:53:38 +00:00
from
2007-09-10 17:10:42 +00:00
<ulink url= "http://subversion.tigris.org/" /> and simply
2007-01-21 04:48:49 +00:00
install it.</para>
</section>
<section >
<title > TortoiseSVN</title>
2007-09-10 17:10:42 +00:00
<para > If you want to work with the Wireshark Subversion
2008-01-20 18:53:38 +00:00
source repositories (which is highly recommended, see
2007-01-21 04:48:49 +00:00
<xref linkend= "ChSrcObtain" /> ), it's recommended to use
TortoiseSVN for your everyday work. You can download the
2008-01-20 18:53:38 +00:00
setup from
2007-09-10 17:10:42 +00:00
<ulink url= "http://tortoisesvn.tigris.org/" /> and simply
2007-01-21 04:48:49 +00:00
install it.</para>
</section>
</section>
<section >
<title > Install and Prepare Sources</title>
2007-09-10 17:10:42 +00:00
<para >
<tip > <title > Tip</title>
<para > It's a good idea to successfully compile and run
2007-01-21 04:48:49 +00:00
Wireshark at least once before you start hacking the
2007-09-10 17:10:42 +00:00
Wireshark sources for your own project! </para>
2008-01-20 18:53:38 +00:00
</tip>
2007-01-21 04:48:49 +00:00
<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 >
2008-01-20 18:53:38 +00:00
<para > URL of repository: "
2007-01-21 04:48:49 +00:00
<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
2008-01-20 18:53:38 +00:00
restrictive firewall, see
2007-08-29 00:15:15 +00:00
<xref linkend= "ChSrcObtain" /> for alternative
download methods</para>
2007-01-21 04:48:49 +00:00
</listitem>
</orderedlist>
</para>
</listitem>
<listitem >
2007-09-10 17:10:42 +00:00
<para > Edit config.nmake: edit the settings in
2007-01-21 04:48:49 +00:00
C:\wireshark\config.nmake, especially:</para>
<para >
<orderedlist >
<listitem >
2008-10-24 21:00:35 +00:00
<para > VERSION_EXTRA : Give Wireshark your "private"
2007-01-21 04:48:49 +00:00
version info, e.g.: -myprotocol123 - to distinguish
it from an official release!</para>
</listitem>
<listitem >
2008-10-24 21:00:35 +00:00
<para > PROGRAM_FILES : Where your programs reside,
2008-01-20 18:53:38 +00:00
usually just keep the default: C:/Program Files
2007-01-21 04:48:49 +00:00
<superscript > 2</superscript> </para>
</listitem>
<listitem >
2008-10-24 21:00:35 +00:00
<para > MSVC_VARIANT : Make sure the variant for your compiler is uncommented, and that all others are commented out. For example, if you're using Visual C++ 2005 Express Edition, find the line
<programlisting >
<![CDATA[#MSVC_VARIANT=MSVC2005EE]]>
</programlisting>
and remove the comment character (<code > #</code> )
from the beginning of the line. Then, find the line
<programlisting >
<![CDATA[MSVC_VARIANT=MSVC2008]]>
</programlisting>
and comment it out.
2007-01-21 04:48:49 +00:00
<superscript > 1</superscript> </para>
</listitem>
</orderedlist>
</para>
</listitem>
</orderedlist>
<superscript > 1</superscript> Compiler dependent: This step
2008-10-24 21:00:35 +00:00
depends on the compiler you are using. For compilers other than
Visual C++ 2008, see the table at
<xref linkend= "ChToolsMSChain" /> .</para>
2007-01-21 04:48:49 +00:00
<para >
<superscript > 2</superscript> International Windows might use
2008-08-13 16:44:18 +00:00
different values here, e.g. a German version uses
2007-01-21 04:48:49 +00:00
C:/Programme - take this also in account where C:\Program
Files appears elsewhere</para>
</section>
2007-03-30 17:57:04 +00:00
<section id= "ChSetupPrepareCommandCom" >
2007-05-14 15:08:01 +00:00
<title > Prepare cmd.exe</title>
2008-01-20 18:53:38 +00:00
<para > Prepare cmd.exe - set environment and current dir.
2007-01-21 04:48:49 +00:00
<orderedlist >
<listitem >
2007-05-14 15:08:01 +00:00
<para > start cmd.exe</para>
2007-01-21 04:48:49 +00:00
</listitem>
2008-10-24 21:00:35 +00:00
<!--
2007-01-21 04:48:49 +00:00
<listitem >
<para > call "C:\Program Files\Microsoft Platform SDK for
2007-01-25 21:07:29 +00:00
Windows Server 2003 R2\SetEnv.Cmd" to set environment
2008-01-20 18:53:38 +00:00
variables of Platform SDK Server 2003 R2
2007-09-10 17:10:42 +00:00
<superscript > 1,2</superscript> </para>
2007-01-21 04:48:49 +00:00
</listitem>
2008-10-24 21:00:35 +00:00
-->
2007-05-14 15:08:01 +00:00
<listitem >
2008-10-24 21:00:35 +00:00
<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
2007-09-10 17:10:42 +00:00
<superscript > 1,2</superscript> </para>
2007-05-14 15:08:01 +00:00
</listitem>
2007-01-21 04:48:49 +00:00
<listitem >
2008-10-24 21:00:35 +00:00
<para > <command > cd C:\wireshark to jump into the source
directory</command> </para>
2007-01-21 04:48:49 +00:00
</listitem>
</orderedlist>
<superscript > 1</superscript> Compiler dependent: This step
depends on the compiler variant used, for other variants than
2008-10-24 21:00:35 +00:00
the recommended Visual C++ 2008 Express Edition see the table
2008-01-20 18:53:38 +00:00
at
2007-08-29 00:15:15 +00:00
<xref linkend= "ChToolsMSChain" /> !</para>
2007-01-21 04:48:49 +00:00
<para >
<superscript > 2</superscript> International Windows might use
2008-08-13 16:44:18 +00:00
different values here, e.g. a German version uses
2007-01-21 04:48:49 +00:00
C:/Programme - take this also in account where C:\Program
2008-08-13 16:44:18 +00:00
Files appears elsewhere. Note: You need to repeat steps 1 - 4
2007-05-14 15:08:01 +00:00
each time you open a new cmd.exe!</para>
2007-01-21 04:48:49 +00:00
</section>
<section id= "ChToolsWin32Verify" >
<title > Verify installed tools</title>
2008-01-20 18:53:38 +00:00
<para > After you've installed the Wireshark sources (see
2007-01-21 04:48:49 +00:00
<xref linkend= "ChSrcObtain" /> ), you can check the correct
installation of all tools by using the verify_tools target of
2008-01-20 18:53:38 +00:00
the
2007-09-10 17:10:42 +00:00
<filename > Makefile.nmake</filename> from the source
2007-01-21 04:48:49 +00:00
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:
2007-03-30 17:57:04 +00:00
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
2007-01-21 04:48:49 +00:00
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
2008-10-23 00:38:34 +00:00
C:/python26/python.exe: /cygdrive/c/python26/python.exe
2007-01-21 04:48:49 +00:00
sed: /usr/bin/sed
unzip: /usr/bin/unzip
wget: /usr/bin/wget]]>
</programlisting>
</para>
2007-09-10 17:10:42 +00:00
<para > If you have problems with all the first three items (cl, link, nmake),
2008-01-20 18:53:38 +00:00
check if you called vcvars32/SetEnv as mentioned in
2007-09-10 17:10:42 +00:00
<xref linkend= "ChSetupPrepareCommandCom" /> (which will "fix"
2007-08-28 17:50:25 +00:00
your PATH settings). However, the exact text will be slightly
different depending on the MSVC version used.</para>
2007-09-10 17:10:42 +00:00
<para > Unfortunately, the link command is defined both in
cygwin and in MSVC each with completely different functionality;
2007-01-21 04:48:49 +00:00
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
2007-09-10 17:10:42 +00:00
change your PATH environment setting or simply rename the
2007-01-21 04:48:49 +00:00
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 >
2007-08-28 17:50:25 +00:00
<para > If you've closed cmd.exe in the meantime, prepare
cmd.exe again</para>
2007-01-21 04:48:49 +00:00
</listitem>
<listitem >
<para > nmake -f Makefile.nmake setup downloads libraries
using wget and installs them - this may take a while
...</para>
</listitem>
<listitem >
2007-09-10 17:10:42 +00:00
<para > If the download fails you may be behind a
2008-08-27 22:06:13 +00:00
restrictive firewall, see the proxy comment in
<xref linkend= "ChToolsWget" /> .</para>
2007-01-21 04:48:49 +00:00
</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
2008-01-20 18:53:38 +00:00
first time!
2007-01-21 04:48:49 +00:00
<orderedlist >
<listitem >
2007-08-28 17:50:25 +00:00
<para > If you've closed cmd.exe in the meantime, prepare
cmd.exe again</para>
2007-01-21 04:48:49 +00:00
</listitem>
<listitem >
<para > nmake -f Makefile.nmake distclean to cleanup the
Wireshark sources</para>
</listitem>
</orderedlist> </para>
</section>
<section >
<title > Build Wireshark</title>
2008-01-20 18:53:38 +00:00
<para > Now it's time to build Wireshark ...
2007-01-21 04:48:49 +00:00
<orderedlist >
<listitem >
2007-08-28 17:50:25 +00:00
<para > If you've closed cmd.exe in the meantime, prepare
cmd.exe again</para>
2007-01-21 04:48:49 +00:00
</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>
2007-11-07 20:13:40 +00:00
</orderedlist> Tip: If compilation fails for suspicious
2007-01-21 04:48:49 +00:00
reasons after you changed some source files try to distclean
2007-11-07 20:13:40 +00:00
the sources and make "all" again</para>
2007-01-21 04:48:49 +00:00
</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>
2007-08-28 17:38:50 +00:00
<section >
<title > Optional: Create User's and Developer's Guide</title>
2007-08-28 17:50:25 +00:00
<para > Detailed information to build these guides can be found
in the file docbook/README.txt in the Wireshark
sources.</para>
2007-08-28 17:38:50 +00:00
</section>
2007-01-21 04:48:49 +00:00
<section >
2007-03-21 21:15:35 +00:00
<title > Optional: Create a Wireshark Installer</title>
2007-09-10 17:10:42 +00:00
<para > Note: You should have successfully built Wireshark
2007-01-21 04:48:49 +00:00
before doing the following!</para>
<para > If you want to build your own wireshark-setup.exe,
2008-01-20 18:53:38 +00:00
you'll need NSIS.
2007-01-21 04:48:49 +00:00
<orderedlist >
<listitem >
2008-01-20 18:53:38 +00:00
<para > NSIS:
2007-01-21 04:48:49 +00:00
<ulink url= "http://nsis.sourceforge.net" >
2007-09-10 17:10:42 +00:00
Download</ulink> and install NSIS</para>
2008-01-20 18:53:38 +00:00
<para > You may check the MAKENSIS setting in the file
2007-09-10 17:10:42 +00:00
<filename > config.nmake</filename> of the Wireshark
2007-01-21 04:48:49 +00:00
sources.</para>
</listitem>
<listitem >
2008-01-20 18:53:38 +00:00
<para > vcredist_x86.exe :
2007-01-23 08:12:20 +00:00
<ulink url= "http://www.microsoft.com/downloads/details.aspx?FamilyId=32BC1BEE-A3F9-4C13-9C99-220B62A191EE&displaylang=en" >
2007-09-10 17:10:42 +00:00
Download</ulink> the C-Runtime redistributable for Visual
2008-10-24 21:00:35 +00:00
C++ 2008 Express Edition (vcredist_x86.exe) and copy it
2008-01-20 18:53:38 +00:00
into C:\wireshark-win32-libs
2007-08-29 00:15:15 +00:00
<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!
2008-01-20 18:53:38 +00:00
See
2007-08-29 00:15:15 +00:00
<xref linkend= "ChToolsMSChain" /> for details!</para>
</warning> </para>
2007-01-21 04:48:49 +00:00
</listitem>
<listitem >
2007-08-28 17:50:25 +00:00
<para > If you've closed cmd.exe in the meantime, prepare
cmd.exe again</para>
2007-01-21 04:48:49 +00:00
</listitem>
<listitem >
<para > nmake -f Makefile.nmake packaging build Wireshark
installer</para>
</listitem>
<listitem >
<para > run
C:\wireshark\packaging\nsis\wireshark-setup-< version> .exe
2007-08-29 00:15:15 +00:00
and test it - it's a good idea to test also on a
2007-09-10 17:10:42 +00:00
different machine than the developer machine.</para>
2007-01-21 04:48:49 +00:00
</listitem>
</orderedlist>
<superscript > 1</superscript> Compiler dependent: This step
depends on the compiler variant used, for other variants than
2008-10-24 21:00:35 +00:00
the recommended Visual C++ 2008 Express Edition see the table
2008-01-20 18:53:38 +00:00
at
2007-08-29 00:15:15 +00:00
<xref linkend= "ChToolsMSChain" /> !</para>
2007-01-21 04:48:49 +00:00
</section>
</section>
</chapter>