docbook/dg-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 will
  88         be referred as Win32, Win or Windows might 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 an setup
 239         .exe file, which will install all the required things for him.
 240     </para>
 241         </listitem>
 242         <listitem>
 243     <para>
 244         Debian (.deb file)
 245     </para>
 246         </listitem>
 247         <listitem>
 248     <para>
 249         RedHat (.rpm file)
 250     </para>
 251         </listitem>
 252         </itemizedlist>
 253         However, if you want to start developing with Ethereal, the binary
 254         distributions won't be much helpful, as you need the source files, of
 255         course.
 256     </para>
 257     <para>
 258         For details about how to build these binary distributions yourself,
 259         e.g. if you need a distribution for a special audience, see
 260         <xref linkend="ChSrcBinary"/>.
 261     </para>
 262         </section>
 263
 264         <section id="ChIntroReleaseSource">
 265         <title>Source code distributions</title>
 266     <para>
 267         It's still common for unix developers to give the end user a source
 268         tarball and let the user compile it on their target machine (configure,
 269         make, make install). However, for different unix (linux) distributions
 270         it's becoming more common to release binary packages (e.g. .deb or .rpm
 271         files) these days.
 272     </para>
 273     <para>
 274         You should use the released sources if you want to build Ethereal from
 275         source on your platform for productive use. However, if you going to
 276         develop changes to the Ethereal sources, it might be better to use the
 277         latest SVN sources. For details about the different ways to get the
 278         Ethereal source code see <xref linkend="ChSrcObtain"/>.
 279     </para>
 280     <para>
 281         Before building Ethereal from a source distribution, make sure you have
 282         all the tools and libraries required to build. The following chapters will
 283         describe the required tools and libraries in detail.
 284     </para>
 285         </section>
 286   </section>
 287
 288   <section id="ChIntroHelp">
 289     <title>Reporting problems and getting help</title>
 290         <para>
 291       If you have problems, or need help with Ethereal, there are several
 292       places that may be of interest to you (well, beside this guide of
 293           course).
 294         </para>
 295
 296         <section id="ChIntroFAQ"><title>FAQ</title>
 297     <para>
 298         The "Frequently Asked Questions" will list often asked questions and
 299         the corresponding answers.
 300         <note><title>Read the FAQ!</title>
 301         <para>
 302         Before sending any mail to the mailing lists below, be sure to read the
 303         FAQ, as it will often answer the question(s) you might have. This will save
 304         yourself and others a lot of time (keep in mind that a lot of people are
 305         subscribed to the mailing lists).
 306     </para>
 307     </note>
 308         You will find the FAQ inside Ethereal by clicking the menu item
 309         Help/Contents and selecting the FAQ page in the upcoming dialog.
 310     </para>
 311     <para>
 312         An online version is available at the ethereal website:
 313         <ulink url="&EtherealFAQPage;">&EtherealFAQPage;</ulink>. You might
 314         prefer this online version, as it's typically more up to date and the HTML
 315         format is easier to use.
 316     </para>
 317         </section>
 318
 319         <section id="ChIntroMailingLists"><title>Mailing Lists</title>
 320     <para>
 321       There are several mailing lists of specific Ethereal topics available:
 322       <variablelist>
 323         <varlistentry><term><command>ethereal-announce</command></term>
 324           <listitem>
 325             <para>
 326               This mailing list will inform you about new program
 327                   releases, which usually appear about every 4-8 weeks.
 328             </para>
 329           </listitem>
 330         </varlistentry>
 331         <varlistentry><term><command>ethereal-users</command></term>
 332           <listitem>
 333             <para>
 334               This list is for users of Ethereal. People post
 335               questions about building and using Ethereal, others (hopefully)
 336                   provide answers.
 337             </para>
 338           </listitem>
 339         </varlistentry>
 340         <varlistentry><term><command>ethereal-dev</command></term>
 341           <listitem>
 342             <para>
 343               This list is for Ethereal developers. People post questions about
 344                   the development of Ethereal, others (hopefully) provide answers.
 345                   If you want to start developing a protocol dissector, join this list.
 346             </para>
 347           </listitem>
 348         </varlistentry>
 349         <varlistentry><term><command>ethereal-cvs</command></term>
 350           <listitem>
 351             <para>
 352               This list is for Ethereal developers. Everytime a change to the SVN
 353                   repository is checked in, a mail to this mailing list is generated.
 354                   If you want to be notified about all the changes to the SVN
 355                   repository, join this list. Details about the SVN repository can be
 356                   found in <xref linkend="ChSrcSVNServer"/>.
 357             </para>
 358           </listitem>
 359         </varlistentry>
 360       </variablelist>
 361       You can subscribe to each of these lists from the Ethereal web site:
 362       <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>.  Simply
 363       select the <command>mailing lists</command> link on the left hand
 364       side of the site. The lists are archived at the Ethereal web site
 365       as well.
 366         <tip><title>Tip!</title>
 367         <para>
 368         You can search in the list archives to see if someone asked the same
 369         question some time before and maybe already got an answer. That way you
 370         don't have to wait until someone answers your question.
 371         </para>
 372         </tip>
 373     </para>
 374         </section>
 375
 376         <section id="ChIntroReportProblems"><title>Reporting Problems</title>
 377         <note><title>Note!</title>
 378         <para>
 379         Before reporting any problems, please make sure you have installed the
 380         latest version of Ethereal.
 381         </para>
 382         </note>
 383     <para>
 384         If you report problems, provide as much
 385         information as possible. In general, just think about what
 386         you would need to find that problem, if someone else sends you such a
 387         problem report. Also keep in mind, that people uses a lot of different
 388         platforms to compile/run Ethereal on.
 389     </para>
 390     <para>
 391       When reporting problems with Ethereal, it is helpful if you supply the
 392       following information:
 393       <orderedlist>
 394         <listitem>
 395           <para>
 396             The version number of Ethereal and the dependent libraries linked with
 397                 it, eg GTK+, etc. You can obtain this with the command
 398             <command>ethereal -v</command>.
 399           </para>
 400         </listitem>
 401         <listitem>
 402           <para>
 403             Information about the platform you run Ethereal on.
 404           </para>
 405         </listitem>
 406         <listitem>
 407           <para>
 408             A detailed description of your problem.
 409           </para>
 410         </listitem>
 411         <listitem>
 412           <para>
 413                 If you get an error/warning message, copy the text of that message (and
 414                 also a few lines before and after it, if there are some), so others may
 415                 find the build step where things go wrong.
 416                 Please don't give something like: "I get a warning when comiling x"
 417                 as this won't give any direction to look at.
 418           </para>
 419         </listitem>
 420       </orderedlist>
 421     </para>
 422         <note><title>Don't send large files!</title>
 423         <para>
 424         Do not send large files (>100KB) to the mailing lists, just place a note
 425         that further data is available on request. Large files will only annoy a
 426         lot of people on the list who are not interested in your specific problem.
 427         If required, you will be asked for further data by the persons who really
 428         can help you.
 429         </para>
 430         </note>
 431         <note><title>Don't send confidential information!</title>
 432         <para>
 433         If you send captured data to the mailing lists, be sure they don't contain
 434         any sensitive or confidential information like passwords or such.
 435         </para>
 436         </note>
 437   </section>
 438
 439   <section><title>Reporting Crashes on UNIX/Linux platforms</title>
 440     <para>
 441       When reporting crashes with Ethereal, it is helpful if you supply the
 442       traceback information (besides the information mentioned in
 443           <xref linkend="ChIntroReportProblems"/>).
 444     </para>
 445           <para>
 446             You can obtain this traceback information with the following commands:
 447             <programlisting>
 448 <![CDATA[
 449 $ gdb `whereis ethereal | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
 450 backtrace
 451 ^D
 452 $
 453 ]]>
 454                 </programlisting>
 455             <note>
 456               <para>
 457                 Type the characters in the first line verbatim! Those are
 458                 back-tics there!
 459               </para>
 460             </note>
 461             <note>
 462               <para>
 463                 backtrace is a <command>gdb</command> command. You should
 464                 enter it verbatim after the first line shown above, but it will not be
 465                 echoed. The ^D
 466                 (Control-D, that is, press the Control key and the D key
 467                 together) will cause <command>gdb</command> to exit. This will
 468                 leave you with a file called
 469                 <filename>bt.txt</filename> in the current directory.
 470                 Include the file with your bug report.
 471               </para>
 472             </note>
 473             <note>
 474               <para>
 475                 If you do not have <command>gdb</command> available, you
 476                 will have to check out your operating system's debugger.
 477               </para>
 478             </note>
 479           </para>
 480           <para>
 481             You should mail the traceback to the
 482                 <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>
 483             mailing list.
 484           </para>
 485   </section>
 486
 487   <section><title>Reporting Crashes on Windows platforms</title>
 488     <para>
 489         The Windows distributions don't contain the symbol files (.pdb), because
 490         they are very large. For this reason it's not possible to create
 491         a meaningful backtrace file from it. You should report your crash just
 492         like other problems, using the mechanism from
 493         <xref linkend="ChIntroReportProblems"/>.
 494     </para>
 495   </section>
 496   </section>
 497
 498   <section id="ChIntroOtherSources"><title>Other sources of developer information
 499   </title>
 500     <para>
 501         If you don't find the information you need inside this book, there are
 502         various other sources of information:
 503         <itemizedlist>
 504         <listitem>
 505         <para>
 506     have a look at the Ethereal source code
 507         </para>
 508         </listitem>
 509         <listitem>
 510         <para>
 511     there are various documentation files on different topics inside the
 512         source code, see all the README.xxx files
 513         </para>
 514         </listitem>
 515         <listitem>
 516         <para>
 517     tool documentation of the various tools used
 518         (e.g. manpages of sed, gcc, ...)
 519         </para>
 520         </listitem>
 521         <listitem>
 522         <para>
 523     the different mailing lists <xref linkend="ChIntroMailingLists"/>
 524         </para>
 525         </listitem>
 526         <listitem>
 527         <para>
 528     ...
 529         </para>
 530         </listitem>
 531         </itemizedlist>
 532     </para>
 533   </section>
 534
 535 </chapter>
 536 <!-- End of EUG Chapter 1 -->