Removed trailing whitespaces from .h and .c files using the
[obnox/wireshark/wip.git] / README.win32
1 $Id: README.win32,v 1.39 2002/07/08 21:03:04 guy Exp $
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 and any of its mirrors.
8
9 The installation package allows you to install:
10
11         o Ethereal - the GUI version
12         o Tethereal - the console, line-mode version
13         o Editcap - a console, line-mode utility to convert
14                 capture files from one format to another.
15                 (The same functions are available in Ethereal)
16         o Text2Pcap - a console, line-mode utility to generate 
17                 a capture file from an ASCII hexdump of packets
18         o Mergecap - a console, line-mode utility to merge two 
19                 capture files into one
20
21 Additionally, the installation package contains a "plugins"
22 option, which installs the Gryphon, MGCP and GIOP dissector plugins
23 for use with Ethereal and Tethereal.
24
25 All binaries in Ethereal package are now built with debugging
26 information embedded. If you are experiencing a crash when running
27 Ethereal or other binaries, Dr. Watson or your debugger
28 can use the information embedded in the binary to provide useful 
29 information to the Ethereal developers that will help them pinpoint 
30 the problem. 
31
32 In the past, two versions of Ethereal binaries were published -- a
33 version that could capture packets and a version which could not.
34 The latter is useful if you're only reading files produced by
35 another product (e.g., a sniffer, firewall, or intrustion detection system)
36 and did not wish to install WinPcap, the library Ethereal uses
37 to capture packets on Win32 platforms.
38
39 As of WinPcap 2.1, all the WinPcap libraries have been released as DLLs. 
40 This means that Ethereal can detect the presence of WinPcap at run time,
41 which means that only one version of the Ethereal binaries needs to be
42 shipped.
43
44 If you don't want to capture packets, just install the Ethereal
45 package. If you do want to capture packets, install Ethereal *and*
46 install the latest non-beta version of WinPcap, available from:
47
48         http://winpcap.polito.it/
49
50 and mirrored at
51
52         http://winpcap.mirror.ethereal.com/
53
54 and
55
56         http://www.mirrors.wiretapped.net/security/packet-capture/winpcap/
57
58 If you already have an earlier version of WinPcap installed, you need to
59 un-install it and install the latest version.  If the older version is
60 WinPcap 2.0 or 2.02, and you have other applications that use the older
61 version , you will have to decide which applications to keep, since
62 WinPcap 2.0/2.02 and later versions cannot be installed on the same
63 system at the same time.
64
65 If Ethereal is not capturing packets and you have WinPcap installed, you
66 can test your WinPcap installation by installing WinDump (tcpdump for
67 Windows) ported by the same folks who make WinPcap.  It's at:
68
69         http://windump.polito.it/
70
71 and mirrored at
72
73         http://windump.mirror.ethereal.com/
74
75 and
76
77         http://www.mirrors.wiretapped.net/security/packet-capture/windump/
78
79 They also make Analyzer, a GUI sniffer for Win32:
80
81         http://analyzer.polito.it/
82
83 The rest of this documentation is only interesting if
84 you want to compile Ethereal yourself.
85
86
87 Running Ethereal, Tethereal, and Editcap on Win32
88 =================================================
89 You need the glib and gtk libraries for running Ethereal. 
90
91 These packages for win32 can be found at:
92
93         http://www.ethereal.com/distribution/win32
94
95 and at the home page for the GTK+ for Win32 project:
96
97         http://www.gimp.org/~tml/gimp/win32
98
99 or
100         http://www.iki.fi/tml/gimp/win32/
101
102 (the mirror nearer to you may be faster).
103
104 Plugins (gryphon.dll and mgcp.dll) can go in:
105         C:\Program Files\Ethereal\plugins\<version>
106         C:\Ethereal\plugins\<version>
107
108 Where <version> is the version number, without brackets.
109 For example, C:\Ethereal\plugins\0.8.16
110
111 Yes, the location of plugins needs to be more flexible.
112
113 Make sure the glib and gtk DLL's are in your path - i.e., that your path
114 includes the directory (folder) or directories (folders) in which those
115 DLLs are found - when you run Ethereal.  This includes gtk-*.dll,
116 glib-*.dll, gmodule-*.dll, gdk-*.dll, gnu-intl.dll, and iconv-*.dll.
117 As of the 20000805 GTK+/GLIB distribution, gthread-*.dll is no longer needed.
118
119 The Win32 Binary distribution, available from
120
121         http://www.ethereal.com/distribution/win32
122
123 used different version of the GTK+/GLIB libraries at different points
124 in time:
125
126 Ethereal Version                GTK+/GLIB version
127 ----------------                -----------------
128 0.8.16 and after                20001226
129 0.8.11 - 0.8.15                 20000805
130 0.8.9 - 0.8.10                  20000416
131 0.8.8 and before                19990828
132
133
134 Capturing Packets
135 -----------------
136 In order to capture with Win32, you need to install the NDIS
137 packet capture driver for your particular Win32 OS; drivers for Windows
138 9x, Windows NT 4.0, and Windows 2000 can be downloaded from the
139 WinPcap home page:
140
141         http://winpcap.polito.it/
142
143 or the mirror site at
144
145         http://www.wiretapped.net/security/packet-capture/winpcap/default.htm
146
147 Compiling the Ethereal distribution from source
148 ===============================================
149 You'll need the development package for GLIB, GTK+, and WinPcap.
150 Those versions are available from the respctive home pages for
151 each project (the same URLs as listed above). The development
152 packages contain header files and stub libaries to link against.
153
154 The use of an SNMP library has not been made to work yet in
155 Ethereal/Win32, but a binary distribution of the UCD SNMP package,
156 including header files and a DLL of the UCD SNMP library, can be had
157 from:
158
159         ftp://ftp.revelstone.com/snmp/binaries/
160
161 The file will probably be called "ucd-snmp-X.X-x86-win32.zip", where
162 "X.X" is the version number of the UCD SNMP library.
163
164 Instructions for MS Visual C
165 ----------------------------
166 Modify the config.nmake file in the top directory of the Ethereal source
167 tree to work for your local configuration; if you don't have Python,
168 comment out the line that defines PYTHON, otherwise set it to refer to
169 the pathname of your Python interpreter executable.  You should not have
170 to modify any other Makefile.
171
172 In order to compile, at least with the default settings, you
173 also need zlib, which is provided as an archive library, not
174 a DLL. The pre-compiled zlib which comes with the "extralibs"
175 package from Gimp/Win32 is faulty; a working version can be
176 downloaded from:
177
178         http://www.ethereal.com/distribution/win32/zlib-1.1.3-fixed.zip
179
180 Many of the file and directory names used in the build process go past
181 the old 8.3 naming limitations.  As a result, at least on Windows NT
182 4.0, Windows 2000, Windows XP, and Windows .NET Server, you should use
183 the newer "cmd.exe" command interpreter instead of the old
184 "command.com", as the "command.com" on Windows 2000, at least, can't
185 handle non-8.3 directory names.  (It may be that the "command.com" in
186 Windows 95, Windows 98, and Windows Me, as it's the only command
187 interpreter in those systems, can handle those directories.  If not, it
188 may not be possible to build Ethereal from the command line on those
189 versions of Windows.)
190
191 Be sure that your command-line environment is set up to compile
192 and link with MSVC. When installing MSVC, you can have your
193 system's environment set up to always allow compiling from the
194 command line, or you can invoke the vcvars32.bat script, which can
195 usually be found in the "VC98\Bin" subdirectory of the directory in
196 which Visual Studio was installed.
197
198 The first time you build Ethereal, run the script "cleanbld.bat" in the
199 top-level Ethereal source directory to make sure that the "config.h"
200 files will be reconstructed from the "config.h.win32" files.  (If, for
201 example, you have "config.h" files left over from a Unix build, a
202 Windows build will fail.)
203
204 In the ethereal directory, type "nmake -f makefile.nmake". It will
205 recurse into the subdirectories as appropriate.
206
207 Some generated source is created by traditionally "Unix-ish" tools.
208 If you are building from an official distribution, these files are
209 already generated, so you have nothing to worry about unless you
210 modify the source. If building from a CVS image, you'll need the tools
211 to generate C source. The "special" files and their requisite tools are:
212
213 Source                          Output                  Tool
214 ------                          ------                  ----
215 config.h.win32                  config.h                sed
216 epan/config.h.win32             epan/config.h           sed
217 image/ethereal.rc.in            image/ethereal.rc       sed
218 image/tethereal.rc.in           image/tethereal.rc      sed
219 image/editcap.rc.in             image/editcap.rc        sed
220 image/mergecap.rc.in            image/mergecap.rc       sed
221 image/text2pcap.rc.in           image/text2pcap.rc      sed
222 packaging/nsis/ethereal.nsi.in  packaging/ethereal.nsi  sed
223 wiretap/config.h.win32          wiretap/config.h        sed
224 epan/dfilter/dfilter-scanner.l  epan/dfilter/*.c        Flex
225 text2pcap-scanner.l             *.c                     Flex
226 wiretap/ascend-scanner.l        *.c                     Flex
227 wiretap/ascend-grammar.y        *.c,*.h                 Bison/Yacc
228 ncp2222.py                      packet-ncp2222.c        Python
229
230 make-reg-dotc, packet*.c        register.c              Bash + grep + sed
231 or
232 make-reg-dotc.py, packet*.c     register.c              Python
233
234 The Makefile.nmake supplied with the Ethereal distribution will, if
235 PYTHON is defined in config.nmake, attempt to make register.c with
236 Python, since it is much much much faster than the shell version.  The
237 reason it is faster is because the shell version launches multiple
238 processes (grep, sed) for each source file, multiple times.  The Python
239 script is one process.  This matters a lot on Win32.
240
241 If you have a Unix system handy, you can first build on Unix to create
242 most of the source files that these tools make, then run the build on
243 Windows.  That will avoid the need for these tools on your Windows
244 computer.  (This won't work for the files in the "image" directory,
245 however, as those aren't built on Unix - they're only for Windows
246 builds.  It also won't work for the "config.h" files; whilst those are
247 built for Unix, they're specific to the platform on which you're
248 building, and the "config.h" files constructed for a Unix build will not
249 work with a Windows build.)
250
251 If you don't have a Unix system handy, most of those tools are available for
252 Win32 systems as part of the Cygwin package:
253
254         http://sources.redhat.com/cygwin/
255
256 After installing them, you will probably have to modify the config.nmake
257 file to specify where the Cygwin binaries are installed.
258
259 Python for Win32 is available from
260
261         http://www.python.org/
262
263
264 Instructions for Cygwin
265 -----------------------
266
267 It is possible to build Ethereal under Cygwin using their version
268 of XFree86.  Ronnie Sahlberg has this to say in 
269 http://www.ethereal.com/lists/ethereal-dev/200205/msg00107.html:
270
271 To get it running there are some small steps :
272 1, Install XFree for Cygwin and make sure it runs properly
273 (www.cygwin.com)
274 2, Follow the GNOME link on www.cygwin.com and download, compile and install
275 both gtk 1.2.10 and glib 1.2.10 . Note on the page that there is a one line
276 fix required for
277 gtk to compile.
278 3, Download ethereal nightly snapshot and configure it with
279  ./autogen.sh --without-pcap --without-plugins
280 (is it --without-plugin or --without-plugins ? dont remember)
281 4, Run 'make ethereal.exe'
282
283 Something is wrong with the makefile that gets generated so it doesnt work
284 just running make.
285 I am not curious enough to look at why 'make' doesnt work. 'make
286 ethereal.exe' works well
287 enough for me.
288
289 4, start X and ethereal, voila behold the mighty sniffer in all its glory.
290