--- /dev/null
+++++++++++++++++++++++++++++++++++++++
+<!-- WSDG Chapter Setup -->
+++++++++++++++++++++++++++++++++++++++
+
+++++++++++++++++++++++++++++++++++++++
+<!-- $Id$ -->
+++++++++++++++++++++++++++++++++++++++
+
+[[ChapterSetup]]
+
+== Quick Setup
+
+[[ChSetupUNIX]]
+
+=== 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 can usually install it
+using the package in your distribution: aptitude, yum, Synaptic, etc.
+
+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.
+
+[[ChSetupWin32]]
+
+=== Win32/64: Step-by-Step Guide
+
+A quick setup guide for Win32 and Win64 with recommended
+configuration.
+
+[WARNING]
+====
+Unless you know exactly what you are doing, you
+should strictly follow the recommendations below.
+====
+
+[[ChSetupMSVC]]
+
+==== Install Microsoft C compiler and SDK
+
+You need to install, in exactly this order:
+
+. C compiler:
+http://www.microsoft.com/visualstudio/eng/downloads#d-2010-express[Download]
+and install "Microsoft Visual $$C++$$ 2010 Express Edition." This is a very
+large download.
+
+. Windows SDK for Windows 7, if you want to build 64-bit binaries for Windows 7:
+http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx[Download] and
+install "Microsoft Windows SDK for Windows 7."
++
+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
+http://ctrlf5.net/?p=184[here] for a solution.
+
+. C compiler service pack:
+http://www.microsoft.com/en-us/download/details.aspx?id=23691[Download] and
+install "Microsoft Visual Studio 2010 Service Pack 1." This is a very large
+download.
+
+. 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:
+http://www.microsoft.com/en-us/download/details.aspx?id=4422[Download] and
+install "Microsoft Visual $$C++$$ 2010 Service Pack 1 Compiler Update for the
+Windows SDK 7.1."
+
+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
+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"]. 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.
+
+[TIP]
+.You can use other Microsoft C compiler variants
+====
+It's possible to compile Wireshark with a wide range
+of Microsoft C compiler variants. For details see
+<<ChToolsMSChain>>!
+====
+
+
+[WARNING]
+.Don't use gcc or Clang
+====
+Compiling with gcc or Clang is not recommended and will
+certainly not work (at least without a lot of advanced
+tweaking). For further details on this topic, see
+<<ChToolsGNUChain>>.
+====
+
+// XXX - mention the compiler and PSDK web installers -
+// which significantly reduce download size - and find out the
+// required components
+
+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.
+
+[[ChSetupCygwin]]
+
+
+==== Install Cygwin
+
+http://www.cygwin.com/setup.exe[Download the Cygwin installer] and start it.
+
+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:
+
+* Archive/unzip
+
+* Base/dos2unix
+
+* Devel/bison
+
+* Devel/flex
+
+* Devel/git (recommended - see discussion about using Git below)
+
+* Interpreters/perl
+
+* Utils/patch (optional)
+
+* Web/wget
+
+After clicking the Next button several times, the setup
+will then download and install the selected packages (this
+may take a while).
+
+Why is this recommended? Cygwin's bash version is required, as no native Win32
+version is available. As additional packages can easily be added, Perl and
+other packages are also used.
+
+[[ChSetupPython]]
+
+==== Install Python
+
+Get the Python 2.7 installer from http://python.org/download/[] and install
+Python into the default location ('C:\Python27').
+
+Why is this recommended? Cygwin's Python package doesn't work on some machines,
+so the Win32 native package is recommended.
+
+[[ChSetupsubversion]]
+
+==== Install Git
+
+Please note that the following is not required to build Wireshark but can be
+quite helpful when working with the sources.
+
+Working with the Git source repositories is highly recommended, see
+<<ChSrcObtain>>. It is much easier to update a personal source tree with Git
+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.
+
+There are several ways in which Git can be installed. Most packages are
+available at the URLs below or via the http://chocolatey.org/[Chocolatey package manager].
+Note that many of the GUI interfaces depend on the command line version.
+
+===== The Official Windows Installer
+
+The official command-line installer is available at http://msysgit.github.io/.
+
+===== From Cygwin
+
+Cygwin comes with a port of git. To install it, run Cygwin's setup.exe, navigate
+to Devel/git, and if the package has a "Skip" item in the "New" column, click on
+the "Skip" item so it shows a version number.
+
+===== Git Extensions
+
+Git Extensions is a native Windows graphical Git client for
+Windows. You can download the installer from
+http://code.google.com/p/gitextensions/.
+
+===== TortoiseGit
+
+TortoiseGit is a native Windows graphical Git
+similar to TortoiseSVN. You can download the installer from
+http://code.google.com/p/tortoisegit/.
+
+===== Others
+
+A list of other GUI interfaces for Git can be found at
+http://git-scm.com/downloads/guis
+
+==== Install and Prepare Sources
+
+[TIP]
+.Make sure everything works
+====
+It's a good idea to make sure Wireshark compiles and runs at least once before
+you start hacking the Wireshark sources for your own project. This example uses
+Git Extensions but any other Git client should work as well.
+====
+
+// XXX -
+
+. *Download sources*. Download Wireshark sources into
+'C:\Development\wireshark' using Git Extensions:
+
+.. Open the Git Extensions application. By default Git Extensions
+ will show a validation checklist at startup. If anything needs to
+ be fixed do so now. You can bring up the checklist at any time
+ via _Tools -> Settings_.
+
+.. In the main screen select _Clone repository_. Fill in the following:
++
+Repository to clone: `https://code.wireshark.org/review/wireshark`
++
+Destination: Your top-level development directory, e.g. `C:\Development`.
++
+Subdirectory to create: Anything you'd like. Usually `wireshark`.
++
+[TIP]
+.Check your paths
+====
+Make sure your repository path doesn't contain spaces.
+====
+
+.. Click the _Clone_ button. Git Extensions should start cloning the
+ Wireshark repository.
+
+. Navigate to your newly cloned directory and open 'config.nmake' in an editor.
+ Edit the following settings:
+
+.. `VERSION_EXTRA`: Give Wireshark your "private" version info, e.g.
+`-myprotocol123` to distinguish it from official releases.
+
+.. `WIRESHARK_TARGET_PLATFORM`: Change to `win64` if you're building
+a 64-bit package. You can also define this in the system environment.
+
+.. `PROGRAM_FILES`: Where your programs reside, usually just keep the default:
+_C:\Program Files_ footnote:[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.]
+
+.. `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++$$
+2010 Express Edition, find the line
++
+--
+----
+#MSVC_VARIANT=MSVC2010EE
+----
+and remove the comment character (#) from the beginning of the line. Then, find
+the line
+----
+MSVC_VARIANT=MSVC2010
+----
+and comment it out, by prefixing a hash (#). footnote:[Compiler dependent: This
+step depends on the compiler you are using. For compilers other than Visual
+$$C++$$ 2010, see the table at <<ChToolsMSChain>>.]
+--
+
+[[ChSetupPrepareCommandCom]]
+
+==== Prepare cmd.exe
+
+Prepare `cmd.exe` -- set its environment and current directory.
+
+. Start `cmd.exe`.
+
+. Set environment variables for Visual $$C++$$ 2010 Express Edition.
+footnote:[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. Note: You need to repeat steps 1 - 4 each time you
+open a new cmd.exe.] footnote:[Compiler dependent: This step depends on the
+compiler variant used. For variants other than the recommended Visual $$C++$$
+2010 Express Edition see the table at <<ChToolsMSChain>>]
++
+--
+To build 32-bit binaries call
+----
+> "C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Release /x86'
+----
+and to build 64-bit binaries call
+----
+> "C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Release /x64
+----
+If your version of the compiler does not have `SetEnv.Cmd` you may need to use
+`vcvarsall.bat` or `vcvars32.bat` which do much the same thing as `SetEnv.cmd`.
+For example, on some 64-bit installations, one would build a 32-bit version by
+invoking
+----
+> "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat
+----
+and one would build a 64-bit version using the command
+----
+> "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\Vcvarsall.bat" amd64
+----
+Consult your compiler's documentation to learn which version applies to your
+installation.
+--
+
+. Set environment variable to select target platform.
++
+--
+To build 32-bit binaries execute
+----
+> set WIRESHARK_TARGET_PLATFORM=win32
+----
+and to build 64-bit binaries execute
+----
+> set WIRESHARK_TARGET_PLATFORM=win64
+----
+--
+
+
+. Run
++
+--
+----
+> cd C:\Development\wireshark
+----
+to jump into the source directory
+--
+
+Wireshark development depends on several additional environment variables,
+particularly PATH. You can use a batch script to fill these in, along with the
+Visual $$C++$$ variables; for example:
+
+----
+@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
+----
+
+[[ChToolsWin32Verify]]
+
+==== Verify installed tools
+
+After you've installed the Wireshark sources (see <<ChSrcObtain>>), you can
+check the correct installation of all tools by using the `verify_tools` target of
+the `Makefile.nmake` from the source package.
+
+[WARNING]
+.Dependencies ahead
+====
+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 Wireshark:
+
+----
+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
+----
+
+If you have problems with all the first three items (cl, link, nmake), check
+that you called `SetEnv.Cmd` as mentioned in <<ChSetupPrepareCommandCom>>(which
+will "fix" your PATHsettings). However, the exact text will be slightly
+different depending on the MSVC version used.
+
+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 `link.exe` in Cygwin. If you rename it, make sure to
+remember that a Cygwin update may provide a new version of it.
+
+Make sure that the other tools found are the Cygwin versions. Some build
+problems have been caused by incompatible versions of `grep` and `unzip`.
+
+==== Install Libraries
+
+. If you've closed `cmd.exe` prepare it again.
+
+. Run
++
+--
+----
+> nmake -f Makefile.nmake setup
+----
+to download and install libraries using `wget`. This may take a while.
+--
+
+. If the download fails you may be behind a restrictive firewall. See the proxy
+comment in <<ChToolsWget>>.
+
+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
+<<ChSetupPrepareCommandCom>>for how to use `SetEnv.Cmd` and
+`WIRESHARK_TARGET_PLATFORM` to select either a 32- or 64-bit build.
+
+==== Distclean Sources
+
+The released Wireshark sources contain files that are
+prepared for a UNIX build (e.g. 'config.h').
+
+You must distclean your sources before building the first time.
+
+. If you've closed `cmd.exe` prepare it again.
+
+. Run
++
+--
+----
+> nmake -f Makefile.nmake distclean
+----
+to cleanup the Wireshark sources.
+--
+
+==== Build Wireshark
+
+Now it's time to build Wireshark!
+
+. If you've closed `cmd.exe` prepare it again.
+
+. Run
++
+--
+----
+> nmake -f Makefile.nmake all
+----
+to build Wireshark.
+--
+
+. Wait for Wireshark to compile. This will take a while.
+
+. Run `C:\wireshark\wireshark-gtk2\wireshark.exe` and make sure it starts. s
+
+. Open 'Help -> About'. If it shows your "private" program
+version, e.g.: Version wireshark-major-minor-version:[].x-myprotocol123
+congratulations! You have compiled your own version of Wireshark!
+
+TIP: If compilation fails for suspicious
+reasons after you changed some source files try to "distclean"
+the sources and make "all" again
+
+==== Debug Environment Setup
+
+****
+Unfortunately this section hasn't been written. You should be able
+to use the Visual Studio debugger to attach to a running executable.
+****
+
+==== Optional: Create User's and Developer's Guide
+
+Detailed information to build these guides can be found in the file
+'docbook/README.txt' in the Wireshark sources.
+
+==== Optional: Create a Wireshark Installer
+
+Note: You should have successfully built Wireshark
+before doing the following.
+
+If you want to build your own
+'wireshark-win32-wireshark-major-minor-version:[].x-myprotocol123.exe',
+you'll need NSIS.
+
+. NSIS:
+http://nsis.sourceforge.net[Download] and install NSIS
++
+You may check the `MAKENSIS` setting in the file 'config.nmake' in the Wireshark
+sources. Note that the 32-bit version of NSIS will work for both 32-bit and
+64-bit versions of Wireshark.
+
+. Runtime redistributable: To build a 32-bit version you will need
+'$$vcredist_x86.exe$$':
+http://www.microsoft.com/en-us/download/details.aspx?id=8328[Download] the
+C-Runtime redistributable for Visual
+$$C++$$ 2010 Express Edition SP1 (__$$vcredist_x86.exe$$__)
+and copy it into 'C:\wireshark-win32-libs'.footnoteref:[compilerdependent,Compiler dependent: This step
+depends on the compiler variant used. For variants other than
+the recommended Visual $$C++$$ 2010 Express Edition SP1 see the table
+at <<ChToolsMSChain>>.]
++
+To build a 64-bit version, you will need
+_$$vcredist_x64.exe$$_:
+http://www.microsoft.com/en-us/download/details.aspx?id=13523[Download] the 64-bit redistributable for Visual $$C++$$ 2010 Express
+Edition SP1 (__$$vcredist_x64.exe$$__) and copy it into
+__C:\Wireshark-win64-libs__.footnoteref:[compilerdependent]
+
+. If you've closed `cmd.exe` prepare it again.
+
+. Run
++
+--
+----
+> nmake -f Makefile.nmake packaging
+----
+to build Wireshark installer.
+--
+
+. Run
++
+--
+----
+> C:\wireshark\packaging\nsis\wireshark-win32-wireshark-major-minor-version:[].x-myprotocol123.exe
+----
+to test your new installer. It's a good idea to test on a different machine
+than the developer machine.
+--
+++ /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