fix doxygen generation
[obnox/wireshark/wip.git] / README.win32
1 $Id$
2
3 Installing Ethereal, Tethereal, and Editcap on Win32
4 ====================================================
5 These are the instructions for installing Ethereal
6 from the installation executable that is provided on
7 the Ethereal website at:
8
9 http://www.ethereal.com/distribution/win32
10
11 and any of its mirrors.
12
13 The installation package allows you to install:
14
15         o Ethereal - the GUI version
16         o Tethereal - the console, line-mode version
17         o Editcap - a console, line-mode utility to convert
18           capture files from one format to another.
19           (The same functions are available in Ethereal)
20         o Text2Pcap - a console, line-mode utility to generate 
21           a capture file from an ASCII hexdump of packets
22         o Mergecap - a console, line-mode utility to merge two 
23           capture files into one
24
25 Additionally, the installation package contains a "plugins"
26 option, which installs some additional dissector plugins
27 for use with Ethereal and Tethereal.
28
29 All binaries in Ethereal package are now built with debugging
30 information embedded. If you are experiencing a crash when running
31 Ethereal or other binaries, Dr. Watson or your debugger
32 can use the information embedded in the binary to provide useful 
33 information to the Ethereal developers that will help them pinpoint 
34 the problem. 
35
36 In the past, two versions of Ethereal binaries were published -- a
37 version that could capture packets and a version which could not.
38 The latter is useful if you're only reading files produced by
39 another product (e.g., a sniffer, firewall, or intrustion detection system)
40 and did not wish to install WinPcap, the library Ethereal uses
41 to capture packets on Win32 platforms.
42
43 As of WinPcap 2.1, all the WinPcap libraries have been released as DLLs. 
44 This means that Ethereal can detect the presence of WinPcap at run time,
45 which means that only one version of the Ethereal binaries needs to be
46 shipped.
47
48 If you don't want to capture packets, just install the Ethereal
49 package. If you do want to capture packets, install Ethereal *and*
50 install the latest non-beta version of WinPcap, available from:
51
52         http://winpcap.polito.it/
53
54 and mirrored at
55
56         http://winpcap.mirror.ethereal.com/
57
58 and
59
60         http://www.mirrors.wiretapped.net/security/packet-capture/winpcap/
61
62 If you already have an earlier version of WinPcap installed, you need to
63 un-install it and install the latest version.  If the older version is
64 WinPcap 2.0 or 2.02, and you have other applications that use the older
65 version , you will have to decide which applications to keep, since
66 WinPcap 2.0/2.02 and later versions cannot be installed on the same
67 system at the same time.
68
69 If Ethereal is not capturing packets and you have WinPcap installed, you
70 can test your WinPcap installation by installing WinDump (tcpdump for
71 Windows) ported by the same folks who make WinPcap.  It's at:
72
73         http://windump.polito.it/
74
75 and mirrored at
76
77         http://windump.mirror.ethereal.com/
78
79 and
80
81         http://www.mirrors.wiretapped.net/security/packet-capture/windump/
82
83 They also make Analyzer, a GUI sniffer for Win32:
84
85         http://analyzer.polito.it/
86
87 The rest of this documentation is only interesting if
88 you want to compile Ethereal yourself.
89
90
91 Compiling the Ethereal distribution from source
92 ===============================================
93
94 Compilers
95 ---------
96 MS Visual C++ Version 6
97 This is the common compiler used for building Ethereal on win32.
98
99 MS Visual C++ Version 7 / VC.NET
100 Currently unsupported for two reasons:
101 -the licence agreement does NOT allow you to compile GPL code.
102 -there are serious problems in using DLL's compiled with MS VC6.
103 See section "Problems with MS Visual C++ Version 7 / VC.NET" below.
104
105 Cygwin GCC
106 Ethereal can entirely be built with cygwin GCC. However the built binaries will
107 only run in a cygwin environment, so they are not standalone Win32 applications.
108 It is however not excluded that native Win32 code can be compiled on cygwin GCC
109 but you then have to use -mms-bitfields as a strict minimum and probably
110 -mno-cygwin or a similar compiler flag too.
111 See section below for instructions.
112
113
114 Automated library download
115 --------------------------
116 Before using the automated download, be sure to edit the config.nmake file 
117 to suit your needs. Especially have a look at the ETHEREAL_LIBS setting.
118 However, the defaults should be working well for a first start.
119
120 If you've installed Microsoft Visual C++ (MSVC), you can run:
121
122 nmake -f makefile.nmake setup 
123
124 This will first check the availability of all required tools and then uses 
125 the tool wget to download each package file (together around 30MB!) from the 
126 server location at:
127
128         http://anonsvn.ethereal.com/ethereal-win32-libs/trunk/packages/
129
130 and unpack it in the $ETHEREAL_LIBS directory. 
131
132 If you have problems downloading the files, you might be connected to the 
133 internet through a proxy/firewall. In this case see the wget documentation 
134 to configure wget accordingly.
135
136
137 Required libraries
138 ------------------
139 If the automated library download finished sucessfully, you should have all
140 libraries on your machine at the right places. So you don't have to read this,
141 unless you are interested which libraries are used.
142
143 You'll need the development packages for GLIB, GTK+, iconv, gettext,
144 WinPcap, Net-SNMP, and optionally ADNS, PCRE and zlib. The development 
145 packages contain header files and stub libraries to link against.  
146
147 PRECOMPILED VERSIONS OF ALL OF THESE PACKAGES ARE AVAILABLE AT:
148
149         http://anonsvn.ethereal.com/ethereal-win32-libs/trunk/packages/
150
151
152 The GLIB, GTK+, iconv, gettext packages for win32 can be found at the home 
153 page for the GTK+ for Win32 project:
154
155         http://www.gimp.org/~tml/gimp/win32 or the mirror
156         http://www.iki.fi/tml/gimp/win32/
157
158 The Net-SNMP package for win32 is available at its homepage:
159
160         http://
161
162 The WinPcap package is available at its homepage:
163
164         http://winpcap.polito.it/ or the mirror
165         http://www.wiretapped.net/security/packet-capture/winpcap/default.htm
166
167 The optional ADNS package for win32 is available at its homepage:
168
169         http://adns.jgaa.com/
170
171 The optional PCRE package (Perl Compatible Regular Expressions) for win32 is 
172 available at its homepage:
173
174         http://gnuwin32.sourceforge.net/packages/pcre.htm
175
176 The optional zlib package for win32 is available at its homepage:
177
178         http://www.gzip.org/zlib/
179
180
181 By default, the build process looks for these packages in
182 C:\ethereal-win32-libs.  You can place them in a different directory, but
183 you must update the ETHEREAL_LIBS variable in config.nmake accordingly.
184
185 The following lists the packages needed to compile Ethereal and the default
186 locations where to unpack them, when the above method isn't used.
187
188     Package                               Default Location
189     -------                               ----------------
190     glib-2.2.3-20040116.zip               C:\ethereal-win32-libs\glib
191     glib-dev-2.2.3-20040116.zip           C:\ethereal-win32-libs\glib
192     gtk+-1.3.0-20030717.zip               C:\ethereal-win32-libs\gtk+
193     gtk+-dev-1.3.0-20030115.zip           C:\ethereal-win32-libs\gtk+
194     libiconv-1.9.1.bin.woe32.zip          C:\ethereal-win32-libs\libiconv-1.9.1.bin.woe32
195     gettext-runtime-0.13.1.zip            C:\ethereal-win32-libs\gettext-runtime-0.13.1
196     net-snmp-5.1.zip                      C:\ethereal-win32-libs
197     wpdpack_3_0.zip                       C:\ethereal-win32-libs
198
199 and optional:
200
201     adns-1.0-win32-03.zip                 C:\ethereal-win32-libs
202     pcre-4.4.zip                          C:\ethereal-win32-libs
203     zlib121-dll.zip                       C:\ethereal-win32-libs\zlib121-dll
204
205 (to use the default locations, the directories in question should be
206 created, and each zip file should be unpacked into the corresponding
207 directory).  If you only want to change the C:\ethereal-win32-libs
208 part, you just change the setting of ETHEREAL_LIBS in config.nmake; if
209 you want to change subdirectories, you'll have to change the individual
210 item for a package.  (Note that some zip files create the subdirectory -
211 those zip files just have C:\ethereal-win32-libs in the list above - so
212 if you don't want the package to be in that subdirectory, you'd have to
213 rename the directory.)
214
215 The gettext runtime package provides intl.dll, which is needed by
216 GLib 2.2.3.
217
218
219 Compiling the Ethereal distribution using GTK+2
220 -----------------------------------------------
221
222 The more recent version 2 of the GTK+ can be used to compile 
223 Ethereal with, but is still considered beta.
224
225 GTK+2 will look better in various ways, especially for WIN32 users.
226
227 You can get the required libraries from:
228
229 http://www.ethereal.com/distribution/win32/development/gtk2
230
231 or (like the GTK+1 libraries from the GTK+ for Win32 project):
232
233 http://www.gimp.org/~tml/gimp/win32/downloads.html
234
235 If you want to try a build with GTK+2.x these Extra libraries are needed 
236
237     Package                               Default Location
238     -------                               ----------------
239     gtk+-2.2.4-20040124.zip               C:\ethereal-win32-libs\gtk2
240     gtk+-dev-2.2.4-20040124.zip           C:\ethereal-win32-libs\gtk2
241     pango-1.2.5-20040124.zip              C:\ethereal-win32-libs\gtk2   
242     pango-dev-1.2.5-20040124.zip          C:\ethereal-win32-libs\gtk2
243     atk-1.4.0.zip                         C:\ethereal-win32-libs\gtk2   
244     atk-dev-1.4.0.zip                     C:\ethereal-win32-libs\gtk2
245
246 and optional:
247
248     gtk-wimp-0.5.3-bin.zip                C:\ethereal-win32-libs\gtk-wimp
249
250 Be sure to set GTK2_DIR in config.nmake correct, to be able to compile.
251
252 Running your freshly compiled Ethereal
253 --------------------------------------
254
255 Make sure the glib and gtk DLL's are in your path or you use a directory 
256 where all required DLL's and the exe files reside.- i.e., that your
257 path includes the directory (folder) or directories (folders) in which
258 those DLLs are found - when you run Ethereal.
259
260 Note the wiretap*.dll must be in your path as well and if wiretap is changed
261 be sure to put the new one in your path.
262
263 Plugins (gryphon.dll and mgcp.dll) can go in:
264         <Ethereal installation directory>\plugins\<version>
265
266 Where <version> is the version number, without brackets.  For example,
267 if you have Ethereal 0.9.8 installed in the default location, plugins
268 will reside in C:\Program Files\Ethereal\plugins\0.9.8
269
270 Yes, the location of plugins needs to be more flexible.
271
272 Instructions for MS Visual C++
273 ----------------------------
274 Modify the config.nmake file in the top directory of the Ethereal source
275 tree to work for your local configuration; if you don't have Python,
276 comment out the line that defines PYTHON, otherwise set it to refer to
277 the pathname of your Python interpreter executable.  You should not have
278 to modify any other Makefile.
279
280 Note that perl is needed to build the documentation, the lines in config.nmake
281
282 POD2MAN=$(SH) pod2man
283 POD2HTML=$(SH) pod2html
284
285 requires Cygwin bash and perl to work.
286
287 Many of the file and directory names used in the build process go past
288 the old 8.3 naming limitations.  As a result, at least on Windows NT 4.0,
289 Windows 2000, Windows XP, and Windows .NET Server, you should use the
290 newer "cmd.exe" command interpreter instead of the old "command.com",
291 as the "command.com" on Windows 2000, at least, can't handle non-8.3
292 directory names.  (It may be that the "command.com" in Windows 95, Windows
293 98, and Windows Me, as it's the only command interpreter in those systems,
294 can handle those directories.  If not, it may not be possible to build
295 Ethereal from the command line on those versions of Windows.)
296
297 Be sure that your command-line environment is set up to compile
298 and link with MSVC++. When installing MSVC++, you can have your
299 system's environment set up to always allow compiling from the
300 command line, or you can invoke the vcvars32.bat script, which can
301 usually be found in the "VC98\Bin" subdirectory of the directory in
302 which Visual Studio was installed.
303
304 The first time you build Ethereal, run the script "cleanbld.bat" in the
305 top-level Ethereal source directory to make sure that the "config.h"
306 files will be reconstructed from the "config.h.win32" files.  (If, for
307 example, you have "config.h" files left over from a Unix build, a
308 Windows build will fail.)
309
310 In the ethereal directory, type "nmake -f makefile.nmake". It will
311 recurse into the subdirectories as appropriate.
312
313 Some generated source is created by traditionally "Unix-ish" tools.
314
315 If you are building from an official distribution, these files are
316 already generated, although they were generated on a Unix-compatible
317 system.  In most cases, the generated files can be used when building on
318 Windows, but the files listed below as being generated by Flex can be
319 used when building on Windows only when generated by a Windows version
320 of Flex, so you will need a Windows version of Flex to do a Windows
321 build.  Those generated files are removed by the "cleanbld.bat" script,
322 to make sure that versions left over from a Unix build aren't used.
323
324 If you are building from a modified version of an official distribution,
325 and you modified any of the source files listed below, you will need the
326 tool(s) that generate output from those source files.
327
328 If building from a CVS image, you'll need all the tools to generate C
329 source.
330
331 The "special" files and their requisite tools are:
332
333 Source                          Output                  Tool
334 ------                          ------                  ----
335 config.h.win32                  config.h                sed
336 epan/config.h.win32             epan/config.h           sed
337 image/ethereal.rc.in            image/ethereal.rc       sed
338 image/tethereal.rc.in           image/tethereal.rc      sed
339 image/editcap.rc.in             image/editcap.rc        sed
340 image/mergecap.rc.in            image/mergecap.rc       sed
341 image/text2pcap.rc.in           image/text2pcap.rc      sed
342 wiretap/config.h.win32          wiretap/config.h        sed
343 epan/dfilter/dfilter-scanner.l  epan/dfilter/*.c        Flex
344 text2pcap-scanner.l             *.c                     Flex
345 wiretap/ascend-scanner.l        *.c                     Flex
346 wiretap/ascend-grammar.y        *.c,*.h                 Bison/Yacc
347 ncp2222.py                      packet-ncp2222.c        Python
348
349 make-reg-dotc, packet*.c        register.c              Bash + grep + sed
350 or
351 make-reg-dotc.py, packet*.c     register.c              Python
352
353 make-tapreg-dotc, tap-*.c       tethereal-tap-register.c
354                                                         Bash + grep + sed
355 make-tapreg-dotc, tap files     gtk/ethereal-tap-register.c
356     in the gtk subdirectory                             Bash + grep + sed
357
358 The Makefile.nmake supplied with the Ethereal distribution will, if
359 PYTHON is defined in config.nmake, attempt to make register.c with
360 Python, since it is much much much faster than the shell version.  The
361 reason it is faster is because the shell version launches multiple
362 processes (grep, sed) for each source file, multiple times.  The Python
363 script is one process.  This matters a lot on Win32.
364
365 If you have a Unix system handy, you can first build on Unix to create
366 most of the source files that these tools make, then run the build on
367 Windows.  That will avoid the need for these tools on your Windows
368 computer.  This won't work for the files in the "image" directory,
369 however, as those aren't built on Unix - they're only for Windows
370 builds.  It also won't work for the "config.h" files; whilst those are
371 built for Unix, they're specific to the platform on which you're
372 building, and the "config.h" files constructed for a Unix build will not
373 work with a Windows build.  In addition, it won't work for the files
374 generated by Flex, as, for a Windows build, those have to be generated
375 by a Windows version of Flex.
376
377 Most of those tools are available for Win32 systems as part of the
378 Cygwin package:
379
380         http://sources.redhat.com/cygwin/
381
382 After installing them, you will probably have to modify the config.nmake
383 file to specify where the Cygwin binaries are installed.
384
385 Python for Win32 is available from:
386
387         http://www.python.org/
388
389
390 Build an (NSIS based) installer
391 -------------------------------
392
393 If you want to build your own installer, you need to get NSIS from:
394
395 http://nsis.sourceforge.net/home/
396
397 After installing it, you will probably have to modify the config.nmake
398 file to specify where the NSIS binaries are installed and wether to use the modern UI or not.
399 You will need NSIS version 2 or higher, to build an installer with the modern user interface,
400 and for a much smaller installer (using the lzma compression).
401
402 In the ethereal directory, type "nmake -f makefile.nmake packaging" to build the installer. 
403 Please be patient while the compression is done, it will take some time even on fast machines.
404
405 You will hopefully now see something like ethereal-setup-0.10.2.exe in the dir packaging/nsis.
406
407
408 Installing GTK-Wimp
409 -------------------
410
411 GTK-Wimp can be used to get a native Look-and-Feel on WinXP machines, 
412 especially with the new "coloured" WinXP theme. It will only take effect
413 together with the GTK2 version of Ethereal. 
414
415 No changes to the Ethereal sources are needed, GTK-Wimp simply changes the 
416 way GTK2 displays the widgets (by changing the GTK2 default theme).
417
418 GTK-Wimp might already be installed. In this case, the files mentioned below
419 are already existing at the appropriate places.
420
421 If GTK-Wimp isn't installed, you can install it yourself: 
422
423 1. Go to http://gtk-wimp.sourceforge.net/
424 2. Download the ZIP archive containing the library and the theme
425 3. Locate the installation directory of Ethereal (C:\Program Files\Ethereal)
426 4. Create a subdirectory 'share\themes\Default\gtk-2.0'
427 5. Drop the file 'gtkrc' in 'share\themes\Default\gtk-2.0'
428 6. Create a subdirectory named 'lib\gtk-2.0\2.2.0\engines'
429 7. Drop the 'libwimp.dll' library in 'lib\gtk-2.0\2.2.0\engines'
430
431 When you're finished, you should have:
432
433 C:\Program Files\Ethereal\lib\gtk-2.0\2.2.0\engines\libwimp.dll
434 C:\Program Files\Ethereal\share\themes\Default\gtk-2.0\gtkrc
435
436 After (re-)starting Ethereal, you should now see it's widgets in the modern 
437 WinXP style on your screen.
438
439
440 Problems with MS Visual C++ Version 7 / VC.NET
441 ----------------------------------------------
442 Beside licensing problems with these compilers, there are known problems with DLL's.
443 If Ethereal is compiled with MSVC Version 7, there are conflicts in the MSVCRT DLL's,
444 The MSVCRT.DLL includes the standard ANSI-C functions like fopen, malloc, etc.. MSVCRT.DLL
445 is shipped with the MSVC 6 compiler versions, and dynamically linked to prebuild DLL's like 
446 the one's for gtk, glib and such. The MSVC 7 compiler now uses and ships MSVCRT71.DLL with 
447 it, which is incompatible with MSVCRT.DLL. So when using the MSVC 7 compiler, some parts of
448 the Ethereal code uses MSVCRT71.DLL, and some others (indirectly from e.g. the gtk DLL) will
449 use MSVCRT.DLL. This will result in incorrect file handles and such.
450
451 The same problem seems to apply on all MSVC compilers after version 6, like the
452 "Microsoft Visual C++ Toolkit 2003".
453
454
455 Instructions for Cygwin
456 -----------------------
457
458 It is possible to build Ethereal under Cygwin using their version
459 of XFree86. References:
460  - http://www.ethereal.com/lists/ethereal-dev/200205/msg00107.html
461  - http://www.ethereal.com/lists/ethereal-dev/200302/msg00026.html
462  
463 To get it running, execute the following steps:
464
465 1. Install the required cygwin packages (compiler, scripting, X, zlib)
466    with the CygWin setup.exe tool (http://www.cygwin.com/).
467    You need the base Xfree86 support plus the X headers package in order
468    to be able to compile the gtk+ package.
469
470 2. Download glib-1.2.10 and gtk+-1.2.10 from a mirror of www.gnome.org.
471
472 3. Retrieve the patches for glib-1.2.10 and gtk+-1.2.10 from
473    http://homepage.ntlworld.com/steven.obrien2/
474
475  + glib-1.2.10
476    http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
477           /libs/patches/glib-1.2.10-cygwin.patch
478
479  + gtk+-1.2.10
480    http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
481           /libs/patches/gtk+-1.2.10-cygwin.patch
482
483 4. Compile and install both packages after patching (see instructions
484    at the bottom of http://homepage.ntlworld.com/steven.obrien2/):
485
486    Set the path:
487
488      $ PATH=/opt/gnome/bin:/usr/X11R6/bin:$PATH
489
490    For glib-1.2.10:
491    
492      $ cd glib-1.2.10
493      $ patch -p1 < /path/to/glib-1.2.10-cygwin.patch
494      $ CFLAGS=-O2 ./configure --prefix=/opt/gnome --with-threads=posix
495      $ make
496      $ make check
497      $ make install
498
499    For gtk+-1.2.10:
500
501      $ cd gtk+-1.2.10
502      $ patch -p1 < /path/to/gtk+-1.2.10-cygwin.patch
503      $ CFLAGS=-O2 ./configure --prefix=/opt/gnome
504      $ make
505      $ make check
506      $ make install
507
508 5. Patch Makefile.am in <ethereal-src>/gtk/Makefile.am by
509    removing "ethclist.c" from the dependencies.
510
511    This patch is required since the private GTK+ clist widget
512    (was required for earlier versions of GTK+ but prevents Ethereal
513    from running with cygwin).
514
515 6. Configure and make Ethereal:
516
517    Set the path (if this has not yet been done earlier)
518
519      $ PATH=/opt/gnome/bin:$PATH
520
521      $ ./autogen.sh
522      $ ./configure --config-cache --without-pcap
523      $ make
524
525 7. Start X
526
527      $ sh /usr/X11R6/bin/startxwin.sh
528
529     Or you can start it from C:\cygwin\usr\X11R6\bin\startxwin.bat 
530
531 8. Run ethereal (add /opt/gnome/bin to $PATH if this is not yet done)
532
533      $ <ethereal-src>/ethereal
534
535     And voila! Behold the mighty sniffer in all its glory!
536
537     Note that the plugin dissectors must be installed (make install) if you
538     want to use them. Note also that running "make install" produces lots of
539     output to the console; this is normal.
540
541 Note: Compiling Ethereal under cygwin takes a lot of time, because the
542 generation of 'register.c' takes ages. If you only edit one dissector and
543 you know what you're doing, it is acceptable to uncomment the generation
544 of the file 'register.c' in Makefile. Look for the 'register.c' target:
545
546     register.c: $(DISSECTOR_SRC) $(srcdir)/make-reg-dotc
547         @echo Making register.c
548         # @$(srcdir)/make-reg-dotc register.c $(srcdir) $(DISSECTOR_SRC)
549         @echo Skipping generation of register.c
550
551 Of course, you need to generate the 'register.c' file at least once.
552
553 Note: You can also capture packets on a cygwin built Ethereal. You then have
554 to unpack the WinPCap development package, install the files in lib/ and
555 include/ in say /usr/lib and /usr/include (they must be in the search path of
556 the compiler and linker, otherwise you have to specify the configure option
557 --with-pcap=/location/to/pcap so the packet capture functionality can be used.
558 In order to run Ethereal, you have to add the .dll files in a directory in the
559 PATH (e.g., /bin).
560 Should you want packet capturing enabled in the cygwin build, then you have to
561 remove --without-pcap from step 6.