+++ /dev/null
-<!-- EDG Chapter Tools -->
-<!-- $Id$ -->
-
-<chapter id="ChapterTools">
- <title>Tools</title>
- <section id="ChToolsIntro">
- <title>Introduction</title>
- <para>
- This chapter will provide you with information how to install
- the various tools needed for Wireshark development.
- </para>
- <para>
- None of the tools mentioned in this chapter is needed to run Ethereal,
- they are only needed to build it.
- </para>
- <para>
- All these tools have
- their roots on UNIX like platforms, but Win32 ports are also
- available. Therefore the tools are available in different "flavours":
- <itemizedlist>
- <listitem>
- <para>
- UNIX (or Win32 Cygwin): as described above, the tools should be commonly
- available on the supported UNIX platforms, and for Win32 platforms by the
- Cygwin UNIX emulation
- </para>
- </listitem>
- <listitem>
- <para>
- Win32 native: some tools are available as native Win32 tools, no
- emulation is required (however, as the installation can be complicated,
- using the Cygwin tools is recommended)
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- General instructions to install the tools are given in:
- <xref linkend="ChToolsInstallUNIX"/> and
- <xref linkend="ChToolsInstallWin32"/>.
- </para>
- <para>
- The following sections give a very brief description of
- what the particular tool is doing, how it is used in the Wireshark project
- and how it can be installed and tested.
- </para>
- <para>
- Don't expect a lot of documentation regarding these tools in this
- document. If you need further documentation of a specific tool, you
- should find lot's of useful information on the web, as these tools are
- commonly used. As all of the tools are command line tools, you can try
- to get help with <userinput>toolname --help</userinput> or read
- the manpage <userinput>man toolname</userinput>.
- </para>
- <para>
- You will find explanations of the tool usage for some of the specific
- development tasks in <xref linkend="ChapterSources"/>.
- </para>
- </section>
-
- <section id="ChToolsInstallUNIX">
- <title>UNIX: Installation</title>
- <para>
- All the tools required are usually installed on a UNIX developer machine.
- </para>
- <para>
- If a tool is not already installed on your system, you will typically use
- the installation package from your distribution (by your favourite package
- manager: apt, yum, synaptics, ...).
- </para>
- <para>
- If an install package is not available, or you have a reason not to use
- it (maybe because it's simply too old), you can install that tool
- from source code. The following sections will provide you with the webpage
- addresses where you can get these sources.
- </para>
- </section>
-
- <section id="ChToolsInstallWin32">
- <title>Win32: Installation</title>
- <para>
- The tool installation on Win32 can be quite confusing as there are several
- ways to do so.
- The following will give you a step-by-step guide to install the
- development tools in the recommended way.
- <warning><title>Warning!</title>
- <para>
- <command>Unless you know exactly what you are doing, you should strictly
- follow the recommendations!</command>
- </para>
- </warning>
- </para>
-
- <section id="ChToolsInstallWin32Recommended">
- <title>Recommendations (Cygwin vs. Win32 native)</title>
- <para>
- Cygwin provides a lot of UNIX based tools on the Win32 platform. It uses
- a UNIX emulation layer which might be a bit slower compared to the native
- Win32 tools, but at an acceptable level.
- The installation and update is pretty easy and done through a single
- (web based) setup.exe.
- </para>
- <para>
- The native Win32 tools will typically be a bit faster, but more
- complicated to install.
- You will have to download the tools from different webpages,
- and install them in different ways, tweaking the PATH and alike.
- </para>
- <note><title>Note!</title>
- <para>
- As there's no Win32 native bash version available, at least a basic
- installation of cygwin is required in any case.
- </para>
- </note>
- <para>
- For all these reasons, the following recommends to use Cygwin tools where
- appropriate.
- </para>
-
- <para>
- <table frame='all'><title>The recommended tools</title>
- <tgroup cols='4' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1'/>
- <colspec colname='c2'/>
- <colspec colname='c3'/>
- <colspec colname='c4'/>
- <thead>
- <row>
- <entry>Tool</entry>
- <entry><link linkend="ChToolsInstallCygwin">Cygwin</link> (Category/Package)</entry>
- <entry>Win32 native</entry>
- <entry>Remark</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><xref linkend="ChToolsCompiler"/></entry>
- <entry>-</entry>
- <entry>cl.exe (MSVC V6)</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsDebugger"/></entry>
- <entry>-</entry>
- <entry>integrated debugger (MSVC V6)</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsMake"/></entry>
- <entry>-</entry>
- <entry>nmake.exe (MSVC V6)</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsBash"/></entry>
- <entry>Base/bash</entry>
- <entry>-</entry>
- <entry>No Win32 native version available!</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsSed"/></entry>
- <entry>Base/sed</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsPython"/></entry>
- <entry>Interpreters/python</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsPerl"/></entry>
- <entry>Interpreters/perl</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsYacc"/></entry>
- <entry>Devel/bison</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsLexx"/></entry>
- <entry>Devel/flex</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsWget"/></entry>
- <entry>Web/wget</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsUnzip"/></entry>
- <entry>Archive/unzip</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsSubversion"/></entry>
- <entry>-</entry>
- <entry><ulink url="http://tortoisesvn.tigris.org/">TortoiseSVN</ulink></entry>
- <entry>Only needed if you access the Wireshark sources using
- the subversion repository (the recommended way).</entry>
- </row>
- <row>
- <entry><xref linkend="ChToolsNSIS"/></entry>
- <entry>-</entry>
- <entry><ulink url="http://nsis.sourceforge.net">NSIS</ulink></entry>
- <entry>Only needed if you want to build your own
- wireshark-setup.exe.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- Don't get confused by the (optional) marker at some of the items in the
- "Tool" column.
- Although these tools are not required to <command>build</command>
- Ethereal they can make development life much easier and some are even
- required by the following installation procedure.
- </para>
- </section>
-
- <section id="ChToolsInstallMSVC">
- <title>Install Microsoft Visual Studio Version 6</title>
- <para>
- Install MSVC the usual way. Don't forget to install vcvars32.bat or call
- it manually before building Ethereal. vcvars32.bat will set some required
- environment settings.
- </para>
- <warning><title>Warning!</title>
- <para>
- Using any other MSVC version is not recommended and will certainly not
- work (at least without a lot of advanced tweaking).
- For further details on this topic, see <xref linkend="ChToolsCompiler"/>.
- </para>
- </warning>
- </section>
- <section id="ChToolsInstallCygwin">
- <title>Install Cygwin</title>
- <para>
- Although Cygwin consists of several seperate packages, the installation
- and update is done through a single setup.exe, which acts similar to other
- web based installers.
- All tools will be installed into one base folder, the default is
- <filename>C:\cygwin</filename>.
- </para>
- <para>
- You will find this network based setup.exe at: <ulink
- url="http://www.cygwin.com/"/>. Click on one of the "Install Cygwin now"
- appearances to download the <filename>setup.exe</filename>.
- After the download completed, start this <filename>setup.exe</filename>
- on your machine.
- </para>
- <para>
- The setup will ask you for some settings, the defaults should usually
- work well for a first start.
- At the "Select Packages" page, you'll need to select some additional
- packages, which are not installed by default.
- Navigate to the required Category/Package row and click on the "Skip"
- item in the "New" column so it shows a version number for:
- <itemizedlist>
- <listitem><para>
- Archive/unzip
- </para></listitem>
- <listitem><para>
- Devel/bison
- </para></listitem>
- <listitem><para>
- Devel/flex
- </para></listitem>
- <listitem><para>
- Interpreters/perl
- </para></listitem>
- <listitem><para>
- Interpreters/python
- </para></listitem>
- <listitem><para>
- Utils/patch
- </para></listitem>
- <listitem><para>
- Web/wget
- </para></listitem>
- </itemizedlist>
- </para>
- <para>
- After clicking the Next button several times, the setup will then
- download and install the selected packages (this may take a while).
- </para>
- <para>
- Under: "Start -> Programs -> Cygwin -> Cygwin Bash Shell" you
- should now be able to start a new Cygwin bash shell, which is similar to
- the command line (command.exe/cmd.exe) in Win32, but much more powerful.
- </para>
- <section id="ChToolsInstallCygwinPackages">
- <title>Add/Update/Remove Cygwin Packages</title>
- <para>
- If you want to add additional, update installed or remove packages later,
- you have to start the setup.exe again.
- At the "Select Packages" page, the entry in the "New" column will control
- what is done (or not) with the package. If a new version of a package is
- available, the new version number will be displayed, so it will be
- automatically updated.
- You can change the current setting by simply clicking at it, it will
- change between:
- <itemizedlist>
- <listitem>
- <para>
- a specific version number - this different package version will be
- installed
- </para>
- </listitem>
- <listitem>
- <para>
- Skip - not installed, no changes
- </para>
- </listitem>
- <listitem>
- <para>
- Keep - already installed, no changes
- </para>
- </listitem>
- <listitem>
- <para>
- Uninstall - uninstall this package
- </para>
- </listitem>
- <listitem>
- <para>
- Reinstall - reinstall this package
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- </section>
-
- <section id="ChToolsInstallAdditional">
- <title>Install Additional Tools</title>
- <para>
- Depending on your actual task the following tools are recommended.
- Please note that they are not required to build Ethereal but can be
- quite helpful.
- </para>
- <section>
- <title>TortoiseSVN</title>
- <para>
- If you want to work with the Wireshark subversion source repositories
- (which is highly recommended, see <xref linkend="ChSrcObtain"/>),
- it's recommended to use TortoiseSVN. You can download the setup from
- <ulink url="http://tortoisesvn.tigris.org/"/> and simply install it.
- </para>
- </section>
- <section>
- <title>Nullsoft Scriptable Install System (NSIS)</title>
- <para>
- If you want to build your own wireshark-setup.exe, you'll need NSIS.
- You can download the NSIS setup from
- <ulink url="http://nsis.sourceforge.net"/> and simply install it.
- </para>
- <para>
- You may check the MAKENSIS setting in the file
- <filename>config.nmake</filename> of the Wireshark sources.
- </para>
- </section>
- </section>
-
- <section id="ChToolsWin32Verify">
- <title>Verify installed tools</title>
- <para>
- After you've installed the Wireshark sources (see <xref
- linkend="ChSrcObtain"/>), you can check the correct installation of
- all tools by using the verify_tools target of the
- <filename>Makefile.nmake</filename> from the source package.
- </para>
- <warning><title>Warning!</title>
- <para>
- You will need the Wireshark sources and some tools (nmake, bash) installed,
- before this verification is able to work.
- </para>
- </warning>
- <para>
- Enter at the command line (cmd.exe, not Cygwin's bash!):
- </para>
- <para>
- <prompt>></prompt>
- <userinput>nmake -f Makefile.nmake verify_tools</userinput>
- </para>
- <para>
- This will check for the various tools needed to build Ethereal:
- </para>
- <para>
- <programlisting>
-<![CDATA[Checking for required applications:
- cl: /cygdrive/c/Program Files/Microsoft Visual Studio/VC98/bin/cl
- link: /cygdrive/c/Program Files/Microsoft Visual Studio/VC98/bin/link
- nmake: /cygdrive/c/Program Files/Microsoft Visual Studio/VC98/bin/nmake
-
- bash: /usr/bin/bash
- bison: /usr/bin/bison
- flex: /usr/bin/flex
- env: /usr/bin/env
- grep: /usr/bin/grep
- /usr/bin/find: /usr/bin/find
- perl: /usr/bin/perl
- env: /usr/bin/env
- python: /usr/bin/python
- sed: /usr/bin/sed
- unzip: /usr/bin/unzip
- wget: /usr/bin/wget]]>
- </programlisting>
- </para>
- <para>
- If you have problems with all the first three ones, check if you called
- ...\Microsoft Visual Studio\VC98\Bin\vcvars32.bat before
- (which will "fix" your PATH settings).
- </para>
- <para>
- Unfortunately, the link command is defined both from cygwin and from MSVC
- with completely different purpose, you'll need the MSVC link.
- If your link command looks something like: /usr/bin/link, the link command
- of cygwin takes precedence over the MSVC one. To fix this, you can change
- your PATH environment setting or simply renaming the link.exe in cygwin.
- If you rename it, make sure to remember that a cygwin update may provide
- a new version of it.
- </para>
- </section>
- </section>
-
- <section id="ChToolsCompiler">
- <title>C compiler</title>
-
- <section id="ChToolsGCC">
- <title>UNIX or Win32 Cygwin: GCC (GNU compiler collection)</title>
- <note><title>Win32 Note!</title>
- <para>
- Although some effort is currently made to use gcc from the Cygwin
- environment, the mainline for several reasons is still using Microsoft
- Visual Studio's C compiler.
- </para>
- </note>
- <para>
- The GCC C compiler is available for most of the UNIX-like platforms and
- as the <application>Devel/gcc</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- If GCC isn't already installed and also not available as a package
- for your platform, you can get it at:
- <ulink url="http://gcc.gnu.org/"/>.
- </para>
- <para>
- After correct installation, typing inside the bash:
- </para>
- <para>
- <prompt>$</prompt> <userinput>gcc --version</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[gcc (GCC) 3.3.3 (cygwin special)
-Copyright (C) 2003 Free Software Foundation, Inc.
-This is free software; see the source for copying conditions. There is NO
-warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsMSVC6">
- <title>Win32 native: Microsoft Visual Studio version 6 C compiler</title>
- <para>
- <note><title>Note!</title>
- <para>
- The Microsoft Visual Studio is not free software.
- This is a tool you have to buy before you use it!
- </para>
- </note>
- </para>
- <para>
- The mainline for generating Ethereal on the windows platform, is using
- the compiler cl.exe from the Microsoft Visual Studio version 6 (and it's
- nmake, as described below).
- </para>
- <para>
- After correct installation, typing inside the command line (cmd.exe):
- </para>
- <para>
- <prompt>></prompt> <userinput>cl</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 12.00.8804 for 80x86
-Copyright (C) Microsoft Corp 1984-1998. All rights reserved.
-
-usage: cl [ option... ] filename... [ /link linkoption... ]]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsMSVC7">
- <title>Win32 native: Microsoft Visual Studio .NET (and alike) C compilers
- </title>
- <para>
- <warning><title>Warning!</title>
- <para>
- The recent "Microsoft Visual Studio .NET" C compiler(s) currently cannot
- be used to compile Ethereal!!!
- </para>
- </warning>
- </para>
- <para>
- The following is a problem summary for:
- <itemizedlist>
- <listitem><para>
- Microsoft Visual Studio .NET
- </para></listitem>
- <listitem><para>
- Microsoft Visual C++ .NET
- </para></listitem>
- <listitem><para>
- Microsoft Visual C++ Toolkit 2003, freely available at: <ulink url="http://msdn.microsoft.com/visualc/vctoolkit2003/"/>
- </para></listitem>
- </itemizedlist>
- All containing version 7 or later of Microsoft's C compiler.
- </para>
- <para>
- It is reported that this compiler requires to ship a MSVCRT70.dll together
- with the compiled exe, which contains the C runtime library. This
- conflicts, as all required libraries currently compiled with (and uses)
- MSVCRT.dll (the older version 6 one).
- </para>
- <para>
- Example why this hurts: A dependant library might try to open a file using
- functions in MSVCRT.dll which creates an internal file handle and keeps
- information about that file. When Ethereal tries to read data from that
- file, it uses the functions from MSVCRT70.dll, which doesn't know anything
- about that previously opened file and returns an error code.
- </para>
- <para>
- There where also attempts to bring the compiler to use only the old
- MSVCRT.dll but they seemed to fail :-(
- </para>
- <para>
- It's also still unsure, if shipping the MSVCRT70.dll together with Ethereal
- is compatible with the GPL license at all.
- </para>
- <note><title>Note!</title>
- <para>
- This isn't an Ethereal specific problem. Any software project trying to use
- the version 7 C compiler will have the problems described above!
- </para>
- </note>
- <para>
- XXX - what about the legal issue, as the MSVCRT70.dll had to be shipped
- with Ethereal.
- </para>
- </section>
-
- </section>
-
- <section id="ChToolsDebugger">
- <title>Debugger</title>
- <para>
- Well, using a good debugger can save you a lot of development time. However
- some people still think it's use is optional.
- </para>
- <para>
- The debugger you use must match the C compiler Ethereal was compiled with,
- otherwise the debugger will simply fail or you will only see a lot of
- garbage.
- </para>
-
- <section id="ChToolsGDB">
- <title>UNIX or Win32 Cygwin: GDB (GNU project debugger)</title>
- <para>
- GDB is the debugger for the GCC compiler. It is available for many (if
- not all) UNIX-like platforms and as the <application>Devel/gdb</application>
- package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>
- </para>
- <para>
- If you don't like debugging using the command line, there are some GUI
- frontends for it available, most notably GNU DDD.
- </para>
- <para>
- If gdb isn't already installed and also not available as a package for
- your platform, you can get it at:
- <ulink url="http://www.gnu.org/software/gdb/gdb.html"/>.
- </para>
- <para>
- After correct installation:
- </para>
- <para>
- <prompt>$</prompt> <userinput>gdb --version</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[GNU gdb 2003-09-20-cvs (cygwin-special)
-Copyright 2003 Free Software Foundation, Inc.
-GDB is free software, covered by the GNU General Public License, and you are
-welcome to change it and/or distribute copies of it under certain conditions.
-Type "show copying" to see the conditions.
-There is absolutely no warranty for GDB. Type "show warranty" for details.
-This GDB was configured as "i686-pc-cygwin".]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsDDD">
- <title>UNIX: DDD (GNU Data Display Debugger)</title>
- <para>
- The GNU Data Display Debugger is a good GUI frontend for GDB (and a lot of
- other command line debuggers), so you have to install GDB first. It is
- available for many UNIX-like platforms and as the
- <application>ddd</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- If GNU DDD isn't already installed and also not available as a package for
- your platform, you can get it at:
- <ulink url="http://www.gnu.org/software/ddd/"/>.
- </para>
- </section>
-
- <section id="ChToolsMSVCDebugger">
- <title>Win32 native: Microsoft Visual Studio debugger</title>
- <para>
- You can use the integrated debugger of Visual Studio.
- </para>
- <para>
- However, setting up
- the environment is a bit tricky, as the Win32 build process is using
- makefiles instead of the .dsp/.dsw files usually used.
- XXX - add instructions how to do it.
- </para>
- </section>
-
- <section id="ChToolsMSDebuggingTools">
- <title>Win32 native: Microsoft Debugging Tools for Windows</title>
- <para>
- You could also use the Microsoft debugging tools, which is a GUI debugger.
- As it's not that comfortable compared to debugging in Visual Studio, it
- can be helpful if you have to debug on a different machine.
- </para>
- <para>
- You can get it free of charge at: <ulink
- url="http://www.microsoft.com/whdc/devtools/debugging/default.mspx"/> (as
- links to microsoft pages changes from time to time, search for
- "Debugging Tools" at their page if this link should be outdated).
- </para>
- </section>
-
- </section>
-
- <section id="ChToolsMake">
- <title>make</title>
-
- <section id="ChToolsGNUmake">
- <title>UNIX or Win32 Cygwin: GNU Make</title>
- <note><title>Win32 Note!</title>
- <para>
- Although some effort is made to use make from the Cygwin environment,
- the mainline is still using Microsoft Visual Studio's nmake.
- </para>
- </note>
- <para>
- GNU Make is available for most of the UNIX-like platforms and
- also as the <application>Devel/make</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- If GNU Make isn't already installed and also not available as a package
- for your platform, you can get it at:
- <ulink url="http://www.gnu.org/software/make/"/>.
- </para>
- <para>
- After correct installation:
- </para>
- <para>
- <prompt>$</prompt> <userinput>make --version</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[GNU Make 3.80
-Copyright (C) 2002 Free Software Foundation, Inc.
-This is free software; see the source for copying conditions.
-There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE.]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsNmake">
- <title>Win32 native: nmake from MSVC</title>
- <para>
- nmake is part of the Microsoft Visual Studio suite, see comment above.
- </para>
- <para>
- Instead of using the the workspace (.dsw) and projects (.dsp) files,
- the traditional nmake makefiles are used. This has one main reason: it
- makes it much easier to maintain changes simultaneous with the GCC
- toolchain makefile.am files as both file formats are similar. However, as
- no Visual Studio workspace/project files are available, this makes it
- hard to use the Visual Studio IDE e.g. for using the integrated
- debugging feature.
- </para>
- <para>
- After correct installation, typing inside the command line (cmd.exe):
- </para>
- <para>
- <prompt>></prompt> <userinput>nmake</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[Microsoft (R) Program Maintenance Utility Version 6.00.8168.0
-Copyright (C) Microsoft Corp 1988-1998. All rights reserved.
-
-NMAKE : fatal error U1064: MAKEFILE not found and no target specified
-Stop.]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsNmake15">
- <title>Win32 native: nmake from microsoft.com</title>
- <warning><title>Warning!</title>
- <para>
- It is recommended to use the Microsoft Visual Studio version 6 to compile
- Ethereal for Win32, see <xref linkend="ChToolsCompiler"/>. Don't follow the
- instructions in this section, until you now what you are doing.
- </para>
- </warning>
- <para>
- NMAKE 1.5 can be downloaded from Microsoft.com if you search for
- "KB132084". Unpack the archive by running it, and drop the 3 extracted
- files in the MSVC++ Toolkit "bin" directory.
- </para>
- <para>
- You will also need <filename>win32.mak</filename>, which you can get from
- the MS Win Platform SDK by browsing to <ulink
- url="http://www.microsoft.com/msdownload/platformsdk/sdkupdate/"/>
- where you select the "Core SDK" and only tick the "Build Environment"
- (31MB) option. After a while, this SDK will be installed.
- </para>
- <para>
- From the start menu, choose "Programs"
- -> "Microsoft Platform SDK February 2003"
- -> "Open build environment window"
- -> (choose your OS Win2K/WinXP/Win2003)
- </para>
- </section>
-
- </section>
-
- <section id="ChToolsBash">
- <title>bash</title>
- <para>
- The bash shell is needed to run several shell scripts.
- </para>
-
- <section id="ChToolsGNUBash">
- <title>UNIX or Win32 Cygwin: GNU bash</title>
- <para>
- The bash is available for most of the UNIX-like platforms and as the
- <application>bash</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- If the bash isn't already installed and also not available as a package
- for your platform, you can get it at:
- <ulink url="http://www.gnu.org/software/bash/bash.html"/>.
- </para>
- <para>
- After correct installation, typing inside any shell:
- </para>
- <para>
- <prompt>$</prompt> <userinput>bash --version</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[GNU bash, version 2.05b.0(1)-release (i686-pc-cygwin)
-Copyright (C) 2002 Free Software Foundation, Inc.]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsWin32Bash">
- <title>Win32 native: -</title>
- <para>
- The authors don't know of any working Win32 native bash implementation.
- </para>
- </section>
-
- </section>
-
-
- <section id="ChToolsPython">
- <title>python</title>
- <para>
- Python is an interpreter based programming language. The homepage of
- the python project is: <ulink url="http://python.org/"/>.
- Python is used to generate some source files.
- Python version 2.2 and above should be working fine.
- </para>
-
- <section id="ChToolsUnixPython">
- <title>UNIX or Win32 Cygwin: python</title>
- <para>
- Python is available for most of the UNIX-like platforms and as the
- <application>python</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>
- </para>
- <para>
- If Python isn't already installed and also not available as a package
- for your platform, you can get it at:
- <ulink url="http://www.python.org/"/>.
- </para>
- <para>
- After correct installation, typing inside the bash:
- </para>
- <para>
- <userinput>$ python -V</userinput>
- </para>
- <para>
- should result in something like:
- </para>
- <para>
- <computeroutput>Python 2.3.3</computeroutput>
- </para>
- <para>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsWin32Python">
- <title>Win32 native: python</title>
- <para>
- Have a look at <ulink url="http://python.org/download/"/>
- to download the latest stable release. You can download a setup there,
- which will install the python system typically into
- <filename>C:\python23</filename> or similiar.
- </para>
- </section>
-
- </section>
-
-
- <section id="ChToolsPerl">
- <title>perl</title>
- <para>
- Perl is an interpreter based programming language. The homepage of the
- perl project is: <ulink url="http://www.perl.com"/>.
- Perl is used to convert various text files into usable source code.
- Perl version 5.6 and above should be working fine.
- </para>
-
- <section id="ChToolsUnixPerl">
- <title>UNIX or Win32 Cygwin: perl</title>
- <para>
- Perl is available for most of the UNIX-like platforms and as the
- <application>perl</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- If perl isn't already installed and also not available as a package
- for your platform, you can get it at:
- <ulink url="http://www.perl.com/"/>.
- </para>
- <para>
- After correct installation, typing inside the bash:
- </para>
- <para>
- <prompt>$</prompt> <userinput>perl --version</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[This is perl, v5.8.5 built for cygwin-thread-multi-64int
-
-Copyright 1987-2004, Larry Wall
-
-Perl may be copied only under the terms of either the Artistic License or the
-GNU General Public License, which may be found in the Perl 5 source kit.
-
-Complete documentation for Perl, including FAQ lists, should be found on
-this system using `man perl' or `perldoc perl'. If you have access to the
-Internet, point your browser at http://www.perl.com/, the Perl Home Page.]]>
- </programlisting>
- However, the version string may vary.
- </para>
-
- </section>
-
- <section id="ChToolsWin32Perl">
- <title>Win32 native: perl</title>
- <para>
- A native Win32 perl package can be obtained from
- <ulink url="http://www.ActiveState.com"/>. The
- installation should be straightforward.
- </para>
- <para>
- After correct installation, typing inside the command line (cmd.exe):
- </para>
- <para>
- <prompt>></prompt> <userinput>perl -v</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[This is perl, v5.8.0 built for MSWin32-x86-multi-thread
-(with 1 registered patch, see perl -V for more detail)
-
-Copyright 1987-2002, Larry Wall
-
-Binary build 805 provided by ActiveState Corp. http://www.ActiveState.com
-Built 18:08:02 Feb 4 2003
-
-...]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- </section>
-
- <section id="ChToolsSed">
- <title>sed</title>
- <para>
- Sed it the streaming editor. It makes it easy for example to replace
- specially marked texts inside a source code file. The Wireshark build
- process uses this to stamp version strings into various places.
- </para>
-
- <section id="ChToolsUnixSed">
- <title>UNIX or Win32 Cygwin: sed</title>
- <para>
- Sed is available for most of the UNIX-like platforms and as the
- <application>sed</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- If sed isn't already installed and also not available as a package
- for your platform, you can get it at:
- <ulink url="http://directory.fsf.org/GNU/sed.html"/>
- </para>
- <para>
- After correct installation, typing inside the bash:
- </para>
- <para>
- <prompt>$</prompt> <userinput>sed --version</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[GNU sed version 4.0.9
-Copyright (C) 2003 Free Software Foundation, Inc.
-This is free software; see the source for copying conditions. There is NO
-warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE,
-to the extent permitted by law.]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsWin32Sed">
- <title>Win32 native: sed</title>
- <para>
- A native Win32 sed package can be obtained from
- <ulink url="http://gnuwin32.sourceforge.net/"/>. The
- installation should be straightforward.
- </para>
- </section>
-
- </section>
-
- <section id="ChToolsYacc">
- <title>yacc (bison)</title>
- <para>
- Bison is a free implementation of yacc.
- </para>
-
- <section id="ChToolsUnixYacc">
- <title>UNIX or Win32 Cygwin: bison</title>
- <para>
- Bison is available for most of the UNIX-like platforms and as the
- <application>bison</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- If GNU Bison isn't already installed and also not available as a package
- for your platform, you can get it at:
- <ulink url="http://www.gnu.org/software/bison/bison.html"/>.
- </para>
- <para>
- After correct installation, typing inside the bash:
- </para>
- <para>
- <prompt>$</prompt> <userinput>bison --version</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[bison (GNU Bison) 1.875b
-Written by Robert Corbett and Richard Stallman.
-
-Copyright (C) 2003 Free Software Foundation, Inc.
-This is free software; see the source for copying conditions. There is NO
-warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsWin32Yacc">
- <title>Win32 native: bison</title>
- <para>
- A native Win32 yacc/bison package can be obtained from
- <ulink url="http://gnuwin32.sourceforge.net/"/>. The
- installation should be straightforward.
- </para>
- </section>
- </section>
-
-
- <section id="ChToolsLexx">
- <title>lexx (flex)</title>
- <para>
- Flex is a free implementation of lexx.
- </para>
-
- <section id="ChToolsUnixLexx">
- <title>UNIX or Win32 Cygwin: flex</title>
- <para>
- Flex is available for most of the UNIX-like platforms and as the
- <application>flex</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- If GNU flex isn't already installed and also not available as a package
- for your platform, you can get it at:
- <ulink url="http://www.gnu.org/software/flex/"/>.
- </para>
- <para>
- After correct installation, typing inside the bash:
- </para>
- <para>
- <prompt>$</prompt> <userinput>flex --version</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[flex version 2.5.4]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsWin32Lexx">
- <title>Win32 native: flex</title>
- <para>
- A native Win32 lexx/flex package can be obtained from
- <ulink url="http://gnuwin32.sourceforge.net/"/>. The
- installation should be straightforward.
- </para>
- </section>
- </section>
-
-
- <section id="ChToolsSubversion">
- <title>Subversion (SVN) client (optional)</title>
- <para>
- The Wireshark project uses it's own subversion (or short SVN) server to keep
- track of all the changes done to the source code. Details about the usage
- of subversion in the Wireshark project can be found in <xref
- linkend="ChSrcSVNServer"/>.
- </para>
- <para>
- If you want to work with the source code and planning to commit your
- changes back to the Wireshark community, it is recommended to use a SVN
- client to get the latest source files. For detailed information about the
- different ways to obtain the Wireshark sources, see
- <xref linkend="ChSrcObtain"/>.
- </para>
- <para>
- Along with the traditional command-line client, several GUI clients are
- available for a number of platforms, see
- <ulink url="http://subversion.tigris.org/project_links.html"/>.
- </para>
- <para>
- You will find more instructions in <xref linkend="ChSrcAnon"/> how to
- use the subversion client.
- </para>
-
- <section id="ChToolsUnixSVN">
- <title>UNIX or Win32 Cygwin: svn (subversion)</title>
- <para>
- SVN is available for most of the UNIX-like platforms and as the
- <application>Devel/subversion</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>
- </para>
- <para>
- If Subversion isn't already installed and also not available as a package
- for your platform, you can get it at:
- <ulink url="http://subversion.tigris.org/"/> (together with the server
- software).
- </para>
- <para>
- After correct installation, typing inside the bash:
- </para>
- <para>
- <prompt>$</prompt> <userinput>svn --version</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[svn, version 1.0.5 (r9954)
- compiled Jun 20 2004, 23:28:30
-
-Copyright (C) 2000-2004 CollabNet.
-Subversion is open source software, see http://subversion.tigris.org/
-This product includes software developed by CollabNet (http://www.Collab.Net/).
-
-...]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsTortoiseSVN">
- <title>Win32 native: TortoiseSVN</title>
- <para>
- A good subversion client for Win32 can be found at:
- <ulink url="http://tortoisesvn.tigris.org/"/>. It will nicely integrate
- into the Windows Explorer window.
- </para>
- </section>
-
- </section>
-
- <section id="ChToolsDiff">
- <title>diff (optional)</title>
- <para>
- Diff is used to get a file of all differences between two source
- files/trees (sometimes called a patch). The diff tool isn't needed for
- building Ethereal, but it's needed if you are going to commit your changes
- back to the Wireshark community.
- </para>
- <note><title>Note!</title>
- <para>
- The recommended way to build patches is using the subversion client,
- see <xref linkend="ChToolsSubversion"/> for details.
- </para>
- </note>
- <para>
- You will find more instructions in <xref linkend="ChSrcDiff"/> how to
- use the diff tool.
- </para>
-
- <section id="ChToolsGNUDiff">
- <title>UNIX or Win32 Cygwin: GNU diff</title>
- <para>
- Diff is available for most of the UNIX-like platforms and as the
- <application>diffutils</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- If GNU diff isn't already installed and also not available as a package
- for your platform, you can get it at:
- <ulink url="http://www.gnu.org/software/diffutils/diffutils.html"/>.
- </para>
- <para>
- After correct installation, typing inside the bash:
- </para>
- <para>
- <prompt>$</prompt> <userinput>diff --version</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[diff (GNU diffutils) 2.8.7
-Written by Paul Eggert, Mike Haertel, David Hayes,
-Richard Stallman, and Len Tower.
-
-Copyright (C) 2004 Free Software Foundation, Inc.
-This is free software; see the source for copying conditions. There is NO
-warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsWin32Diff">
- <title>Win32 native: diff</title>
- <para>
- A native Win32 diff package can be obtained from
- <ulink url="http://gnuwin32.sourceforge.net/"/>. The
- installation should be straightforward.
- </para>
- <para>
- The subversion client TortoiseSVN has a build in diff feature, see
- <xref linkend="ChToolsTortoiseSVN"/>. If this can be used to create diff
- files in the required format, so other persons can use them, is currently
- unknown.
- </para>
- </section>
-
- </section>
-
-
- <section id="ChToolsPatch">
- <title>patch (optional)</title>
- <para>
- The patch utility is used to merge a diff file into your own source
- tree. This tool is only needed, if you want to apply a patch (diff file)
- from someone else (probably from the developer mailing list) to try out
- in your own private source tree.
- </para>
- <tip><title>Tip!</title>
- <para>
- Unless you are in the rare case needing to apply a patch to your private
- source tree, you won't need the patch tool installed.
- </para>
- </tip>
- <para>
- You will find more instructions in <xref linkend="ChSrcPatchApply"/> how
- to use the patch tool.
- </para>
-
- <section id="ChToolsUnixPatch">
- <title>UNIX or Win32 Cygwin: patch</title>
- <para>
- Patch is available for most of the UNIX-like platforms and as the
- <application>patch</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- If GNU patch isn't already installed and also not available as a package
- for your platform, you can get it at:
- <ulink url="http://www.gnu.org/software/patch/patch.html"/>.
- </para>
- <para>
- After correct installation, typing inside the bash:
- </para>
- <para>
- <prompt>$</prompt> <userinput>patch --version</userinput>
- </para>
- <para>
- should result in something like:
- <programlisting>
-<![CDATA[patch 2.5.8
-Copyright (C) 1988 Larry Wall
-Copyright (C) 2002 Free Software Foundation, Inc.
-
-This program comes with NO WARRANTY, to the extent permitted by law.
-You may redistribute copies of this program
-under the terms of the GNU General Public License.
-For more information about these matters, see the file named COPYING.
-
-written by Larry Wall and Paul Eggert]]>
- </programlisting>
- However, the version string may vary.
- </para>
- </section>
-
- <section id="ChToolsWin32Patch">
- <title>Win32 native: patch</title>
- <para>
- A native Win32 patch package can be obtained from
- <ulink url="http://gnuwin32.sourceforge.net/"/>. The
- installation should be straightforward.
- </para>
- <para>
- The subversion client TortoiseSVN has a build in patch feature, see
- <xref linkend="ChToolsTortoiseSVN"/>. The last time tested (Version 1.1.0),
- this feature failed to apply patches known to be ok.
- </para>
- </section>
-
- </section>
-
-
- <section id="ChToolsWget">
- <title>Win32: GNU wget (optional)</title>
- <para>
- GNU wget is used to download files from the internet using the command line.
- </para>
- <para>
- GNU wget is available for most of the UNIX-like platforms and as the
- <application>wget</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- You will only need wget, if you want to use the Win32 automated library
- download, see <xref linkend="ChLibsSetup"/> for details.
- </para>
- <para>
- If GNU wget isn't already installed and also not available as a package
- for your platform (well, for Win32 it is available as a Cygwin package),
- you can get it at:
- <ulink url="http://www.gnu.org/software/wget/wget.html"/>.
- </para>
- <para>
- If wget is trying to download files but fails to do so, your internet
- connection might use a HTTP proxy. Some Internet providers using such a
- proxy and it is common for company networks today. In this case, you
- must set the environment variable
- http_proxy before using wget. For example, if you are behind proxy.com
- which is listening on port 8080, you have to set it to something like:
- </para>
- <para>
- <programlisting>set HTTP_PROXY=http://proxy.com:8080/</programlisting>
- </para>
- <para>
- If you are unsure about the settings, you might ask your system
- administrator.
- </para>
- </section>
-
- <section id="ChToolsUnzip">
- <title>Win32: GNU unzip (optional)</title>
- <para>
- GNU unzip is used to, well, unzip the zip files downloaded using the wget
- tool.
- </para>
- <para>
- GNU wget is available for most of the UNIX-like platforms and as the
- <application>unzip</application> package from the <link
- linkend="ChToolsInstallCygwin">Cygwin setup</link>.
- </para>
- <para>
- You will only need unzip, if you want to use the Win32 automated library
- download, see <xref linkend="ChLibsSetup"/> for details.
- </para>
- <para>
- If GNU unzip isn't already installed and also not available as a package
- for your platform (well, for Win32 it is available as a Cygwin package),
- you can get it at:
- <ulink url="http://www.gnu.org/software/unzip/unzip.html"/>.
- </para>
- </section>
-
-
- <section id="ChToolsNSIS">
- <title>Win32: NSIS (optional)</title>
- <para>
- The NSIS (Nullsoft Scriptable Install System) is used to generate a
- setup.exe from all the files needed to be installed, including all
- required DLL's and such.
- </para>
- <para>
- To install it, simply download the latest released version (currently: 2.0
- final) from <ulink url="http://nsis.sourceforge.net"/>
- and start the downloaded installer. You will need NSIS version 2 final
- or higher.
- </para>
- <para>
- You will find more instructions in <xref linkend="ChSrcNSIS"/> how to
- use the NSIS tool.
- </para>
- </section>
-
-
- <section id="ChToolsCVS">
- <title>Obsolete: CVS client</title>
- <para>
- Some time ago, the Wireshark project was using CVS to keep track of all
- the source code changes. As now subversion (SVN) is used, a CVS client
- is no longer helpful, see <xref linkend="ChToolsSubversion"/> for details
- about subversion clients.
- </para>
- </section>
-
-
-</chapter>
-<!-- End of EDG Chapter Tools -->