Update references to the WinPcap Web site.
[obnox/wireshark/wip.git] / docbook / edg_src / EDG_chapter_libraries.xml
1 <!-- EDG Chapter Libraries -->
2 <!-- $Id$ -->
3
4 <chapter id="ChapterLibraries">
5   <title>Libraries</title>
6   
7   <section id="ChLibIntro">
8         <title>Introduction</title>
9         <para>
10         Several libraries are needed to build / run Ethereal. Most of the
11         libraries are splitted 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 ethereal
27         </para>
28         </listitem>
29         </orderedlist>
30         <tip><title>Tip!</title>
31         <para>
32         Win32: All required libraries for the MSVC
33         generation are available at: 
34         <ulink  url="http://www.ethereal.com/distribution/win32/development/"/>,
35         but see <xref linkend="ChLibsSetup"/> for an easier way to install the 
36         libraries.
37         </para>
38         </tip>
39         </para>
40   </section>
41         
42   <section id="ChLibsFormat">
43     <title>Binary library formats</title>
44         <para>
45         Binary libraries are available in different formats, depending on the C 
46         compiler (see <xref linkend="ChToolsCompiler"/>) used to build it and of 
47         course the platform they were build for.
48         </para>
49         
50         <section id="ChLibsFormatUnix">
51         <title>Unix</title>
52         <para>
53         If you have installed unix binary libraries on your system, they will 
54         match the C compiler. If not already installed, the libraries should be
55         available as a package from the platform installer, or you can download
56         and compile the source and install that binaries then.
57         </para>
58         </section>
59
60         <section id="ChLibsFormatWin32MSVC6">
61         <title>Win32: MSVC V6</title>
62         <para>
63         Recommended for current Win32 Ethereal releases.
64         Most of the Win32 binary libraries you will find on the web are in this
65         format. You will recognize MSVC libraries by the .lib/.dll file extension.
66         </para>
67         </section>
68
69         <section id="ChLibsFormatWin32MSVC2003">
70         <title>Win32: MSVC 2003</title>
71         <para>
72         Currently not widely available, but the first libraries in that format can 
73         be seen on the web. These libraries have the same .lib/.dll file 
74         extension, but unfortunately they are not completely compatible as they 
75         are linked with different dependant libraries, see <xref 
76         linkend="ChToolsCompiler"/> for some further explanations.
77         </para>
78         </section>
79
80         <section id="ChLibsFormatWin32Cygwin">
81         <title>Win32: cygwin gcc</title>
82         <para>
83         Cygwin provides most of the required libraries (with file extension .a/.lib) 
84         for Ethereal suitable for cygwin's gcc compiler.
85         </para>
86         </section>
87   </section>
88         
89   <section id="ChLibsSetup">
90         <title>Win32: Automated library download</title>
91         <tip><title>Tip!</title>
92         <para>
93         It's a really good idea to use the Win32 automated library download to 
94         install the required libraries as it makes this download very easy.
95         </para>
96         </tip>
97         <warning><title>Warning!</title>
98         <para>
99         The library zip files on the server and in the setup target will match 
100         only for the latest sources, as old zip files will be moved into the 
101         <filename>old</filename> folder on the server. So you cannot use the 
102         setup target for "old" (this may even include the released) sources!
103         </para>
104         </warning>
105         <para>
106         You can download/install all required libraries by using the setup target 
107         of the <filename>Makefile.nmake</filename> from the source package.
108         </para>
109         <para>
110         Before you start the download, you must have installed both
111         the required tools (see <xref linkend="ChapterTools"/>) and also the 
112         Ethereal sources (see <xref linkend="ChSrcObtain"/>).
113         </para>
114         <para>
115         By default the libraries will be downloaded and installed into 
116         <filename>C:\ethereal-win32-libs</filename>.
117         You can change this to any other location by editing the file
118         <filename>config.nmake</filename> and changing the line containing 
119         the ETHEREAL_LIBS setting to your favourite place (use an absolute path 
120         here).
121         </para>
122         <para>
123         Then enter at the command line:
124         </para>
125         <para>
126         <prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake setup</userinput>
127         </para>
128         <para>
129         This will first check for all the various tools needed to build Ethereal,
130         as described already in <xref linkend="ChToolsWin32Verify"/>.
131         </para>
132         <para>
133         Then it will download the zipped libraries into the directory specified by 
134         ETHEREAL_LIBS and install (unzip) all required library files there.
135         </para>
136         <para>
137         If you have problems downloading the library files, see the wget proxy 
138         comment in <xref linkend="ChToolsWget"/>.
139         </para>
140
141         <section id="ChLibsSetupUpdate">
142         <title>Update of a previous download</title>
143         <para>
144         As new versions of the libraries become available, maybe with bugfixes or
145         some new functionality, your libraries get outdated.
146         </para>
147         <para>
148         You could simply remove everything in the ETHEREAL_LIBS dir and call the 
149         setup target again, but that would require to download every file again 
150         (currently about 33MB), which isn't necessary.
151         </para>
152         <para>
153         The following will bring your libraries up to date:
154         </para>
155         <itemizedlist>
156         <listitem>
157         <para>
158         Update your Ethereal sources to the latest SVN files (see <xref 
159         linkend="ChSrcObtain"/>), so the zip filenames in the setup target 
160         of Makefile.nmake is in sync with the library zip files on the server.
161         </para>
162         </listitem>
163         <listitem>
164         <para>  
165         Remove all files previously unzipped from the downloaded files in your 
166         ETHEREAL_LIBS library path (all the subdirs, e.g. 
167         <filename>c:\ethereal_libs\gtk+</filename>), 
168         except for the zip files located at the toplevel, which are the files 
169         downloaded the last time(s). You could do this, be entering at the command line:
170         </para>
171         <para>
172         <prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake clean_setup</userinput>
173         </para>
174         </listitem>
175         <listitem>
176         <para>
177         Start the setup target described above. As wget will download only the 
178         missing files, existing zip files in the ETHEREAL_LIBS dir won't be 
179         downloaded again. Outdated zip files shouldn't do any harm.
180         </para>
181         </listitem>
182         </itemizedlist>
183         </section>
184         
185   </section>
186
187   <section id="ChLibsGtk">
188         <title>GTK+ / GLib / GDK / Pango / ATK / GNU gettext / GNU libiconv</title>
189         <para>
190         The Glib library is used as a basic platform abstraction library, it's 
191         not related to graphical user interface (GUI) things. For a detailed 
192         description about GLib, see <xref linkend="ChCodeGLib"/>.
193         </para>
194         <para>
195         The GTK and it's dependant libraries are used to build Ethereal's GUI. 
196         For a detailed description of the GTK libraries, see <xref 
197         linkend="ChUIGTK"/>.
198         </para>
199         <para>
200         All other libraries are dependant on the two libraries mentioned above, 
201         you will typically not come in touch with these while doing Ethereal 
202         development. 
203         </para>
204         <para>
205         As the requirements for the GLib/GTK libraries increased in the past, it 
206         depends on the GLib/GTK versions you have, which additional libraries are 
207         required. The 1.x versions only needed GLib/GDK/GTK+, while the 2.x 
208         versions require all mentioned libs.
209         </para>
210
211         <section id="ChLibsUnixGTK">
212         <title>Unix</title>
213         <para>
214         The GLib/GTK+ libraries are available for many unix-like platforms and 
215         cygwin.
216         </para>
217         <para>
218         If these libraries aren't already installed and also not available as a 
219         package for your platform, you can get them at: 
220         <ulink url="http://www.gtk.org"/>.
221         </para>
222         </section>
223
224         <section id="ChLibsWin32GTK">
225         <title>Win32 MSVC</title>
226         <para>
227         You can get the latest version at: 
228         <ulink url="http://www.gimp.org/%7Etml/gimp/win32/downloads.html"/>.
229         </para>
230         </section>
231   </section>
232   
233   <section id="ChLibsSNMP">
234         <title>Net SNMP (previously known as "ucd-snmp")</title>
235         <para>
236         "Various tools relating to the Simple Network Management Protocol"
237         </para>
238         
239         <section id="ChLibsUnixSNMP">
240         <title>Unix</title>
241         <para>
242         If this library isn't already installed and also not available as a 
243         package for your platform, you can get it at: 
244         <ulink url="http://sourceforge.net/projects/net-snmp/"/>.
245         </para>
246         </section>
247
248         <section id="ChLibsWin32SNMP">
249         <title>Win32 MSVC</title>
250         <para>
251         Ethereal uses the source Net-SNMP distribution at 
252         <ulink url="http://sourceforge.net/projects/net-snmp/"/>.
253         Then libsnmp is compiled with the "libsnmp - Win32 Release" project 
254         using MSVC++ 6.0. A file called "README.ethereal" has been placed in the 
255         net-snmp zip archive at <ulink 
256         url="http://anonsvn.ethereal.com/ethereal-win32-libs/trunk/packages/"/>
257         describing the changes in more detail.
258         </para>
259         </section>
260                 
261   </section>
262   
263
264   <section id="ChLibsADNS">
265         <title>GNU ADNS (optional)</title>
266         <para>
267         "Advanced, easy to use, asynchronous-capable DNS client library and
268 utilities."
269         </para>
270         
271         <section id="ChLibsUnixADNS">
272         <title>Unix</title>
273         <para>
274         If this library isn't already installed and also not available as a 
275         package for your platform, you can get it at: 
276         <ulink url="http://www.gnu.org/software/adns/"/>.
277         </para>
278         </section>
279
280         <section id="ChLibsWin32ADNS">
281         <title>Win32 MSVC</title>
282         <para>
283         You can get the latest version at: 
284         <ulink url="http://adns.jgaa.com/"/>
285         </para>
286         </section>
287         
288   </section>
289   
290
291   <section id="ChLibsPCRE">
292         <title>PCRE(optional)</title>
293         <para>
294         "Perl compatible regular expressions"
295         </para>
296         
297         <section id="ChLibsUnixPCRE">
298         <title>Unix</title>
299         <para>
300         If this library isn't already installed and also not available as a 
301         package for your platform, you can get it at: 
302         <ulink url="http://www.pcre.org/"/>.
303         </para>
304         </section>
305
306         <section id="ChLibsWin32PCRE">
307         <title>Win32 MSVC</title>
308         <para>
309         You can get the latest version at: 
310         <ulink url="http://gnuwin32.sourceforge.net/packages/pcre.htm"/>
311         </para>
312         </section>
313                 
314   </section>
315   
316   
317   <section id="ChLibsZlib">
318         <title>zlib (optional)</title>
319         <para>
320         "zlib is designed to be a 
321         <ulink url="http://www.gzip.org/zlib/zlib_license.html">free</ulink>,
322         general-purpose, legally unencumbered -- that is, not covered by any
323         patents -- lossless data-compression library for use on virtually any computer
324         hardware and operating system."
325         </para>
326
327         <section id="ChLibsUnixZlib">
328         <title>Unix</title>
329         <para>
330         If this library isn't already installed and also not available as a 
331         package for your platform, you can get it at: 
332         <ulink url="http://www.gzip.org/zlib/"/>.
333         </para>
334         </section>
335
336         <section id="ChLibsWin32Zlib">
337         <title>Win32 MSVC</title>
338         <para>
339         You can get the latest version at: 
340         <ulink url="http://gnuwin32.sourceforge.net/packages/zlib.htm"/>
341         </para>
342         <para>
343         (A version for the MSVC2003 compiler can be found at:
344         <ulink url="http://www.winimage.com/zLibDll/"/>)
345         </para>
346         </section>
347
348   </section>
349   
350   
351   <section id="ChLibsPcap">
352         <title>libpcap/WinPcap (optional)</title>
353         <para>
354         "packet capture library"
355         </para>
356         
357         <section id="ChLibsLibpcap">
358         <title>Unix: libpcap</title>
359         <para>
360         If this library isn't already installed and also not available as a 
361         package for your platform, you can get it at: 
362         <ulink url="http://www.tcpdump.org/"/>.
363         </para>
364         </section>
365
366         <section id="ChLibsWinpPcap">
367         <title>Win32 MSVC: WinPcap</title>
368         <para>
369         You can get the "Windows packet capture library" at:
370         <ulink url="http://www.winpcap.org/install/default.htm"/>
371         </para>
372         </section>
373
374   </section>
375
376
377   <section id="ChLibsWimp">
378         <title>Win32: GTK WIMP (optional) for GTK 2.x only</title>
379         <para>
380         "GTK-Wimp ("Windows impersonator") is a GTK theme that blends well into
381         the Windows desktop environment."
382         </para>
383         <para>
384         Wimp is only available for the GTK2.x versions at: 
385         <ulink url="http://gtk-wimp.sourceforge.net/"/>.
386         </para>
387
388   </section>
389
390   
391 </chapter>
392 <!-- End of EUG Chapter Libraries -->