docbook/edg_src/EDG_chapter_env_intro.xml

   1 <!-- EDG Chapter Introduction -->
   2 <!-- $Id$ -->
   3
   4 <chapter id="ChapterIntroduction">
   5   <title>Introduction</title>
   6
   7   <section id="ChIntroIntro">
   8     <title>Introduction</title>
   9     <para>
  10         This chapter will provide you with information about Ethereal
  11         development in general.
  12     </para>
  13   </section>
  14
  15   <section id="ChIntroWhatIs">
  16     <title>What is <application>Ethereal?</application></title>
  17     <para>
  18         Well, if you want to start Ethereal development, you might already
  19         know what Ethereal is doing. If not, please have a look at the
  20         <ulink url="&EtherealUsersGuidePage;">Ethereal User's Guide</ulink>,
  21         which will provide a lot of general information about it.
  22     </para>
  23
  24   </section>
  25
  26   <section id="ChIntroPlatforms">
  27     <title>Platforms Ethereal runs on</title>
  28     <para>
  29       Ethereal currently runs on most UNIX platforms and various Windows
  30       platforms. It requires GTK+, GLib, libpcap and some other libraries in
  31           order to run.
  32     </para>
  33     <para>
  34         As Ethereal is developed in a platform independant way and uses libraries
  35         which are available for a lot of different platforms (such as the GTK+
  36         GUI library), it's available on a such a wide variety of platforms.
  37     </para>
  38     <para>
  39       If a binary package is not available for your platform, you should
  40       download the source and try to build it. Please report your experiences
  41           to <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>.
  42     </para>
  43     <para>
  44       Binary packages are available for at least the following platforms:
  45     </para>
  46
  47         <section><title>Unix</title>
  48         <para>
  49         <itemizedlist>
  50         <listitem><para>Apple Mac OS X</para></listitem>
  51         <listitem><para>BeOS</para></listitem>
  52         <listitem><para>FreeBSD</para></listitem>
  53         <listitem><para>HP-UX</para></listitem>
  54         <listitem><para>IBM AIX</para></listitem>
  55         <listitem><para>NetBSD</para></listitem>
  56         <listitem><para>OpenBSD</para></listitem>
  57         <listitem><para>SCO UnixWare/OpenUnix</para></listitem>
  58         <listitem><para>SGI Irix</para></listitem>
  59         <listitem><para>Sun Solaris/Intel</para></listitem>
  60         <listitem><para>Sun Solaris/Sparc</para></listitem>
  61         <listitem><para>Tru64 UNIX (formerly Digital UNIX)</para></listitem>
  62         </itemizedlist>
  63         </para>
  64         </section>
  65
  66         <section><title>Linux</title>
  67         <para>
  68         <itemizedlist>
  69         <listitem><para>Debian GNU/Linux</para></listitem>
  70         <listitem><para>Gentoo Linux</para></listitem>
  71         <listitem><para>IBM S/390 Linux (Red Hat)</para></listitem>
  72         <listitem><para>Mandrake Linux</para></listitem>
  73         <listitem><para>PLD Linux</para></listitem>
  74         <listitem><para>Red Hat Linux</para></listitem>
  75         <listitem><para>Rock Linux</para></listitem>
  76         <listitem><para>Slackware Linux</para></listitem>
  77         <listitem><para>Suse Linux</para></listitem>
  78         </itemizedlist>
  79         </para>
  80         </section>
  81
  82         <section><title>Microsoft Windows</title>
  83     <para>
  84         Thanks to the Win32 API, development on all Windows platforms will be
  85         done in a very similar way. However some differences between the platforms
  86         are existing (especially between the NT and 95 based platforms), the
  87         differences will be notified where appropriate. All Windows platforms
  88         referred to as Win32, Win or Windows may be used with the same meaning.
  89         As Windows CE differs a lot compared to the other Windows platforms
  90         mentioned, Ethereal will not run on Windows CE and there are no plans to
  91         support it.
  92         <itemizedlist>
  93         <listitem><para>Windows Me / 98 / 95</para></listitem>
  94         <listitem><para>Windows Server 2003 / XP / 2000 / NT 4.0</para></listitem>
  95         </itemizedlist>
  96     </para>
  97         </section>
  98
  99   </section>
 100
 101   <section id="ChIntroDevelopment">
 102     <title>
 103         Development and maintenance of <application>Ethereal</application>
 104     </title>
 105     <para>
 106       Ethereal was initially developed by Gerald Combs. Ongoing development
 107       and maintenance of Ethereal is handled by the Ethereal team, a loose
 108       group of individuals who fix bugs and provide new functionality.
 109     </para>
 110     <para>
 111       There have also been a large number of people who have contributed
 112       protocol dissectors to Ethereal, and it is expected that this will
 113       continue.  You can find a list of the people who have contributed
 114       code to Ethereal by checking the about dialog box of Ethereal, or have
 115           a look at the <ulink url="&EtherealAuthorsPage;"/> page on the Ethereal
 116           web site.
 117     </para>
 118     <para>
 119         The
 120         communication between the developers is usually done trough the developer
 121         mailing list, which can be joined by anyone interested in the development
 122         process. At the time writing of this document, more than 500 persons are
 123         subscribed to this mailing list!
 124     </para>
 125     <para>
 126         It is strongly recommended to join the developer mailing list, if you
 127         are going to do any Ethereal development. See
 128         <xref linkend="ChIntroMailingLists"/> about the different Ethereal
 129         mailing lists available.
 130     </para>
 131
 132         <section><title>Programming language(s) used</title>
 133     <para>
 134         Almost any part of Ethereal is implemented in plain ANSI C.
 135     </para>
 136     <para>
 137         The typical task for a new Ethereal developer is to extend an existing,
 138         or write a new dissector for a specific network protocol. As (almost) any
 139         dissector is written in plain old ANSI C, a good knowledge about ANSI C
 140         will be sufficient for Ethereal development in almost any case.
 141     </para>
 142     <para>
 143         So unless you are going to change the development process of Ethereal
 144         itself, you won't come in touch with any other programming language than
 145         ANSI C (such as perl or python, which are used only in the Ethereal build
 146         process).
 147     </para>
 148     <para>
 149         Beside the usual tools for developing a program in C (compiler, make, ...),
 150         the build process uses some additional helper tools (Perl, Python, Sed,
 151         ...), which are needed for the build process and in the case Ethereal
 152         should be installed from the released source packages. If Ethereal is
 153         installed from a binary package, none of these helper tools are needed on
 154         the target system.
 155         </para>
 156         </section>
 157
 158
 159         <section><title>Open Source Software</title>
 160     <para>
 161       Ethereal is an open source software project, and is released under
 162       the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL).
 163           You can freely use Ethereal on any number of computers you like, without
 164           worrying about license keys or fees or such. In addition, all source
 165           code is freely available under the GPL. Because of that, it is very easy
 166           for people to add new protocols to Ethereal, either as plugins, or built
 167           into the source, and they often do!
 168     </para>
 169     <para>
 170           You are welcome to
 171       modify Ethereal to suit your own needs, and it would be appreciated
 172       if you contribute your improvements back to the Ethereal team.
 173     </para>
 174     <para>
 175       You gain three benefits by contributing your improvements back to the
 176       community:
 177       <itemizedlist>
 178         <listitem>
 179           <para>
 180             Other people who find your contributions useful will appreciate
 181             them, and you will know that you have helped people in the
 182             same way that the developers of Ethereal have helped people.
 183           </para>
 184         </listitem>
 185         <listitem>
 186           <para>
 187             The developers of Ethereal might improve your changes even more,
 188                 as there's always room for improvements. Or they may implement some
 189                 advanced things on top of your code, which can be useful for yourself
 190                 too.
 191           </para>
 192         </listitem>
 193         <listitem>
 194           <para>
 195             The maintainers and developers of Ethereal will maintain your
 196             code as well, fixing it when API changes or other changes are
 197             made, and generally keeping it in tune with what is happening
 198             with Ethereal. So if Ethereal is updated (which is done often),
 199                 you can get a new Ethereal version from the website and your changes
 200                 will already be included without any effort for you.
 201           </para>
 202         </listitem>
 203       </itemizedlist>
 204     </para>
 205     <para>
 206       The Ethereal source code and binary kits for some platforms are all
 207       available on the download page of the Ethereal website:
 208       <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>.
 209     </para>
 210
 211         </section>
 212
 213   </section>
 214
 215   <section id="ChIntroReleases">
 216     <title>Releases and distributions</title>
 217     <para>
 218         The officially released files can be found at: <ulink
 219         url="&EtherealDownloadPage;"/>. A new Ethereal version is released, after
 220         significant changes compared to the last release were completed or a
 221         serious security issue was encountered. The typical release schedule is
 222         about every 4-8 weeks (although this may vary).
 223     </para>
 224     <para>
 225         There are two kinds of distributions: binary and source, both have their
 226         advantages and disadvantages.
 227     </para>
 228
 229         <section id="ChIntroReleaseBinary">
 230     <title>Binary distributions</title>
 231     <para>
 232         Binary distributions are usually easy to install (as simply starting
 233         the appropriate file is usually the only thing to do). They are available
 234         for the following systems:
 235         <itemizedlist>
 236         <listitem>
 237     <para>
 238         Win32 (.exe file). The typical Windows end user is used to get a setup.exe
 239         file, which will install all the required things for him.
 240     </para>
 241         </listitem>
 242         <listitem>
 243     <para>
 244         Debian (.deb file). A user of a Debian Package Manager (DPKG) based system
 245         is used to get a .deb file from which the package manager checks the
 246         dependancies and installs the software.
 247     </para>
 248         </listitem>
 249         <listitem>
 250     <para>
 251         RedHat (.rpm file). A user of a RedHat Package Manager (RPM) based system
 252         is used to get a .rpm file from which the package manager checks the
 253         dependancies and installs the software.
 254     </para>
 255         </listitem>
 256         <listitem>
 257     <para>
 258         Solaris. A Solaris user is used to get a file from which the package manager
 259         (PKG) checks the dependancies and installs the software.
 260     </para>
 261         </listitem>
 262         </itemizedlist>
 263         However, if you want to start developing with Ethereal, the binary
 264         distributions won't be much helpful, as you need the source files, of
 265         course.
 266     </para>
 267     <para>
 268         For details about how to build these binary distributions yourself,
 269         e.g. if you need a distribution for a special audience, see
 270         <xref linkend="ChSrcBinary"/>.
 271     </para>
 272         </section>
 273
 274         <section id="ChIntroReleaseSource">
 275         <title>Source code distributions</title>
 276     <para>
 277         It's still common for UNIX developers to give the end user a source
 278         tarball and let the user compile it on their target machine (configure,
 279         make, make install). However, for different UNIX (Linux) distributions
 280         it's becoming more common to release binary packages (e.g. .deb or .rpm
 281         files) these days.
 282     </para>
 283     <para>
 284         You should use the released sources if you want to build Ethereal from
 285         source on your platform for productive use. However, if you going to
 286         develop changes to the Ethereal sources, it might be better to use the
 287         latest SVN sources. For details about the different ways to get the
 288         Ethereal source code see <xref linkend="ChSrcObtain"/>.
 289     </para>
 290     <para>
 291         Before building Ethereal from a source distribution, make sure you have
 292         all the tools and libraries required to build. The following chapters will
 293         describe the required tools and libraries in detail.
 294     </para>
 295         </section>
 296   </section>
 297
 298   <section id="ChIntroHelp">
 299     <title>Reporting problems and getting help</title>
 300         <para>
 301       If you have problems, or need help with Ethereal, there are several
 302       places that may be of interest to you (well, beside this guide of
 303           course).
 304         </para>
 305
 306         <section id="ChIntroHomepage"><title>Website</title>
 307     <para>
 308         You will find lot's of useful information on the Ethereal homepage at
 309         <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>.
 310         </para>
 311         </section>
 312
 313         <section id="ChIntroWiki"><title>Wiki</title>
 314     <para>
 315         The Ethereal Wiki at <ulink
 316         url="&EtherealWikiSite;">&EtherealWikiSite;</ulink> provides a wide range
 317         of information related to Ethereal and packet capturing in general.
 318         You will find a lot of information not part of this developer's guide. For
 319         example, there is an explanation how to capture on a switched network,
 320         an ongoing effort to build a protocol reference and a lot more.
 321         </para>
 322         <para>
 323         And best of all, if you would like to contribute your knowledge on a
 324         specific topic (maybe a network protocol you know well), you can edit the
 325         wiki pages by simply using your webbrowser.
 326         </para>
 327         </section>
 328
 329         <section id="ChIntroFAQ"><title>FAQ</title>
 330     <para>
 331         The "Frequently Asked Questions" will list often asked questions and
 332         the corresponding answers.
 333         <note><title>Read the FAQ!</title>
 334         <para>
 335         Before sending any mail to the mailing lists below, be sure to read the
 336         FAQ, as it will often answer the question(s) you might have. This will save
 337         yourself and others a lot of time (keep in mind that a lot of people are
 338         subscribed to the mailing lists).
 339     </para>
 340     </note>
 341         You will find the FAQ inside Ethereal by clicking the menu item
 342         Help/Contents and selecting the FAQ page in the upcoming dialog.
 343     </para>
 344     <para>
 345         An online version is available at the ethereal website:
 346         <ulink url="&EtherealFAQPage;">&EtherealFAQPage;</ulink>. You might
 347         prefer this online version, as it's typically more up to date and the HTML
 348         format is easier to use.
 349     </para>
 350         </section>
 351
 352         <section id="ChIntroMailingLists"><title>Mailing Lists</title>
 353     <para>
 354       There are several mailing lists of specific Ethereal topics available:
 355       <variablelist>
 356         <varlistentry><term><command>ethereal-announce</command></term>
 357           <listitem>
 358             <para>
 359               This mailing list will inform you about new program
 360                   releases, which usually appear about every 4-8 weeks.
 361             </para>
 362           </listitem>
 363         </varlistentry>
 364         <varlistentry><term><command>ethereal-users</command></term>
 365           <listitem>
 366             <para>
 367               This list is for users of Ethereal. People post
 368               questions about building and using Ethereal, others (hopefully)
 369                   provide answers.
 370             </para>
 371           </listitem>
 372         </varlistentry>
 373         <varlistentry><term><command>ethereal-dev</command></term>
 374           <listitem>
 375             <para>
 376               This list is for Ethereal developers. People post questions about
 377                   the development of Ethereal, others (hopefully) provide answers.
 378                   If you want to start developing a protocol dissector, join this list.
 379             </para>
 380           </listitem>
 381         </varlistentry>
 382         <varlistentry><term><command>ethereal-bugs</command></term>
 383           <listitem>
 384             <para>
 385               This list is for Ethereal developers. Everytime a change to the bug
 386                   database occurs, a mail to this mailing list is generated.
 387                   If you want to be notified about all the changes to the bug
 388                   database, join this list. Details about the bug database can be
 389                   found in <xref linkend="ChIntroBugDatabase"/>.
 390             </para>
 391           </listitem>
 392         </varlistentry>
 393         <varlistentry><term><command>ethereal-cvs</command></term>
 394           <listitem>
 395             <para>
 396               This list is for Ethereal developers. Everytime a change to the SVN
 397                   repository is checked in, a mail to this mailing list is generated.
 398                   If you want to be notified about all the changes to the SVN
 399                   repository, join this list. Details about the SVN repository can be
 400                   found in <xref linkend="ChSrcSVNServer"/>.
 401             </para>
 402           </listitem>
 403         </varlistentry>
 404       </variablelist>
 405       You can subscribe to each of these lists from the Ethereal web site:
 406       <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>.  Simply
 407       select the <command>mailing lists</command> link on the left hand
 408       side of the site. The lists are archived at the Ethereal web site
 409       as well.
 410         <tip><title>Tip!</title>
 411         <para>
 412         You can search in the list archives to see if someone asked the same
 413         question some time before and maybe already got an answer. That way you
 414         don't have to wait until someone answers your question.
 415         </para>
 416         </tip>
 417     </para>
 418         </section>
 419
 420         <section id="ChIntroBugDatabase"><title>Bug database</title>
 421         <para>
 422         The Etereal community started collecting bug reports in a Bugzilla database at
 423         <ulink url="&EtherealBugsSite;">&EtherealBugsSite;</ulink>.
 424         This database is filled with manually filed bug reports, usually after some
 425         discussion on ethereal-dev, and bug reports from the QA build tooling.
 426         </para>
 427         </section>
 428
 429         <section id="ChIntroReportProblems"><title>Reporting Problems</title>
 430         <note><title>Note!</title>
 431         <para>
 432         Before reporting any problems, please make sure you have installed the
 433         latest version of Ethereal.
 434         </para>
 435         </note>
 436     <para>
 437         If you report problems, provide as much
 438         information as possible. In general, just think about what
 439         you would need to find that problem, if someone else sends you such a
 440         problem report. Also keep in mind, that people uses a lot of different
 441         platforms to compile/run Ethereal on.
 442     </para>
 443     <para>
 444       When reporting problems with Ethereal, it is helpful if you supply the
 445       following information:
 446       <orderedlist>
 447         <listitem>
 448           <para>
 449             The version number of Ethereal and the dependent libraries linked with
 450                 it, eg GTK+, etc. You can obtain this with the command
 451             <command>ethereal -v</command>.
 452           </para>
 453         </listitem>
 454         <listitem>
 455           <para>
 456             Information about the platform you run Ethereal on.
 457           </para>
 458         </listitem>
 459         <listitem>
 460           <para>
 461             A detailed description of your problem.
 462           </para>
 463         </listitem>
 464         <listitem>
 465           <para>
 466                 If you get an error/warning message, copy the text of that message (and
 467                 also a few lines before and after it, if there are some), so others may
 468                 find the build step where things go wrong.
 469                 Please don't give something like: "I get a warning when comiling x"
 470                 as this won't give any direction to look at.
 471           </para>
 472         </listitem>
 473       </orderedlist>
 474     </para>
 475         <note><title>Don't send large files!</title>
 476         <para>
 477         Do not send large files (>100KB) to the mailing lists, just place a note
 478         that further data is available on request. Large files will only annoy a
 479         lot of people on the list who are not interested in your specific problem.
 480         If required, you will be asked for further data by the persons who really
 481         can help you.
 482         </para>
 483         </note>
 484         <note><title>Don't send confidential information!</title>
 485         <para>
 486         If you send captured data to the mailing lists, or add it to your bug report,
 487         be sure it doesn't contain any sensitive or confidential information,
 488         such as passwords.
 489         </para>
 490         </note>
 491   </section>
 492
 493   <section><title>Reporting Crashes on UNIX/Linux platforms</title>
 494     <para>
 495       When reporting crashes with Ethereal, it is helpful if you supply the
 496       traceback information (besides the information mentioned in
 497           <xref linkend="ChIntroReportProblems"/>).
 498     </para>
 499           <para>
 500             You can obtain this traceback information with the following commands:
 501             <programlisting>
 502 <![CDATA[
 503 $ gdb `whereis ethereal | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
 504 backtrace
 505 ^D
 506 $
 507 ]]>
 508                 </programlisting>
 509             <note>
 510               <para>
 511                 Type the characters in the first line verbatim! Those are
 512                 back-tics there!
 513               </para>
 514             </note>
 515             <note>
 516               <para>
 517                 backtrace is a <command>gdb</command> command. You should
 518                 enter it verbatim after the first line shown above, but it will not be
 519                 echoed. The ^D
 520                 (Control-D, that is, press the Control key and the D key
 521                 together) will cause <command>gdb</command> to exit. This will
 522                 leave you with a file called
 523                 <filename>bt.txt</filename> in the current directory.
 524                 Include the file with your bug report.
 525               </para>
 526             </note>
 527             <note>
 528               <para>
 529                 If you do not have <command>gdb</command> available, you
 530                 will have to check out your operating system's debugger.
 531               </para>
 532             </note>
 533           </para>
 534           <para>
 535             You should mail the traceback to the
 536                 <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>
 537             mailing list, or append it to your bug report.
 538           </para>
 539   </section>
 540
 541   <section><title>Reporting Crashes on Windows platforms</title>
 542     <para>
 543         The Windows distributions don't contain the symbol files (.pdb), because
 544         they are very large. For this reason it's not possible to create
 545         a meaningful backtrace file from it. You should report your crash just
 546         like other problems, using the mechanism from
 547         <xref linkend="ChIntroReportProblems"/>.
 548     </para>
 549   </section>
 550   </section>
 551
 552   <section id="ChIntroOtherSources"><title>Other sources of developer information
 553   </title>
 554     <para>
 555         If you don't find the information you need inside this book, there are
 556         various other sources of information:
 557         <itemizedlist>
 558         <listitem>
 559         <para>
 560     have a look at the Ethereal source code
 561         </para>
 562         </listitem>
 563         <listitem>
 564         <para>
 565     there are various documentation files on different topics inside the
 566         source code, see all the README.xxx files
 567         </para>
 568         </listitem>
 569         <listitem>
 570         <para>
 571     tool documentation of the various tools used
 572         (e.g. manpages of sed, gcc, ...)
 573         </para>
 574         </listitem>
 575         <listitem>
 576         <para>
 577     the different mailing lists <xref linkend="ChIntroMailingLists"/>
 578         </para>
 579         </listitem>
 580         <listitem>
 581         <para>
 582     ...
 583         </para>
 584         </listitem>
 585         </itemizedlist>
 586     </para>
 587   </section>
 588
 589 </chapter>
 590 <!-- End of EUG Chapter 1 -->