docbook/wsdg_src/WSDG_chapter_tools.xml

   1 <!-- WSDG Chapter Tools -->
   2 <!-- $Id$ -->
   3 <chapter id="ChapterTools">
   4   <title>Tool Reference</title>
   5   <section id="ChToolsIntro">
   6     <title>Introduction</title>
   7     <para>This chapter will provide you with information about the
   8     various tools needed for Wireshark development.</para>
   9     <para>None of the tools mentioned in this chapter are needed to
  10     run Wireshark; they are only needed to build it.</para>
  11     <para>Most of these tools have their roots on UNIX like
  12     platforms, but Win32 ports are also available. Therefore the
  13     tools are available in different "flavours":
  14     <itemizedlist>
  15       <listitem>
  16         <para>UNIX (or Win32 Cygwin): the tools should be commonly
  17         available on the supported UNIX platforms, and for Win32
  18         platforms by using the Cygwin UNIX emulation</para>
  19       </listitem>
  20       <listitem>
  21         <para>Win32 native: some tools are available as native
  22         Win32 tools, no special emulation is required</para>
  23       </listitem>
  24     </itemizedlist></para>
  25     <warning>
  26       <title>Warning!</title>
  27       <para>
  28       <command>Unless you know exactly what you are doing, you
  29       should strictly follow the recommendations given in</command>
  30       <xref linkend="ChapterSetup" />!</para>
  31     </warning>
  32     <para>The following sections give a very brief description of
  33     what a particular tool is doing, how it is used in the
  34     Wireshark project and how it can be installed and
  35     tested.</para>
  36     <para>Don't expect a lot of documentation regarding these tools
  37     in this document. If you need further documentation of a
  38     specific tool, you should find lot's of useful information on
  39     the web, as these tools are commonly used. You can also try to
  40     get help for the UNIX based tools with
  41     <userinput>toolname --help</userinput> or read the manpage
  42     <userinput>man toolname</userinput>.</para>
  43     <para>You will find explanations of the tool usage for some of
  44     the specific development tasks in
  45     <xref linkend="ChapterSources" />.</para>
  46   </section>
  47   <section id="ChToolsCygwin">
  48     <title>Win32: Cygwin</title>
  49     <para>Cygwin provides a lot of UNIX based tools on the Win32
  50     platform. It uses a UNIX emulation layer which might be a bit
  51     slower compared to the native Win32 tools, but at an acceptable
  52     level. The installation and update is pretty easy and done
  53     through a single (web based) setup.exe.</para>
  54     <para>The native Win32 tools will typically be a bit faster,
  55     but more complicated to install, as you would have to download
  56     the tools from different webpages, and install them in
  57     different ways, tweaking the PATH and alike.</para>
  58     <note>
  59       <title>Note!</title>
  60       <para>As there's no Win32 native bash version available, at
  61       least a basic installation of cygwin is required in any
  62       case.</para>
  63     </note>
  64     <para>Although Cygwin consists of several separate packages,
  65     the installation and update is done through a single setup.exe,
  66     which acts similar to other web based installers. All tools
  67     will be installed into one base folder, the default is
  68     <filename>C:\cygwin</filename>.</para>
  69     <para>You will find this network based setup.exe at:
  70     <ulink url="http://www.cygwin.com/" />. Click on one of the
  71     "Install Cygwin now" appearances to download the
  72     <filename>setup.exe</filename>. After the download completed,
  73     start this
  74     <filename>setup.exe</filename> on your machine.</para>
  75     <para>The setup will ask you for some settings, the defaults
  76     should usually work well for a first start. At the "Select
  77     Packages" page, you'll need to select some additional packages,
  78     which are not installed by default. Navigate to the required
  79     Category/Package row and click on the "Skip" item in the "New"
  80     column so it shows a version number for the required
  81     package</para>
  82     <para>After clicking the Next button several times, the setup
  83     will then download and install the selected packages (this may
  84     take a while, depending on the package size).</para>
  85     <para>Under: "Start -&gt; Programs -&gt; Cygwin -&gt; Cygwin
  86     Bash Shell" you should now be able to start a new Cygwin bash
  87     shell, which is similar to the command line
  88     (command.com/cmd.exe) in Win32, but much more powerful.</para>
  89     <section id="ChToolsCygwinPackages">
  90       <title>Add/Update/Remove Cygwin Packages</title>
  91       <para>If you want to add additional, update installed or
  92       remove packages later, you have to start the setup.exe again.
  93       At the "Select Packages" page, the entry in the "New" column
  94       will control what is done (or not) with the package. If a new
  95       version of a package is available, the new version number
  96       will be displayed, so it will be automatically updated. You
  97       can change the current setting by simply clicking at it, it
  98       will change between:
  99       <itemizedlist>
 100         <listitem>
 101           <para>a specific version number - this different package
 102           version will be installed</para>
 103         </listitem>
 104         <listitem>
 105           <para>Skip - not installed, no changes</para>
 106         </listitem>
 107         <listitem>
 108           <para>Keep - already installed, no changes</para>
 109         </listitem>
 110         <listitem>
 111           <para>Uninstall - uninstall this package</para>
 112         </listitem>
 113         <listitem>
 114           <para>Reinstall - reinstall this package</para>
 115         </listitem>
 116       </itemizedlist></para>
 117     </section>
 118   </section>
 119   <section id="ChToolsGNUChain">
 120     <title>GNU compiler toolchain (UNIX or Win32 Cygwin)</title>
 121     <section id="ChToolsGCC">
 122       <title>gcc (GNU compiler collection)</title>
 123       <warning>
 124         <title>Win32: Warn!</title>
 125         <para>Using Cygwin gcc to compile Wireshark is "EXPERT
 126         ONLY" and therefore NOT recommended. If you really want to
 127         try it anyway, see:
 128         <ulink url="http://wiki.wireshark.org/Development/CygwinGCC" /> for
 129         some details!</para>
 130       </warning>
 131       <para>The GCC C compiler is available for most of the
 132       UNIX-like platforms and as the Devel/gcc package from the
 133       <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
 134       <para>If GCC isn't already installed or available
 135       as a package for your platform, you can get it at:
 136       <ulink url="http://gcc.gnu.org/" />.</para>
 137       <para>After correct installation, typing at the
 138       bash command line prompt:</para>
 139       <para>
 140         <prompt>$</prompt>
 141         <userinput>gcc --version</userinput>
 142       </para>
 143       <para>should result in something like:
 144       <programlisting>
 145         <![CDATA[gcc (GCC) 3.4.4 (cygwin special) (gdc 0.12, using dmd 0.125)
 146 Copyright (C) 2004 Free Software Foundation, Inc.
 147 This is free software; see the source for copying conditions.  There is NO
 148 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.]]>
 149 </programlisting>However, the version string may vary.</para>
 150     </section>
 151     <section id="ChToolsGDB">
 152       <title>gdb (GNU project debugger)</title>
 153       <para>GDB is the debugger for the GCC compiler. It is
 154       available for many (if not all) UNIX-like platforms and as
 155       the Devel/gdb package from the
 156       <link linkend="ChToolsCygwin">Cygwin setup</link></para>
 157       <para>If you don't like debugging using the command line,
 158       there are some GUI frontends for it available, most notably
 159       GNU DDD.</para>
 160       <para>If gdb isn't already installed or available
 161       as a package for your platform, you can get it at:
 162       <ulink url="http://www.gnu.org/software/gdb/gdb.html" />.</para>
 163       <para>After correct installation:</para>
 164       <para>
 165         <prompt>$</prompt>
 166         <userinput>gdb --version</userinput>
 167       </para>
 168       <para>should result in something like:
 169       <programlisting>
 170         <![CDATA[GNU gdb 6.5.50.20060706-cvs (cygwin-special)
 171 Copyright 2003 Free Software Foundation, Inc.
 172 GDB is free software, covered by the GNU General Public License, and you are
 173 welcome to change it and/or distribute copies of it under certain conditions.
 174 Type "show copying" to see the conditions.
 175 There is absolutely no warranty for GDB.  Type "show warranty" for details.
 176 This GDB was configured as "i686-pc-cygwin".]]>
 177 </programlisting>However, the version string may vary.</para>
 178     </section>
 179     <section id="ChToolsDDD">
 180       <title>ddd (GNU Data Display Debugger)</title>
 181       <para>The GNU Data Display Debugger is a good GUI frontend
 182       for GDB (and a lot of other command line debuggers), so you
 183       have to install GDB first. It is available for many UNIX-like
 184       platforms and as the ddd package from the
 185       <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
 186       <para>If GNU DDD isn't already installed or
 187       available as a package for your platform, you can get it at:
 188       <ulink url="http://www.gnu.org/software/ddd/" />.</para>
 189     </section>
 190     <section id="ChToolsGNUmake">
 191       <title>make (GNU Make)</title>
 192       <note>
 193         <title>Win32 Note!</title>
 194         <para>Although some effort is made to use make from the
 195         Cygwin environment, the mainline is still using Microsoft
 196         Visual Studio's nmake.</para>
 197       </note>
 198       <para>GNU Make is available for most of the UNIX-like
 199       platforms and also as the Devel/make package from the
 200       <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
 201       <para>If GNU Make isn't already installed or
 202       available as a package for your platform, you can get it at:
 203       <ulink url="http://www.gnu.org/software/make/" />.</para>
 204       <para>After correct installation:</para>
 205       <para>
 206         <prompt>$</prompt>
 207         <userinput>make --version</userinput>
 208       </para>
 209       <para>should result in something like:
 210       <programlisting>
 211         <![CDATA[GNU Make 3.81
 212 Copyright (C) 2006  Free Software Foundation, Inc.
 213 This is free software; see the source for copying conditions.
 214 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
 215 PARTICULAR PURPOSE.]]>
 216 </programlisting>However, the version string may vary.</para>
 217     </section>
 218   </section>
 219   <section id="ChToolsMSChain">
 220     <title>Microsoft compiler toolchain (Win32 native)</title>
 221     <para>To compile Wireshark on Windows using the Microsoft C/C++
 222     compiler, you'll need:</para>
 223     <orderedlist>
 224       <listitem>
 225         <para>C compiler (cl.exe)</para>
 226       </listitem>
 227       <listitem>
 228         <para>Linker (link.exe)</para>
 229       </listitem>
 230       <listitem>
 231         <para>Make (nmake.exe)</para>
 232       </listitem>
 233       <listitem>
 234         <para>C runtime headers and libraries (e.g. stdio.h,
 235         msvcrt.lib)</para>
 236       </listitem>
 237       <listitem>
 238         <para>Windows platform headers and libraries (e.g.
 239         windows.h, WSock32.lib)</para>
 240       </listitem>
 241       <listitem>
 242         <para>HTML help headers and libraries (htmlhelp.h,
 243         htmlhelp.lib)</para>
 244       </listitem>
 245     </orderedlist>
 246     <section>
 247       <title>Toolchain Package Alternatives</title>
 248       <para>The official Wireshark 1.0.x releases are compiled using Microsoft
 249       Visual C++ 6.0. The 1.1.x development releases are compiled using
 250       Microsoft Visual C++ 2008 SP1. Using the release compilers is recommended
 251       for Wireshark development work. Visual C++ 2008 Express Edition SP1 may
 252       be used for the development branch, but it cannot create PortableApps
 253       or U3 packages.</para>
 254       <para>However, you might already have a different Microsoft C
 255       compiler installed. With the considerations listed below, it should
 256       be possible to use it as well:</para>
 257
 258       <informaltable frame="all">
 259         <tgroup cols="7">
 260           <colspec colname="c1" colwidth="14*" />
 261           <colspec colname="c2" colwidth="14*" />
 262           <colspec colname="c3" colwidth="14*" />
 263           <colspec colname="c4" colwidth="14*" />
 264           <colspec colname="c5" colwidth="14*" />
 265           <colspec colname="c6" colwidth="14*" />
 266           <colspec colname="c7" colwidth="14*" />
 267           <tbody>
 268             <row>
 269               <entry>
 270                 <para>Compiler Package</para>
 271               </entry>
 272               <entry>
 273                 <para>IDE /</para>
 274                 <para>Debugger?</para>
 275               </entry>
 276               <entry>
 277                 <para>Publicly</para>
 278                 <para>available?</para>
 279               </entry>
 280               <entry>
 281                 <para>Platform SDK</para>
 282                 <para>required?</para>
 283               </entry>
 284               <entry>
 285                 <para>config.nmake:</para>
 286                 <para>MSVC_VARIANT</para>
 287               </entry>
 288               <entry>
 289                 <para>set compiler PATH and alike settings
 290                 with:</para>
 291               </entry>
 292               <entry>
 293                 <para>Remarks</para>
 294               </entry>
 295             </row>
 296             <row>
 297               <entry>
 298                 <para>Visual Studio 6.0</para>
 299               </entry>
 300               <entry>
 301                 <para>Yes</para>
 302               </entry>
 303               <entry>
 304                 <para>Commercial
 305                 <superscript>1</superscript></para>
 306               </entry>
 307               <entry align="center" morerows="3" valign="middle">
 308                 <para>No
 309                 <superscript>2</superscript></para>
 310               </entry>
 311               <entry>
 312                 <para>MSVC6</para>
 313               </entry>
 314               <entry>
 315                 <para>Microsoft Visual
 316                 Studio\VC98\Bin\vcvars32.bat</para>
 317               </entry>
 318               <entry>
 319                 <para>-</para>
 320               </entry>
 321             </row>
 322             <row>
 323               <entry>
 324                 <para>Visual Studio .NET (2002)</para>
 325               </entry>
 326               <entry>
 327                 <para>Yes</para>
 328               </entry>
 329               <entry>
 330                 <para>Commercial
 331                 <superscript>1</superscript></para>
 332               </entry>
 333               <entry>
 334                 <para>MSVC2002</para>
 335               </entry>
 336               <entry>
 337                 <para>Microsoft Visual Studio
 338                 .NET\Vc7\bin\vcvars32.bat</para>
 339               </entry>
 340               <entry>
 341                 <para>-</para>
 342               </entry>
 343             </row>
 344             <row>
 345               <entry>
 346                 <para>Visual Studio .NET 2003</para>
 347               </entry>
 348               <entry>
 349                 <para>Yes</para>
 350               </entry>
 351               <entry>
 352                 <para>Commercial
 353                 <superscript>1</superscript></para>
 354               </entry>
 355               <entry>
 356                 <para>MSVC2003</para>
 357               </entry>
 358               <entry>
 359                 <para>Microsoft Visual Studio .NET
 360                 2003\Vc7\bin\vcvars32.bat</para>
 361               </entry>
 362               <entry>
 363                 <para>-</para>
 364               </entry>
 365             </row>
 366             <row>
 367               <entry>
 368                 <para>Visual Studio 2005</para>
 369               </entry>
 370               <entry>
 371                 <para>Yes</para>
 372               </entry>
 373               <entry>
 374                 <para>Commercial</para>
 375               </entry>
 376               <entry>
 377                 <para>MSVC2005</para>
 378               </entry>
 379               <entry>
 380                 <para>Microsoft Visual Studio
 381                 8\VC\bin\vcvars32.bat</para>
 382               </entry>
 383               <entry>
 384                 <para>-</para>
 385               </entry>
 386             </row>
 387             <row>
 388               <entry>
 389                 <para>Visual C++ 2005 Express Edition</para>
 390                 <para>(recommended)</para>
 391               </entry>
 392               <entry>
 393                 <para>Yes</para>
 394               </entry>
 395               <entry>
 396                 <para>
 397                 <ulink url="http://www.microsoft.com/express/2005/download/default.aspx">
 398                 Free Download</ulink>(474MB)</para>
 399               </entry>
 400               <entry>
 401                 <para>
 402                   <ulink url="#">Free Download</ulink>
 403                 </para>
 404                 <para>(420MB)</para>
 405               </entry>
 406               <entry>
 407                 <para>MSVC2005EE</para>
 408               </entry>
 409               <entry>
 410                 <para>Microsoft Visual Studio
 411                 8\VC\bin\vcvars32.bat</para>
 412               </entry>
 413               <entry>
 414                 <para>vcredist_x86.exe
 415                 <superscript>3</superscript></para>
 416               </entry>
 417             </row>
 418             <row>
 419               <entry>
 420                 <para>Visual Studio 2008</para>
 421               </entry>
 422               <entry>
 423                 <para>Yes</para>
 424               </entry>
 425               <entry>
 426                 <para>Commercial</para>
 427               </entry>
 428               <entry>
 429                 <para>No
 430                 <superscript>2</superscript></para>
 431               </entry>
 432               <entry>
 433                 <para>-</para>
 434                 <para>MSVC2008</para>
 435               </entry>
 436               <entry>
 437                 <para>Microsoft Visual Studio
 438                 9.0\VC\bin\vcvars32.bat</para>
 439               </entry>
 440               <entry>
 441                 <para>-</para>
 442               </entry>
 443             </row>
 444             <row>
 445               <entry>
 446                 <para>Visual C++ 2008 Express Edition</para>
 447               </entry>
 448               <entry>
 449                 <para>Yes</para>
 450               </entry>
 451               <entry>
 452                 <para>
 453                 <ulink url="http://www.microsoft.com/express/vc/">
 454                 Free Download</ulink></para>
 455               </entry>
 456               <entry>
 457                 <para>No
 458                 <superscript>2</superscript></para>
 459               </entry>
 460               <entry>
 461                 <para>MSVC2008EE</para>
 462               </entry>
 463               <entry>
 464                 <para>Microsoft Visual Studio
 465                 9.0\VC\bin\vcvars32.bat</para>
 466               </entry>
 467               <entry>
 468                 <para>vcredist_x86.exe
 469                 <superscript>3</superscript></para>
 470               </entry>
 471             </row>
 472             <row>
 473               <entry>
 474                 <para>.NET Framework SDK version 1.0a</para>
 475               </entry>
 476               <entry>
 477                 <para>No</para>
 478               </entry>
 479               <entry>
 480                 <para>
 481                 <ulink url="#">Free Download</ulink>(104MB)</para>
 482               </entry>
 483               <entry align="center" morerows="2" valign="middle">
 484                 <para>
 485                   <ulink url="#">Free Download</ulink>
 486                 </para>
 487                 <para>(420MB)</para>
 488               </entry>
 489               <entry>
 490                 <para>DOTNET10</para>
 491               </entry>
 492               <entry>
 493                 <para>
 494                 Microsoft.NET\FrameworkSDK\Bin\corvars.bat</para>
 495               </entry>
 496               <entry>
 497                 <para>can't build setup
 498                 <superscript>4</superscript></para>
 499               </entry>
 500             </row>
 501             <row>
 502               <entry>
 503                 <para>.NET Framework SDK Version 1.1
 504                 <superscript>5</superscript></para>
 505               </entry>
 506               <entry>
 507                 <para>No</para>
 508               </entry>
 509               <entry>
 510                 <para>
 511                 <ulink url="#">Free Download</ulink>(106MB)</para>
 512               </entry>
 513               <entry>
 514                 <para>DOTNET11</para>
 515               </entry>
 516               <entry>
 517                 <para>Microsoft.NET\SDK\v1.1\Bin\sdkvars.bat</para>
 518               </entry>
 519               <entry>
 520                 <para>can't build setup
 521                 <superscript>4</superscript></para>
 522               </entry>
 523             </row>
 524             <row>
 525               <entry>
 526                 <para>.NET Framework 2.0 SDK
 527                 <superscript>5</superscript></para>
 528               </entry>
 529               <entry>
 530                 <para>No</para>
 531               </entry>
 532               <entry>
 533                 <para>
 534                 <ulink url="#">Free Download</ulink>(363MB)</para>
 535               </entry>
 536               <entry>
 537                 <para>DOTNET20</para>
 538               </entry>
 539               <entry>
 540                 <para>Microsoft.NET\SDK\v2.0\Bin\sdkvars.bat</para>
 541               </entry>
 542               <entry>
 543                 <para>vcredist_x86.exe
 544                 <superscript>3</superscript></para>
 545               </entry>
 546             </row>
 547             <row>
 548               <entry>
 549                 <para>Windows SDK for Windows Vista and</para>
 550                 <para>.NET Framework 3.0 Runtime Components</para>
 551               </entry>
 552               <entry>
 553                 <para>No</para>
 554               </entry>
 555               <entry>
 556                 <para>
 557                 <ulink url="#">Free Download</ulink>(1188MB)</para>
 558               </entry>
 559               <entry>
 560                 <para>No
 561                 <superscript>2</superscript></para>
 562               </entry>
 563               <entry>
 564                 <para>-</para>
 565                 <para>(not yet implemented!)</para>
 566               </entry>
 567               <entry>
 568                 <para>Microsoft
 569                 SDKs\Windows\v6.0\Bin\SetEnv.Cmd</para>
 570               </entry>
 571               <entry>
 572                 <para>vcredist_x86.exe
 573                 <superscript>3</superscript></para>
 574               </entry>
 575             </row>
 576           </tbody>
 577         </tgroup>
 578       </informaltable>
 579       <para>
 580       <superscript>1</superscript>no longer officially available,
 581       might still be available through the MSDN
 582       subscriptions</para>
 583       <para>
 584       <superscript>2</superscript>as the Platform SDK is already
 585       integrated in the package, you obviously don't need to
 586       install it and don't even need to call a separate environment
 587       setting batch file for the Platform SDK!</para>
 588       <para>
 589       <superscript>3</superscript>vcredist_x86.exe (3MB free
 590       download) is required to build Wireshark-setup.exe. The
 591       version of vcredist_x86.exe MUST match the version for
 592       your compiler.</para>
 593       <para>
 594       <superscript>4</superscript>Wireshark-setup.exe cannot be
 595       created with this package, as msvcr*.dll is not available or
 596       not redistributable!</para>
 597       <para>
 598       <superscript>5</superscript>MSDN remarks that the
 599       corresponding .NET runtime is required. It's currently
 600       unclear if the runtime needs to be installed for the C
 601       compiler to work - or is this only needed to compile / run
 602       .NET programs?!?</para>
 603       <para>
 604       <superscript>6</superscript>beta version, not suitable for
 605       production use!</para>
 606       <note>
 607         <title>Note!</title>
 608         <para>The "Visual C++ Toolkit 2003" should NOT be used to
 609         compile Wireshark!</para>
 610       </note>
 611     </section>
 612     <section>
 613       <title>Legal issues with MSVC &gt; V6?</title>
 614       <para>Please note: The following is not legal advice - ask
 615       your preferred lawyer instead! It's the authors view, but
 616       this view might be wrong!</para>
 617       <para>The myriad of&#160;
 618       <ulink url="http://anonsvn.wireshark.org/wireshark-win32-libs/tags/">
 619       Win32 support lib</ulink> port projects all seem to believe
 620       there are legal issues involved in using newer versions of
 621       Visual Studio. This FUD essentially stems from two
 622       misconceptions:</para>
 623       <para>
 624       <orderedlist>
 625         <listitem>
 626           <para>Unfortunately, it is believed by many that the
 627           Microsoft Visual Studio 2003 EULA explicitly forbids
 628           linking with GPL'ed programs. This belief is probably due
 629           to an improper interpretation of the&#160;
 630           <ulink url="http://msdn.microsoft.com/visualc/vctoolkit2003/eula.aspx">
 631           Visual Studio 2003 Toolkit EULA</ulink>, which places
 632           redistribution restrictions only on SOURCE CODE SAMPLES
 633           which accompany the toolkit.</para>
 634         </listitem>
 635         <listitem>
 636           <para>Other maintainers believe that the GPL itself
 637           forbids using Visual Studio 2003, since one of the
 638           required support libraries (MSVCR71.DLL) does not ship
 639           with the Windows operating system. This is also a
 640           wrongful interpretation, and the&#160;
 641           <ulink url="http://www.gnu.org/licenses/gpl-faq.xml#WindowsRuntimeAndGPL">
 642           GPL FAQ</ulink> explicitly addresses this issue.</para>
 643         </listitem>
 644       </orderedlist>Similar applies to Visual Studio 2005 and
 645       alike.</para>
 646       <para>So in effect it should be perfectly legal to compile
 647       Wireshark and distribute / run it if it was compiled with any
 648       MSVC version &gt; V6!</para>
 649     </section>
 650     <section>
 651       <title>cl.exe (C Compiler)</title>
 652       <para>The following table gives an overview of the possible
 653       Microsoft toolchain variants and their specific C compiler
 654       versions "ordered by release date":</para>
 655       <informaltable frame="all">
 656         <tgroup cols="4">
 657           <colspec colname="c1" colwidth="25*" />
 658           <colspec colname="c2" colwidth="25*" />
 659           <colspec colname="c3" colwidth="25*" />
 660           <colspec colname="c4" colwidth="25*" />
 661           <tbody>
 662             <row>
 663               <entry>
 664                 <para>Compiler Package</para>
 665               </entry>
 666               <entry>
 667                 <para>cl.exe</para>
 668               </entry>
 669               <entry>
 670                 <para>#define _MSC_VER</para>
 671               </entry>
 672               <entry>
 673                 <para>required C-Runtime DLL</para>
 674               </entry>
 675             </row>
 676             <row>
 677               <entry>
 678                 <para>Visual Studio 6.0</para>
 679               </entry>
 680               <entry align="center">
 681                 <para>6.0</para>
 682               </entry>
 683               <entry align="center">
 684                 <para>1200</para>
 685               </entry>
 686               <entry align="center">
 687                 <para>msvcrt.dll</para>
 688                 <para>(Version 6)</para>
 689               </entry>
 690             </row>
 691             <row>
 692               <entry>
 693                 <para>Visual Studio .NET (2002)</para>
 694               </entry>
 695               <entry align="center" morerows="1" valign="middle">
 696                 <para>7.0</para>
 697               </entry>
 698               <entry align="center" morerows="1" valign="middle">
 699                 <para>1300</para>
 700               </entry>
 701               <entry align="center" morerows="1" valign="middle">
 702                 <para>msvcr70.dll</para>
 703               </entry>
 704             </row>
 705             <row>
 706               <entry>
 707                 <para>.NET Framework SDK version 1.0a</para>
 708               </entry>
 709             </row>
 710             <row>
 711               <entry>
 712                 <para>Visual Studio .NET 2003</para>
 713               </entry>
 714               <entry align="center" morerows="1" valign="middle">
 715                 <para>7.10</para>
 716               </entry>
 717               <entry align="center" morerows="1" valign="middle">
 718                 <para>1310</para>
 719               </entry>
 720               <entry align="center" morerows="1" valign="middle">
 721                 <para>msvcr71.dll</para>
 722               </entry>
 723             </row>
 724             <row>
 725               <entry>
 726                 <para>.NET Framework SDK Version 1.1</para>
 727               </entry>
 728             </row>
 729             <row>
 730               <entry>
 731                 <para>Visual Studio 2005</para>
 732               </entry>
 733               <entry align="center" morerows="3" valign="middle">
 734                 <para>8.0</para>
 735               </entry>
 736               <entry align="center" morerows="3" valign="middle">
 737                 <para>1400</para>
 738               </entry>
 739               <entry align="center" morerows="3" valign="middle">
 740                 <para>msvcr80.dll</para>
 741               </entry>
 742             </row>
 743             <row>
 744               <entry>
 745                 <para>Visual C++ 2005 Express Edition</para>
 746               </entry>
 747             </row>
 748             <row>
 749               <entry>
 750                 <para>.NET Framework 2.0 SDK</para>
 751               </entry>
 752             </row>
 753             <row>
 754               <entry>
 755                 <para>Windows SDK for Windows Vista and</para>
 756                 <para>.NET Framework 3.0 Runtime Components</para>
 757               </entry>
 758             </row>
 759             <row>
 760               <entry>
 761                 <para>Visual Studio 2008</para>
 762                 <para>(Code Name "Orcas")</para>
 763               </entry>
 764               <entry align="center" morerows="2" valign="middle">
 765                 <para>9.0</para>
 766               </entry>
 767               <entry align="center" morerows="2" valign="middle">
 768                 <para>1500</para>
 769               </entry>
 770               <entry align="center" morerows="2" valign="middle">
 771                 <para>msvcr90.dll</para>
 772               </entry>
 773             </row>
 774             <row>
 775               <entry>
 776                 <para>Visual Studio 2008 Express Edition</para>
 777                 <para>(Code Name "Orcas")</para>
 778               </entry>
 779             </row>
 780           </tbody>
 781         </tgroup>
 782       </informaltable>
 783       <para>After correct installation of the toolchain, typing
 784       at the command line prompt (cmd.exe):</para>
 785       <para>
 786         <prompt>&gt;</prompt>
 787         <userinput>cl</userinput>
 788       </para>
 789       <para>should result in something like:
 790       <programlisting>
 791         <![CDATA[Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 12.00.8804 for 80x86
 792 Copyright (C) Microsoft Corp 1984-1998. All rights reserved.
 793
 794 usage: cl [ option... ] filename... [ /link linkoption... ]]>
 795 </programlisting>However, the version string may vary.</para>
 796     </section>
 797     <section id="ChToolsNMake">
 798       <title>nmake.exe (Make)</title>
 799       <para>nmake is part of the toolchain packages described
 800       above.</para>
 801       <para>Instead of using the workspace (.dsw) and projects
 802       (.dsp) files, the traditional nmake makefiles are used. This
 803       has one main reason: it makes it much easier to maintain
 804       changes simultaneously with the GCC toolchain makefile.am files
 805       as both file formats are similar. However, as no Visual
 806       Studio workspace/project files are available, this makes it
 807       hard to use the Visual Studio IDE e.g. for using the
 808       integrated debugging feature.</para>
 809       <para>After correct installation, typing at the command
 810       line prompt (cmd.exe):</para>
 811       <para>
 812         <prompt>&gt;</prompt>
 813         <userinput>nmake</userinput>
 814       </para>
 815       <para>should result in something like:
 816       <programlisting>
 817         <![CDATA[Microsoft (R) Program Maintenance Utility   Version 6.00.9782.0
 818 Copyright (C) Microsoft Corp 1988-1998. All rights reserved.
 819
 820 NMAKE : fatal error U1064: MAKEFILE not found and no target specified
 821 Stop.]]>
 822 </programlisting>However, the version string may vary.</para>
 823       <para>Documentation on nmake can be found at
 824       <ulink url="http://msdn2.microsoft.com/en-us/library/dd9y37ha(VS.71).aspx">
 825       Microsoft MSDN</ulink></para>
 826     </section>
 827     <section>
 828       <title>link.exe (Linker)</title>
 829       <para>XXX - add info here</para>
 830     </section>
 831     <section>
 832       <title>C-Runtime "Redistributable" files</title>
 833       <para>Please note: The following is not legal advice - ask
 834       your preferred lawyer instead! It's the authors view, but
 835       this view might be wrong!</para>
 836       <para>Depending on the Microsoft compiler version you use,
 837       some binary files coming from Microsoft might
 838       be&#160;required to be installed on Windows machine to run
 839       Wireshark. On a developer machine, the compiler setup
 840       installs these files so they are available - but they might
 841       not be available on a user machine!</para>
 842       <para>This is especially true for the C runtime DLL
 843       (msvcr*.dll), which contains the implementation of ANSI and
 844       alike functions, e.g.: fopen(), malloc(). The DLL is named
 845       like: msvcr&lt;version&gt;.dll, an abbreviation for
 846       "MicroSoft Visual C Runtime". For Wireshark to work, this DLL
 847       must be available on the users machine.</para>
 848       <para>MSVC6 was using msvcrt.dll, which is already available
 849       on all recent windows systems - no need to redistribute
 850       anything. Starting with MSVC7, it is necessary to ship the C
 851       runtime DLL (msvcr&lt;version&gt;.dll) together with the
 852       application installer somehow, as that DLL is possibly not
 853       available on the target system.</para>
 854       <note>
 855         <title>Note!</title>
 856         <para>The files to redistribute must be mentioned in the
 857         redist.txt file of the compiler package - otherwise it
 858         can't be legally redistributed by third parties like
 859         us!</para>
 860       </note>
 861       <para>The following MSDN links are recommended for the
 862       interested reader:</para>
 863       <para>
 864         <itemizedlist>
 865           <listitem>
 866             <para>
 867             <ulink url="http://msdn2.microsoft.com/en-us/library/ms235299(VS.80).aspx">
 868             "Redistributing Visual C++ Files"</ulink>
 869             </para>
 870           </listitem>
 871           <listitem>
 872             <para>
 873             <ulink url="http://msdn2.microsoft.com/en-us/library/ms235291(VS.80).aspx">
 874             "How to: Deploy using XCopy"</ulink>
 875             </para>
 876           </listitem>
 877           <listitem>
 878             <para>
 879             <ulink url="http://support.microsoft.com/?scid=kb%3Ben-us%3B326922&amp;x=10&amp;y=13">
 880             "Redistribution of the shared C runtime component
 881             in Visual C++ 2005 and in Visual C++ .NET"</ulink>
 882             </para>
 883           </listitem>
 884         </itemizedlist>
 885       </para>
 886       <section>
 887         <title>msvcrt.dll - Version 6.0</title>
 888         <para>Redistributables weren't an issue with MSVC 6, as any
 889         realistic installer target system (&gt;= Win95) already
 890         contains the corresponding msvcrt.dll.</para>
 891       </section>
 892       <section>
 893         <title>msvcr70.dll - Version 7.0 (2002)</title>
 894         <para>"Visual Studio .NET (2002)" - comes with this dll and
 895         it's mentioned in redist.txt.</para>
 896         <para>".NET Framework SDK 1.0" doesn't even come with this
 897         dll. XXX - Is this file available with the&#160;.NET 1.0
 898         runtime (dotnetfx.exe) - so it could be shipped instead?!?
 899         Do we want it that way?</para>
 900       </section>
 901       <section>
 902         <title>msvcr71.dll - Version 7.1 (2003)</title>
 903         <para>"Visual Studio .NET&#160;2003" comes with this dll
 904         and it's mentioned in redist.txt.</para>
 905         <para>".NET Framework SDK 1.1" comes with this dll, but
 906         it's NOT mentioned in redist.txt. XXX - Is this file
 907         available with the&#160;.NET 1.1&#160;runtime
 908         (dotnetfx.exe) - so it could be shipped instead ?!? Do we
 909         want it that way?</para>
 910       </section>
 911       <section>
 912         <title>msvcr80.dll / vcredist_x86.exe - Version 8.0
 913         (2005)</title>
 914         <para>There are three redistribution methods that MSDN
 915         mentions for MSVC 8 (see: "
 916         <ulink url="http://msdn2.microsoft.com/en-us/library/ms235316%28VS.80%29.aspx">
 917         Choosing a Deployment Method</ulink>"):</para>
 918         <para>
 919         <orderedlist>
 920           <listitem>
 921             <para>"Redistributable Merge Modules" (kind of loadable
 922             modules for building msi installers - not suitable for
 923             Wireshark's NSIS based installer)</para>
 924           </listitem>
 925           <listitem>
 926             <para>copy the folder content of Microsoft.VC80.CRT to
 927             the target directory (e.g. "C:\program
 928             files\Wireshark")</para>
 929           </listitem>
 930           <listitem>
 931             <para>vcredist_x86.exe (needs to be executed on the
 932             target machine - MSDN recommends this for the 2005
 933             Express Editions)</para>
 934           </listitem>
 935         </orderedlist>To save installer size, MSVC2005 uses the
 936         content of Microsoft.VC80.CRT (method 2 - this is the
 937         smallest package). As MSVC2005EE and DOTNET20 doesn't
 938         provide the folder "Microsoft.VC80.CRT" they use method 3.
 939         You'll have to download a vcredist_x86.exe from Microsoft
 940         that matches your compiler version. The best way to
 941         determine this version is to open one of the generated
 942         manifest files (e.g. wireshark.exe.manifest) and look for
 943         the version of the Microsoft.VC80.CRT entry.</para>
 944         <para>
 945           <itemizedlist>
 946             <listitem>
 947               <para>
 948               <command>8.0.50608.0</command>, from: "Microsoft
 949               Visual C++ 2005" (and probably the Express Edition as
 950               well):
 951               <ulink url="http://www.microsoft.com/downloads/details.aspx?FamilyId=32BC1BEE-A3F9-4C13-9C99-220B62A191EE" /></para>
 952             </listitem>
 953             <listitem>
 954               <para>
 955               <command>8.0.50727.762</command>, from: "Microsoft
 956               Visual C++ 2005 Express Edition - ENU Service Pack 1
 957               (KB926748)":
 958               <ulink url="http://www.microsoft.com/downloads/details.aspx?familyid=200B2FD9-AE1A-4A14-984D-389C36F85647" /></para>
 959             </listitem>
 960           </itemizedlist>
 961         </para>
 962         <para>Please report to the developer mailing list, if you
 963         find a different version number!</para>
 964       </section>
 965       <section>
 966         <title>msvcr90.dll / vcredist_x86.exe - Version 9.0 (2008)</title>
 967         <para>
 968           <itemizedlist>
 969             <listitem>
 970               <para>
 971               <command>9.0.21022.8</command>, from: "Microsoft Visual C++
 972                           2008 Redistributable Package (x86)":
 973               <ulink url="http://www.microsoft.com/downloads/details.aspx?FamilyID=9B2DA534-3E03-4391-8A4D-074B9F2BC1BF" /></para>
 974             </listitem>
 975             <listitem>
 976               <para>
 977               <command>9.0.30729.1</command>, from: "Microsoft Visual C++
 978                           2008 SP1 Redistributable Package (x86)":
 979               <ulink url="http://www.microsoft.com/downloads/details.aspx?FamilyID=A5C84275-3B97-4AB7-A40D-3802B2AF5FC2" /></para>
 980             </listitem>
 981           </itemizedlist>
 982         </para>
 983         <para>Please report to the developer mailing list, if you
 984         find a different version number!</para>
 985       </section>
 986       <section>
 987         <title>Version 10.0 (2010)?</title>
 988         <para>As the corresponding C compiler is preliminary, it's
 989         too early to say!</para>
 990       </section>
 991     </section>
 992     <section>
 993       <title>Windows (Platform) SDK</title>
 994       <para>The&#160;Windows Platform SDK (PSDK) is a free (as in
 995       beer) download and contains platform specific headers and
 996       libraries (e.g. windows.h, WSock32.lib, ...). As new Windows
 997       features evolve in time, updated PSDK's become available that
 998       include new and updated API's.</para>
 999       <para>When you purchase a commercial Visual Studio, it will
1000       include a PSDK. The free (as in beer) downloadable C compiler
1001       versions (VC++ 2005 Express, .NET Framework, ...) do not
1002       contain a PSDK - you'll need to download a PSDK in order to
1003       have the required C header files and libraries.</para>
1004       <para>Older Versions of the Platform SDK should also work.
1005       However, the command to set the environment settings will be
1006       different, try search for SetEnv.* in the SDK
1007       directory.</para>
1008       <para>BTW: "Windows SDK" seems to be the new name of the
1009       Platform SDK for Vista. The current SDK name is misleading:
1010       "Microsoft&#174; Windows&#174; Software Development Kit for
1011       Windows Vista&#8482; and .NET Framework 3.0 Runtime
1012       Components" - translated this means: the Windows SDK for
1013       Windows Vista and Platforms (like WinXP) that have the .NET
1014       3.0 runtime installed.</para>
1015     </section>
1016     <section>
1017       <title>HTML Help</title>
1018       <para>The HTML Help is used to create the User's and
1019       Developer's Guide in .chm format and to show the User's Guide
1020       as the Wireshark "Online Help".</para>
1021       <para>Both&#160;features are currently optional, but might be
1022       mandatory in future versions.</para>
1023       <section>
1024         <title>HTML Help Compiler (hhc.exe)</title>
1025         <para>This compiler is used to&#160;generate a .chm file
1026         from a bunch&#160;of HTML files - in our case to generate
1027         the User's and Developer's Guide in .chm format.</para>
1028         <para>The compiler is only available as the free (as in
1029         beer) "HTML Help Workshop" download. If you want to compile
1030         the guides yourself, you need to download and install this.
1031         If you don't install it into the default directory, you may
1032         also have a look at the HHC_DIR setting in the file
1033         docbook/Makefile.</para>
1034       </section>
1035       <section>
1036         <title>HTML Help Build Files (htmlhelp.c /
1037         htmlhelp.lib)</title>
1038         <para>The files htmlhelp.c and htmlhelp.lib are required to
1039         be able to open .chm files from Wireshark - to show the
1040         "online help".</para>
1041         <para>Both files are part of the Platform SDK (standalone
1042         PSDK or MSVC since 2002). If you still use MSVC 6, you
1043         can&#160;get them from the "HTML Help Workshop" mentioned
1044         above.</para>
1045         <para>The related settings in config.nmake depend on the
1046         MSVC variant you use:</para>
1047         <para>
1048           <itemizedlist>
1049             <listitem>
1050               <para>MSVC 6: if the "HTML Help Workshop" is
1051               installed, set HHC_DIR to its directory</para>
1052             </listitem>
1053             <listitem>
1054               <para>&gt; MSVC 6: set HHC_DIR to use it (the actual
1055               value doesn't matter in this case)</para>
1056             </listitem>
1057           </itemizedlist>
1058         </para>
1059       </section>
1060     </section>
1061     <section id="ChToolsDebugger">
1062       <title>Debugger</title>
1063       <para>Well, using a good debugger can save you a lot of
1064       development time.</para>
1065       <para>The debugger you use must match the C compiler
1066       Wireshark was compiled with, otherwise the debugger will
1067       simply fail or you will only see a lot of garbage.</para>
1068       <section id="ChToolsMSVCDebugger">
1069         <title>Visual Studio integrated debugger</title>
1070         <para>You can use the integrated debugger of Visual Studio
1071         - only available in some of the toolchain packages.</para>
1072         <para>However, setting up the environment is a bit tricky,
1073         as the Win32 build process is using makefiles instead of
1074         the .dsp/.dsw files usually used.</para>
1075         <para>XXX - add instructions how to do it.</para>
1076       </section>
1077       <section id="ChToolsMSDebuggingTools">
1078         <title>Debugging Tools for Windows</title>
1079         <para>You could also use the Microsoft Debugging Tools for Windows toolkit,
1080         which is a standalone GUI debugger. Although it's not that
1081         comfortable compared to debugging with the Visual Studio
1082         integrated debugger, it can be helpful if you have to debug
1083         on a machine where an integrated debugger is not
1084         available.</para>
1085         <para>You can get it free of charge at:
1086         <ulink url="http://www.microsoft.com/whdc/devtools/debugging/default.mspx" /> (as
1087         links to Microsoft pages change from time to time, search
1088         for "Debugging Tools" at their page if this link should be
1089         outdated).</para>
1090       </section>
1091     </section>
1092   </section>
1093   <section id="ChToolsBash">
1094     <title>bash</title>
1095     <para>The bash shell is needed to run several shell
1096     scripts.</para>
1097     <section id="ChToolsGNUBash">
1098       <title>UNIX or Win32 Cygwin: GNU bash</title>
1099       <para>The bash shell is available for most of the UNIX-like
1100       platforms and as the bash package from the
1101       <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
1102       <para>If bash isn't already installed or
1103       available as a package for your platform, you can get it at:
1104       <ulink url="http://www.gnu.org/software/bash/bash.html" />.</para>
1105       <para>After correct installation, typing at the bash command line prompt:</para>
1106       <para>
1107         <prompt>$</prompt>
1108         <userinput>bash --version</userinput>
1109       </para>
1110       <para>should result in something like:
1111       <programlisting>
1112         <![CDATA[GNU bash, version 3.1.17(6)-release (i686-pc-cygwin)
1113 Copyright (C) 2005 Free Software Foundation, Inc.]]>
1114 </programlisting>However, the version string may vary.</para>
1115     </section>
1116     <section id="ChToolsWin32Bash">
1117       <title>Win32 native: -</title>
1118       <para>The authors don't know of any working Win32 native bash
1119       implementation.</para>
1120     </section>
1121   </section>
1122   <section id="ChToolsPython">
1123     <title>python</title>
1124     <para>Python is an interpreter based programming language. The
1125     homepage of the python project is:
1126     <ulink url="http://python.org/" />. Python is used to generate
1127     some source files. Python 2.4 to 2.6 should work fine.
1128     </para>
1129     <section id="ChToolsUnixPython">
1130       <title>UNIX or Win32 Cygwin: python</title>
1131       <para>Python is available for most of the UNIX-like platforms
1132       and as the python package from the
1133       <link linkend="ChToolsCygwin">Cygwin setup</link></para>
1134       <para>If Python isn't already installed or
1135       available as a package for your platform, you can get it at:
1136       <ulink url="http://www.python.org/" />.</para>
1137       <para>After correct installation, typing at the
1138       bash command line prompt:</para>
1139       <para>
1140         <userinput>$ python -V</userinput>
1141       </para>
1142       <para>should result in something like:</para>
1143       <para>
1144         <computeroutput>Python 2.4.3</computeroutput>
1145       </para>
1146       <para>However, the version string may vary.</para>
1147     </section>
1148     <section id="ChToolsWin32Python">
1149       <title>Win32 native: python</title>
1150       <para>Get Python 2.6, 2.5, or 2.4 from
1151       <ulink url="http://python.org/download/" />.
1152       You can download an installation package there, which
1153       will install the Python system in the top level of your
1154       <filename>C:</filename> drive by default, e.g.
1155       <filename>C:\Python26</filename>.</para>
1156       <para>You can check for a successful installation from a command prompt (cmd.exe):</para>
1157       <para>
1158         <prompt>C:\&gt;</prompt>
1159         <userinput>cd python26</userinput>
1160       </para>
1161       <para>
1162         <prompt>C:\Python26&gt;</prompt>
1163         <userinput>python -V</userinput>
1164       </para>
1165       <para>The output should look something like:
1166       <programlisting>
1167         <![CDATA[Python 2.6]]>
1168 </programlisting>However, the version string may vary.</para>
1169     </section>
1170   </section>
1171   <section id="ChToolsPerl">
1172     <title>perl</title>
1173     <para>Perl is an interpreter based programming language. The
1174     homepage of the perl project is:
1175     <ulink url="http://www.perl.com" />. Perl is used to convert
1176     various text files into usable source code. Perl version 5.6
1177     and above should be working fine.</para>
1178     <section id="ChToolsUnixPerl">
1179       <title>UNIX or Win32 Cygwin: perl</title>
1180       <para>Perl is available for most of the UNIX-like platforms
1181       and as the perl package from the
1182       <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
1183       <para>If perl isn't already installed or available
1184       as a package for your platform, you can get it at:
1185       <ulink url="http://www.perl.com/" />.</para>
1186       <para>After correct installation, typing at the
1187       bash command line prompt:</para>
1188       <para>
1189         <prompt>$</prompt>
1190         <userinput>perl --version</userinput>
1191       </para>
1192       <para>should result in something like:
1193       <programlisting>
1194         <![CDATA[This is perl, v5.8.7 built for cygwin-thread-multi-64int
1195 (with 1 registered patch, see perl -V for more detail)
1196
1197 Copyright 1987-2005, Larry Wall
1198
1199 Perl may be copied only under the terms of either the Artistic License or the
1200 GNU General Public License, which may be found in the Perl 5 source kit.
1201
1202 Complete documentation for Perl, including FAQ lists, should be found on
1203 this system using `man perl' or `perldoc perl'.  If you have access to the
1204 Internet, point your browser at http://www.perl.com/, the Perl Home Page.]]>
1205 </programlisting>However, the version string may vary.</para>
1206     </section>
1207     <section id="ChToolsWin32Perl">
1208       <title>Win32 native: perl</title>
1209       <para>A native Win32 perl package can be obtained from
1210       <ulink url="http://www.ActiveState.com" />. The installation
1211       should be straightforward.</para>
1212       <para>After correct installation, typing at the command
1213       line prompt (cmd.exe):</para>
1214       <para>
1215         <prompt>&gt;</prompt>
1216         <userinput>perl -v</userinput>
1217       </para>
1218       <para>should result in something like:
1219       <programlisting>
1220         <![CDATA[This is perl, v5.8.0 built for MSWin32-x86-multi-thread
1221 (with 1 registered patch, see perl -V for more detail)
1222
1223 Copyright 1987-2002, Larry Wall
1224
1225 Binary build 805 provided by ActiveState Corp. http://www.ActiveState.com
1226 Built 18:08:02 Feb  4 2003
1227
1228 ...]]>
1229 </programlisting>However, the version string may vary.</para>
1230     </section>
1231   </section>
1232   <section id="ChToolsSed">
1233     <title>sed</title>
1234     <para>Sed it the streaming editor. It makes it easy for example
1235     to replace specially marked texts inside a source code file.
1236     The Wireshark build process uses this to stamp version strings
1237     into various places.</para>
1238     <section id="ChToolsUnixSed">
1239       <title>UNIX or Win32 Cygwin: sed</title>
1240       <para>Sed is available for most of the UNIX-like platforms
1241       and as the sed package from the
1242       <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
1243       <para>If sed isn't already installed or available
1244       as a package for your platform, you can get it at:
1245       <ulink url="http://directory.fsf.org/GNU/sed.html" /></para>
1246       <para>After correct installation, typing at the
1247       bash command line prompt:</para>
1248       <para>
1249         <prompt>$</prompt>
1250         <userinput>sed --version</userinput>
1251       </para>
1252       <para>should result in something like:
1253       <programlisting>
1254         <![CDATA[GNU sed version 4.1.5
1255 Copyright (C) 2003 Free Software Foundation, Inc.
1256 This is free software; see the source for copying conditions.  There is NO
1257 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE,
1258 to the extent permitted by law.]]>
1259 </programlisting>However, the version string may vary.</para>
1260     </section>
1261     <section id="ChToolsWin32Sed">
1262       <title>Win32 native: sed</title>
1263       <para>A native Win32 sed package can be obtained from
1264       <ulink url="http://gnuwin32.sourceforge.net/" />. The
1265       installation should be straightforward.</para>
1266     </section>
1267   </section>
1268   <section id="ChToolsYacc">
1269     <title>yacc (bison)</title>
1270     <para>Bison is a free implementation of yacc.</para>
1271     <section id="ChToolsUnixYacc">
1272       <title>UNIX or Win32 Cygwin: bison</title>
1273       <para>Bison is available for most of the UNIX-like platforms
1274       and as the bison package from the
1275       <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
1276       <para>If GNU Bison isn't already installed or
1277       available as a package for your platform, you can get it at:
1278       <ulink url="http://www.gnu.org/software/bison/bison.html" />.</para>
1279       <para>After correct installation, typing at the
1280       bash command line prompt:</para>
1281       <para>
1282         <prompt>$</prompt>
1283         <userinput>bison --version</userinput>
1284       </para>
1285       <para>should result in something like:
1286       <programlisting>
1287         <![CDATA[bison (GNU Bison) 2.3
1288 Written by Robert Corbett and Richard Stallman.
1289
1290 Copyright (C) 2006 Free Software Foundation, Inc.
1291 This is free software; see the source for copying conditions.  There is NO
1292 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.]]>
1293 </programlisting>However, the version string may vary.</para>
1294     </section>
1295     <section id="ChToolsWin32Yacc">
1296       <title>Win32 native: bison</title>
1297       <para>A native Win32 yacc/bison package can be obtained from
1298       <ulink url="http://gnuwin32.sourceforge.net/" />. The
1299       installation should be straightforward.</para>
1300     </section>
1301   </section>
1302   <section id="ChToolsLexx">
1303     <title>flex</title>
1304     <para>Flex is a free implementation of lexx.</para>
1305     <section id="ChToolsUnixLexx">
1306       <title>UNIX or Win32 Cygwin: flex</title>
1307       <para>Flex is available for most of the UNIX-like platforms
1308       and as the flex package from the
1309       <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
1310       <para>If GNU flex isn't already installed or
1311       available as a package for your platform, you can get it at:
1312       <ulink url="http://www.gnu.org/software/flex/" />.</para>
1313       <para>After correct installation, typing at the
1314       bash command line prompt:</para>
1315       <para>
1316         <prompt>$</prompt>
1317         <userinput>flex --version</userinput>
1318       </para>
1319       <para>should result in something like:
1320       <programlisting>
1321         <![CDATA[flex version 2.5.4]]>
1322 </programlisting>However, the version string may vary.</para>
1323     </section>
1324     <section id="ChToolsWin32Lexx">
1325       <title>Win32 native: flex</title>
1326       <para>A native Win32 lexx/flex package can be obtained from
1327       <ulink url="http://gnuwin32.sourceforge.net/" />. The
1328       installation should be straightforward.</para>
1329     </section>
1330   </section>
1331   <section id="ChToolsSubversion">
1332     <title>Subversion (SVN) client (optional)</title>
1333     <para>The Wireshark project uses its own Subversion (or short
1334     SVN) server to keep track of all the changes done to the source
1335     code. Details about the usage of Subversion in the Wireshark
1336     project can be found in
1337     <xref linkend="ChSrcSVNServer" />.</para>
1338     <para>If you want to work with the source code and are planning to
1339     commit your changes back to the Wireshark community, it is
1340     recommended to use a SVN client to get the latest source files.
1341     For detailed information about the different ways to obtain the
1342     Wireshark sources, see
1343     <xref linkend="ChSrcObtain" />.</para>
1344     <para>You will find more instructions in
1345     <xref linkend="ChSrcAnon" /> on how to use the Subversion
1346     client.</para>
1347     <section id="ChToolsUnixSVN">
1348       <title>UNIX or Win32 Cygwin: svn</title>
1349       <para>SVN is available for most of the UNIX-like platforms
1350       and as the Subversion package from the
1351       <link linkend="ChToolsCygwin">Cygwin setup</link></para>
1352       <para>If Subversion isn't already installed or
1353       available as a package for your platform, you can get it at:
1354       <ulink url="http://subversion.tigris.org/" /> (together with
1355       the server software).</para>
1356       <para>After correct installation, typing at the
1357       bash command line prompt:</para>
1358       <para>
1359         <prompt>$</prompt>
1360         <userinput>svn --version</userinput>
1361       </para>
1362       <para>should result in something like:
1363       <programlisting>
1364         <![CDATA[svn, version 1.0.5 (r9954)
1365    compiled Jun 20 2004, 23:28:30
1366
1367 Copyright (C) 2000-2004 CollabNet.
1368 Subversion is open source software, see http://subversion.tigris.org/
1369 This product includes software developed by CollabNet (http://www.Collab.Net/).
1370
1371 ...]]>
1372 </programlisting>However, the version string may vary.</para>
1373     </section>
1374     <section id="ChToolsWin32SVN">
1375       <title>Win32 native: svn</title>
1376       <para>The Subversion command line tools for Win32 can be
1377       found at:
1378       <ulink url="http://subversion.tigris.org/" />. This will come
1379       with both client and server software - only the client
1380       software will be used.</para>
1381       <para>After correct installation, typing at the command
1382       line prompt (cmd.exe):</para>
1383       <para>
1384         <prompt>&gt;</prompt>
1385         <userinput>svn --version</userinput>
1386       </para>
1387       <para>should result in something like:
1388       <programlisting>
1389         <![CDATA[svn, Version 1.4.0 (r21228)
1390
1391 Copyright (C) 2000-2006 CollabNet.
1392 ...]]>
1393 </programlisting>However, the version string may vary.</para>
1394     </section>
1395   </section>
1396   <section id="ChToolsSubversionGUI">
1397     <title>Subversion (SVN) GUI client (optional)</title>
1398     <para>Along with the traditional command-line client, several
1399     GUI clients are available for a number of platforms, see
1400     <ulink url="http://subversion.tigris.org/project_links.html" />.</para>
1401     <warning>
1402       <title>Keep Subversion program versions in sync!</title>
1403       <para>If you are working with both command line and GUI
1404       clients, keep the Subversion program versions in sync, at
1405       least the major/minor versions (e.g. 1.4).</para>
1406     </warning>
1407     <section id="ChToolsUnixSVNGUI">
1408       <title>UNIX or Win32 Cygwin: rapidSVN, subcommander</title>
1409       <para>RapidSVN is a cross platform Subversion frontend based
1410       on wxWidgets. It can be found at:
1411       <ulink url="http://rapidsvn.tigris.org/" />. Subcommander is
1412       another cross platform Subversion frontend. It can be found
1413       at:
1414       <ulink url="http://subcommander.tigris.org/" />.</para>
1415       <para>Cygwin doesn't provide any GUI client for
1416       Subversion.</para>
1417     </section>
1418     <section id="ChToolsTortoiseSVN">
1419       <title>Win32 native: TortoiseSVN</title>
1420       <para>A good Subversion client for Win32 can be found at:
1421       <ulink url="http://tortoisesvn.tigris.org/" />. It will
1422       nicely integrate into the Windows Explorer window.</para>
1423     </section>
1424   </section>
1425   <section id="ChToolsDiff">
1426     <title>diff (optional)</title>
1427     <para>Diff is used to get a file of all differences between two
1428     source files/trees (sometimes called a patch). The diff tool
1429     isn't needed for building Wireshark, but it's needed if you are
1430     going to commit your changes back to the Wireshark
1431     community.</para>
1432     <note>
1433       <title>Note!</title>
1434       <para>The recommended way to build patches is using the
1435       Subversion client, see
1436       <xref linkend="ChToolsSubversion" /> for details.</para>
1437     </note>
1438     <para>You will find more instructions in
1439     <xref linkend="ChSrcDiff" /> on how to use the diff tool.</para>
1440     <section id="ChToolsGNUDiff">
1441       <title>UNIX or Win32 Cygwin: GNU diff</title>
1442       <para>Diff is available for most of the UNIX-like platforms
1443       and as the diffutils package from the
1444       <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
1445       <para>If GNU diff isn't already installed or
1446       available as a package for your platform, you can get it at:
1447       <ulink url="http://www.gnu.org/software/diffutils/diffutils.html" />.</para>
1448       <para>After correct installation, typing at the
1449       bash command line prompt:</para>
1450       <para>
1451         <prompt>$</prompt>
1452         <userinput>diff --version</userinput>
1453       </para>
1454       <para>should result in something like:
1455       <programlisting>
1456         <![CDATA[diff (GNU diffutils) 2.8.7
1457 Written by Paul Eggert, Mike Haertel, David Hayes,
1458 Richard Stallman, and Len Tower.
1459
1460 Copyright (C) 2004 Free Software Foundation, Inc.
1461 This is free software; see the source for copying conditions.  There is NO
1462 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.]]>
1463 </programlisting>However, the version string may vary.</para>
1464     </section>
1465     <section id="ChToolsWin32Diff">
1466       <title>Win32 native: diff</title>
1467       <para>A native Win32 diff package can be obtained from
1468       <ulink url="http://gnuwin32.sourceforge.net/" />. The
1469       installation should be straightforward.</para>
1470       <para>The Subversion client TortoiseSVN has a built-in diff
1471       feature, see
1472       <xref linkend="ChToolsTortoiseSVN" />. It is currently unknown
1473       if this tool can be used to
1474       create diff files in the required format, so other persons
1475       can use them.</para>
1476     </section>
1477   </section>
1478   <section id="ChToolsPatch">
1479     <title>patch (optional)</title>
1480     <para>The patch utility is used to merge a diff file into your
1481     own source tree. This tool is only needed, if you want to apply
1482     a patch (diff file) from someone else (probably from the
1483     developer mailing list) to try out in your own private source
1484     tree.</para>
1485     <tip>
1486       <title>Tip!</title>
1487       <para>Unless you are in the rare case needing to apply a
1488       patch to your private source tree, you won't need the patch
1489       tool installed.</para>
1490     </tip>
1491     <para>You will find more instructions in
1492     <xref linkend="ChSrcPatchApply" /> on how to use the patch
1493     tool.</para>
1494     <section id="ChToolsUnixPatch">
1495       <title>UNIX or Win32 Cygwin: patch</title>
1496       <para>Patch is available for most of the UNIX-like platforms
1497       and as the patch package from the
1498       <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
1499       <para>If GNU patch isn't already installed or
1500       available as a package for your platform, you can get it at:
1501       <ulink url="http://www.gnu.org/software/patch/patch.html" />.</para>
1502       <para>After correct installation, typing at the
1503       bash command line prompt:</para>
1504       <para>
1505         <prompt>$</prompt>
1506         <userinput>patch --version</userinput>
1507       </para>
1508       <para>should result in something like:
1509       <programlisting>
1510         <![CDATA[patch 2.5.8
1511 Copyright (C) 1988 Larry Wall
1512 Copyright (C) 2002 Free Software Foundation, Inc.
1513
1514 This program comes with NO WARRANTY, to the extent permitted by law.
1515 You may redistribute copies of this program
1516 under the terms of the GNU General Public License.
1517 For more information about these matters, see the file named COPYING.
1518
1519 written by Larry Wall and Paul Eggert]]>
1520 </programlisting>However, the version string may vary.</para>
1521     </section>
1522     <section id="ChToolsWin32Patch">
1523       <title>Win32 native: patch</title>
1524       <para>A native Win32 patch package can be obtained from
1525       <ulink url="http://gnuwin32.sourceforge.net/" />. The
1526       installation should be straightforward.</para>
1527       <para>The Subversion client TortoiseSVN has a built-in patch
1528       feature, see
1529       <xref linkend="ChToolsTortoiseSVN" />. The last time tested
1530       (Version 1.1.0), this feature failed to apply patches known
1531       to be ok.</para>
1532     </section>
1533   </section>
1534   <section id="ChToolsWget">
1535     <title>Win32: GNU wget (optional)</title>
1536     <para>GNU wget is used to download files from the internet
1537     using the command line.</para>
1538     <para>GNU wget is available for most of the UNIX-like platforms
1539     and as the wget package from the
1540     <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
1541     <para>You will only need wget, if you want to use the Win32
1542     automated library download, see
1543     <xref linkend="ChLibsSetup" /> for details.</para>
1544     <para>If GNU wget isn't already installed or
1545     available as a package for your platform (well, for Win32 it is
1546     available as a Cygwin package), you can get it at:
1547     <ulink url="http://www.gnu.org/software/wget/wget.html" />.</para>
1548     <para>If wget is trying to download files but fails to do so,
1549     your Internet connection might use an HTTP proxy. Some Internet
1550     providers use such a proxy and it is common in many company
1551     networks today. Wireshark's setup script will try to discover
1552     your proxy settings automatically, but you you may need to set
1553     the environment variable HTTP_PROXY by hand before using wget.
1554     For example, if you are behind proxy.com which is listening on
1555     port 8080, you have to set it to something like:</para>
1556     <para>
1557       <programlisting>set
1558       HTTP_PROXY=http://proxy.com:8080/</programlisting>
1559     </para>
1560     <para>If you are unsure about the settings, you might ask your
1561     system administrator.</para>
1562   </section>
1563   <section id="ChToolsUnzip">
1564     <title>Win32: GNU unzip (optional)</title>
1565     <para>GNU unzip is used to, well, unzip the zip files
1566     downloaded using the wget tool.</para>
1567     <para>GNU unzip is available for most of the UNIX-like platforms
1568     and as the unzip package from the
1569     <link linkend="ChToolsCygwin">Cygwin setup</link>.</para>
1570     <para>You will only need unzip, if you want to use the Win32
1571     automated library download, see
1572     <xref linkend="ChLibsSetup" /> for details.</para>
1573     <para>If GNU unzip isn't already installed or
1574     available as a package for your platform (well, for Win32 it is
1575     available as a Cygwin package), you can get it at:
1576     <ulink url="http://gnuwin32.sourceforge.net/packages/unzip.htm" />.</para>
1577   </section>
1578   <section id="ChToolsNSIS">
1579     <title>Win32: NSIS (optional)</title>
1580     <para>The NSIS (Nullsoft Scriptable Install System) is used to
1581     generate a wireshark-setup-&lt;version&gt;.exe from all the
1582     files needed to be installed, including all required DLL's and
1583     such.</para>
1584     <para>To install it, simply download the latest released
1585     version (currently: 2.28) from
1586     <ulink url="http://nsis.sourceforge.net" /> and start the
1587     downloaded installer. You will need NSIS version 2 final or
1588     higher.</para>
1589     <para>You will find more instructions in
1590     <xref linkend="ChSrcNSIS" /> on how to use the NSIS tool.</para>
1591   </section>
1592 </chapter>
1593 <!-- End of WSDG Chapter Tools -->