f3b0d0145c3869ceae114b88c4fd558bb0e813f5
[metze/wireshark/wip.git] / docbook / wsdg_src / WSDG_chapter_tools.asciidoc
1 // WSDG Chapter Tools
2
3 [[ChapterTools]]
4
5 == Tool Reference
6
7 [[ChToolsIntro]]
8
9 === Introduction
10
11 This chapter will provide you with information about the
12 various tools needed for Wireshark development.
13
14 None of the tools mentioned in this chapter are needed to
15 run Wireshark; they are only needed to build it.
16
17 Most of these tools have their roots on UNIX like
18 platforms, but Windows ports are also available. Therefore the
19 tools are available in different "flavours":
20
21 * UNIX (or Windows Cygwin): the tools should be commonly available on the
22   supported UNIX platforms, and for Windows platforms by using the Cygwin UNIX
23   emulation
24 * Windows native: some tools are available as native Windows tools, no special
25   emulation is required.  Many of these tools can be installed (and updated)
26   using http://chocolatey.org[Chocolatey], a Windows package manager similar
27   to the Linux package managers apt-get or yum.
28
29 [WARNING]
30 .Follow the directions
31 ====
32 Unless you know exactly what you are doing, you should strictly follow the recommendations given in <<ChapterSetup>>.
33 ====
34
35 The following sections give a very brief description of
36 what a particular tool is doing, how it is used in the
37 Wireshark project and how it can be installed and
38 tested.
39
40 Documentation for these tools is outside the scope of this document. If you need
41 further information on using a specific tool you should find lots of useful
42 information on the web, as these tools are commonly used. You can also get help
43 for the UNIX based tools with +**toolname** --help+ or the man page via +man
44 **toolname**+.
45
46 You will find explanations of the tool usage for some of the specific
47 development tasks in <<ChapterSources>>.
48
49 === Chocolatey
50
51 Chocolatey is a Windows package manager that can be used to install (and update)
52 many of the packages required for Wireshark development. Chocolatey can be
53 obtained from the http://chocolatey.org[website] or from a Command Prompt:
54
55 ----
56 C:\>@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString(_https://chocolatey.org/install.ps1_))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin
57 ----
58
59 or a Powershell prompt:
60
61 ----
62 PS:\>iex ((new-object net.webclient).DownloadString(_https://chocolatey.org/install.ps1_))
63 ----
64
65 Chocolatey sometimes installs packages in unexpected locations. Cygwin is a notable
66 example -- recent versions of the Cygwin package are installed in _C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin_ instead of Cygwin’s default location
67 (_C:\cygwin_ or _C:\cygwin64_).
68
69 [[ChToolsCygwin]]
70
71 === Windows: Cygwin
72
73 Cygwin provides a lot of UNIX based tools on the Windows platform. It uses a UNIX
74 emulation layer which might be a bit slower compared to the native Windows tools,
75 but at an acceptable level. The installation and update is pretty easy and done
76 through a single utility, _setup-x86.exe_ for 32-bit Windows and
77 _setup-x86_64.exe_ for 64-bit Windows.
78
79 Over time the Wireshark development toolchain has been migrating away from Cygwin
80 toward native tools and we hope to eliminate it as a requirement someday.
81
82 Although Cygwin consists of several separate packages, the installation
83 and update is done through a single utility, _setup-x86.exe_ or
84 _setup-x86_64.exe_, which acts similarly to other web based installers.
85 You can install Cygwin and its packages using Chocolatey, but this is not
86 recommended due to Chocolatey’s default installation location, described
87 in the previous section.
88
89 ==== Installing Cygwin using the Cygwin installer
90
91 You will find _setup-x86.exe_, for 32-bit systems, and
92 _setup-x86_64.exe_, for 64-bit systems, at
93 http://www.cygwin.com/install.html[]. Click on the link for the
94 appropriate setup utility to download it. After the download completes,
95 run it.
96
97 All tools will be installed into one base folder. The default is
98 _C:\cygwin_ for the 32-bit installer and _C:\cygwin64_ for the 64-bit
99 installer.
100
101 The setup utility will ask you for some settings. The defaults
102 should usually work well, at least initially.
103
104 If, at the "Choose A Download Source" page, you use the default "Install
105 from Internet" setting, you will need to choose a download site at the
106 "Choose A Download Site" page. See the list of mirror sites at
107 http://cygwin.com/mirrors.html[] to choose a download site appropriate
108 to your location.
109
110 At the "Select Packages" page, you'll need to select some additional
111 packages, which are not installed by default.  Navigate to the required
112 Category/Package row and click on the "Skip" item in the "New" column so
113 it shows a version number for the required package.
114
115 After clicking the Next button several times the setup
116 will then download and install the selected packages (this may
117 take a while, depending on the package size).
118
119 Under menu:Start[Programs,Cygwin,Cygwin Bash Shell] you should now be able to start
120 a new Cygwin bash shell, which is similar to the standard Windows Command Prompt
121 (cmd.exe) but much more powerful.
122
123 [[ChToolsCygwinPackages]]
124
125 ==== Add/Update/Remove Cygwin Packages
126
127 If you want to add, update, or remove packages later you can do so by
128 running the setup utility again.  At the "Select Packages" page, the
129 entry in the "New" column will control what is done (or not) with the
130 package.  If a new version of a package is available, the new version
131 number will be displayed, so it will be automatically updated.  You can
132 change the current setting by simply clicking at it, it will change
133 between:
134
135 * _A specific version number._ This specific package version will be installed.
136
137 * _Skip._ Not installed, no changes.
138
139 * _Keep._ Already installed, no changes.
140
141 * _Uninstall._ Uninstall this package.
142
143 * _Reinstall._ Reinstall this package.
144
145 ==== Installing Cygwin using Chocolatey
146
147 Chocolatey supports Cygwin as an external package source.
148 To install Cygwin itself run
149
150 ----
151 PS$>choco install cygwin
152 # You might also need to install cyg-get:
153 PS$>choco install cyg-get
154 ----
155
156 Chocolatey installs Cygwin in _C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin_ by default.
157
158 One or more Cygwin packages can be installed using `cyg-get`:
159
160 ----
161 PS$>cyg-get sed asciidoc
162 ----
163
164 [[ChToolsGNUChain]]
165
166 === GNU compiler toolchain (UNIX only)
167
168 [[ChToolsGCC]]
169
170 ==== gcc (GNU compiler collection)
171
172 The GCC C compiler is available for most of the
173 UNIX-like platforms.
174
175 If GCC isn't already installed or available
176 as a package for your platform, you can get it at:
177 http://gcc.gnu.org/[].
178
179 After correct installation, typing at the
180 bash command line prompt:
181
182 ----
183 $ gcc --version
184 ----
185
186 should result in something like
187
188 ----
189 gcc (Ubuntu 4.9.1-16ubuntu6) 4.9.1
190 Copyright (C) 2014 Free Software Foundation, Inc.
191 This is free software; see the source for copying conditions.  There is NO
192 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
193 ----
194
195 Your version string may vary, of course.
196
197 [[ChToolsCMake]]
198
199 Wireshark’s build environment can be configured using CMake on Windows
200 and either CMake or Autotools on Linux, macOS, and UNIX. CMake is designed
201 to support out of tree builds. So much so, that in tree builds do not work
202 properly in all cases. Along with being cross-platform, CMake supports
203 many build tools and environments including traditional make, Ninja, and
204 MSBuild. Our Buildbot runs CMake steps on Ubuntu, Win32, Win64, and macOS.
205 In particular, the macOS and Windows packages are built using CMake.
206
207 Building with CMake typically includes creating a build directory and
208 specifying a *generator*, aka a build tool. For example, to build
209 Wireshark using Ninja in the directory _wireshark-ninja_ you might
210 run the following commands:
211
212 ----
213 # Starting from your Wireshark source directory, create a build directory
214 # alongside it.
215 $ cd ..
216 $ mkdir wireshark-ninja
217 $ cd wireshark-ninja
218 # Assumes your source directory is named "wireshark".
219 $ cmake -G Ninja ../wireshark
220 $ ninja (or cmake --build .)
221 ----
222
223 Using CMake on Windows is described further in <<ChWin32Generate>>.
224
225 Along with specifying a generator with the `-G` flag you can set variables
226 using the `-D` flag. Useful variables and generators include the following:
227
228 -DENABLE_CAP=OFF:: Disable the POSIX capabilities check
229
230 -DCMAKE_BUILD_TYPE=Debug:: Enable debugging symbols
231
232 -DENABLE_GTK3=ON:: Enable GTK+ 3
233
234 +++-DCMAKE_C_FLAGS='-Qunused-arguments'+++:: Make ccache and clang work together
235
236 -DPYTHON_EXECUTABLE=c:/Python27/python:: Force the Python path. Useful on Windows since Cygwin’s /usrbin/python is a symlink.
237
238 -DENABLE_APPLICATION_BUNDLE=OFF:: Disable building an application bundle (Wireshark.app) on macOS
239
240 You can list all build variables (with help) by running *`cmake -LH [options]
241 ../<Name_of_WS_source_dir>`*. This lists the cache of build variables
242 after the cmake run. To only view the current cache, add option `-N`.
243
244 After running cmake, you can always run *`make help`* to see a list of all possible make targets.
245
246 Note that CMake honors user umask for creating directories as of now. You should set
247 the umask explicitly before running the `install` target.
248
249 CMake links:
250
251 The home page of the CMake project: http://www.cmake.org/
252
253 Official documentation: https://cmake.org/documentation/
254
255 About CMake in general and why KDE4 uses it: http://lwn.net/Articles/188693/
256
257 Introductory tutorial/presentation:
258 http://ait.web.psi.ch/services/linux/hpc/hpc_user_cookbook/tools/cmake/docs/Cmake_VM_2007.pdf
259
260 Introductory article in the Linux Journal:
261 http://www.linuxjournal.com/node/6700/print
262
263 Useful variables: http://www.cmake.org/Wiki/CMake_Useful_Variables
264
265 Frequently Asked Questions: http://www.cmake.org/Wiki/CMake_FAQ
266
267 // 2017-08-04 dead
268 //Additional cmake modules: http://code.google.com/p/cmake-modules/
269
270 [[ChToolsGDB]]
271
272 ==== gdb (GNU project debugger)
273
274 GDB is the debugger for the GCC compiler. It is
275 available for many (if not all) UNIX-like platforms.
276
277 If you don't like debugging using the command line
278 there are some GUI frontends for it available, most notably
279 GNU DDD.
280
281 If gdb isn't already installed or available
282 as a package for your platform, you can get it at:
283 http://www.gnu.org/software/gdb/gdb.html[].
284
285 After correct installation:
286
287 ----
288 $ gdb --version
289 ----
290
291 should result in something like:
292
293 ----
294 GNU gdb (Ubuntu 7.8-1ubuntu4) 7.8.0.20141001-cvs
295 Copyright (C) 2014 Free Software Foundation, Inc.
296 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
297 This is free software: you are free to change and redistribute it.
298 There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
299 and "show warranty" for details.
300 This GDB was configured as "x86_64-linux-gnu".
301 Type "show configuration" for configuration details.
302 For bug reporting instructions, please see:
303 <http://www.gnu.org/software/gdb/bugs/>.
304 Find the GDB manual and other documentation resources online at:
305 <http://www.gnu.org/software/gdb/documentation/>.
306 For help, type "help".
307 Type "apropos word" to search for commands related to "word".
308 ----
309
310 Your version string may vary, of course.
311
312 [[ChToolsDDD]]
313
314
315 ==== ddd (GNU Data Display Debugger)
316
317 The GNU Data Display Debugger is a good GUI frontend
318 for GDB (and a lot of other command line debuggers), so you
319 have to install GDB first. It is available for many UNIX-like
320 platforms.
321
322 If GNU DDD isn't already installed or
323 available as a package for your platform, you can get it at:
324 http://www.gnu.org/software/ddd/[].
325
326 [[ChToolsGNUmake]]
327
328 ==== make (GNU Make)
329
330 [NOTE]
331 .GNU make isn't supported either for Windows
332
333 GNU Make is available for most of the UNIX-like
334 platforms.
335
336 If GNU Make isn't already installed or
337 available as a package for your platform, you can get it at:
338 http://www.gnu.org/software/make/[].
339
340 After correct installation:
341
342 ----
343 $ make --version
344 ----
345
346 should result in something like:
347
348 ----
349 GNU Make 4.0
350 Built for x86_64-pc-linux-gnu
351 Copyright (C) 1988-2013 Free Software Foundation, Inc.
352 Licence GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
353 This is free software: you are free to change and redistribute it.
354 There is NO WARRANTY, to the extent permitted by law.
355 ----
356
357 Your version string may vary, of course.
358
359 [[ChToolsMSChain]]
360
361 === Microsoft compiler toolchain (Windows native)
362
363 To compile Wireshark on Windows using the Microsoft C/{cpp}
364 compiler, you'll need:
365
366 . C compiler (_cl.exe_)
367
368 . Assembler (_ml.exe_ for 32-bit targets and _ml64.exe_ for 64-bit targets)
369
370 . Linker (_link.exe_)
371
372 . Resource Compiler (_rc.exe_)
373
374 . C runtime headers and libraries (e.g. _stdio.h_, _msvcrt.lib_)
375
376 . Windows platform headers and libraries (e.g.
377 _windows.h_, _WSock32.lib_)
378 +
379 // Can we drop support for CHM?
380 . HTML help headers and libraries (_htmlhelp.h_, _htmlhelp.lib_)
381
382 ==== Official Toolchain Packages And Alternatives
383
384 The official Wireshark 2.4.x releases are compiled using Microsoft Visual {cpp} 2015.
385 The Wireshark 2.2.x and 2.0.x releases are compiled using Microsoft Visual {cpp} 2013.
386 The Wireshark 1.12.x and 1.10.x releases were compiled using
387 Microsoft Visual {cpp} 2010 SP1.
388 The 1.8 releases were compiled using
389 Microsoft Visual {cpp} 2010 SP1 as well.
390 The 1.6, 1.4, and 1.2 releases were compiled using
391 Microsoft Visual {cpp} 2008 SP1.
392 Other past releases, including the 1.0 branch,
393 were compiled using Microsoft Visual {cpp} 6.0.
394
395 Using the release compilers is recommended for Wireshark development work.
396
397 The older "Express
398 Edition" compilers such as Visual {cpp} 2010 Express Edition SP1 can be
399 used but any PortableApps packages you create with them
400 will require the installation of a separate Visual {cpp}
401 Redistributable package on any machine on which the PortableApps
402 package is to be used. See
403 <<msvc-runtime-redistributable>> below for more details.
404
405 However, you might already have a different Microsoft {cpp} compiler
406 installed. It should be possible to use any of the following with the considerations listed:
407
408 .Visual {cpp} 2013 Community Edition
409
410 IDE + Debugger?:: Yes
411
412 Purchase required?:: http://www.visualstudio.com/en-us/downloads/download-visual-studio-vs#d-community[Free Download]
413
414 SDK required for 64-bit builds?:: No
415
416 CMake Generator: *`Visual Studio 12`*
417
418 .Visual {cpp} 2010 Express Edition
419
420 IDE + Debugger?:: Yes
421
422 Purchase required?:: http://www.microsoft.com/express/Downloads/#Visual_Studio_2010_Express_Downloads[Free Download]
423
424 SDK required for 64-bit builds?:: Yes.
425
426 CMake Generator: *`Visual Studio 10`*
427
428 Remarks:: Installers created using express editions require a {cpp} redistributable
429 _vcredist_x86.exe_ (3MB free
430 download) is required to build
431 Wireshark-win32-{wireshark-version}.exe, and
432 _vcredist_x64.exe_ is required to build
433 Wireshark-win64-{wireshark-version}.exe. The version of
434 _vcredist_x86.exe_ or _vcredist_x64.exe_ _must_ match the version for your
435 compiler including any service packs installed for the compiler.]
436
437 .Visual Studio 2010
438
439 IDE + Debugger?:: Yes
440
441 Purchase required?:: Yes
442
443 SDK required for 64-bit builds?:: No
444
445 CMake Generator: *`Visual Studio 10`*
446
447 Remarks:: Building a 64-bit installer
448 requires a a {cpp} redistributable
449 (_vcredist_x86.exe_).footnoteref[vcredist]
450
451 You can use Chocolatey to install Visual Studio, e.g:
452
453 ----
454 PS:\> choco install VisualStudioCommunity2013
455 ----
456
457 ==== cl.exe (C Compiler)
458
459 The following table gives an overview of the possible
460 Microsoft toolchain variants and their specific C compiler
461 versions ordered by release date.
462
463 |===============
464 |Compiler Package|cl.exe|_MSC_VER|CRT DLL
465 |Visual Studio 2015|14.0|1900|msvcr140.dll
466 |Visual Studio 2013|12.0|1800|msvcr120.dll
467 |Visual Studio 2012|11.0|1700|msvcr110.dll
468 |Visual Studio 2010|10.0|1600|msvcr100.dll
469 |===============
470
471 After correct installation of the toolchain, typing
472 at the Visual Studio Command line prompt (cmd.exe):
473
474 ----
475 > cl
476 ----
477
478 should result in something like:
479
480 ----
481 Microsoft (R) C/{cpp} Optimizing Compiler Version 18.00.31101 for x86
482 Copyright (C) Microsoft Corporation.  All rights reserved.
483
484 usage: cl [ option... ] filename... [ /link linkoption...
485 ----
486
487 However, the version string may vary.
488
489 Documentation on the compiler can be found at
490 http://msdn.microsoft.com/en-us/library/wk21sfcf.aspx[Microsoft MSDN]
491
492 ==== link.exe (Linker)
493
494 After correct installation, typing at the Visual Studio Command line prompt (cmd.exe):
495
496 ----
497 > link
498 ----
499
500 should result in something like:
501
502 ----
503 Microsoft (R) Incremental Linker Version 12.00.31101.0
504 Copyright (C) Microsoft Corporation.  All rights reserved.
505
506  usage: LINK [options] [files] [@commandfile]
507  ...
508 ----
509
510 However, the version string may vary.
511
512 Documentation on the linker can be found at
513 http://msdn.microsoft.com/en-us/library/t2fck18t.aspx[Microsoft MSDN]
514
515 [[msvc-runtime-redistributable]]
516
517
518 ==== C-Runtime "Redistributable" Files
519
520 Please note: The following is not legal advice - ask your preferred lawyer
521 instead. It’s the authors view and this view might be wrong.
522
523 Depending on the Microsoft compiler version you use, some binary files coming
524 from Microsoft might be required to be installed on Windows machine to run
525 Wireshark. On a developer machine, the compiler setup installs these files so
526 they are available - but they might not be available on a user machine!
527
528 This is especially true for the C runtime DLL (msvcr*.dll), which contains the
529 implementation of ANSI and alike functions, e.g.: fopen(), malloc(). The DLL is
530 named like: _msvcr**version**.dll_, an abbreviation for "Microsoft Visual C
531 Runtime". For Wireshark to work, this DLL must be available on the users
532 machine.
533
534 Starting with MSVC7, it is necessary to ship the C runtime DLL
535 (_msvcr**version**.dll_) together with the application installer somehow, as that
536 DLL is possibly not available on the target system.
537
538
539 [NOTE]
540 .Make sure you're allowed to distribute this file
541 ====
542 The files to redistribute must be mentioned in the
543 redist.txt file of the compiler package. Otherwise it
544 can't be legally redistributed by third parties like
545 us.
546 ====
547
548 The following MSDN link is recommended for the
549 interested reader:
550
551 * http://msdn.microsoft.com/en-us/library/ms235299.aspx[Redistributing Visual C++ Files]
552
553 In all cases where _vcredist_x86.exe_ or _vcredist_x64.exe_ is
554 downloaded it should be downloaded to the directory into which the support
555 libraries for Wireshark have been downloaded and installed. This directory is
556 specified by the WIRESHARK_BASE_DIR or WIRESHARK_LIB_DIR environment variables.
557 It need not, and should not, be run after being downloaded.
558
559 ===== msvcr120.dll / vcredist_x86.exe / vcredist_x64.exe - Version 12.0 (2013)
560
561 There are three redistribution methods that MSDN
562 mentions for MSVC 2013 (see:
563 http://msdn.microsoft.com/en-us/library/vstudio/ms235316(v=vs.120).aspx["Choosing a Deployment Method"]):
564
565 . _Using Visual {cpp} Redistributable Package._
566 The Microsoft libraries are installed by copying
567 _vcredist_x64.exe_ or
568 _vcredist_x86.exe_ to the target
569 machine and executing it on that machine (MSDN recommends
570 this for applications built with Visual Studio 2013)
571
572 . _Using Visual {cpp} Redistributable Merge Modules._
573 (Loadable modules for building msi installers.
574 Not suitable for Wireshark’s NSIS based installer)
575
576 . _Install a particular Visual {cpp} assembly as a
577 private assembly for the application._ The
578 Microsoft libraries are installed by copying the folder
579 content of _Microsoft.VC120.CRT_ to
580 the target directory (e.g. _C:\Program Files\Wireshark_)
581
582 To save installer size, and to make a portable
583 version of Wireshark (which must be completely self-contained,
584 on a medium such as a flash drive, and not require that an
585 installer be run to install anything on the target machine)
586 possible, when building 32-bit Wireshark with MSVC2013, method
587 3 (copying the content of _Microsoft.VC120.CRT_)
588 is used (this produces the smallest package).
589
590 ==== Windows (Platform) SDK
591
592 The Windows Platform SDK (PSDK) or Windows SDK is a free
593 (as in beer) download and contains platform specific headers and
594 libraries (e.g. _windows.h_, _WSock32.lib_, etc.). As new Windows
595 features evolve in time, updated SDK’s become available that
596 include new and updated APIs.
597
598 When you purchase a commercial Visual Studio or use the Community Edition, it will
599 include an SDK. The free Express (as in beer) downloadable C compiler
600 versions (V{cpp} 2012 Express, V{cpp} 2012 Express, etc.) do not
601 contain an SDK -- you'll need to download a PSDK in order to
602 have the required C header files and libraries.
603
604 Older versions of the SDK should also work. However, the
605 command to set the environment settings will be different, try
606 search for SetEnv.* in the SDK directory.
607
608 ==== HTML Help
609
610 HTML Help is used to create the User’s and Developer’s Guide in .chm format and
611 to show the User’s Guide as the Wireshark "Online Help".
612
613 Both features are currently optional, and might be removed in future versions.
614
615 ===== HTML Help Compiler (hhc.exe)
616
617 This compiler is used to generate a .chm file from a bunch of HTML files -- in
618 our case to generate the User’s and Developer’s Guide in .chm format.
619
620 The compiler is only available as the free (as in beer) "HTML Help Workshop"
621 download. If you want to compile the guides yourself, you need to download and
622 install this. If you don't install it into the default directory, you may also
623 have a look at the HHC_DIR setting in the file docbook/Makefile.
624
625 ===== HTML Help Build Files (htmlhelp.c / htmlhelp.lib)
626
627 The files _htmlhelp.c_ and _htmlhelp.lib_ are required to
628 be able to open .chm files from Wireshark and show the
629 online help. Both files are part of the SDK (standalone (P)SDK or MSVC
630 since 2002).
631
632 [[ChToolsDebugger]]
633
634 ==== Debugger
635
636 Using a good debugger can save you a lot of development time.
637
638 The debugger you use must match the C compiler Wireshark was compiled with,
639 otherwise the debugger will simply fail or you will only see a lot of garbage.
640
641 [[ChToolsMSVCDebugger]]
642
643 ===== Visual Studio integrated debugger
644
645 You can use the integrated debugger of Visual Studio if your toolchain includes
646 it.  Open the solution in your build directory and build and debug as normal
647 with a Visual Studio solution.
648
649 To set the correct paths for Visual Studio when running Wireshark under the
650 debugger, add the build output directory to the path before opening Visual
651 Studio from the same command prompt, e.g.
652
653 ----
654 C:\Development\wsbuild32>set PATH="%PATH%;C:\Development\wsbuild32\run\RelwithDebInfo"
655 C:\Development\wsbuild32>wireshark.sln
656 ----
657
658 for PowerShell use
659
660 ----
661 PS C:\Development\wsbuild32>$env:PATH += ";$(Convert-Path run\RelWithDebInfo)"
662 PS C:\Development\wsbuild32>wireshark.sln
663 ----
664
665 When Visual Studio has finished loading the solution, set the executable to
666 be run in the debugger, e.g. Executables\Wireshark, by right clicking it in
667 the Solution Explorer window and selecting "Set as StartUp Project".  Also
668 set the Solution Configuration (usually RelWithDebInfo) from the droplist on
669 the toolbar.
670
671 NOTE: Currently Visual Studio regards a command line build as incomplete, so
672 will report that some items need to be built when starting the debugger.  These
673 can either be rebuilt or ignored as you wish.
674
675
676 The normal build is an optimised release version so debugging can be a bit
677 difficult as variables are optimised out into registers and the execution
678 order of statements can jump around.
679
680 If you require a non-optimised version, then build using a debug configuration.
681
682 [[ChToolsMSDebuggingTools]]
683
684 ===== Debugging Tools for Windows
685
686 You can also use the Microsoft Debugging Tools for Windows toolkit, which is a
687 standalone GUI debugger. Although it’s not that comfortable compared to
688 debugging with the Visual Studio integrated debugger it can be helpful if you
689 have to debug on a machine where an integrated debugger is not available.
690
691 You can get it free of charge from Microsoft in several ways, see the
692 http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063%28v=vs.85%29.aspx)[Debugging tools for Windows] page.
693
694 You can also use Chocolatey to install WinDbg:
695
696 ----
697 PS:\> choco install windbg
698 ----
699
700 To debug Wireshark using WinDbg, open the built copy of Wireshark using
701 the File -> Open Executable... menu,
702 i.e. C:\Development\wsbuild32\run\RelWithDebInfo\Wireshark.exe.  To set a
703 breakpoint open the required source file using the File -> Open Source File...
704 menu and then click on the required line and press F9.  To run the program,
705 press F5.
706
707 If you require a non-optimised version, then build using a debug configuration, e.g.
708 *`msbuild /m /p:Configuration=Debug Wireshark.sln`*. The build products will be found
709 in C:\Development\wsbuild32\run\Debug\.
710
711 [[ChToolsBash]]
712
713 === bash
714
715 The bash shell is needed to run several shell scripts.
716
717 [[ChToolsGNUBash]]
718
719 ==== UNIX and Cygwin: GNU bash
720
721 The bash shell is available for most of the UNIX-like
722 platforms and as the bash package from the
723 <<ChToolsCygwin,Cygwin setup>>.
724
725 If bash isn't already installed or
726 available as a package for your platform, you can get it at
727 http://www.gnu.org/software/bash/bash.html[].
728
729 After correct installation, typing at the bash command line prompt:
730
731 ----
732 $ bash --version
733 ----
734
735 should result in something like:
736
737 ----
738 GNU bash, version 3.1.17(6)-release (i686-pc-cygwin)
739 Copyright (C) 2005 Free Software Foundation, Inc.
740 ----
741
742 However, the version string may vary.
743
744 [[ChToolsWindowsBash]]
745
746 [[ChToolsPython]]
747
748 === Python
749
750 http://python.org/[Python] is an interpreted programming language. It is
751 used to generate some source files, documenation, and other tasks.
752 Python 2.5 or later (including Python 3) should work fine and Python 3.5 and
753 2.7 are recommended. If you're building documentation you must have Python
754 2 installed since AsciiDoc doesn't support Python 3.
755
756 Python is either included or available as a package on most UNIX-like platforms.
757 Windows packages and source are available at http://python.org/download/[].
758 The Cygwin Python package is *not* recommended since _/usr/bin/python_ is
759 a symbolic link, which causes confusion outside Cygwin.
760
761 You can also use Chocolatey to install Python:
762
763 ----
764 PS:\> choco install Python3
765 ----
766
767 or
768
769 ----
770 PS:\> choco install Python2
771 ----
772
773 Chocolatey installs Python into _C:\tools\python3_ or _C:\tools\python2_ by
774 default. You can verify your Python version by running
775
776 ----
777 $ python --version
778 ----
779
780 on UNIX and Linux and
781
782 ----
783 rem Official package
784 C:> cd python35
785 C:Python35> python --version
786
787 rem Chocolatey
788 C:> cd \tools\python3
789 C:\tools\python3> python --version
790 ----
791
792 on Windows. You should see something like
793
794 ----
795 Python 3.5.1
796 ----
797
798 Your version string may vary of course.
799
800 [[ChToolsPerl]]
801
802 === Perl
803
804 Perl is an interpreted programming language. The
805 homepage of the Perl project is
806 http://www.perl.com[]. Perl is used to convert
807 various text files into usable source code. Perl version 5.6
808 and above should work fine.
809
810 [[ChToolsUnixPerl]]
811
812 ==== UNIX and Cygwin: Perl
813
814 Perl is available for most of the UNIX-like platforms
815 and as the perl package from the
816 <<ChToolsCygwin,Cygwin setup>>.
817
818 If perl isn't already installed or available
819 as a package for your platform, you can get it at
820 http://www.perl.com/[].
821
822 After correct installation, typing at the
823 bash command line prompt:
824
825 ----
826 $ perl --version
827 ----
828
829 should result in something like:
830
831 ----
832 This is perl, v5.8.7 built for cygwin-thread-multi-64int
833 (with 1 registered patch, see perl -V for more detail)
834
835 Copyright 1987-2005, Larry Wall
836
837 Perl may be copied only under the terms of either the Artistic License or the
838 GNU General Public License, which may be found in the Perl 5 source kit.
839
840 Complete documentation for Perl, including FAQ lists, should be found on
841 this system using *`man perl'* or *`perldoc perl'*.  If you have access to the
842 Internet, point your browser at http://www.perl.com/, the Perl Home Page.
843 ----
844
845 However, the version string may vary.
846
847 //[[ChToolsWindowsPerl]]
848 //
849 //==== Windows native: Perl
850 //
851 //A native Windows Perl package can be obtained from
852 //http://www.ActiveState.com[Active State] or http://strawberryperl.com/[Strawberry Perl]. The installation
853 //should be straightforward.
854 //
855 //You may also use Chocolatey to install either package:
856 //
857 //----
858 //PS:\> choco install ActivePerl
859 //----
860 //
861 //or
862 //
863 //----
864 //PS:\> choco install StrawberryPerl
865 //----
866 //
867 //After correct installation, typing at the command
868 //line prompt (cmd.exe):
869 //
870 //----
871 //> perl -v
872 //----
873 //
874 //should result in something like:
875 //
876 //----
877 //This is perl, v5.8.0 built for MSWin32-x86-multi-thread
878 //(with 1 registered patch, see perl -V for more detail)
879 //
880 //Copyright 1987-2002, Larry Wall
881 //
882 //Binary build 805 provided by ActiveState Corp. http://www.ActiveState.com
883 //Built 18:08:02 Feb  4 2003
884 //...
885 //----
886 //
887 //However, the version string may vary.
888
889 // Sed is no longer required.
890 //[[ChToolsSed]]
891
892 [[ChToolsBison]]
893
894 === Bison
895
896 Bison is a parser generator used for some of Wireshark’s file format support.
897
898 [[ChToolsUnixBison]]
899
900 ==== UNIX or Cygwin: bison
901
902 Bison is available for most UNIX-like platforms and as the bison package from
903 <<ChToolsCygwin,Cygwin>>. See the next section for native Windows options.
904
905 If GNU Bison isn't already installed or available as a package for your
906 platform you can get it at: http://www.gnu.org/software/bison/bison.html[].
907
908 After correct installation running the following
909
910 ----
911 $ bison --version
912 ----
913
914 should result in something like:
915
916 ----
917 bison (GNU Bison) 2.3
918 Written by Robert Corbett and Richard Stallman.
919
920 Copyright (C) 2006 Free Software Foundation, Inc.
921 This is free software; see the source for copying conditions.  There is NO
922 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
923 ----
924
925 Your version string may vary.
926
927 [[ChToolsWindowsBison]]
928
929 ==== Windows Native: Win flex-bison and bison
930
931 A native Windows version of bison is available in the _winflexbison_
932 https://chocolatey.org/[Chocolatey] package. Note that the executable is named
933 _win_bison_.
934
935 Native packages are available from other sources such as
936 http://gnuwin32.sourceforge.net/packages/bison.htm[GnuWin]. They aren't
937 officially supported but _should_ work.
938
939 [[ChToolsFlex]]
940
941 === Flex
942
943 Flex is a lexical analyzer generator used for Wireshark’s display filters, some
944 file formats, and other features.
945
946 [[ChToolsUnixFlex]]
947
948 ==== UNIX or Cygwin: flex
949
950 Flex is available for most UNIX-like platforms and as the flex package from
951 <<ChToolsCygwin,Cygwin>>. See the next section for native Windows options.
952
953 If GNU flex isn't already installed or available as a package for your platform
954 you can get it at http://www.gnu.org/software/flex/[].
955
956 After correct installation running the following
957
958 ----
959 $ flex --version
960 ----
961
962 should result in something like:
963
964 ----
965 flex version 2.5.4
966 ----
967
968 Your version string may vary.
969
970 [[ChToolsWindowsFlex]]
971
972 ==== Windows Native: Win flex-bison and flex
973
974 A native Windows version of flex is available in the _winflexbison_
975 https://chocolatey.org/[Chocolatey] package. Note that the executable is named
976 _win_flex_.
977
978 ----
979 PS:\>choco install winflexbison
980 ----
981
982 Native packages are available from other sources such as
983 http://gnuwin32.sourceforge.net/packages/flex.htm[GnuWin]. They aren't
984 officially supported but _should_ work.
985
986 [[ChToolsGit]]
987
988 === Git client
989
990 The Wireshark project uses its own Git repository to keep track of all
991 the changes done to the source code. Details about the usage of Git in
992 the Wireshark project can be found in <<ChSrcGitRepository>>.
993
994 If you want to work with the source code and are planning to commit your
995 changes back to the Wireshark community, it is recommended to use a Git
996 client to get the latest source files. For detailed information about
997 the different ways to obtain the Wireshark sources, see <<ChSrcObtain>>.
998
999 You will find more instructions in <<ChSrcGit>> on how to use the Git
1000 client.
1001
1002 [[ChToolsUnixGit]]
1003
1004 ==== UNIX or Cygwin: git
1005
1006 Git is available for most of the UNIX-like platforms
1007 and as the Git package from the
1008 <<ChToolsCygwin,Cygwin setup>>
1009
1010 If Git isn't already installed or available as a package for your platform, you
1011 can get it at: http://git-scm.com/[].
1012
1013 After correct installation, typing at the bash command line prompt:
1014
1015 ----
1016 $ git --version
1017 ----
1018
1019 should result in something like:
1020
1021 ----
1022 git version 1.8.3.4
1023 ----
1024
1025 Your version will likely be different.
1026
1027 [[ChToolsWindowsGit]]
1028
1029 ==== Windows native: git
1030
1031 The Git command line tools for Windows can be found at
1032 http://git-scm.com/download/win[] and can also be installed using Chocolatey:
1033
1034 ----
1035 PS:\> choco install git
1036 ----
1037
1038 After correct installation, typing at the command
1039 line prompt (cmd.exe):
1040
1041 ----
1042 $ git --version
1043 ----
1044
1045 should result in something like:
1046
1047 ----
1048 git version 1.8.3.4
1049 ----
1050
1051 However, the version string may vary.
1052
1053 [[ChToolsGitPowerShellExtensions]]
1054
1055 === Git Powershell Extensions (optional)
1056
1057 A useful tool for command line git on Windows is https://github.com/dahlbyk/posh-git[PoshGit].
1058 Poshgit provides git command completion and alters the prompt to indicate the local working
1059 copy status.  You can install it using Chocolatey:
1060
1061 ----
1062 PS:\>choco install poshgit
1063 ----
1064
1065 [[ChToolsGitGUI]]
1066
1067 === Git GUI client (optional)
1068
1069 Along with the traditional command-line client, several
1070 GUI clients are available for a number of platforms. See
1071 http://git-scm.com/downloads/guis[] for details.
1072
1073 // [[ChToolsUnixGitGUI]]
1074 // XXX Add Gui client section
1075
1076 [[ChToolsPatch]]
1077
1078 === patch (optional)
1079
1080 The patch utility is used to merge a diff file into your own source tree. This
1081 tool is only needed, if you want to apply a patch (diff file) from someone else
1082 (probably from the developer mailing list) to try out in your own private source
1083 tree.
1084
1085 It most cases you may not need the patch tool installed. Git and Gerrit should
1086 handle patches for you.
1087
1088 You will find more instructions in <<ChSrcPatchApply>>on how to use the patch
1089 tool.
1090
1091 [[ChToolsUnixPatch]]
1092
1093 ==== UNIX and Cygwin: patch
1094
1095 Patch is available for most of the UNIX-like platforms
1096 and as the patch package from the
1097 <<ChToolsCygwin,Cygwin setup>>.
1098
1099 If GNU patch isn't already installed or
1100 available as a package for your platform, you can get it at
1101 http://www.gnu.org/software/patch/patch.html[].
1102
1103 After correct installation, typing at the
1104 bash command line prompt:
1105
1106 ----
1107 $ patch --version
1108 ----
1109
1110 should result in something like:
1111
1112 ----
1113 patch 2.5.8
1114 Copyright (C) 1988 Larry Wall
1115 Copyright (C) 2002 Free Software Foundation, Inc.
1116
1117 This program comes with NO WARRANTY, to the extent permitted by law.
1118 You may redistribute copies of this program
1119 under the terms of the GNU General Public License.
1120 For more information about these matters, see the file named COPYING.
1121
1122 written by Larry Wall and Paul Eggert
1123 ----
1124
1125 However, the version string may vary.
1126
1127 [[ChToolsWindowsPatch]]
1128
1129 ==== Windows native: patch
1130
1131 The Windows native Git tools provide patch. A native Windows patch package can be obtained from
1132 http://gnuwin32.sourceforge.net/[]. The
1133 installation should be straightforward.
1134
1135 [[ChToolsNSIS]]
1136
1137 === Windows: NSIS (optional)
1138
1139 The NSIS (Nullsoft Scriptable Install System) is used to generate
1140 _Wireshark-win32-{wireshark-version}.exe_ from all the files
1141 needed to be installed, including all required DLLs, plugins, and supporting
1142 files.
1143
1144 To install it, download the latest released version from
1145 http://nsis.sourceforge.net[]. NSIS v3 is recommended and may be
1146 required in the future. You can also install it using Chocolatey:
1147
1148 ----
1149 PS$> choco install nsis
1150 ----
1151
1152 You can find more instructions on using NSIS in <<ChSrcNSIS>>.
1153
1154 === Windows: PortableApps (optional)
1155
1156 The PortableApps.com Installer is used to generate
1157 _WiresharkPortable-{wireshark-version}.paf.exe_ from all the files
1158 needed to be installed, including all required DLLs, plugins, and supporting
1159 files.
1160
1161 To install it, do the following:
1162
1163 * Download the latest PortableApps.com Platform release from
1164   http://portableapps.com/[].
1165
1166 * Install the following applications in the PortableApps.com environment:
1167
1168 ** PortableApps.com Installer
1169
1170 ** PortableApps.com Launcher
1171
1172 ** NSIS Portable (Unicode)
1173
1174 ** PortableApps.com AppCompactor
1175
1176 You can find more instructions on using the PortableApps.com Installer in
1177 <<ChSrcPortableApps>>.
1178
1179 // End of WSDG Chapter Tools
1180
1181 // vim: set syntax=asciidoc: