<title>Ethereal Build Environment</title>
<partintro>
<para>
-This is the first of two parts:
+<command>Part I. Ethereal Build Environment</command>
</para>
<para>
-<command>Part I. Ethereal Build Environment</command>
+<command>The first part describes how to set up the tools, libraries and
+source needed to generate Ethereal, and how to do some typical development
+tasks.</command>
</para>
<para>
Part II. Ethereal Development
</para>
+<para>
+The second part describes how the Ethereal sources are structured and how
+to change the sources (e.g. adding a new dissector).
+</para>
</partintro>
&EnvIntroduction;
&Tools;
&Sources;
</part>
<part id="PartDevelopment" label="II">
-<title>Ethereal Development</title>
+<title>Ethereal Development (incomplete)</title>
<partintro>
-<para>
+<!--<para>
This is the second of two parts:
-</para>
+</para>-->
<para>
Part I. Ethereal Build Environment
</para>
<para>
+The first part describes how to set up the tools, libraries and source needed
+to generate Ethereal, and how to do some typical development tasks.
+</para>
+<para>
<command>Part II. Ethereal Development</command>
</para>
+<para>
+<command>The second part describes how the Ethereal sources are structured and how
+to change the sources (e.g. adding a new dissector).</command>
+</para>
</partintro>
&BuildIntroduction;
&Dissection;
<chapter id="ChapterDissection">\r
<title>Packet dissection</title>\r
\r
- <section id="ChDissWorks">\r
+ <section id="ChDissectWorks">\r
<title>How it works</title>\r
<para>\r
XXX - well, how does it work?\r
</para>\r
</section>\r
\r
- <section id="ChDissAdd">\r
+ <section id="ChDissectAdd">\r
<title>Adding a basic dissector</title>\r
<para>\r
The steps to add a new dissector (including some skeleton code) can be \r
</para>\r
</section>\r
\r
- <section id="ChDissConversation">\r
+ <section id="ChDissectConversation">\r
<title>How to use conversations</title>\r
<para>\r
Some info about how to use conversations in a dissector can be \r
<section id="ChIntroWhatIs">
<title>What is <application>Ethereal?</application></title>
<para>
- Well, if you want to develop some things into Ethereal, you might already
+ Well, if you want to start Ethereal development, you might already
know what Ethereal is doing. If not, please have a look at the
<ulink url="&EtherealUsersGuidePage;">Ethereal User's Guide</ulink>,
- which will explain what Ethereal is doing and a lot more general
- information about it.
+ which will provide a lot of general information about it.
</para>
</section>
<para>
As Ethereal is developed in a platform independant way and uses libraries
which are available for a lot of different platforms (such as the GTK+
- GUI library), it's available on a wide variety of platforms.
+ GUI library), it's available on a such a wide variety of platforms.
</para>
<para>
If a binary package is not available for your platform, you should
There have also been a large number of people who have contributed
protocol dissectors to Ethereal, and it is expected that this will
continue. You can find a list of the people who have contributed
- code to Ethereal by checking the about dialog box of Ethereal, or at
- the <ulink url="&EtherealAuthorsPage;">authors</ulink> page on the
- Ethereal web site.
+ code to Ethereal by checking the about dialog box of Ethereal, or have
+ a look at the <ulink url="&EtherealAuthorsPage;"/> page on the Ethereal
+ web site.
</para>
<para>
The
will be sufficient for Ethereal development in almost any case.
</para>
<para>
- So unless you are going to change the development process of Ethereal in
+ So unless you are going to change the development process of Ethereal
itself, you won't come in touch with any other programming language than
ANSI C (such as perl or python, which are used only in the Ethereal build
process).
<varlistentry><term><command>ethereal-users</command></term>
<listitem>
<para>
- This list is for users of Ethereal. People post
+ This list is for users of Ethereal. People post
questions about building and using Ethereal, others (hopefully)
provide answers.
</para>
<varlistentry><term><command>ethereal-dev</command></term>
<listitem>
<para>
- This list is for Ethereal developers. If you want to start
- developing a protocol dissector, join this list.
+ This list is for Ethereal developers. People post questions about
+ the development of Ethereal, others (hopefully) provide answers.
+ If you want to start developing a protocol dissector, join this list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>ethereal-cvs</command></term>
+ <listitem>
+ <para>
+ This list is for Ethereal developers. Everytime a change to the SVN
+ repository is checked in, a mail to this mailing list is generated.
+ If you want to be notified about all the changes to the SVN
+ repository, join this list. Details about the SVN repository can be
+ found in <xref linkend="ChSrcSVNServer"/>.
</para>
</listitem>
</varlistentry>
<chapter id="ChapterLibraries">
<title>Libraries</title>
- <section>
+ <section id="ChLibIntro">
<title>Introduction</title>
<para>
Several libraries are needed to build / run Ethereal. Most of the
libraries.
</para>
- <section>
+ <section id="ChLibsUnixGTK">
<title>Unix: ...</title>
<para>
Unix: <ulink url="http://www.gtk.org"/>
</para>
</section>
- <section>
+ <section id="ChLibsWin32GTK">
<title>Win32 native: ...</title>
<para>
Win32 native: <ulink url="http://www.gimp.org/%7Etml/gimp/win32/downloads.html"/>
"Various tools relating to the Simple Network Management Protocol"
</para>
- <section>
+ <section id="ChLibsUnixSNMP">
<title>Unix: Net SNMP</title>
<para>
Unix: XXX: where to find the right binaries?
</para>
</section>
- <section>
+ <section id="ChLibsWin32SNMP">
<title>Win32 native: Net SNMP</title>
<para>
Win32 native: XXX: where to find the right binaries?
utilities."
</para>
- <section>
+ <section id="ChLibsUnixADNS">
<title>Unix: GNU ADNS</title>
<para>
Unix: XXX: where to find the right binaries?
</para>
</section>
- <section>
+ <section id="ChLibsWin32ADNS">
<title>Win32 native: GNU ADNS</title>
<para>
Win32 native: <ulink url="http://adns.jgaa.com/"/>
"Perl compatible regular expressions"
</para>
- <section>
+ <section id="ChLibsUnixPCRE">
<title>Unix: PCRE</title>
<para>
Unix: XXX: where to find the right binaries?
</para>
</section>
- <section>
+ <section id="ChLibsWin32PCRE">
<title>Win32 native: PCRE</title>
<para>
Win32 native: <ulink url="http://gnuwin32.sourceforge.net/packages/pcre.htm"/>
hardware and operating system."
</para>
- <section>
+ <section id="ChLibsUnixZlib">
<title>Unix: zlib</title>
<para>
Unix: XXX: where to find the right binaries?
</para>
</section>
- <section>
+ <section id="ChLibsWin32Zlib">
<title>Win32 native: zlib</title>
<para>
Win32 native: <ulink url="http://www.gzip.org/zlib/"/>
</section>
- <section id="ChLibsWinpPcap">
+ <section id="ChLibsPcap">
<title>libpcap/WinPcap (optional)</title>
<para>
"packet capture library"
</para>
- <section>
+ <section id="ChLibsLibpcap">
<title>Unix: libpcap</title>
<para>
Unix: XXX
</para>
</section>
- <section>
+ <section id="ChLibsWinpPcap">
<title>Win32 native: WinPcap</title>
<para>
"Windows packet capture library"
<section id="ChLibsWimp">
- <title>Win32: GTK WIMP (optional)</title>
+ <title>Win32: GTK WIMP (optional) for GTK 2.x only</title>
<para>
"GTK-Wimp ("Windows impersonator") is a GTK theme that blends well into
the Windows desktop environment."
</para>
-
- <section>
- <title>Unix: -</title>
- <para>
- </para>
- </section>
-
- <section>
- <title>Win32 native: WIMP (for GTK2.x only)</title>
<para>
Wimp is only available for the GTK2.x versions at:
- <ulink url="http://gtk-wimp.sourceforge.net/"/>
+ <ulink url="http://gtk-wimp.sourceforge.net/"/>.
</para>
- </section>
</section>
track of the changes made to the source code.
</para>
<para>
- The svn server makes it possible to get the source files from any previous
- release, see which person changed a specific piece of code, and a lot more
- things related to the history of the Ethereal source code development.
+ Using the SVN repository you can:
+ <itemizedlist>
+ <listitem><para>
+ keep your private sources uptodate with very little effort
+ </para></listitem>
+ <listitem><para>
+ get a mail notification if someone changes the latest sources
+ </para></listitem>
+ <listitem><para>
+ get the source files from any previous release (or any other point in time)
+ </para></listitem>
+ <listitem><para>
+ have a quick look at the sources using a web interface
+ </para></listitem>
+ <listitem><para>
+ see which person changed a specific piece of code
+ </para></listitem>
+ <listitem><para>
+ ... and a lot more things related to the history of the Ethereal source
+ code development
+ </para></listitem>
+ </itemizedlist>
</para>
<para>
- There are several ways to have a look at and obtain the sources from this
- server. Please note that the anonymous SVN repository is separate from
+ For further reference about subversion, have a look at the homepage of the
+ subversion project: <ulink url="http://subversion.tigris.org/"/>. There
+ is a book about it available at: <ulink url="http://svnbook.red-bean.com/"/>.
+ </para>
+ <para>
+ Please note that the anonymous SVN repository is separate from
the main repository. It may take several minutes for committed changes to
appear in the anonymous repository. XXX - be more specific here.
</para>
CVS in the Ethereal documentation and source files.
</para>
</tip>
- <para>
- For further reference about subversion, have a look at the homepage of the
- subversion project: <ulink url="http://subversion.tigris.org/"/>. There
- is a book about it available at: <ulink url="http://svnbook.red-bean.com/"/>.
- </para>
</section>
<section id="ChSrcQuickLook">
If they're relative to a higher-level directory, you'd replace 0 with the
number of higher-level directories in the path, e.g. if the names are
"ethereal.orig/prefs.c" and "ethereal.mine/prefs.c", you'd run it with:
+ </para>
<para>
<userinput>patch -p1 <new.diff</userinput>
</para>
+ <para>
If they're relative to a <command>subdirectory</command> of the top-level
directory, you'd run "patch" in <command>that</command> directory and run
it with "-p0".
The bash shell is needed to run several shell scripts.
</para>
- <section>
+ <section id="ChToolsGNUBash">
<title>Unix: GNU bash</title>
<para>
The bash is available for most of the unix-like platforms and as the
</para>
</section>
- <section>
+ <section id="ChToolsWin32Bash">
<title>Win32 native: -</title>
<para>
The authors don't know of any working win32 native bash implementation.
<section id="ChToolsCompiler">
<title>C compiler</title>
- <section>
-
+ <section id="ChToolsGCC">
<title>Unix: GCC (GNU compiler collection)</title>
<note><title>Win32 Note!</title>
<para>
</para>
</section>
- <section>
+ <section id="ChToolsMSVC6">
<title>Win32 native: Microsoft Visual Studio version 6 C compiler</title>
<para>
<note><title>Note!</title>
</para>
</section>
- <section>
+ <section id="ChToolsMSVC7">
<title>Win32 native: Microsoft Visual Studio .NET (and alike) C compilers
</title>
<para>
<warning><title>Warning!</title>
<para>
- The more recent "Microsoft Visual Studio .NET" C compiler currently cannot
+ The recent "Microsoft Visual Studio .NET" C compiler(s) currently cannot
be used to compile Ethereal!!!
</para>
</warning>
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 C compiler.
+ 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
</para>
<para>
Example why this hurts: A dependant library might try to open a file using
- functions in MSVCRT.dll which creates a file handle and internally keeps
+ 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 about
- that previously opened file and returns an error code.
+ 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
<note><title>Note!</title>
<para>
This isn't an Ethereal specific problem. Any software project trying to use
- the new C compiler will have the problems described above!
+ the version 7 C compiler will have the problems described above!
</para>
</note>
</section>
<section id="ChToolsMake">
<title>make</title>
- <section>
+ <section id="ChToolsGNUmake">
<title>Unix: GNU make</title>
<note><title>Win32 Note!</title>
<para>
</para>
</section>
- <section>
+ <section id="ChToolsNmake">
<title>Win32 native: nmake</title>
<para>
nmake is part of the Microsoft Visual Studio suite, see comment above.
fine.
</para>
- <section>
+ <section id="ChToolsUnixPython">
<title>Unix: python</title>
<para>
Python is available for most of the unix-like platforms and as the
</para>
</section>
- <section>
+ <section id="ChToolsWin32Python">
<title>Win32 native: python</title>
<para>
Have a look at <ulink url="http://python.org/download/"/>
Perl is used to XXX. Perl version XXX and above should be working fine.
</para>
- <section>
+ <section id="ChToolsUnixPerl">
<title>Unix: perl</title>
<para>
Perl is available for most of the unix-like platforms and as the
</section>
- <section>
+ <section id="ChToolsWin32Perl">
<title>Win32 native: perl</title>
<para>
A native Win32 perl package can be obtained from
process uses this to stamp version strings into various places.
</para>
- <section>
+ <section id="ChToolsUnixSed">
<title>Unix: sed</title>
<para>
Sed is available for most of the unix-like platforms and as the
</para>
</section>
- <section>
+ <section id="ChToolsWin32Sed">
<title>Win32 native: -</title>
<para>
The authors don't know of any working win32 native sed implementation.
Bison is a free implementation of yacc.
</para>
- <section>
+ <section id="ChToolsUnixYacc">
<title>Unix: bison</title>
<para>
Bison is available for most of the unix-like platforms and as the
</para>
</section>
- <section>
+ <section id="ChToolsWin32Yacc">
<title>Win32 native: -</title>
<para>
The authors don't know of any working win32 native yacc/bison
<para>
Flex is a free implementation of lexx.
</para>
- <section>
+ <section id="ChToolsUnixLexx">
<title>Unix: flex</title>
<para>
Flex is available for most of the unix-like platforms and as the
</para>
</section>
- <section>
+ <section id="ChToolsWin32Lexx">
<title>Win32 native: -</title>
<para>
The authors don't know of any working win32 native lexx/flex
use the subversion client.
</para>
- <section>
+ <section id="ChToolsUnixSVN">
<title>Unix: svn</title>
<para>
SVN is available for most of the unix-like platforms and as the
</para>
</section>
- <section>
+ <section id="ChToolsTortoiseSVN">
<title>Win32 native: TortoiseSVN</title>
<para>
A good subversion client for Win32 can be found at:
use the diff tool.
</para>
- <section>
+ <section id="ChToolsGNUDiff">
<title>Unix: GNU diff</title>
<para>
Diff is available for most of the unix-like platforms and as the
</para>
</section>
- <section>
+ <section id="ChToolsWin32Diff">
<title>Win32 native: -</title>
<para>
The authors don't know of any working win32 native diff implementation.
to use the patch tool.
</para>
- <section>
+ <section id="ChToolsUnixPatch">
<title>Unix: patch</title>
<para>
Patch is available for most of the unix-like platforms and as the
</para>
</section>
- <section>
+ <section id="ChToolsWin32Patch">
<title>Win32 native: -</title>
<para>
The authors don't know of any working win32 native patch implementation.