Docs: Updates for xsltproc and Asciidoctor.
[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 === Documentation Toolchain
609
610 Wireshark’s documentation is split across two directories. The `doc`
611 directory contains man pages written in Perl’s POD (Plain Old
612 Documentation) format. The `docbook` directory contains the User’s
613 Guide, Developer’s Guide, and the release notes, which are written in
614 Asciidoctor markup.
615
616 Our various output formats are generated using the following tools.
617 Intermediate formats are in _italics_.
618
619 Guide HTML:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL
620 Guide PDF:: Asciidoctor
621 Guide HTML Help:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL → HHC
622
623 Release notes HTML:: Asciidoctor
624 Release notes text:: Asciidoctor → _HTML_ → html2text.py
625
626 ==== Asciidoctor
627
628 Asciidoctor[https://asciidoctor.org/] comes in several flavors: a Ruby
629 gem (Asciidoctor), a Java bundle (AsciidoctorJ), and transpiled
630 JavaScript (Asciidoctor.js). Only the Asciidoctor and AsciidoctorJ
631 flavors are supported for building the Wireshark documentation and
632 AsciidoctorJ is recommended.
633
634 The guides and release notes were originally written in DocBook (hence
635 the directory name). They were later converted to AsciiDoc and then
636 migrated to Asciidoctor.
637 `compat-mode`[https://asciidoctor.org/docs/migration/] is currently
638 enabled for the guides, but we are steadily migrating to Asciidoctor’s
639 modern (>= 1.5.0) syntax.
640
641 PDF output requires Asciidoctor PDF. It is included with AsciidoctorJ
642 but _not_ with Asciidoctor.
643
644 ==== Xsltproc And DocBook
645
646 The single HTML, chunked HTML, and HTML Help guides are generated using
647 DocBook XSL stylesheets. They in turn require an XSLT processor. We use
648 `xsltproc`.
649
650 ==== HTML Help
651
652 HTML Help is used to create the User’s and Developer’s Guide in .chm format.
653 The User’s Guide .chm file is included with the NSIS and WiX installers and
654 is used as Wireshark's built-in help on Windows.
655
656 This compiler is used to generate a .chm file from a bunch of HTML files -- in
657 our case to generate the User’s and Developer’s Guide in .chm format.
658
659 The compiler is only available as the free (as in beer) "HTML Help Workshop"
660 download. If you want to compile the guides yourself, you need to download and
661 install this. If you don't install it into the default directory, you may also
662 have a look at the HHC_DIR setting in the file docbook/Makefile.
663
664 The files `htmlhelp.c` and `htmlhelp.lib` are required to
665 be able to open .chm files from Wireshark and show the
666 online help. Both files are part of the SDK (standalone (P)SDK or MSVC
667 since 2002).
668
669 [[ChToolsDebugger]]
670
671 ==== Debugger
672
673 Using a good debugger can save you a lot of development time.
674
675 The debugger you use must match the C compiler Wireshark was compiled with,
676 otherwise the debugger will simply fail or you will only see a lot of garbage.
677
678 [[ChToolsMSVCDebugger]]
679
680 ===== Visual Studio integrated debugger
681
682 You can use the integrated debugger of Visual Studio if your toolchain includes
683 it.  Open the solution in your build directory and build and debug as normal
684 with a Visual Studio solution.
685
686 To set the correct paths for Visual Studio when running Wireshark under the
687 debugger, add the build output directory to the path before opening Visual
688 Studio from the same command prompt, e.g.
689
690 ----
691 C:\Development\wsbuild32>set PATH="%PATH%;C:\Development\wsbuild32\run\RelwithDebInfo"
692 C:\Development\wsbuild32>wireshark.sln
693 ----
694
695 for PowerShell use
696
697 ----
698 PS C:\Development\wsbuild32>$env:PATH += ";$(Convert-Path run\RelWithDebInfo)"
699 PS C:\Development\wsbuild32>wireshark.sln
700 ----
701
702 When Visual Studio has finished loading the solution, set the executable to
703 be run in the debugger, e.g. Executables\Wireshark, by right clicking it in
704 the Solution Explorer window and selecting "Set as StartUp Project".  Also
705 set the Solution Configuration (usually RelWithDebInfo) from the droplist on
706 the toolbar.
707
708 NOTE: Currently Visual Studio regards a command line build as incomplete, so
709 will report that some items need to be built when starting the debugger.  These
710 can either be rebuilt or ignored as you wish.
711
712
713 The normal build is an optimised release version so debugging can be a bit
714 difficult as variables are optimised out into registers and the execution
715 order of statements can jump around.
716
717 If you require a non-optimised version, then build using a debug configuration.
718
719 [[ChToolsMSDebuggingTools]]
720
721 ===== Debugging Tools for Windows
722
723 You can also use the Microsoft Debugging Tools for Windows toolkit, which is a
724 standalone GUI debugger. Although it’s not that comfortable compared to
725 debugging with the Visual Studio integrated debugger it can be helpful if you
726 have to debug on a machine where an integrated debugger is not available.
727
728 You can get it free of charge from Microsoft in several ways, see the
729 http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063%28v=vs.85%29.aspx)[Debugging tools for Windows] page.
730
731 You can also use Chocolatey to install WinDbg:
732
733 ----
734 PS:\> choco install windbg
735 ----
736
737 To debug Wireshark using WinDbg, open the built copy of Wireshark using
738 the File -> Open Executable... menu,
739 i.e. C:\Development\wsbuild32\run\RelWithDebInfo\Wireshark.exe.  To set a
740 breakpoint open the required source file using the File -> Open Source File...
741 menu and then click on the required line and press F9.  To run the program,
742 press F5.
743
744 If you require a non-optimised version, then build using a debug configuration, e.g.
745 *`msbuild /m /p:Configuration=Debug Wireshark.sln`*. The build products will be found
746 in C:\Development\wsbuild32\run\Debug\.
747
748 [[ChToolsBash]]
749
750 === bash
751
752 The bash shell is needed to run several shell scripts.
753
754 [[ChToolsGNUBash]]
755
756 ==== UNIX and Cygwin: GNU bash
757
758 The bash shell is available for most of the UNIX-like
759 platforms and as the bash package from the
760 <<ChToolsCygwin,Cygwin setup>>.
761
762 If bash isn't already installed or
763 available as a package for your platform, you can get it at
764 http://www.gnu.org/software/bash/bash.html[].
765
766 After correct installation, typing at the bash command line prompt:
767
768 ----
769 $ bash --version
770 ----
771
772 should result in something like:
773
774 ----
775 GNU bash, version 3.1.17(6)-release (i686-pc-cygwin)
776 Copyright (C) 2005 Free Software Foundation, Inc.
777 ----
778
779 However, the version string may vary.
780
781 [[ChToolsWindowsBash]]
782
783 [[ChToolsPython]]
784
785 === Python
786
787 http://python.org/[Python] is an interpreted programming language. It is
788 used to generate some source files, documenation, and other tasks.
789 Python 2.5 or later (including Python 3) should work fine and Python 3.5 and
790 2.7 are recommended. If you're building documentation you must have Python
791 2 installed since AsciiDoc doesn't support Python 3.
792
793 Python is either included or available as a package on most UNIX-like platforms.
794 Windows packages and source are available at http://python.org/download/[].
795 The Cygwin Python package is *not* recommended since _/usr/bin/python_ is
796 a symbolic link, which causes confusion outside Cygwin.
797
798 You can also use Chocolatey to install Python:
799
800 ----
801 PS:\> choco install Python3
802 ----
803
804 or
805
806 ----
807 PS:\> choco install Python2
808 ----
809
810 Chocolatey installs Python into _C:\tools\python3_ or _C:\tools\python2_ by
811 default. You can verify your Python version by running
812
813 ----
814 $ python --version
815 ----
816
817 on UNIX and Linux and
818
819 ----
820 rem Official package
821 C:> cd python35
822 C:Python35> python --version
823
824 rem Chocolatey
825 C:> cd \tools\python3
826 C:\tools\python3> python --version
827 ----
828
829 on Windows. You should see something like
830
831 ----
832 Python 3.5.1
833 ----
834
835 Your version string may vary of course.
836
837 [[ChToolsPerl]]
838
839 === Perl
840
841 Perl is an interpreted programming language. The
842 homepage of the Perl project is
843 http://www.perl.com[]. Perl is used to convert
844 various text files into usable source code. Perl version 5.6
845 and above should work fine.
846
847 [[ChToolsUnixPerl]]
848
849 ==== UNIX and Cygwin: Perl
850
851 Perl is available for most of the UNIX-like platforms
852 and as the perl package from the
853 <<ChToolsCygwin,Cygwin setup>>.
854
855 If perl isn't already installed or available
856 as a package for your platform, you can get it at
857 http://www.perl.com/[].
858
859 After correct installation, typing at the
860 bash command line prompt:
861
862 ----
863 $ perl --version
864 ----
865
866 should result in something like:
867
868 ----
869 This is perl, v5.8.7 built for cygwin-thread-multi-64int
870 (with 1 registered patch, see perl -V for more detail)
871
872 Copyright 1987-2005, Larry Wall
873
874 Perl may be copied only under the terms of either the Artistic License or the
875 GNU General Public License, which may be found in the Perl 5 source kit.
876
877 Complete documentation for Perl, including FAQ lists, should be found on
878 this system using *`man perl'* or *`perldoc perl'*.  If you have access to the
879 Internet, point your browser at http://www.perl.com/, the Perl Home Page.
880 ----
881
882 However, the version string may vary.
883
884 //[[ChToolsWindowsPerl]]
885 //
886 //==== Windows native: Perl
887 //
888 //A native Windows Perl package can be obtained from
889 //http://www.ActiveState.com[Active State] or http://strawberryperl.com/[Strawberry Perl]. The installation
890 //should be straightforward.
891 //
892 //You may also use Chocolatey to install either package:
893 //
894 //----
895 //PS:\> choco install ActivePerl
896 //----
897 //
898 //or
899 //
900 //----
901 //PS:\> choco install StrawberryPerl
902 //----
903 //
904 //After correct installation, typing at the command
905 //line prompt (cmd.exe):
906 //
907 //----
908 //> perl -v
909 //----
910 //
911 //should result in something like:
912 //
913 //----
914 //This is perl, v5.8.0 built for MSWin32-x86-multi-thread
915 //(with 1 registered patch, see perl -V for more detail)
916 //
917 //Copyright 1987-2002, Larry Wall
918 //
919 //Binary build 805 provided by ActiveState Corp. http://www.ActiveState.com
920 //Built 18:08:02 Feb  4 2003
921 //...
922 //----
923 //
924 //However, the version string may vary.
925
926 // Sed is no longer required.
927 //[[ChToolsSed]]
928
929 [[ChToolsBison]]
930
931 === Bison
932
933 Bison is a parser generator used for some of Wireshark’s file format support.
934
935 [[ChToolsUnixBison]]
936
937 ==== UNIX or Cygwin: bison
938
939 Bison is available for most UNIX-like platforms and as the bison package from
940 <<ChToolsCygwin,Cygwin>>. See the next section for native Windows options.
941
942 If GNU Bison isn't already installed or available as a package for your
943 platform you can get it at: http://www.gnu.org/software/bison/bison.html[].
944
945 After correct installation running the following
946
947 ----
948 $ bison --version
949 ----
950
951 should result in something like:
952
953 ----
954 bison (GNU Bison) 2.3
955 Written by Robert Corbett and Richard Stallman.
956
957 Copyright (C) 2006 Free Software Foundation, Inc.
958 This is free software; see the source for copying conditions.  There is NO
959 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
960 ----
961
962 Your version string may vary.
963
964 [[ChToolsWindowsBison]]
965
966 ==== Windows Native: Win flex-bison and bison
967
968 A native Windows version of bison is available in the _winflexbison_
969 https://chocolatey.org/[Chocolatey] package. Note that the executable is named
970 _win_bison_.
971
972 Native packages are available from other sources such as
973 http://gnuwin32.sourceforge.net/packages/bison.htm[GnuWin]. They aren't
974 officially supported but _should_ work.
975
976 [[ChToolsFlex]]
977
978 === Flex
979
980 Flex is a lexical analyzer generator used for Wireshark’s display filters, some
981 file formats, and other features.
982
983 [[ChToolsUnixFlex]]
984
985 ==== UNIX or Cygwin: flex
986
987 Flex is available for most UNIX-like platforms and as the flex package from
988 <<ChToolsCygwin,Cygwin>>. See the next section for native Windows options.
989
990 If GNU flex isn't already installed or available as a package for your platform
991 you can get it at http://www.gnu.org/software/flex/[].
992
993 After correct installation running the following
994
995 ----
996 $ flex --version
997 ----
998
999 should result in something like:
1000
1001 ----
1002 flex version 2.5.4
1003 ----
1004
1005 Your version string may vary.
1006
1007 [[ChToolsWindowsFlex]]
1008
1009 ==== Windows Native: Win flex-bison and flex
1010
1011 A native Windows version of flex is available in the _winflexbison_
1012 https://chocolatey.org/[Chocolatey] package. Note that the executable is named
1013 _win_flex_.
1014
1015 ----
1016 PS:\>choco install winflexbison
1017 ----
1018
1019 Native packages are available from other sources such as
1020 http://gnuwin32.sourceforge.net/packages/flex.htm[GnuWin]. They aren't
1021 officially supported but _should_ work.
1022
1023 [[ChToolsGit]]
1024
1025 === Git client
1026
1027 The Wireshark project uses its own Git repository to keep track of all
1028 the changes done to the source code. Details about the usage of Git in
1029 the Wireshark project can be found in <<ChSrcGitRepository>>.
1030
1031 If you want to work with the source code and are planning to commit your
1032 changes back to the Wireshark community, it is recommended to use a Git
1033 client to get the latest source files. For detailed information about
1034 the different ways to obtain the Wireshark sources, see <<ChSrcObtain>>.
1035
1036 You will find more instructions in <<ChSrcGit>> on how to use the Git
1037 client.
1038
1039 [[ChToolsUnixGit]]
1040
1041 ==== UNIX or Cygwin: git
1042
1043 Git is available for most of the UNIX-like platforms
1044 and as the Git package from the
1045 <<ChToolsCygwin,Cygwin setup>>
1046
1047 If Git isn't already installed or available as a package for your platform, you
1048 can get it at: http://git-scm.com/[].
1049
1050 After correct installation, typing at the bash command line prompt:
1051
1052 ----
1053 $ git --version
1054 ----
1055
1056 should result in something like:
1057
1058 ----
1059 git version 1.8.3.4
1060 ----
1061
1062 Your version will likely be different.
1063
1064 [[ChToolsWindowsGit]]
1065
1066 ==== Windows native: git
1067
1068 The Git command line tools for Windows can be found at
1069 http://git-scm.com/download/win[] and can also be installed using Chocolatey:
1070
1071 ----
1072 PS:\> choco install git
1073 ----
1074
1075 After correct installation, typing at the command
1076 line prompt (cmd.exe):
1077
1078 ----
1079 $ git --version
1080 ----
1081
1082 should result in something like:
1083
1084 ----
1085 git version 1.8.3.4
1086 ----
1087
1088 However, the version string may vary.
1089
1090 [[ChToolsGitPowerShellExtensions]]
1091
1092 === Git Powershell Extensions (optional)
1093
1094 A useful tool for command line git on Windows is https://github.com/dahlbyk/posh-git[PoshGit].
1095 Poshgit provides git command completion and alters the prompt to indicate the local working
1096 copy status.  You can install it using Chocolatey:
1097
1098 ----
1099 PS:\>choco install poshgit
1100 ----
1101
1102 [[ChToolsGitGUI]]
1103
1104 === Git GUI client (optional)
1105
1106 Along with the traditional command-line client, several
1107 GUI clients are available for a number of platforms. See
1108 http://git-scm.com/downloads/guis[] for details.
1109
1110 // [[ChToolsUnixGitGUI]]
1111 // XXX Add Gui client section
1112
1113 [[ChToolsPatch]]
1114
1115 === patch (optional)
1116
1117 The patch utility is used to merge a diff file into your own source tree. This
1118 tool is only needed, if you want to apply a patch (diff file) from someone else
1119 (probably from the developer mailing list) to try out in your own private source
1120 tree.
1121
1122 It most cases you may not need the patch tool installed. Git and Gerrit should
1123 handle patches for you.
1124
1125 You will find more instructions in <<ChSrcPatchApply>>on how to use the patch
1126 tool.
1127
1128 [[ChToolsUnixPatch]]
1129
1130 ==== UNIX and Cygwin: patch
1131
1132 Patch is available for most of the UNIX-like platforms
1133 and as the patch package from the
1134 <<ChToolsCygwin,Cygwin setup>>.
1135
1136 If GNU patch isn't already installed or
1137 available as a package for your platform, you can get it at
1138 http://www.gnu.org/software/patch/patch.html[].
1139
1140 After correct installation, typing at the
1141 bash command line prompt:
1142
1143 ----
1144 $ patch --version
1145 ----
1146
1147 should result in something like:
1148
1149 ----
1150 patch 2.5.8
1151 Copyright (C) 1988 Larry Wall
1152 Copyright (C) 2002 Free Software Foundation, Inc.
1153
1154 This program comes with NO WARRANTY, to the extent permitted by law.
1155 You may redistribute copies of this program
1156 under the terms of the GNU General Public License.
1157 For more information about these matters, see the file named COPYING.
1158
1159 written by Larry Wall and Paul Eggert
1160 ----
1161
1162 However, the version string may vary.
1163
1164 [[ChToolsWindowsPatch]]
1165
1166 ==== Windows native: patch
1167
1168 The Windows native Git tools provide patch. A native Windows patch package can be obtained from
1169 http://gnuwin32.sourceforge.net/[]. The
1170 installation should be straightforward.
1171
1172 [[ChToolsNSIS]]
1173
1174 === Windows: NSIS (optional)
1175
1176 The NSIS (Nullsoft Scriptable Install System) is used to generate
1177 _Wireshark-win32-{wireshark-version}.exe_ from all the files
1178 needed to be installed, including all required DLLs, plugins, and supporting
1179 files.
1180
1181 To install it, download the latest released version from
1182 http://nsis.sourceforge.net[]. NSIS v3 is recommended and may be
1183 required in the future. You can also install it using Chocolatey:
1184
1185 ----
1186 PS$> choco install nsis
1187 ----
1188
1189 You can find more instructions on using NSIS in <<ChSrcNSIS>>.
1190
1191 === Windows: PortableApps (optional)
1192
1193 The PortableApps.com Installer is used to generate
1194 _WiresharkPortable-{wireshark-version}.paf.exe_ from all the files
1195 needed to be installed, including all required DLLs, plugins, and supporting
1196 files.
1197
1198 To install it, do the following:
1199
1200 * Download the latest PortableApps.com Platform release from
1201   http://portableapps.com/[].
1202
1203 * Install the following applications in the PortableApps.com environment:
1204
1205 ** PortableApps.com Installer
1206
1207 ** PortableApps.com Launcher
1208
1209 ** NSIS Portable (Unicode)
1210
1211 ** PortableApps.com AppCompactor
1212
1213 You can find more instructions on using the PortableApps.com Installer in
1214 <<ChSrcPortableApps>>.
1215
1216 // End of WSDG Chapter Tools
1217
1218 // vim: set syntax=asciidoc: