docbook/wsdg_src/WSDG_chapter_libraries.xml

   1 <!-- WSDG Chapter Libraries -->
   2 <!-- $Id$ -->
   3
   4 <chapter id="ChapterLibraries">
   5   <title>Library Reference</title>
   6
   7   <section id="ChLibIntro">
   8         <title>Introduction</title>
   9         <para>
  10         Several libraries are needed to build / run Wireshark. Most of the
  11         libraries are split into three packages:
  12         <orderedlist>
  13         <listitem>
  14         <para>
  15         Runtime package: binaries (e.g. win32 DLL's) and alike
  16         </para>
  17         </listitem>
  18         <listitem>
  19         <para>
  20         Developer package: documentation, header files and alike
  21         </para>
  22         </listitem>
  23         <listitem>
  24         <para>
  25         Source package: library sources, usually not required to
  26         build Wireshark
  27         </para>
  28         </listitem>
  29         </orderedlist>
  30         <tip><title>Tip!</title>
  31         <para>
  32         Win32: All libraries for the VS9 generation are available at:
  33         <ulink  url="http://anonsvn.wireshark.org/wireshark-win32-libs/trunk/packages/"/>,
  34         but see <xref linkend="ChLibsSetup"/> for an easier way to install the
  35         libraries.
  36         </para>
  37         </tip>
  38         <tip><title>Tip!</title>
  39         <para>
  40         Win64: All required libraries for the VS9 generation are available at:
  41         <ulink  url="http://anonsvn.wireshark.org/wireshark-win64-libs/trunk/packages/"/>,
  42         but see <xref linkend="ChLibsSetup"/> for an easier way to install the
  43         libraries. Not all libraries are available, yet.
  44         </para>
  45         </tip>
  46         </para>
  47   </section>
  48
  49   <section id="ChLibsFormat">
  50     <title>Binary library formats</title>
  51         <para>
  52         Binary libraries are available in different formats, depending on the C
  53         compiler used to build it and of course the platform they were built for.
  54         </para>
  55
  56         <section id="ChLibsFormatUnix">
  57         <title>Unix</title>
  58         <para>
  59         If you have installed unix binary libraries on your system, they will
  60         match the C compiler. If not already installed, the libraries should be
  61         available as a package from the platform installer, or you can download
  62         and compile the source and then install the binaries.
  63         </para>
  64         </section>
  65
  66         <section id="ChLibsFormatWin32">
  67         <title>Win32: MSVC</title>
  68         <para>
  69         Most of the Win32 binary libraries you will find on the web are in this
  70         format. You will recognize MSVC libraries by the .lib/.dll file extension.
  71         </para>
  72         </section>
  73
  74         <section id="ChLibsFormatWin32Cygwin">
  75         <title>Win32: cygwin gcc</title>
  76         <para>
  77         Cygwin provides most of the required libraries (with file extension .a or .lib)
  78         for Wireshark suitable for cygwin's gcc compiler.
  79         </para>
  80         </section>
  81   </section>
  82
  83   <section id="ChLibsSetup">
  84         <title>Win32: Automated library download</title>
  85         <section id="ChLibsSetupInitial">
  86         <title>Initial download</title>
  87
  88         <para>
  89         You can download/install all required libraries by using the setup target
  90         of the <filename>Makefile.nmake</filename> from the source package.
  91         </para>
  92         <tip><title>Tip!</title>
  93         <para>
  94         It's a really good idea to use the Win32 automated library download to
  95         install the required libraries as it makes this download very easy.
  96         </para>
  97         </tip>
  98         <note><title>Note!</title>
  99         <para>
 100         Before you start the download, you must have installed both
 101         the required tools (see <xref linkend="ChapterTools"/>) and also the
 102         Wireshark sources (see <xref linkend="ChSrcObtain"/>).
 103         </para>
 104         </note>
 105         <para>
 106         By default the libraries will be downloaded and installed into
 107         <filename>C:\wireshark-win32-libs</filename>.
 108         You can change this to any other location by editing the file
 109         <filename>config.nmake</filename> and changing the line containing
 110         the WIRESHARK_LIB_DIR setting to your favourite place (use an absolute path
 111         here).
 112         </para>
 113         <para>
 114         Then enter at the command line:
 115         </para>
 116         <para>
 117         <prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake setup</userinput>
 118         </para>
 119         <para>
 120         This will first check for all the various tools needed to build Wireshark,
 121         as described already in <xref linkend="ChToolsWin32Verify"/>.
 122         </para>
 123         <para>
 124         Then it will download the zipped libraries (together around 30MB!) from
 125         the server location at: <ulink
 126         url="http://anonsvn.wireshark.org/wireshark-win32-libs/trunk/packages/"/>
 127         into the directory specified by WIRESHARK_LIB_DIR and install (unzip) all
 128         required library files there.
 129         </para>
 130         <para>
 131         If you have problems downloading the library files, you might be connected
 132         to the internet through a proxy/firewall.
 133         In this case see the wget proxy comment in <xref linkend="ChToolsWget"/>.
 134         </para>
 135         </section>
 136         <section id="ChLibsSetupUpdate">
 137         <title>Update of a previous download</title>
 138         <para>
 139         As new versions of the libraries become available, maybe with bugfixes or
 140         some new functionality, your libraries get outdated.
 141         </para>
 142         <para>
 143         You could simply remove everything in the WIRESHARK_LIB_DIR dir and call the
 144         <userinput>setup</userinput> target again, but that would require a download of every file again,
 145         which isn't necessary.
 146         </para>
 147         <para>
 148         The following will bring your libraries up to date:
 149         </para>
 150         <itemizedlist>
 151         <listitem>
 152         <para>
 153         Update your Wireshark sources to the latest SVN files (see <xref
 154         linkend="ChSrcObtain"/>), so the zip filenames in the setup target
 155         of Makefile.nmake are in sync with the library zip files on the server.
 156         </para>
 157         </listitem>
 158         <listitem>
 159           <para>
 160             Execute the library setup command as described above.
 161           </para>
 162           <para>
 163         <prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake setup</userinput>
 164         </para>
 165         <para>
 166         Note that this command will automatically do a <userinput>clean-setup</userinput> which will
 167         remove all files previously unzipped from the downloaded files in your
 168         WIRESHARK_LIB_DIR library path (all the subdirs, e.g.
 169         <filename>c:\wireshark-win32-libs\gtk+</filename>),
 170         except for the zip files located at the toplevel, which are the files
 171         downloaded the last time(s).
 172         </para>
 173         <para>
 174         Also note that as wget will download only the
 175         missing (updated) files, existing zip files in the WIRESHARK_LIB_DIR dir won't be
 176         downloaded again. Remaining (outdated) zip files shouldn't do any harm.
 177         </para>
 178         </listitem>
 179         </itemizedlist>
 180         </section>
 181
 182   </section>
 183
 184   <section id="ChLibsGtk">
 185         <title>GTK+ / GLib / GDK / Pango / ATK / GNU gettext / GNU libiconv</title>
 186         <para>
 187         The Glib library is used as a basic platform abstraction library, it's
 188         not related to graphical user interface (GUI) things. For a detailed
 189         description about GLib, see <xref linkend="ChCodeGLib"/>.
 190         </para>
 191         <para>
 192         The GTK and its dependent libraries are used to build Wireshark's GUI.
 193         For a detailed description of the GTK libraries, see <xref
 194         linkend="ChUIGTK"/>.
 195         </para>
 196         <para>
 197         All other libraries are dependent on the two libraries mentioned above,
 198         you will typically not come in touch with these while doing Wireshark
 199         development.
 200         </para>
 201         <para>
 202         As the requirements for the GLib/GTK libraries have increased in the past,
 203         the required additional libraries depend on the GLib/GTK versions you have.
 204         The 2.x versions require all mentioned libs.
 205         </para>
 206
 207         <section id="ChLibsUnixGTK">
 208         <title>Unix</title>
 209         <para>
 210         The GLib/GTK+ libraries are available for many unix-like platforms and
 211         cygwin.
 212         </para>
 213         <para>
 214         If these libraries aren't already installed and also aren't available as a
 215         package for your platform, you can get them at:
 216         <ulink url="http://www.gtk.org/download.html"/>.
 217         </para>
 218         </section>
 219
 220         <section id="ChLibsWin32GTK">
 221         <title>Win32 MSVC</title>
 222         <para>
 223         You can get the latest version at:
 224         <ulink url="http://www.gtk.org/download.html"/>.
 225         </para>
 226         </section>
 227   </section>
 228
 229   <section id="ChLibsSMI">
 230         <title>SMI (optional)</title>
 231         <para>
 232         "Various tools relating to the SMI MIB Information"
 233         </para>
 234
 235         <section id="ChLibsUnixSMI">
 236         <title>Unix</title>
 237         <para>
 238         If this library isn't already installed or available as a
 239         package for your platform, you can get it at:
 240         <ulink url="http://www.ibr.cs.tu-bs.de/projects/libsmi/"/>.
 241         </para>
 242         </section>
 243
 244         <section id="ChLibsWin32SMI">
 245         <title>Win32 MSVC</title>
 246         <para>
 247         Wireshark uses the source libSMI distribution at
 248         <ulink url="http://www.ibr.cs.tu-bs.de/projects/libsmi/"/>.
 249         libSMI is compiled using MSVC++ 6.0. It's stored in the libsmi zip archive at
 250         <ulink url="http://anonsvn.wireshark.org/wireshark-win32-libs/trunk/packages/"/>
 251         </para>
 252         </section>
 253
 254   </section>
 255
 256   <section id="ChLibsCares">
 257     <title>c-ares (optional)</title>
 258         <para>
 259         "Library for asynchronous name resolves."
 260         </para>
 261         <para>
 262         This is the primary name resolving library for Wireshark. It replaces ADNS.
 263         </para>
 264         <section id="ChLibsUnixCares">
 265         <title>Unix</title>
 266         <para>
 267         If this library isn't already installed or available as a
 268         package for your platform, you can get it at:
 269         <ulink url="http://c-ares.haxx.se/"/>.
 270         </para>
 271         </section>
 272         <section id="ChLibsWin32Cares">
 273         <title>Win32 MSVC</title>
 274         <para>
 275         You can get the latest version at:
 276         <ulink url="http://c-ares.haxx.se/"/>.
 277         </para>
 278         </section>
 279   </section>
 280
 281   <section id="ChLibsADNS">
 282         <title>GNU adns (optional)</title>
 283         <para>
 284         "Advanced, easy to use, asynchronous-capable DNS client library and
 285 utilities."
 286         </para>
 287
 288         <section id="ChLibsUnixADNS">
 289         <title>Unix</title>
 290         <para>
 291         If this library isn't already installed or available as a
 292         package for your platform, you can get it at:
 293         <ulink url="http://www.gnu.org/software/adns/"/>.
 294         </para>
 295         </section>
 296
 297         <section id="ChLibsWin32ADNS">
 298         <title>Win32 MSVC</title>
 299         <para>
 300         You can get the latest version at:
 301         <ulink url="http://adns.jgaa.com/"/>
 302         </para>
 303         </section>
 304
 305   </section>
 306
 307
 308   <section id="ChLibsZlib">
 309         <title>zlib (optional)</title>
 310         <para>
 311         "zlib is designed to be a
 312         <ulink url="http://www.gzip.org/zlib/zlib_license.html">free</ulink>,
 313         general-purpose, legally unencumbered -- that is, not covered by any
 314         patents -- lossless data-compression library for use on virtually any computer
 315         hardware and operating system."
 316         </para>
 317
 318         <section id="ChLibsUnixZlib">
 319         <title>Unix</title>
 320         <para>
 321         If this library isn't already installed or available as a
 322         package for your platform, you can get it at:
 323         <ulink url="http://www.gzip.org/zlib/"/>.
 324         </para>
 325         </section>
 326
 327         <section id="ChLibsWin32Zlib">
 328         <title>Win32 MSVC</title>
 329         <para>
 330         You can get the latest version at:
 331         <ulink url="http://gnuwin32.sourceforge.net/packages/zlib.htm"/>
 332         </para>
 333         <para>
 334         (A version for the MSVC2003 compiler can be found at:
 335         <ulink url="http://www.winimage.com/zLibDll/"/>)
 336         </para>
 337         </section>
 338
 339   </section>
 340
 341
 342   <section id="ChLibsPcap">
 343         <title>libpcap/WinPcap (optional)</title>
 344         <para>
 345         "packet capture library"
 346         </para>
 347
 348         <section id="ChLibsLibpcap">
 349         <title>Unix: libpcap</title>
 350         <para>
 351         If this library isn't already installed or available as a
 352         package for your platform, you can get it at:
 353         <ulink url="http://www.tcpdump.org/"/>.
 354         </para>
 355         </section>
 356
 357         <section id="ChLibsWinpPcap">
 358         <title>Win32 MSVC: WinPcap</title>
 359         <para>
 360         You can get the "Windows packet capture library" at:
 361         <ulink url="http://www.winpcap.org/install/default.htm"/>
 362         </para>
 363         </section>
 364
 365   </section>
 366
 367
 368   <section id="ChLibsGNUTLS">
 369         <title>GnuTLS (optional)</title>
 370         <para>
 371         The "GNU Transport Layer Security Library" is used to dissect SSL and TLS
 372         protocols (aka: HTTPS).
 373         </para>
 374
 375         <section id="ChLibsUnixGNUTLS">
 376         <title>Unix</title>
 377         <para>
 378         If this library isn't already installed or available as a
 379         package for your platform, you can get it at:
 380         <ulink url="http://www.gnu.org/software/gnutls/download.html"/>.
 381         </para>
 382         </section>
 383
 384         <section id="ChLibsWin32GNUTLS">
 385         <title>Win32 MSVC</title>
 386         <para>
 387         We roll our own version using:
 388         <ulink url="http://josefsson.org/gnutls4win/"/>
 389         </para>
 390         </section>
 391
 392   </section>
 393
 394   <section id="ChLibsGcrypt">
 395         <title>Gcrypt (optional)</title>
 396         <para>
 397         The "Gcrypt Library" is Low-level encryption library and provides
 398         support for many ciphers, such as DES, 3DES, AES, Blowfish, and others..
 399         </para>
 400
 401         <section id="ChLibsUnixGcrypt">
 402         <title>Unix</title>
 403         <para>
 404         If this library isn't already installed or available as a
 405         package for your platform, you can get it at:
 406         <ulink url="http://directory.fsf.org/security/libgcrypt.html"/>.
 407         </para>
 408         </section>
 409
 410         <section id="ChLibsWin32Gcrypt">
 411         <title>Win32 MSVC</title>
 412         <para>
 413         Part of our homemade GnuTLS package.
 414         </para>
 415         </section>
 416
 417   </section>
 418
 419   <section id="ChLibsKerberos">
 420         <title>Kerberos (optional)</title>
 421         <para>
 422         The Kerberos library is used to dissect Kerberos, sealed DCERPC and
 423         secureLDAP protocols.
 424         </para>
 425
 426         <section id="ChLibsUnixKerberos">
 427         <title>Unix</title>
 428         <para>
 429         If this library isn't already installed or available as a
 430         package for your platform, you can get it at:
 431         <ulink url="http://web.mit.edu/Kerberos/dist/"/>.
 432         </para>
 433         <para>
 434         XXX - Is it supported on *NIX at all?
 435         </para>
 436         </section>
 437
 438         <section id="ChLibsWin32Kerberos">
 439         <title>Win32 MSVC</title>
 440         <para>
 441         You can get the latest version of KfW "Kerberos for Windows" at:
 442         <ulink url="http://web.mit.edu/Kerberos/dist/"/>
 443         </para>
 444         </section>
 445
 446   </section>
 447
 448   <section id="ChLibsLua">
 449         <title>LUA (optional)</title>
 450         <para>
 451         The LUA library is used to add scripting support to Wireshark.
 452         </para>
 453
 454         <section id="ChLibsUnixLua">
 455         <title>Unix</title>
 456         <para>
 457         If this library isn't already installed or available as a
 458         package for your platform, you can get it at:
 459         <ulink url="http://www.lua.org/download.html"/>.
 460         </para>
 461         </section>
 462
 463         <section id="ChLibsWin32Lua">
 464         <title>Win32 MSVC</title>
 465         <para>
 466         You can get the latest version at:
 467         <ulink url="http://luaforge.net/frs/?group_id=110"/>
 468         </para>
 469         </section>
 470
 471   </section>
 472
 473   <section id="ChLibsPortAudio">
 474         <title>PortAudio (optional)</title>
 475         <para>
 476         The PortAudio library enables audio output for RTP streams.
 477         </para>
 478
 479         <section id="ChLibsUnixPortAudio">
 480         <title>Unix</title>
 481         <para>
 482         If this library isn't already installed or available as a
 483         package for your platform, you can get it at:
 484         <ulink url="http://www.portaudio.com/download.html"/>.
 485         </para>
 486         </section>
 487
 488         <section id="ChLibsWin32PortAudio">
 489         <title>Win32 MSVC</title>
 490         <para>
 491         You can get the latest version at:
 492         <ulink url="http://www.portaudio.com/download.html"/>
 493         </para>
 494         </section>
 495
 496   </section>
 497
 498   <section id="ChLibsGeoIP">
 499         <title>GeoIP (optional)</title>
 500         <para>
 501         MaxMind Inc. publishes a GeoIP database for use in open source software.
 502         It can be used to map IP addresses to geographical locations.
 503         </para>
 504
 505         <section id="ChLibsUnixGeoIP">
 506         <title>Unix</title>
 507         <para>
 508         If this library isn't already installed or available as a
 509         package for your platform, you can get it at:
 510         <ulink url="http://www.maxmind.com/app/c"/>.
 511         </para>
 512         </section>
 513
 514         <section id="ChLibsWin32GeoIP">
 515         <title>Win32 MSVC</title>
 516         <para>
 517         You can get the latest version at:
 518         <ulink url="http://www.maxmind.com/app/c"/>
 519         </para>
 520         </section>
 521   </section>
 522
 523 </chapter>
 524 <!-- End of WSDG Chapter Libraries -->