+++ /dev/null
-<!-- 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/64: Step-by-Step Guide</title>
- <para>A quick setup guide for Win32 and Win64 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 SDK</title>
- <para>You need to install, in exactly this order:
- <orderedlist>
- <listitem>
- <para>C compiler:
- <ulink url="http://www.microsoft.com/visualstudio/eng/downloads#d-2010-express">
- Download</ulink> and install "Microsoft Visual C++
- 2010 Express Edition." (This is a very large download.)</para>
- </listitem>
- <listitem>
- <para>Windows SDK for Windows 7, if you want to build 64-bit
- binaries for Windows 7:
- <ulink url="http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx">
- Download</ulink> and install "Microsoft Windows SDK for
- Windows 7."</para>
- <para>In case the install of the SDK fails go to software management and
- remove the vc++2010 runtime and redist packages (don't worry, they
- will be added back via the service pack later). If installation of
- the SDK still fails, there may be a permission problem. See
- <ulink url="http://ctrlf5.net/?p=184">here</ulink> how to resolve
- that.</para>
- </listitem>
- <listitem>
- <para>C compiler service pack:
- <ulink url="http://www.microsoft.com/en-us/download/details.aspx?id=23691">
- Download</ulink> and install "Microsoft Visual Studio 2010
- Service Pack 1." (This is a very large download.)</para>
- </listitem>
- <listitem>
- <para>Microsoft Visual C++ 2010 Service Pack 1 Compiler Update
- for the Windows SDK 7.1, if you want to build 64-bit
- binaries for Windows 7:
- <ulink url="http://www.microsoft.com/en-us/download/details.aspx?id=4422">
- Download</ulink> and install "Microsoft Visual C++ 2010
- Service Pack 1 Compiler Update for the Windows SDK 7.1."</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>If you will be building 64-bit binaries, those items must be
- installed in that order, as installing the Microsoft Visual Studio
- 2010 Service Pack 1 can, if you've installed the Microsoft Windows
- SDK for Windows 7, remove the 64-bit compilers, as per
- <ulink url="http://support.microsoft.com/?kbid=2519277">the
- Microsoft Knowledge Base article "FIX: Visual C++ compilers are
- removed when you upgrade Visual Studio 2010 Professional or Visual
- Studio 2010 Express to Visual Studio 2010 SP1 if Windows SDK v7.1
- is installed"</ulink>. The release notes for the Microsoft Visual
- C++ 2010 Service Pack 1 Compiler Update for the Windows SDK 7.1
- say that, to ensure that your system has a supported
- configuration, you must install the items in the order specified
- above. If you have Microsoft Update installed, so that the
- Windows update process will update software other than components
- of Windows, and thus will update Visual Studio, you may need to
- disable it until after all of the above are installed, to make
- sure it doesn't install Visual Studio 2010 SP1 out of order.</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>Why is this recommended? While this is a huge download,
- the 2010 Express Edition is the only free (as in beer)
- version that includes the Visual Studio integrated
- debugger. Visual C++ 2010 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, if the package
- has a "Skip" item in the "New" column, click on the "Skip" item
- so it shows a version number for:
- <itemizedlist>
- <listitem>
- <para>Archive/unzip</para>
- </listitem>
- <listitem>
- <para>Base/dos2unix</para>
- </listitem>
- <listitem>
- <para>Devel/bison</para>
- </listitem>
- <listitem>
- <para>Devel/flex</para>
- </listitem>
- <listitem>
- <para>Devel/subversion (optional - see discussion about using Subversion below)</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.7 installer from:
- <ulink url="http://python.org/download/" /> and install Python
- into the default location (C:\Python27).</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>Working with the Subversion source repositories is highly
- recommended, see <xref linkend="ChSrcObtain" />. It is much easier
- to update a personal source tree with Subversion 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.</para>
- <para>There are several ways in which Subversion can be
- installed:</para>
- <section>
- <title>Subversion from Cygwin</title>
- <para>Cygwin comes with a command-line Subversion client. To install
- it, run Cygwin's setup.exe, navigate to Devel/subversion, and
- if the package has a "Skip" item in the "New" column, click on the
- "Skip" item so it shows a version number.</para>
- </section>
- <section>
- <title>Subversion from apache.org</title>
- <para>There are several binary-distribution Subversion clients
- available from apache.org. Go to
- <ulink url="http://subversion.apache.org/" /> and simply
- install one.</para>
- </section>
- <section>
- <title>TortoiseSVN</title>
- <para>TortoiseSVN is a native Windows graphical Subversion client for
- Windows. You can download the setup from
- <ulink url="http://tortoisesvn.net/" /> 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! This example uses TortoiseSVN
- but another Subversion client would work as well.</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>1</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++ 2010 Express Edition, find the line
- <programlisting>
-<![CDATA[#MSVC_VARIANT=MSVC2010EE]]>
- </programlisting>
- and remove the comment character (#)
- from the beginning of the line. Then, find the line
- <programlisting>
-<![CDATA[MSVC_VARIANT=MSVC2010]]>
- </programlisting>
- and comment it out, by prefixing a hash (#).
- <superscript>2</superscript></para>
- </listitem>
- </orderedlist>
- </para>
- </listitem>
- </orderedlist>
- <superscript>1</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>
- <para>
- <superscript>2</superscript>Compiler dependent: This step
- depends on the compiler you are using. For compilers other than
- Visual C++ 2010, see the table at
- <xref linkend="ChToolsMSChain" />.</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>set environment variables for Visual C++ 2010 Express
- Edition:<superscript>1,2</superscript></para>
- <para>to build 32-bit binaries call
- <command>"C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Release /x86</command>
- and to build 64-bit binaries call
- <command>"C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Release /x64</command></para>
- <para>If your version of the compiler does not have <filename>SetEnv.Cmd</filename>, you
- may need to use <filename>vcvarsall.bat</filename> or <filename>vcvars32.bat</filename>
- which do much the same thing as <filename>SetEnv.cmd</filename>.</para>
- <para>
- For example, on some 64-bit installations, one would build a 32-bit version
- by invoking
- <command>C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat</command>
- and one would build a 64-bit version using the command
- <command>C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\Vcvarsall.bat amd64</command>
- Consult your compiler's documentation to learn which version applies to your installation.</para>
- </listitem>
- <listitem>
- <para>set environment variable to select target platform</para>
- <para>to build 32-bit binaries execute
- <command>set WIRESHARK_TARGET_PLATFORM=win32</command>
- and to build 64-bit binaries execute
- <command>set WIRESHARK_TARGET_PLATFORM=win64</command></para>
- </listitem>
- <listitem>
- <para><command>cd C:\wireshark</command> to jump into the source
- directory</para>
- </listitem>
- </orderedlist>
- <superscript>1</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>
- <para><superscript>2</superscript>Compiler dependent: This step
- depends on the compiler variant used, for other variants than
- the recommended Visual C++ 2010 Express Edition see the table
- at
- <xref linkend="ChToolsMSChain" />!</para>
-
- <para>Wireshark development depends on several additional
- environment variables, particularly <varname>PATH</varname>.
- You can use a batch script to fill these in, along with the Visual
- C++ variables; for example:
-
- <programlisting>
-<![CDATA[@echo off
-
-if "%1" == "" goto x86
-if /i %1 == x86 goto x86
-if /i %1 == x64 goto x64
-goto usage
-
-:usage
-echo Error in script usage. The correct usage is:
-echo %0 [option]
-echo where [option] is: x86 ^| x64
-echo:
-echo For example:
-echo %0 x86
-goto :eof
-
-:x64
-echo Adding things to the path...
-set PATH=%PATH%;c:\cygwin\bin
-set WIRESHARK_TARGET_PLATFORM=win64
-call "c:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Release /x64
-title Command Prompt (VC++ 2010 x64)
-goto :eof
-
-:x86
-echo Adding things to the path...
-set PATH=%PATH%;c:\cygwin\bin
-set WIRESHARK_TARGET_PLATFORM=win32
-call "c:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Release /x86
-title Command Prompt (VC++ 2010 -x86)
-goto :eof]]>
-
- </programlisting>
- </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/Program Files (x86)/Microsoft Visual Studio 10.0/VC/Bin/amd64/cl
- link: /cygdrive/c/Program Files (x86)/Microsoft Visual Studio 10.0/VC/Bin/amd64/link
- nmake: /cygdrive/c/Program Files (x86)/Microsoft Visual Studio 10.0/VC/Bin/amd64/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
- peflags: /usr/bin/peflags
- perl: /usr/bin/perl
- C:\Python27\python.exe: /cygdrive/c/Python27/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 that you called <command>SetEnv.Cmd</command>
- 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>
- <para>Make sure that the other tools found are the Cygwin versions. Some build
- problems have been caused by incompatible versions of <command>grep</command> and
- <command>unzip</command>.</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>
- <para>Note that 32-bit versions of the software require 32-bit versions of the
- libraries and that 64-bit versions require 64-bit libraries. The build process
- creates independent directories for each as needed. See
- <xref linkend="ChSetupPrepareCommandCom" /> for how to use
- <command>SetEnv.Cmd</command> and <varname>WIRESHARK_TARGET_PLATFORM</varname>
- to select either a 32- or 64-bit build.</para>
- </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. Note that the
- 32-bit version of NSIS will work for both 32-bit and 64-bit versions of
- Wireshark.</para>
- </listitem>
- <listitem>
- <para>Runtime redistributable: to build a 32-bit version you will need
- <filename>vcredist_x86.exe</filename> :
- <ulink url="http://www.microsoft.com/en-us/download/details.aspx?id=8328">
- Download</ulink> the C-Runtime redistributable for Visual
- C++ 2010 Express Edition SP1 (<filename>vcredist_x86.exe</filename>)
- and copy it into <filename>C:\wireshark-win32-libs</filename>
- <superscript>1</superscript></para>
- <para>To build a 64-bit version, you will need
- <filename>vcredist_x64.exe</filename> :
- <ulink url="http://www.microsoft.com/en-us/download/details.aspx?id=13523">
- Download</ulink> the 64-bit redistributable for Visual C++ 2010 Express
- Edition SP1 (<filename>vcredist_x64.exe</filename>) and copy it into
- <filename>C:\Wireshark-win64-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++ 2010 Express Edition SP1 see the table
- at <xref linkend="ChToolsMSChain" />!</para>
- </section>
- </section>
-</chapter>
git.samba.org / metze / wireshark / wip.git / commitdiff