--- /dev/null
+<!-- EDG Chapter Introduction -->
+<!-- $Id$ -->
+
+<chapter id="ChapterIntroduction">
+ <title>Introduction</title>
+
+ <section id="ChIntroIntro">
+ <title>Introduction</title>
+ <para>
+ This chapter will provide you with information about Ethereal
+ development in general.
+ </para>
+ </section>
+
+ <section id="ChIntroWhatIs">
+ <title>What is <application>Ethereal?</application></title>
+ <para>
+ 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 provide a lot of general information about it.
+ </para>
+
+ </section>
+
+ <section id="ChIntroPlatforms">
+ <title>Platforms Ethereal runs on</title>
+ <para>
+ Ethereal currently runs on most UNIX platforms and various Windows
+ platforms. It requires GTK+, GLib, libpcap and some other libraries in
+ order to run.
+ </para>
+ <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 such a wide variety of platforms.
+ </para>
+ <para>
+ If a binary package is not available for your platform, you should
+ download the source and try to build it. Please report your experiences
+ to <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>.
+ </para>
+ <para>
+ Binary packages are available for at least the following platforms:
+ </para>
+
+ <section><title>Unix</title>
+ <para>
+ <itemizedlist>
+ <listitem><para>Apple Mac OS X</para></listitem>
+ <listitem><para>BeOS</para></listitem>
+ <listitem><para>FreeBSD</para></listitem>
+ <listitem><para>HP-UX</para></listitem>
+ <listitem><para>IBM AIX</para></listitem>
+ <listitem><para>NetBSD</para></listitem>
+ <listitem><para>OpenBSD</para></listitem>
+ <listitem><para>SCO UnixWare/OpenUnix</para></listitem>
+ <listitem><para>SGI Irix</para></listitem>
+ <listitem><para>Sun Solaris/Intel</para></listitem>
+ <listitem><para>Sun Solaris/Sparc</para></listitem>
+ <listitem><para>Tru64 UNIX (formerly Digital UNIX)</para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section><title>Linux</title>
+ <para>
+ <itemizedlist>
+ <listitem><para>Debian GNU/Linux</para></listitem>
+ <listitem><para>Gentoo Linux</para></listitem>
+ <listitem><para>IBM S/390 Linux (Red Hat)</para></listitem>
+ <listitem><para>Mandrake Linux</para></listitem>
+ <listitem><para>PLD Linux</para></listitem>
+ <listitem><para>Red Hat Linux</para></listitem>
+ <listitem><para>Rock Linux</para></listitem>
+ <listitem><para>Slackware Linux</para></listitem>
+ <listitem><para>Suse Linux</para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section><title>Microsoft Windows</title>
+ <para>
+ Thanks to the Win32 API, development on all windows platforms will be
+ done in a very similar way. However some differences between the platforms
+ are existing (especially between the NT and 95 based platforms), the
+ differences will be notified where appropriate. All Windows platforms will
+ be referred as Win32, Win or Windows might be used with the same meaning.
+ As Windows CE differs a lot compared to the other windows platforms
+ mentioned, Ethereal will not run on Windows CE and there are no plans to
+ support it.
+ <itemizedlist>
+ <listitem><para>Windows Me / 98 / 95</para></listitem>
+ <listitem><para>Windows Server 2003 / XP / 2000 / NT 4.0</para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ </section>
+
+ <section id="ChIntroDevelopment">
+ <title>
+ Development and maintenance of <application>Ethereal</application>
+ </title>
+ <para>
+ Ethereal was initially developed by Gerald Combs. Ongoing development
+ and maintenance of Ethereal is handled by the Ethereal team, a loose
+ group of individuals who fix bugs and provide new functionality.
+ </para>
+ <para>
+ 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 have
+ a look at the <ulink url="&EtherealAuthorsPage;"/> page on the Ethereal
+ web site.
+ </para>
+ <para>
+ The
+ communication between the developers is usually done trough the developer
+ mailing list, which can be joined by anyone interested in the development
+ process. At the time writing of this document, more than 500 persons are
+ subscribed to this mailing list!
+ </para>
+ <para>
+ It is strongly recommended to join the developer mailing list, if you
+ are going to do any Ethereal development. See
+ <xref linkend="ChIntroMailingLists"/> about the different Ethereal
+ mailing lists available.
+ </para>
+
+ <section><title>Programming language(s) used</title>
+ <para>
+ Almost any part of Ethereal is implemented in plain ANSI C.
+ </para>
+ <para>
+ The typical task for a new Ethereal developer is to extend an existing,
+ or write a new dissector for a specific network protocol. As (almost) any
+ dissector is written in plain old ANSI C, a good knowledge about ANSI C
+ will be sufficient for Ethereal development in almost any case.
+ </para>
+ <para>
+ 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).
+ </para>
+ <para>
+ Beside the usual tools for developing a program in C (compiler, make, ...),
+ the build process uses some additional helper tools (Perl, Python, Sed,
+ ...), which are needed for the build process and in the case Ethereal
+ should be installed from the released source packages. If Ethereal is
+ installed from a binary package, none of these helper tools are needed on
+ the target system.
+ </para>
+ </section>
+
+
+ <section><title>Open Source Software</title>
+ <para>
+ Ethereal is an open source software project, and is released under
+ the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL).
+ You can freely use Ethereal on any number of computers you like, without
+ worrying about license keys or fees or such. In addition, all source
+ code is freely available under the GPL. Because of that, it is very easy
+ for people to add new protocols to Ethereal, either as plugins, or built
+ into the source, and they often do!
+ </para>
+ <para>
+ You are welcome to
+ modify Ethereal to suit your own needs, and it would be appreciated
+ if you contribute your improvements back to the Ethereal team.
+ </para>
+ <para>
+ You gain three benefits by contributing your improvements back to the
+ community:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Other people who find your contributions useful will appreciate
+ them, and you will know that you have helped people in the
+ same way that the developers of Ethereal have helped people.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The developers of Ethereal might improve your changes even more,
+ as there's always room for improvements. Or they may implement some
+ advanced things on top of your code, which can be useful for yourself
+ too.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The maintainers and developers of Ethereal will maintain your
+ code as well, fixing it when API changes or other changes are
+ made, and generally keeping it in tune with what is happening
+ with Ethereal. So if Ethereal is updated (which is done often),
+ you can get a new Ethereal version from the website and your changes
+ will already be included without any effort for you.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ The Ethereal source code and binary kits for some platforms are all
+ available on the download page of the Ethereal website:
+ <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="ChIntroReleases">
+ <title>Releases and distributions</title>
+ <para>
+ The officially released files can be found at: <ulink
+ url="&EtherealDownloadPage;"/>. A new Ethereal version is released, after
+ significant changes compared to the last release were completed or a
+ serious security issue was encountered. The typical release schedule is
+ about every 4-8 weeks (although this may vary).
+ </para>
+ <para>
+ There are two kinds of distributions: binary and source, both have their
+ advantages and disadvantages.
+ </para>
+
+ <section id="ChIntroReleaseBinary">
+ <title>Binary distributions</title>
+ <para>
+ Binary distributions are usually easy to install (as simply starting
+ the appropriate file is usually the only thing to do). They are available
+ for the following systems:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Win32 (.exe file). The typical windows end user is used to get an setup
+ .exe file, which will install all the required things for him.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Debian (.deb file)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ RedHat (.rpm file)
+ </para>
+ </listitem>
+ </itemizedlist>
+ However, if you want to start developing with Ethereal, the binary
+ distributions won't be much helpful, as you need the source files, of
+ course.
+ </para>
+ <para>
+ For details about how to build these binary distributions yourself,
+ e.g. if you need a distribution for a special audience, see
+ <xref linkend="ChSrcBinary"/>.
+ </para>
+ </section>
+
+ <section id="ChIntroReleaseSource">
+ <title>Source code distributions</title>
+ <para>
+ It's still common for unix developers to give the end user a source
+ tarball and let the user compile it on their target machine (configure,
+ make, make install). However, for different unix (linux) distributions
+ it's becoming more common to release binary packages (e.g. .deb or .rpm
+ files) these days.
+ </para>
+ <para>
+ You should use the released sources if you want to build Ethereal from
+ source on your platform for productive use. However, if you going to
+ develop changes to the Ethereal sources, it might be better to use the
+ latest SVN sources. For details about the different ways to get the
+ Ethereal source code see <xref linkend="ChSrcObtain"/>.
+ </para>
+ <para>
+ Before building Ethereal from a source distribution, make sure you have
+ all the tools and libraries required to build. The following chapters will
+ describe the required tools and libraries in detail.
+ </para>
+ </section>
+ </section>
+
+ <section id="ChIntroHelp">
+ <title>Reporting problems and getting help</title>
+ <para>
+ If you have problems, or need help with Ethereal, there are several
+ places that may be of interest to you (well, beside this guide of
+ course).
+ </para>
+
+ <section id="ChIntroFAQ"><title>FAQ</title>
+ <para>
+ The "Frequently Asked Questions" will list often asked questions and
+ the corresponding answers.
+ <note><title>Read the FAQ!</title>
+ <para>
+ Before sending any mail to the mailing lists below, be sure to read the
+ FAQ, as it will often answer the question(s) you might have. This will save
+ yourself and others a lot of time (keep in mind that a lot of people are
+ subscribed to the mailing lists).
+ </para>
+ </note>
+ You will find the FAQ inside Ethereal by clicking the menu item
+ Help/Contents and selecting the FAQ page in the upcoming dialog.
+ </para>
+ <para>
+ An online version is available at the ethereal website:
+ <ulink url="&EtherealFAQPage;">&EtherealFAQPage;</ulink>. You might
+ prefer this online version, as it's typically more up to date and the HTML
+ format is easier to use.
+ </para>
+ </section>
+
+ <section id="ChIntroMailingLists"><title>Mailing Lists</title>
+ <para>
+ There are several mailing lists of specific Ethereal topics available:
+ <variablelist>
+ <varlistentry><term><command>ethereal-announce</command></term>
+ <listitem>
+ <para>
+ This mailing list will inform you about new program
+ releases, which usually appear about every 4-8 weeks.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>ethereal-users</command></term>
+ <listitem>
+ <para>
+ This list is for users of Ethereal. People post
+ questions about building and using Ethereal, others (hopefully)
+ provide answers.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>ethereal-dev</command></term>
+ <listitem>
+ <para>
+ 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>
+ </variablelist>
+ You can subscribe to each of these lists from the Ethereal web site:
+ <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>. Simply
+ select the <command>mailing lists</command> link on the left hand
+ side of the site. The lists are archived at the Ethereal web site
+ as well.
+ <tip><title>Tip!</title>
+ <para>
+ You can search in the list archives to see if someone asked the same
+ question some time before and maybe already got an answer. That way you
+ don't have to wait until someone answers your question.
+ </para>
+ </tip>
+ </para>
+ </section>
+
+ <section id="ChIntroReportProblems"><title>Reporting Problems</title>
+ <note><title>Note!</title>
+ <para>
+ Before reporting any problems, please make sure you have installed the
+ latest version of Ethereal.
+ </para>
+ </note>
+ <para>
+ If you report problems, provide as much
+ information as possible. In general, just think about what
+ you would need to find that problem, if someone else sends you such a
+ problem report. Also keep in mind, that people uses a lot of different
+ platforms to compile/run Ethereal on.
+ </para>
+ <para>
+ When reporting problems with Ethereal, it is helpful if you supply the
+ following information:
+ <orderedlist>
+ <listitem>
+ <para>
+ The version number of Ethereal and the dependent libraries linked with
+ it, eg GTK+, etc. You can obtain this with the command
+ <command>ethereal -v</command>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Information about the platform you run Ethereal on.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A detailed description of your problem.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you get an error/warning message, copy the text of that message (and
+ also a few lines before and after it, if there are some), so others may
+ find the build step where things go wrong.
+ Please don't give something like: "I get a warning when comiling x"
+ as this won't give any direction to look at.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <note><title>Don't send large files!</title>
+ <para>
+ Do not send large files (>100KB) to the mailing lists, just place a note
+ that further data is available on request. Large files will only annoy a
+ lot of people on the list who are not interested in your specific problem.
+ If required, you will be asked for further data by the persons who really
+ can help you.
+ </para>
+ </note>
+ <note><title>Don't send confidential information!</title>
+ <para>
+ If you send captured data to the mailing lists, be sure they don't contain
+ any sensitive or confidential information like passwords or such.
+ </para>
+ </note>
+ </section>
+
+ <section><title>Reporting Crashes on UNIX/Linux platforms</title>
+ <para>
+ When reporting crashes with Ethereal, it is helpful if you supply the
+ traceback information (besides the information mentioned in
+ <xref linkend="ChIntroReportProblems"/>).
+ </para>
+ <para>
+ You can obtain this traceback information with the following commands:
+ <programlisting>
+<![CDATA[
+$ gdb `whereis ethereal | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
+backtrace
+^D
+$
+]]>
+ </programlisting>
+ <note>
+ <para>
+ Type the characters in the first line verbatim! Those are
+ back-tics there!
+ </para>
+ </note>
+ <note>
+ <para>
+ backtrace is a <command>gdb</command> command. You should
+ enter it verbatim after the first line shown above, but it will not be
+ echoed. The ^D
+ (Control-D, that is, press the Control key and the D key
+ together) will cause <command>gdb</command> to exit. This will
+ leave you with a file called
+ <filename>bt.txt</filename> in the current directory.
+ Include the file with your bug report.
+ </para>
+ </note>
+ <note>
+ <para>
+ If you do not have <command>gdb</command> available, you
+ will have to check out your operating system's debugger.
+ </para>
+ </note>
+ </para>
+ <para>
+ You should mail the traceback to the
+ <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>
+ mailing list.
+ </para>
+ </section>
+
+ <section><title>Reporting Crashes on Windows platforms</title>
+ <para>
+ The Windows distributions don't contain the symbol files (.pdb), because
+ they are very large. For this reason it's not possible to create
+ a meaningful backtrace file from it. You should report your crash just
+ like other problems, using the mechanism from
+ <xref linkend="ChIntroReportProblems"/>.
+ </para>
+ </section>
+ </section>
+
+ <section id="ChIntroOtherSources"><title>Other sources of developer information
+ </title>
+ <para>
+ If you don't find the information you need inside this book, there are
+ various other sources of information:
+ <itemizedlist>
+ <listitem>
+ <para>
+ have a look at the Ethereal source code
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ there are various documentation files on different topics inside the
+ source code, see all the README.xxx files
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ tool documentation of the various tools used
+ (e.g. manpages of sed, gcc, ...)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the different mailing lists <xref linkend="ChIntroMailingLists"/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ ...
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+</chapter>
+<!-- End of EUG Chapter 1 -->
git.samba.org / obnox / wireshark / wip.git / blobdiff