docbook/dg-src/EDG_chapter_tools.xml

   1 <!-- EDG Chapter Tools -->
   2 <!-- $Id$ -->
   3
   4 <chapter id="ChapterTools">
   5   <title>Tools</title>
   6   <section id="ChToolsIntro">
   7     <title>Introduction</title>
   8         <para>
   9         This chapter will provide you with information how to install
  10         the various tools needed for Ethereal development.
  11         </para>
  12         <para>
  13         None of the tools mentioned in this chapter is needed to run Ethereal,
  14         they are only needed to build it.
  15         </para>
  16         <para>
  17         All these tools have
  18         their roots on unix like platforms, but win32 ports are also
  19         available. Therefore the tools are available in different "flavours":
  20         <itemizedlist>
  21         <listitem>
  22         <para>
  23         Unix: as described above, the tools should be commonly available on the
  24         supported unix platforms, and for win32 platforms by the cygwin unix
  25         emulation
  26         </para>
  27         </listitem>
  28         <listitem>
  29         <para>
  30         Win32 native: some tools are available as native Win32 tools, no
  31         emulation is required
  32         </para>
  33         </listitem>
  34         </itemizedlist>
  35         </para>
  36         <para>
  37         The following sections will only do a very brief description of
  38         what the particular tool is doing, how it is used in the Ethereal project
  39         and how it can be installed and tested.
  40         </para>
  41         <para>
  42         Don't expect a lot of documentation regarding these tools in this
  43         document. If you need further documentation of a specific tool, you
  44         should find lot's of useful information on the web, as these tools are
  45         commonly used. As all of the tools are command line tools, you can try
  46         to get help with <userinput>toolname --help</userinput> or read
  47         the manpage <userinput>man toolname</userinput>.
  48         </para>
  49         <para>
  50         You will find explanations of the tool usage for some of the specific
  51         development tasks in <xref linkend="ChapterSources"/>.
  52         </para>
  53         <para>
  54         Some recommendations are given for the
  55         easiest way to get a win32 development platform up and running, see
  56         <xref linkend="ChToolsWin32Recommended"/>.
  57         </para>
  58   </section>
  59
  60   <section id="ChToolsInstall">
  61         <title>Installation</title>
  62         <para>
  63         The installation of the tools depend on the platform you use:
  64         </para>
  65
  66         <section id="ChToolsInstallUnix">
  67         <title>Unix</title>
  68         <para>
  69         All the tools required are usually installed on a unix developer machine.
  70         </para>
  71         <para>
  72         If a tool is not already installed on your system, you will typically use
  73         the installation package from your distribution.
  74         </para>
  75         <para>
  76         If an install package is not available, or you have a reason not to use
  77         it (maybe because it's simply too old), you can install that tool
  78         from source code, the following sections will provide you with the webpage
  79         addresses where you can get these sources.
  80         </para>
  81         </section>
  82
  83         <section id="ChToolsInstallWin32Native">
  84         <title>Win32 Native</title>
  85         <para>
  86         The native tools will typically be a bit faster, but more complicated to
  87         install. You will have to download a lot of tools from different webpages,
  88         and install them in the ways they have to be installed. The default
  89         installation location will typically not be the
  90         <filename>c:\program files</filename> folder. Have a look at
  91         <xref linkend="ChToolsWin32Recommended"/> for an overview of the
  92         recommended tools.
  93         </para>
  94         </section>
  95
  96         <section id="ChToolsInstallCygwin">
  97         <title>Win32 Cygwin</title>
  98         <para>
  99         Installation of the cygwin tools is very simple. As cygwin uses an
 100         unix emulation layer,
 101         it might be a bit slower compared to the native tools, but at an
 102         acceptable level. All tools will be installed into one base folder, the
 103         default is <filename>c:\cygwin</filename>.
 104         </para>
 105         <para>
 106         Cygwin provides a unix emulation layer with a lot of unix based tools
 107         on the win32 platform. Although cygwin consists of several
 108         seperate packages, the installation and update is done through only a
 109         single setup.exe, which acts similar like other web based installers.
 110         </para>
 111         <para>
 112         You will find this network based setup.exe at: <ulink
 113         url="http://www.cygwin.com/"/> click on one
 114         of the "Install Cygwin now" appearances, this will start the download
 115         of the setup.exe.
 116         </para>
 117         <para>
 118         After the download completed, start this setup.exe on your machine. It
 119         will ask you for some
 120         settings, the defaults should usually work well. The setup will
 121         then download and install a basic set of packages.
 122         </para>
 123         <para>
 124         Under: "Start -&gt; Programs -&gt; Cygwin -&gt; Cygwin Bash Shell" you
 125         should now be able to start a new cygwin bash shell, which is similar to
 126         the command line (command.exe/cmd.exe) in win32, but much more powerful.
 127         </para>
 128         <para>
 129         If you want to add additional, update installed or remove packages, you
 130         should start the setup.exe again. At the "Select Packages" page, the
 131         entry in the "New" column will control what is done (or not) with the
 132         package. If a new version of a package is available, the new version
 133         number will be displayed, so it will be automatically updated. You can
 134         change the current setting by simply clicking at it, it will change
 135         between:
 136         <itemizedlist>
 137         <listitem>
 138         <para>
 139         a specific version number - this different package version will be
 140         installed
 141         </para>
 142         </listitem>
 143         <listitem>
 144         <para>
 145         Skip - not installed, no changes
 146         </para>
 147         </listitem>
 148         <listitem>
 149         <para>
 150         Keep - already installed, no changes
 151         </para>
 152         </listitem>
 153         <listitem>
 154         <para>
 155         Uninstall - uninstall this package
 156         </para>
 157         </listitem>
 158         <listitem>
 159         <para>
 160         Reinstall - reinstall this package
 161         </para>
 162         </listitem>
 163         </itemizedlist>
 164         </para>
 165         <para>
 166         You will find a list of required / recommended packages needed to develop
 167         Ethereal in <xref linkend="ChToolsWin32Recommended"/>.
 168         </para>
 169         </section>
 170
 171   </section>
 172
 173         <section id="ChToolsWin32Recommended">
 174         <title>Win32: Recommended tools</title>
 175         <para>
 176         As there are different forms of the Win32 tools available, the following
 177         will give an overview of the recommended tools (which are highlighted in
 178         bold face).
 179
 180         <table frame='all'><title>The mandatory tools</title>
 181         <tgroup cols='3' align='left' colsep='1' rowsep='1'>
 182         <colspec colname='c1'/>
 183         <colspec colname='c2'/>
 184         <colspec colname='c3'/>
 185         <thead>
 186         <row>
 187           <entry>Tool</entry>
 188           <entry><link linkend="ChToolsInstallCygwin">Cygwin</link> packet</entry>
 189           <entry>Win32 native</entry>
 190         </row>
 191         </thead>
 192         <tbody>
 193         <row>
 194           <entry><xref linkend="ChToolsBash"/></entry>
 195           <entry><command>bash</command></entry>
 196           <entry>-</entry>
 197         </row>
 198         <row>
 199           <entry><xref linkend="ChToolsCompiler"/></entry>
 200           <entry>gcc</entry>
 201           <entry><command>cl.exe (MSVC)</command></entry>
 202         </row>
 203         <row>
 204           <entry><xref linkend="ChToolsDebugger"/></entry>
 205           <entry>DDD</entry>
 206           <entry><command>integrated debugger (MSVC)</command></entry>
 207         </row>
 208         <row>
 209           <entry><xref linkend="ChToolsMake"/></entry>
 210           <entry>make</entry>
 211           <entry><command>nmake.exe (MSVC)</command></entry>
 212         </row>
 213         <row>
 214           <entry><xref linkend="ChToolsPython"/></entry>
 215           <entry><command>python</command></entry>
 216           <entry><ulink url="http://python.org/download/"/></entry>
 217         </row>
 218         <row>
 219           <entry><xref linkend="ChToolsPerl"/></entry>
 220           <entry><command>perl</command></entry>
 221           <entry><ulink url="http://www.ActiveState.com"/></entry>
 222         </row>
 223         <row>
 224           <entry><xref linkend="ChToolsSed"/></entry>
 225           <entry><command>sed</command></entry>
 226           <entry>-</entry>
 227         </row>
 228         <row>
 229           <entry><xref linkend="ChToolsYacc"/></entry>
 230           <entry><command>yacc</command></entry>
 231           <entry>-</entry>
 232         </row>
 233         <row>
 234           <entry><xref linkend="ChToolsLexx"/></entry>
 235           <entry><command>lexx</command></entry>
 236           <entry>-</entry>
 237         </row>
 238         </tbody>
 239         </tgroup>
 240         </table>
 241
 242         <table frame='all'><title>The optional tools</title>
 243         <tgroup cols='3' align='left' colsep='1' rowsep='1'>
 244         <colspec colname='c1'/>
 245         <colspec colname='c2'/>
 246         <colspec colname='c3'/>
 247         <thead>
 248         <row>
 249           <entry>Tool</entry>
 250           <entry><link linkend="ChToolsInstallCygwin">Cygwin</link> packet</entry>
 251           <entry>Win32 native</entry>
 252         </row>
 253         </thead>
 254         <tbody>
 255         <row>
 256           <entry><xref linkend="ChToolsSubversion"/></entry>
 257           <entry>svn</entry>
 258           <entry><command><ulink url="http://tortoisesvn.tigris.org/">TortoiseSVN</ulink></command></entry>
 259         </row>
 260         <row>
 261           <entry><xref linkend="ChToolsDiff"/></entry>
 262           <entry><command>diff</command></entry>
 263           <entry>-</entry>
 264         </row>
 265         <row>
 266           <entry><xref linkend="ChToolsPatch"/></entry>
 267           <entry><command>patch</command></entry>
 268           <entry>-</entry>
 269         </row>
 270         <row>
 271           <entry><xref linkend="ChToolsWget"/></entry>
 272           <entry><command>wget</command></entry>
 273           <entry>-</entry>
 274         </row>
 275         <row>
 276           <entry><xref linkend="ChToolsNSIS"/></entry>
 277           <entry>-</entry>
 278           <entry>
 279           <command><ulink url="http://nsis.sourceforge.net">NSIS</ulink></command>
 280           </entry>
 281         </row>
 282         </tbody>
 283         </tgroup>
 284         </table>
 285         XXX - mark, which cygwin packages are installed by default.
 286         </para>
 287         </section>
 288
 289         <section id="ChToolsBash">
 290         <title>bash</title>
 291         <para>
 292         The bash shell is needed to run several shell scripts.
 293         </para>
 294
 295         <section id="ChToolsGNUBash">
 296         <title>Unix: GNU bash</title>
 297         <para>
 298         The bash is available for most of the unix-like platforms and as the
 299         <application>bash</application> package from the <link
 300         linkend="ChToolsInstallCygwin">Cygwin setup</link>.
 301         </para>
 302         <para>
 303         If the bash isn't already installed and also not available as a package
 304         for your platform, you can get it at:
 305         <ulink url="http://www.gnu.org/software/bash/bash.html"/>.
 306         </para>
 307         <para>
 308         After correct installation, typing inside any shell:
 309         </para>
 310         <para>
 311         <prompt>$</prompt> <userinput>bash --version</userinput>
 312         </para>
 313         <para>
 314         should result in something like:
 315         <programlisting>
 316 <![CDATA[GNU bash, version 2.05b.0(1)-release (i686-pc-cygwin)
 317 Copyright (C) 2002 Free Software Foundation, Inc.]]>
 318         </programlisting>
 319         However, the version string may vary.
 320         </para>
 321         </section>
 322
 323         <section id="ChToolsWin32Bash">
 324         <title>Win32 native: -</title>
 325         <para>
 326         The authors don't know of any working win32 native bash implementation.
 327         </para>
 328         </section>
 329
 330         </section>
 331
 332         <section id="ChToolsCompiler">
 333         <title>C compiler</title>
 334
 335         <section id="ChToolsGCC">
 336         <title>Unix: GCC (GNU compiler collection)</title>
 337         <note><title>Win32 Note!</title>
 338         <para>
 339         Although some effort is currently made to use gcc from the cygwin
 340         environment, the mainline for several reasons is still using Microsoft
 341         Visual Studio's C compiler.
 342         </para>
 343         </note>
 344         <para>
 345         The gcc C compiler is available for most of the unix-like platforms and
 346         as the <application>gcc</application> package from the <link
 347         linkend="ChToolsInstallCygwin">Cygwin setup</link>.
 348         </para>
 349         <para>
 350         If gcc isn't already installed and also not available as a package
 351         for your platform, you can get it at:
 352         <ulink url="http://gcc.gnu.org/"/>.
 353         </para>
 354         <para>
 355         After correct installation, typing inside the bash:
 356         </para>
 357         <para>
 358         <prompt>$</prompt> <userinput>gcc --version</userinput>
 359         </para>
 360         <para>
 361         should result in something like:
 362         <programlisting>
 363 <![CDATA[gcc (GCC) 3.3.3 (cygwin special)
 364 Copyright (C) 2003 Free Software Foundation, Inc.
 365 This is free software; see the source for copying conditions.  There is NO
 366 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.]]>
 367         </programlisting>
 368         However, the version string may vary.
 369         </para>
 370         </section>
 371
 372         <section id="ChToolsMSVC6">
 373         <title>Win32 native: Microsoft Visual Studio version 6 C compiler</title>
 374         <para>
 375         <note><title>Note!</title>
 376         <para>
 377         The Microsoft Visual Studio is not free software.
 378         This is a tool you have to buy before you use it!
 379         </para>
 380         </note>
 381         </para>
 382         <para>
 383         The mainline for generating Ethereal on the windows platform, is using
 384         the compiler cl.exe from the Microsoft Visual Studio version 6 (and it's
 385         nmake, as described below).
 386         </para>
 387         <para>
 388         After correct installation, typing inside the command line (cmd.exe):
 389         </para>
 390         <para>
 391         <prompt>&gt;</prompt> <userinput>cl</userinput>
 392         </para>
 393         <para>
 394         should result in something like:
 395         <programlisting>
 396 <![CDATA[Optimierender Microsoft (R) 32-Bit C/C++-Compiler, Version 12.00.8804, fuer x86
 397 Copyright (C) Microsoft Corp 1984-1998. Alle Rechte vorbehalten.
 398
 399 Verwendung: cl [ Option... ] Dateiname... [ /link Linker-Option... ]]]>
 400         </programlisting>
 401         However, the version string may vary.
 402         </para>
 403         </section>
 404
 405         <section id="ChToolsMSVC7">
 406         <title>Win32 native: Microsoft Visual Studio .NET (and alike) C compilers
 407         </title>
 408         <para>
 409         <warning><title>Warning!</title>
 410         <para>
 411         The recent "Microsoft Visual Studio .NET" C compiler(s) currently cannot
 412         be used to compile Ethereal!!!
 413         </para>
 414         </warning>
 415         </para>
 416         <para>
 417         The following is a problem summary for:
 418         <itemizedlist>
 419         <listitem><para>
 420         Microsoft Visual Studio .NET
 421         </para></listitem>
 422         <listitem><para>
 423         Microsoft Visual C++ .NET
 424         </para></listitem>
 425         <listitem><para>
 426         Microsoft Visual C++ Toolkit 2003, freely available at: <ulink url="http://msdn.microsoft.com/visualc/vctoolkit2003/"/>
 427         </para></listitem>
 428         </itemizedlist>
 429         All containing version 7 or later of Microsoft's C compiler.
 430         </para>
 431         <para>
 432         It is reported that this compiler requires to ship a MSVCRT70.dll together
 433         with the compiled exe, which contains the C runtime library. This
 434         conflicts, as all required libraries currently compiled with (and uses)
 435         MSVCRT.dll (the older version 6 one).
 436         </para>
 437         <para>
 438         Example why this hurts: A dependant library might try to open a file using
 439         functions in MSVCRT.dll which creates an internal file handle and keeps
 440         information about that file. When Ethereal tries to read data from that
 441         file, it uses the functions from MSVCRT70.dll, which doesn't know anything
 442         about that previously opened file and returns an error code.
 443         </para>
 444         <para>
 445         There where also attempts to bring the compiler to use only the old
 446         MSVCRT.dll but they seemed to fail :-(
 447         </para>
 448         <para>
 449         It's also still unsure, if shipping the MSVCRT70.dll together with Ethereal
 450         is compatible with the GPL license at all.
 451         </para>
 452         <note><title>Note!</title>
 453         <para>
 454         This isn't an Ethereal specific problem. Any software project trying to use
 455         the version 7 C compiler will have the problems described above!
 456         </para>
 457         </note>
 458         <para>
 459         XXX - what about the legal issue, as the MSVCRT70.dll had to be shipped
 460         with Ethereal.
 461         </para>
 462         </section>
 463
 464         </section>
 465
 466         <section id="ChToolsDebugger">
 467         <title>Debugger</title>
 468         <para>
 469         Well, using a good debugger can save you a lot of development time. However
 470         some people still think it's use is optional.
 471         </para>
 472         <para>
 473         The debugger you use must match the C compiler Ethereal was compiled with,
 474         otherwise the debugger will simply fail or you will only see a lot of
 475         garbage.
 476         </para>
 477
 478         <section id="ChToolsGDB">
 479         <title>Unix: GNU gdb</title>
 480         <para>
 481         gdb is the debugger for the gcc compiler. It is available for many (if
 482         not all) unix-like platforms and as the <application>gdb</application>
 483         package from the <link
 484         linkend="ChToolsInstallCygwin">Cygwin setup</link>
 485         </para>
 486         <para>
 487         If you don't like debugging using the command line, there are some GUI
 488         frontends for it available, most notably GNU DDD.
 489         </para>
 490         <para>
 491         If gdb isn't already installed and also not available as a package for
 492         your platform, you can get it at:
 493         <ulink url="http://www.gnu.org/software/gdb/gdb.html"/>.
 494         </para>
 495         <para>
 496         After correct installation, typing inside the bash:
 497         </para>
 498         <para>
 499         <prompt>$</prompt> <userinput>gdb --version</userinput>
 500         </para>
 501         <para>
 502         should result in something like:
 503         <programlisting>
 504 <![CDATA[
 505 GNU gdb 2003-09-20-cvs (cygwin-special)
 506 Copyright 2003 Free Software Foundation, Inc.
 507 GDB is free software, covered by the GNU General Public License, and you are
 508 welcome to change it and/or distribute copies of it under certain conditions.
 509 Type "show copying" to see the conditions.
 510 There is absolutely no warranty for GDB.  Type "show warranty" for details.
 511 This GDB was configured as "i686-pc-cygwin".]]>
 512         </programlisting>
 513         However, the version string may vary.
 514         </para>
 515         </section>
 516
 517         <section id="ChToolsDDD">
 518         <title>Unix: GNU DDD</title>
 519         <para>
 520         The GNU Data Display Debugger is a good GUI frontend for gdb (and a lot of
 521         other command line debuggers), so you have to install gdb first. It is
 522         available for many unix-like platforms and as the
 523         <application>ddd</application> package from the <link
 524         linkend="ChToolsInstallCygwin">Cygwin setup</link>.
 525         </para>
 526         <para>
 527         If GNU DDD isn't already installed and also not available as a package for
 528         your platform, you can get it at:
 529         <ulink url="http://www.gnu.org/software/ddd/"/>.
 530         </para>
 531         </section>
 532
 533         <section id="ChToolsMSVCDebugger">
 534         <title>Win32 native: Microsoft Visual Studio debugger</title>
 535         <para>
 536         You can use the integrated debugger of Visual Studio.
 537         </para>
 538         <para>
 539         However, setting up
 540         the environment is a bit tricky, as the win32 build process is using
 541         makefiles instead of the .dsp/.dsw files usually used.
 542         XXX - add instructions how to do it.
 543         </para>
 544         </section>
 545
 546         <section id="ChToolsMSDebuggingTools">
 547         <title>Win32 native: Microsoft Debugging Tools for Windows</title>
 548         <para>
 549         You could also use the Microsoft debugging tools, which is a GUI debugger.
 550         As it's not that comfortable compared to debugging in visual studio, it
 551         can be helpful if you have to debug on a different machine.
 552         </para>
 553         <para>
 554         You can get it free of charge at: <ulink
 555         url="http://www.microsoft.com/whdc/devtools/debugging/default.mspx"/> (as
 556         links to microsoft pages changes from time to time, search for
 557         "Debugging Tools" at their page if this link should be outdated).
 558         </para>
 559         </section>
 560
 561         </section>
 562
 563         <section id="ChToolsMake">
 564         <title>make</title>
 565
 566         <section id="ChToolsGNUmake">
 567         <title>Unix: GNU make</title>
 568         <note><title>Win32 Note!</title>
 569         <para>
 570         Although some effort is made to use make from the cygwin environment,
 571         the mainline is still using Microsoft Visual Studio's nmake.
 572         </para>
 573         </note>
 574         <para>
 575         GNU make is available for most of the unix-like platforms and
 576         also as the <application>make</application> package from the <link
 577         linkend="ChToolsInstallCygwin">Cygwin setup</link>.
 578         </para>
 579         <para>
 580         If GNU make isn't already installed and also not available as a package
 581         for your platform, you can get it at:
 582         <ulink url="http://www.gnu.org/software/make/"/>.
 583         </para>
 584         <para>
 585         After correct installation, typing inside the bash:
 586         </para>
 587         <para>
 588         <prompt>$</prompt> <userinput>make --version</userinput>
 589         </para>
 590         <para>
 591         should result in something like:
 592         <programlisting>
 593 <![CDATA[GNU Make 3.80
 594 Copyright (C) 2002  Free Software Foundation, Inc.
 595 This is free software; see the source for copying conditions.
 596 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
 597 PARTICULAR PURPOSE.]]>
 598         </programlisting>
 599         However, the version string may vary.
 600         </para>
 601         </section>
 602
 603         <section id="ChToolsNmake">
 604         <title>Win32 native: nmake from MSVC</title>
 605         <para>
 606         nmake is part of the Microsoft Visual Studio suite, see comment above.
 607         </para>
 608         <para>
 609         Instead of using the the workspace (.dsw) and projects (.dsp) files,
 610         the     traditional nmake makefiles are used. This has one main reason: it
 611         makes it much easier to maintain changes simultaneous with the gcc
 612         toolchain makefile.am files as both file formats are similar. However, as
 613         no Visual Studio workspace/project files are available, this makes it
 614         hard to use the Visual Studio IDE e.g. for using the integrated
 615         debugging feature.
 616         </para>
 617         <para>
 618         After correct installation, typing inside the command line (cmd.exe):
 619         </para>
 620         <para>
 621         <prompt>&gt;</prompt> <userinput>nmake</userinput>
 622         </para>
 623         <para>
 624         should result in something like:
 625         <programlisting>
 626 <![CDATA[Microsoft (R) Program Maintenance-Dienstprogramm: Version 6.00.9782.0
 627 Copyright (C) Microsoft Corp 1988-1998. Alle Rechte vorbehalten.
 628
 629 NMAKE : fatal error U1064: MAKEFILE nicht gefunden und kein Ziel angegeben
 630 Stop.]]]>
 631         </programlisting>
 632         However, the version string may vary.
 633         </para>
 634         </section>
 635
 636         <section id="ChToolsNmake15">
 637         <title>Win32 native: nmake from microsoft.com</title>
 638         <warning><title>Warning!</title>
 639         <para>
 640         It is recommended to use the Microsoft Visual Studio version 6 to compile
 641         Ethereal for Win32, see <xref linkend="ChToolsCompiler"/>. Don't follow the
 642         instructions in this section, until you now what you are doing.
 643         </para>
 644         </warning>
 645         <para>
 646         NMAKE 1.5 can be downloaded from Microsoft.com if you search for
 647         "KB132084". Unpack the archive by running it, and drop the 3 extracted
 648         files in the MSVC++ Toolkit "bin" directory.
 649         </para>
 650         <para>
 651         You will also need <filename>win32.mak</filename>, which you can get from
 652         the MS Win Platform SDK by browsing to <ulink
 653         url="http://www.microsoft.com/msdownload/platformsdk/sdkupdate/"/>
 654         where you select the "Core SDK" and only tick the "Build Environment"
 655         (31MB) option. After a while, this SDK will be installed.
 656         </para>
 657         <para>
 658         From the start menu, choose "Programs"
 659         -> "Microsoft Platform SDK February 2003"
 660         -> "Open build environment window"
 661         -> (choose your OS Win2K/WinXP/Win2003)
 662         </para>
 663         </section>
 664
 665         </section>
 666
 667
 668         <section id="ChToolsPython">
 669         <title>python</title>
 670         <para>
 671         Python is an interpreter based programming language. The homepage of
 672         the python project is: <ulink url="http://python.org/"/>.
 673         Python is used to XXX. Python version 2.2 and above should be working
 674         fine.
 675         </para>
 676
 677         <section id="ChToolsUnixPython">
 678         <title>Unix: python</title>
 679         <para>
 680         Python is available for most of the unix-like platforms and as the
 681         <application>python</application> package from the <link
 682         linkend="ChToolsInstallCygwin">Cygwin setup</link>
 683         </para>
 684         <para>
 685         If Python isn't already installed and also not available as a package
 686         for your platform, you can get it at:
 687         <ulink url="http://www.python.org/"/>.
 688         </para>
 689         <para>
 690         After correct installation, typing inside the bash:
 691         </para>
 692         <para>
 693         <userinput>$ python -V</userinput>
 694         </para>
 695         <para>
 696         should result in something like:
 697         </para>
 698         <para>
 699         <computeroutput>Python 2.3.3</computeroutput>
 700         </para>
 701         <para>
 702         However, the version string may vary.
 703         </para>
 704         </section>
 705
 706         <section id="ChToolsWin32Python">
 707         <title>Win32 native: python</title>
 708         <para>
 709         Have a look at <ulink url="http://python.org/download/"/>
 710         to download the latest stable release. You can download a setup there,
 711         which will install the python system typically into:
 712         C:\python23 or similiar.
 713         </para>
 714         </section>
 715
 716         </section>
 717
 718
 719         <section id="ChToolsPerl">
 720         <title>perl</title>
 721         <para>
 722         Perl is an interpreter based programming language. The homepage of the
 723         perl project is: <ulink url="http://www.perl.com"/>.
 724         Perl is used to XXX. Perl version XXX and above should be working fine.
 725         </para>
 726
 727         <section id="ChToolsUnixPerl">
 728         <title>Unix: perl</title>
 729         <para>
 730         Perl is available for most of the unix-like platforms and as the
 731         <application>perl</application> package from the <link
 732         linkend="ChToolsInstallCygwin">Cygwin setup</link>.
 733         </para>
 734         <para>
 735         If Perl isn't already installed and also not available as a package
 736         for your platform, you can get it at:
 737         <ulink url="http://www.perl.com/"/>.
 738         </para>
 739         <para>
 740         After correct installation, typing inside the bash:
 741         </para>
 742         <para>
 743         <prompt>$</prompt> <userinput>perl --version</userinput>
 744         </para>
 745         <para>
 746         should result in something like:
 747         <programlisting>
 748 <![CDATA[This is perl, v5.8.5 built for cygwin-thread-multi-64int
 749
 750 Copyright 1987-2004, Larry Wall
 751
 752 Perl may be copied only under the terms of either the Artistic License or the
 753 GNU General Public License, which may be found in the Perl 5 source kit.
 754
 755 Complete documentation for Perl, including FAQ lists, should be found on
 756 this system using `man perl' or `perldoc perl'.  If you have access to the
 757 Internet, point your browser at http://www.perl.com/, the Perl Home Page.]]>
 758         </programlisting>
 759         However, the version string may vary.
 760         </para>
 761
 762         </section>
 763
 764         <section id="ChToolsWin32Perl">
 765         <title>Win32 native: perl</title>
 766         <para>
 767         A native Win32 perl package can be obtained from
 768         <ulink url="http://www.ActiveState.com"/>. The
 769         installation should be straightforward.
 770         </para>
 771         <para>
 772         After correct installation, typing inside the command line (cmd.exe):
 773         </para>
 774         <para>
 775         <prompt>&gt;</prompt> <userinput>perl -v</userinput>
 776         </para>
 777         <para>
 778         should result in something like:
 779         <programlisting>
 780 <![CDATA[This is perl, v5.8.0 built for MSWin32-x86-multi-thread
 781 (with 1 registered patch, see perl -V for more detail)
 782
 783 Copyright 1987-2002, Larry Wall
 784
 785 Binary build 805 provided by ActiveState Corp. http://www.ActiveState.com
 786 Built 18:08:02 Feb  4 2003
 787
 788 ...]]>
 789         </programlisting>
 790         However, the version string may vary.
 791         </para>
 792         </section>
 793
 794         </section>
 795
 796         <section id="ChToolsSed">
 797         <title>sed</title>
 798         <para>
 799         Sed it the streaming editor. It makes it easy for example to replace
 800         specially marked texts inside a source code file. The Ethereal build
 801         process uses this to stamp version strings into various places.
 802         </para>
 803
 804         <section id="ChToolsUnixSed">
 805         <title>Unix: sed</title>
 806         <para>
 807         Sed is available for most of the unix-like platforms and as the
 808         <application>sed</application> package from the <link
 809         linkend="ChToolsInstallCygwin">Cygwin setup</link>.
 810         </para>
 811         <para>
 812         If Sed isn't already installed and also not available as a package
 813         for your platform, you can get it at:
 814         <ulink url="http://sed.sourceforge.net/"/>
 815         (XXX - is this the official home?).
 816         </para>
 817         <para>
 818         After correct installation, typing inside the bash:
 819         </para>
 820         <para>
 821         <prompt>$</prompt> <userinput>sed --version</userinput>
 822         </para>
 823         <para>
 824         should result in something like:
 825         <programlisting>
 826 <![CDATA[GNU sed version 4.0.9
 827 Copyright (C) 2003 Free Software Foundation, Inc.
 828 This is free software; see the source for copying conditions.  There is NO
 829 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE,
 830 to the extent permitted by law.]]>
 831         </programlisting>
 832         However, the version string may vary.
 833         </para>
 834         </section>
 835
 836         <section id="ChToolsWin32Sed">
 837         <title>Win32 native: -</title>
 838         <para>
 839         The authors don't know of any working win32 native sed implementation.
 840         </para>
 841         </section>
 842
 843         </section>
 844
 845         <section id="ChToolsYacc">
 846         <title>yacc (bison)</title>
 847         <para>
 848         Bison is a free implementation of yacc.
 849         </para>
 850
 851         <section id="ChToolsUnixYacc">
 852         <title>Unix: bison</title>
 853         <para>
 854         Bison is available for most of the unix-like platforms and as the
 855         <application>bison</application> package from the <link
 856         linkend="ChToolsInstallCygwin">Cygwin setup</link>.
 857         </para>
 858         <para>
 859         If GNU Bison isn't already installed and also not available as a package
 860         for your platform, you can get it at:
 861         <ulink url="http://www.gnu.org/software/bison/bison.html"/>.
 862         </para>
 863         <para>
 864         After correct installation, typing inside the bash:
 865         </para>
 866         <para>
 867         <prompt>$</prompt> <userinput>bison --version</userinput>
 868         </para>
 869         <para>
 870         should result in something like:
 871         <programlisting>
 872 <![CDATA[bison (GNU Bison) 1.875b
 873 Written by Robert Corbett and Richard Stallman.
 874
 875 Copyright (C) 2003 Free Software Foundation, Inc.
 876 This is free software; see the source for copying conditions.  There is NO
 877 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.]]>
 878         </programlisting>
 879         However, the version string may vary.
 880         </para>
 881         </section>
 882
 883         <section id="ChToolsWin32Yacc">
 884         <title>Win32 native: -</title>
 885         <para>
 886         The authors don't know of any working win32 native yacc/bison
 887         implementation.
 888         </para>
 889         </section>
 890         </section>
 891
 892
 893         <section id="ChToolsLexx">
 894         <title>lexx (flex)</title>
 895         <para>
 896         Flex is a free implementation of lexx.
 897         </para>
 898
 899         <section id="ChToolsUnixLexx">
 900         <title>Unix: flex</title>
 901         <para>
 902         Flex is available for most of the unix-like platforms and as the
 903         <application>flex</application> package from the <link
 904         linkend="ChToolsInstallCygwin">Cygwin setup</link>.
 905         </para>
 906         <para>
 907         If GNU Flex isn't already installed and also not available as a package
 908         for your platform, you can get it at:
 909         <ulink url="http://www.gnu.org/software/flex/"/>.
 910         </para>
 911         <para>
 912         After correct installation, typing inside the bash:
 913         </para>
 914         <para>
 915         <prompt>$</prompt> <userinput>flexx --version</userinput>
 916         </para>
 917         <para>
 918         should result in something like:
 919         <programlisting>
 920 <![CDATA[flex version 2.5.4]]>
 921         </programlisting>
 922         However, the version string may vary.
 923         </para>
 924         </section>
 925
 926         <section id="ChToolsWin32Lexx">
 927         <title>Win32 native: -</title>
 928         <para>
 929         The authors don't know of any working win32 native lexx/flex
 930         implementation.
 931         </para>
 932         </section>
 933         </section>
 934
 935
 936         <section id="ChToolsSubversion">
 937         <title>Subversion (SVN) client (optional)</title>
 938         <para>
 939         The Ethereal project uses it's own subversion (or short SVN) server to keep
 940         track of all the changes done to the source code. Details about the usage
 941         of subversion in the Ethereal project can be found in <xref
 942         linkend="ChSrcSVNServer"/>.
 943         </para>
 944         <para>
 945         If you want to work with the source code and planning to commit your
 946         changes back to the Ethereal community, it is recommended to use a SVN
 947         client to get the latest source files. For detailed information about the
 948         different ways to obtain the Ethereal sources, see
 949         <xref linkend="ChSrcObtain"/>.
 950         </para>
 951         <para>
 952         Along with the traditional command-line client, several GUI clients are
 953         available for a number of platforms, see
 954         <ulink url="http://subversion.tigris.org/project_links.html"/>.
 955         </para>
 956         <para>
 957         You will find more instructions in <xref linkend="ChSrcAnon"/> how to
 958         use the subversion client.
 959         </para>
 960
 961         <section id="ChToolsUnixSVN">
 962         <title>Unix: svn</title>
 963         <para>
 964         SVN is available for most of the unix-like platforms and as the
 965         <application>SVN</application> package from the <link
 966         linkend="ChToolsInstallCygwin">Cygwin setup</link>
 967         </para>
 968         <para>
 969         If Subversion isn't already installed and also not available as a package
 970         for your platform, you can get it at:
 971         <ulink url="http://subversion.tigris.org/"/> (together with the server
 972         software).
 973         </para>
 974         <para>
 975         After correct installation, typing inside the bash:
 976         </para>
 977         <para>
 978         <prompt>$</prompt> <userinput>svn --version</userinput>
 979         </para>
 980         <para>
 981         should result in something like:
 982         <programlisting>
 983 <![CDATA[svn, version 1.0.5 (r9954)
 984    compiled Jun 20 2004, 23:28:30
 985
 986 Copyright (C) 2000-2004 CollabNet.
 987 Subversion is open source software, see http://subversion.tigris.org/
 988 This product includes software developed by CollabNet (http://www.Collab.Net/).
 989
 990 ...]]>
 991         </programlisting>
 992         However, the version string may vary.
 993         </para>
 994         </section>
 995
 996         <section id="ChToolsTortoiseSVN">
 997         <title>Win32 native: TortoiseSVN</title>
 998         <para>
 999         A good subversion client for Win32 can be found at:
1000         <ulink url="http://tortoisesvn.tigris.org/"/>. It will nicely integrate
1001         into the windows Explorer window.
1002         </para>
1003         </section>
1004
1005         </section>
1006
1007         <section id="ChToolsDiff">
1008         <title>diff (optional)</title>
1009         <para>
1010         Diff is used to get a file of all differences between two source
1011         files/trees (sometimes called a patch). The diff tool isn't needed for
1012         building ethereal, but it's needed if you are going to commit your changes
1013         back to the ethereal community.
1014         </para>
1015         <note><title>Note!</title>
1016         <para>
1017         The recommended way to build patches is using the subversion client,
1018         see <xref linkend="ChToolsSubversion"/> for details.
1019         </para>
1020         </note>
1021         <para>
1022         You will find more instructions in <xref linkend="ChSrcDiff"/> how to
1023         use the diff tool.
1024         </para>
1025
1026         <section id="ChToolsGNUDiff">
1027         <title>Unix: GNU diff</title>
1028         <para>
1029         Diff is available for most of the unix-like platforms and as the
1030         <application>diffutils</application> package from the <link
1031         linkend="ChToolsInstallCygwin">Cygwin setup</link>.
1032         </para>
1033         <para>
1034         If GNU diff isn't already installed and also not available as a package
1035         for your platform, you can get it at:
1036         <ulink url="http://www.gnu.org/software/diffutils/diffutils.html"/>.
1037         </para>
1038         <para>
1039         After correct installation, typing inside the bash:
1040         </para>
1041         <para>
1042         <prompt>$</prompt> <userinput>diff --version</userinput>
1043         </para>
1044         <para>
1045         should result in something like:
1046         <programlisting>
1047 <![CDATA[diff (GNU diffutils) 2.8.7
1048 Written by Paul Eggert, Mike Haertel, David Hayes,
1049 Richard Stallman, and Len Tower.
1050
1051 Copyright (C) 2004 Free Software Foundation, Inc.
1052 This is free software; see the source for copying conditions.  There is NO
1053 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.]]>
1054         </programlisting>
1055         However, the version string may vary.
1056         </para>
1057         </section>
1058
1059         <section id="ChToolsWin32Diff">
1060         <title>Win32 native: -</title>
1061         <para>
1062         The authors don't know of any working win32 native diff implementation.
1063         </para>
1064         </section>
1065
1066         </section>
1067
1068
1069         <section id="ChToolsPatch">
1070         <title>patch (optional)</title>
1071         <para>
1072         The patch utility is used to merge a diff file into your own source
1073         tree. This tool is only needed, if you want to apply a patch (diff file)
1074         from someone else (probably from the developer mailing list) to try out
1075         in your own private source tree.
1076         </para>
1077         <tip><title>Tip!</title>
1078         <para>
1079         Unless you are in the rare case needing to apply a patch to your private
1080         source tree, you won't need the patch tool installed.
1081         </para>
1082         </tip>
1083         <para>
1084         You will find more instructions in <xref linkend="ChSrcPatchApply"/> how
1085         to use the patch tool.
1086         </para>
1087
1088         <section id="ChToolsUnixPatch">
1089         <title>Unix: patch</title>
1090         <para>
1091         Patch is available for most of the unix-like platforms and as the
1092         <application>patch</application> package from the <link
1093         linkend="ChToolsInstallCygwin">Cygwin setup</link>.
1094         </para>
1095         <para>
1096         If GNU patch isn't already installed and also not available as a package
1097         for your platform, you can get it at:
1098         <ulink url="http://www.gnu.org/software/patch/patch.html"/>.
1099         </para>
1100         <para>
1101         After correct installation, typing inside the bash:
1102         </para>
1103         <para>
1104         <prompt>$</prompt> <userinput>patch --version</userinput>
1105         </para>
1106         <para>
1107         should result in something like:
1108         <programlisting>
1109 <![CDATA[patch 2.5.8
1110 Copyright (C) 1988 Larry Wall
1111 Copyright (C) 2002 Free Software Foundation, Inc.
1112
1113 This program comes with NO WARRANTY, to the extent permitted by law.
1114 You may redistribute copies of this program
1115 under the terms of the GNU General Public License.
1116 For more information about these matters, see the file named COPYING.
1117
1118 written by Larry Wall and Paul Eggert]]>
1119         </programlisting>
1120         However, the version string may vary.
1121         </para>
1122         </section>
1123
1124         <section id="ChToolsWin32Patch">
1125         <title>Win32 native: -</title>
1126         <para>
1127         The authors don't know of any working win32 native patch implementation.
1128         </para>
1129         </section>
1130
1131         </section>
1132
1133
1134         <section id="ChToolsWget">
1135         <title>Win32: GNU wget (optional)</title>
1136         <para>
1137         GNU wget is used to download files from the internet using the command line.
1138         </para>
1139         <para>
1140         GNU wget is available for most of the unix-like platforms and as the
1141         <application>wget</application> package from the <link
1142         linkend="ChToolsInstallCygwin">Cygwin setup</link>.
1143         </para>
1144         <para>
1145         You will only need wget, if you want to use the win32 automated library
1146         download, see <xref linkend="ChLibsSetup"/> for details.
1147         </para>
1148         <para>
1149         If GNU wget isn't already installed and also not available as a package
1150         for your platform (well, for win32 it is available as a cygwin package),
1151         you can get it at:
1152         <ulink url="http://www.gnu.org/software/wget/wget.html"/>.
1153         </para>
1154         <para>
1155         If wget is trying to download files but fails to do so, your internet
1156         connection might use a HTTP proxy. Some internet providers using such a
1157         proxy and it is common for company networks today. In this case, you
1158         must set the environment variable
1159         http_proxy before using wget. For example, if you are behind proxy.com
1160         which is listening on port 8080, you have to set it to something like:
1161         </para>
1162         <para>
1163         <programlisting>set HTTP_PROXY=http://proxy.com:8080/</programlisting>
1164         </para>
1165         <para>
1166         If you are unsure about the settings, you might ask your system
1167         administrator.
1168         </para>
1169         </section>
1170
1171
1172         <section id="ChToolsNSIS">
1173         <title>Win32: NSIS (optional)</title>
1174         <para>
1175         The NSIS (Nullsoft Scriptable Install System) is used to generate a
1176         setup.exe from all the files needed to be installed, including all
1177         required DLL's and such.
1178         </para>
1179         <para>
1180         To install it, simply download the latest released version (currently: 2.0
1181         final) from <ulink url="http://nsis.sourceforge.net"/>
1182         and start the downloaded installer. You will need NSIS version 2 final
1183         or higher.
1184         </para>
1185         <para>
1186         You will find more instructions in <xref linkend="ChSrcNSIS"/> how to
1187         use the NSIS tool.
1188         </para>
1189         </section>
1190
1191
1192         <section id="ChToolsCVS">
1193         <title>Obsolete: CVS client</title>
1194         <para>
1195         Some time ago, the Ethereal project was using CVS to keep track of all
1196         the source code changes. As now subversion (SVN) is used, a CVS client
1197         is no longer helpful, see <xref linkend="ChToolsSubversion"/> for details
1198         about subversion clients.
1199         </para>
1200         </section>
1201
1202
1203         <section id="ChToolsWin32Verify">
1204         <title>Win32: Verify installed tools</title>
1205         <para>
1206         After you've installed the Ethereal sources (see <xref
1207         linkend="ChSrcObtain"/>), you can check the correct installation of
1208         all tools by using the verify_tools target of the
1209         <filename>Makefile.nmake</filename> from the source package.
1210         </para>
1211         <warning><title>Warning!</title>
1212         <para>
1213         You will need the Ethereal sources and some tools (nmake, bash) installed,
1214         before this verification is able to work.
1215         </para>
1216         </warning>
1217         <para>
1218         Enter at the command line:
1219         </para>
1220         <para>
1221         <prompt>&gt;</prompt>
1222         <userinput>nmake -f Makefile.nmake verify_tools</userinput>
1223         </para>
1224         <para>
1225         This will check for the various tools needed to build Ethereal:
1226         </para>
1227         <para>
1228         <programlisting>
1229 <![CDATA[Checking for required applications:
1230         bash: /usr/bin/bash
1231         bison: /usr/bin/bison
1232         flex: /usr/bin/flex
1233         grep: /usr/bin/grep
1234         perl: /usr/bin/perl
1235         env: /usr/bin/env
1236         python: /usr/bin/python
1237         sed: /usr/bin/sed
1238         unzip: /usr/bin/unzip
1239         wget: /usr/bin/wget]]>
1240         </programlisting>
1241         </para>
1242         </section>
1243
1244 </chapter>
1245 <!-- End of EUG Chapter Tools -->