wireshark/docbook/wsdg_src/WSDG_chapter_libraries.xml

<!-- WSDG Chapter Libraries -->
<!-- $Id$ -->

<chapter id="ChapterLibraries">
  <title>Library Reference</title>

  <section id="ChLibIntro">
	<title>Introduction</title>
	<para>
	Several libraries are needed to build / run Wireshark. Most of the
	libraries are split into three packages:
	<orderedlist>
	<listitem>
	<para>
	Runtime package: binaries (e.g. win32 DLL's) and alike
	</para>
	</listitem>
	<listitem>
	<para>
	Developer package: documentation, header files and alike
	</para>
	</listitem>
	<listitem>
	<para>
	Source package: library sources, usually not required to
	build Wireshark
	</para>
	</listitem>
	</orderedlist>
	<tip><title>Tip!</title>
	<para>
	Win32: All libraries for the VS9 generation are available at:
	<ulink	url="http://anonsvn.wireshark.org/wireshark-win32-libs/trunk/packages/"/>,
	but see <xref linkend="ChLibsSetup"/> for an easier way to install the
	libraries.
	</para>
	</tip>
	<tip><title>Tip!</title>
	<para>
	Win64: All required libraries for the VS9 generation are available at:
	<ulink	url="http://anonsvn.wireshark.org/wireshark-win64-libs/trunk/packages/"/>,
	but see <xref linkend="ChLibsSetup"/> for an easier way to install the
	libraries. Not all libraries are available, yet.
	</para>
	</tip>
	</para>
  </section>

  <section id="ChLibsFormat">
    <title>Binary library formats</title>
	<para>
	Binary libraries are available in different formats, depending on the C
	compiler used to build it and of course the platform they were built for.
	</para>

	<section id="ChLibsFormatUnix">
	<title>Unix</title>
	<para>
	If you have installed unix binary libraries on your system, they will
	match the C compiler. If not already installed, the libraries should be
	available as a package from the platform installer, or you can download
	and compile the source and then install the binaries.
	</para>
	</section>

	<section id="ChLibsFormatWin32">
	<title>Win32: MSVC</title>
	<para>
	Most of the Win32 binary libraries you will find on the web are in this
	format. You will recognize MSVC libraries by the .lib/.dll file extension.
	</para>
	</section>

	<section id="ChLibsFormatWin32Cygwin">
	<title>Win32: cygwin gcc</title>
	<para>
	Cygwin provides most of the required libraries (with file extension .a or .lib)
	for Wireshark suitable for cygwin's gcc compiler.
	</para>
	</section>
  </section>

  <section id="ChLibsSetup">
	<title>Win32: Automated library download</title>
	<section id="ChLibsSetupInitial">
	<title>Initial download</title>

	<para>
	You can download/install all required libraries by using the setup target
	of the <filename>Makefile.nmake</filename> from the source package.
	</para>
	<tip><title>Tip!</title>
	<para>
	It's a really good idea to use the Win32 automated library download to
	install the required libraries as it makes this download very easy.
	</para>
	</tip>
	<note><title>Note!</title>
	<para>
	Before you start the download, you must have installed both
	the required tools (see <xref linkend="ChapterTools"/>) and also the
	Wireshark sources (see <xref linkend="ChSrcObtain"/>).
	</para>
	</note>
	<para>
	By default the libraries will be downloaded and installed into
	<filename>C:\wireshark-win32-libs</filename>.
	You can change this to any other location by editing the file
	<filename>config.nmake</filename> and changing the line containing
	the WIRESHARK_LIB_DIR setting to your favourite place (use an absolute path
	here).
	</para>
	<para>
	Then enter at the command line:
	</para>
	<para>
	<prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake setup</userinput>
	</para>
	<para>
	This will first check for all the various tools needed to build Wireshark,
	as described already in <xref linkend="ChToolsWin32Verify"/>.
	</para>
	<para>
	Then it will download the zipped libraries (together around 30MB!) from
	the server location at: <ulink
	url="http://anonsvn.wireshark.org/wireshark-win32-libs/trunk/packages/"/>
	into the directory specified by WIRESHARK_LIB_DIR and install (unzip) all
	required library files there.
	</para>
	<para>
	If you have problems downloading the library files, you might be connected
	to the internet through a proxy/firewall.
	In this case see the wget proxy comment in <xref linkend="ChToolsWget"/>.
	</para>
        </section>
	<section id="ChLibsSetupUpdate">
	<title>Update of a previous download</title>
	<para>
	As new versions of the libraries become available, maybe with bugfixes or
	some new functionality, your libraries get outdated.
	</para>
	<para>
	You could simply remove everything in the WIRESHARK_LIB_DIR dir and call the
	<userinput>setup</userinput> target again, but that would require a download of every file again,
	which isn't necessary.
	</para>
	<para>
	The following will bring your libraries up to date:
	</para>
	<itemizedlist>
	<listitem>
	<para>
	Update your Wireshark sources to the latest SVN files (see <xref
	linkend="ChSrcObtain"/>), so the zip filenames in the setup target
	of Makefile.nmake are in sync with the library zip files on the server.
	</para>
        </listitem>
	<listitem>
          <para>
            Execute the library setup command as described above.
	  </para>
          <para>
	<prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake setup</userinput>
	</para>
	<para>
	Note that this command will automatically do a <userinput>clean-setup</userinput> which will
        remove all files previously unzipped from the downloaded files in your
	WIRESHARK_LIB_DIR library path (all the subdirs, e.g.
	<filename>c:\wireshark-win32-libs\gtk+</filename>),
	except for the zip files located at the toplevel, which are the files
	downloaded the last time(s).
	</para>
	<para>
	Also note that as wget will download only the
	missing (updated) files, existing zip files in the WIRESHARK_LIB_DIR dir won't be
	downloaded again. Remaining (outdated) zip files shouldn't do any harm.
	</para>
        </listitem>
	</itemizedlist>
	</section>

  </section>

  <section id="ChLibsGtk">
	<title>GTK+ / GLib / GDK / Pango / ATK / GNU gettext / GNU libiconv</title>
	<para>
	The Glib library is used as a basic platform abstraction library, it's
	not related to graphical user interface (GUI) things. For a detailed
	description about GLib, see <xref linkend="ChCodeGLib"/>.
	</para>
	<para>
	The GTK and its dependent libraries are used to build Wireshark's GUI.
	For a detailed description of the GTK libraries, see <xref
	linkend="ChUIGTK"/>.
	</para>
	<para>
	All other libraries are dependent on the two libraries mentioned above,
	you will typically not come in touch with these while doing Wireshark
	development.
	</para>
	<para>
	As the requirements for the GLib/GTK libraries have increased in the past,
	the required additional libraries depend on the GLib/GTK versions you have.
	The 2.x versions require all mentioned libs.
	</para>

	<section id="ChLibsUnixGTK">
	<title>Unix</title>
	<para>
	The GLib/GTK+ libraries are available for many unix-like platforms and
	cygwin.
	</para>
	<para>
	If these libraries aren't already installed and also aren't available as a
	package for your platform, you can get them at:
	<ulink url="http://www.gtk.org/download.html"/>.
	</para>
	</section>

	<section id="ChLibsWin32GTK">
	<title>Win32 MSVC</title>
	<para>
	You can get the latest version at:
	<ulink url="http://www.gtk.org/download.html"/>.
	</para>
	</section>
  </section>

  <section id="ChLibsSMI">
	<title>SMI (optional)</title>
	<para>
	"Various tools relating to the SMI MIB Information"
	</para>

	<section id="ChLibsUnixSMI">
	<title>Unix</title>
	<para>
	If this library isn't already installed or available as a
	package for your platform, you can get it at:
	<ulink url="http://www.ibr.cs.tu-bs.de/projects/libsmi/"/>.
	</para>
	</section>

	<section id="ChLibsWin32SMI">
	<title>Win32 MSVC</title>
	<para>
	Wireshark uses the source libSMI distribution at
	<ulink url="http://www.ibr.cs.tu-bs.de/projects/libsmi/"/>.
	libSMI is compiled using MSVC++ 6.0. It's stored in the libsmi zip archive at
	<ulink url="http://anonsvn.wireshark.org/wireshark-win32-libs/trunk/packages/"/>
	</para>
	</section>

  </section>

  <section id="ChLibsCares">
    <title>c-ares (optional)</title>
	<para>
	"Library for asynchronous name resolves."
	</para>
	<para>
	This is the primary name resolving library for Wireshark. It replaces ADNS.
	</para>
	<section id="ChLibsUnixCares">
	<title>Unix</title>
	<para>
	If this library isn't already installed or available as a
	package for your platform, you can get it at:
	<ulink url="http://c-ares.haxx.se/"/>.
	</para>
	</section>
	<section id="ChLibsWin32Cares">
	<title>Win32 MSVC</title>
	<para>
	You can get the latest version at:
	<ulink url="http://c-ares.haxx.se/"/>.
	</para>
	</section>
  </section>

  <section id="ChLibsADNS">
	<title>GNU adns (optional)</title>
	<para>
	"Advanced, easy to use, asynchronous-capable DNS client library and
utilities."
	</para>

	<section id="ChLibsUnixADNS">
	<title>Unix</title>
	<para>
	If this library isn't already installed or available as a
	package for your platform, you can get it at:
	<ulink url="http://www.gnu.org/software/adns/"/>.
	</para>
	</section>

	<section id="ChLibsWin32ADNS">
	<title>Win32 MSVC</title>
	<para>
	You can get the latest version at:
	<ulink url="http://adns.jgaa.com/"/>
	</para>
	</section>

  </section>


  <section id="ChLibsZlib">
	<title>zlib (optional)</title>
	<para>
	"zlib is designed to be a
	<ulink url="http://www.gzip.org/zlib/zlib_license.html">free</ulink>,
	general-purpose, legally unencumbered -- that is, not covered by any
	patents -- lossless data-compression library for use on virtually any computer
	hardware and operating system."
	</para>

	<section id="ChLibsUnixZlib">
	<title>Unix</title>
	<para>
	If this library isn't already installed or available as a
	package for your platform, you can get it at:
	<ulink url="http://www.gzip.org/zlib/"/>.
	</para>
	</section>

	<section id="ChLibsWin32Zlib">
	<title>Win32 MSVC</title>
	<para>
	You can get the latest version at:
	<ulink url="http://gnuwin32.sourceforge.net/packages/zlib.htm"/>
	</para>
	<para>
	(A version for the MSVC2003 compiler can be found at:
	<ulink url="http://www.winimage.com/zLibDll/"/>)
	</para>
	</section>

  </section>


  <section id="ChLibsPcap">
	<title>libpcap/WinPcap (optional)</title>
	<para>
	"packet capture library"
	</para>

	<section id="ChLibsLibpcap">
	<title>Unix: libpcap</title>
	<para>
	If this library isn't already installed or available as a
	package for your platform, you can get it at:
	<ulink url="http://www.tcpdump.org/"/>.
	</para>
	</section>

	<section id="ChLibsWinpPcap">
	<title>Win32 MSVC: WinPcap</title>
	<para>
	You can get the "Windows packet capture library" at:
	<ulink url="http://www.winpcap.org/install/default.htm"/>
	</para>
	</section>

  </section>


  <section id="ChLibsGNUTLS">
	<title>GnuTLS (optional)</title>
	<para>
	The "GNU Transport Layer Security Library" is used to dissect SSL and TLS
	protocols (aka: HTTPS).
	</para>

	<section id="ChLibsUnixGNUTLS">
	<title>Unix</title>
	<para>
	If this library isn't already installed or available as a
	package for your platform, you can get it at:
	<ulink url="http://www.gnu.org/software/gnutls/download.html"/>.
	</para>
	</section>

	<section id="ChLibsWin32GNUTLS">
	<title>Win32 MSVC</title>
	<para>
	We roll our own version using:
	<ulink url="http://josefsson.org/gnutls4win/"/>
	</para>
	</section>

  </section>

  <section id="ChLibsGcrypt">
	<title>Gcrypt (optional)</title>
	<para>
	The "Gcrypt Library" is Low-level encryption library and provides
	support for many ciphers, such as DES, 3DES, AES, Blowfish, and others..
	</para>

	<section id="ChLibsUnixGcrypt">
	<title>Unix</title>
	<para>
	If this library isn't already installed or available as a
	package for your platform, you can get it at:
	<ulink url="http://directory.fsf.org/security/libgcrypt.html"/>.
	</para>
	</section>

	<section id="ChLibsWin32Gcrypt">
	<title>Win32 MSVC</title>
	<para>
	Part of our homemade GnuTLS package.
	</para>
	</section>

  </section>

  <section id="ChLibsKerberos">
	<title>Kerberos (optional)</title>
	<para>
	The Kerberos library is used to dissect Kerberos, sealed DCERPC and
	secureLDAP protocols.
	</para>

	<section id="ChLibsUnixKerberos">
	<title>Unix</title>
	<para>
	If this library isn't already installed or available as a
	package for your platform, you can get it at:
	<ulink url="http://web.mit.edu/Kerberos/dist/"/>.
	</para>
	<para>
	XXX - Is it supported on *NIX at all?
	</para>
	</section>

	<section id="ChLibsWin32Kerberos">
	<title>Win32 MSVC</title>
	<para>
	You can get the latest version of KfW "Kerberos for Windows" at:
	<ulink url="http://web.mit.edu/Kerberos/dist/"/>
	</para>
	</section>

  </section>

  <section id="ChLibsLua">
	<title>LUA (optional)</title>
	<para>
	The LUA library is used to add scripting support to Wireshark.
	</para>

	<section id="ChLibsUnixLua">
	<title>Unix</title>
	<para>
	If this library isn't already installed or available as a
	package for your platform, you can get it at:
	<ulink url="http://www.lua.org/download.html"/>.
	</para>
	</section>

	<section id="ChLibsWin32Lua">
	<title>Win32 MSVC</title>
	<para>
	You can get the latest version at:
	<ulink url="http://luaforge.net/frs/?group_id=110"/>
	</para>
	</section>

  </section>

  <section id="ChLibsPortAudio">
	<title>PortAudio (optional)</title>
	<para>
	The PortAudio library enables audio output for RTP streams.
	</para>

	<section id="ChLibsUnixPortAudio">
	<title>Unix</title>
	<para>
	If this library isn't already installed or available as a
	package for your platform, you can get it at:
	<ulink url="http://www.portaudio.com/download.html"/>.
	</para>
	</section>

	<section id="ChLibsWin32PortAudio">
	<title>Win32 MSVC</title>
	<para>
	You can get the latest version at:
	<ulink url="http://www.portaudio.com/download.html"/>
	</para>
	</section>

  </section>

  <section id="ChLibsGeoIP">
	<title>GeoIP (optional)</title>
	<para>
	MaxMind Inc. publishes a GeoIP database for use in open source software.
	It can be used to map IP addresses to geographical locations.
	</para>

	<section id="ChLibsUnixGeoIP">
	<title>Unix</title>
	<para>
	If this library isn't already installed or available as a
	package for your platform, you can get it at:
	<ulink url="http://www.maxmind.com/app/c"/>.
	</para>
	</section>

	<section id="ChLibsWin32GeoIP">
	<title>Win32 MSVC</title>
	<para>
	You can get the latest version at:
	<ulink url="http://www.maxmind.com/app/c"/>
	</para>
	</section>
  </section>

</chapter>
<!-- End of WSDG Chapter Libraries -->