Docs: Updates for xsltproc and Asciidoctor.
[metze/wireshark/wip.git] / docbook / wsdg_src / WSDG_chapter_quick_setup.asciidoc
1 // WSDG Chapter Setup
2
3 [[ChapterSetup]]
4
5 == Quick Setup
6
7 [[ChSetupUNIX]]
8
9 === UNIX: Installation
10
11 All the tools required are usually installed on a UNIX developer machine.
12
13 If a tool is not already installed on your system, you can usually install it
14 using the package in your distribution: aptitude, yum, Synaptic, etc.
15
16 If an install package is not available or you have a
17 reason not to use it (maybe because it’s simply too old), you
18 can install that tool from source code. The following sections
19 will provide you with the webpage addresses where you can get
20 these sources.
21
22 [[ChSetupWin32]]
23
24 === Win32/64: Step-by-Step Guide
25
26 A quick setup guide for Win32 and Win64 with recommended
27 configuration.
28
29 [WARNING]
30 ====
31 Unless you know exactly what you are doing, you
32 should strictly follow the recommendations below. They are known to work
33 and if the build breaks, please re-read this guide carefully.
34
35 Known traps are:
36
37 . Not using the correct (x86 or x64) version of the Visual Studio command prompt.
38
39 . Not copying/downloading the correct version of vcredist_xYY.exe.
40
41 ====
42
43 [[ChSetupChocolatey]]
44
45 ==== Recommended: Install Chocolatey
46
47 https://chocolatey.org/[Chocolatey] is a native package manager for Windows.
48 There are https://chocolatey.org/packages[packages] for most of the software
49 listed below. Along with traditional Windows packages it supports Cygwin and
50 the Python Package Index.
51
52 // ...such as:
53 // - Active Perl and/or StrawberryPerl
54 // - Devbox-UnZip and/or 7zip and/or peazip
55 // - Wget
56 // - Git (a native win32 (MSYS) version)
57
58 [[ChSetupMSVC]]
59
60 ==== Install Microsoft C compiler and SDK
61
62 You need to install, in exactly this order:
63
64 . C compiler:
65 https://go.microsoft.com/fwlink/?LinkId=532606&clcid=0x409[Download]
66 and install ``Microsoft Visual Studio 2015 Community Edition.'' This is a small
67 download that then downloads all the other required parts (which are quite large).
68
69 Select the "Custom" install and then uncheck all the optional components other
70 than "Common Tools for Visual C++ 2015" (unless you want to use them for purposes
71 other than Wireshark).
72
73 You can use Chocolatey to install Visual Studio, to correctly configure the
74 installation, copy the deployment XML file https://code.wireshark.org/review/gitweb?p=wireshark.git;a=blob_plain;f=tools/msvc2015AdminDeployment.xml;hb=HEAD[msvc2015AdminDeployment.xml] from the source code tools directory
75 and pass the path the file to the chocolatey install command:
76
77 ----
78 PS$>choco install VisualStudio2015Community --timeout 0 -package-parameters "--AdminFile path\to\msvc2015AdminDeployment.xml"
79 ----
80
81 You can use other Microsoft C compiler variants, but VS2015 is used to
82 build the development releases and is the preferred option. It’s
83 possible to compile Wireshark with a wide range of Microsoft C compiler
84 variants. For details see <<ChToolsMSChain>>.
85
86 You may have to do this as Administrator.
87
88 Compiling with gcc or Clang is not recommended and will
89 certainly not work (at least not without a lot of advanced
90 tweaking). For further details on this topic, see
91 <<ChToolsGNUChain>>. This may change in future as releases
92 of Visual Studio add more cross-platform support.
93
94 // XXX - mention the compiler and PSDK web installers -
95 // which significantly reduce download size - and find out the
96 // required components
97
98 Why is this recommended? While this is a huge download,
99 Visual Studio 2015 Community Edition is the only free (as in beer)
100 versions that includes the Visual Studio integrated
101 debugger. Visual Studio 2015 is also used to create official
102 Wireshark builds, so it will likely have fewer development-related
103 problems.
104
105 [[ChSetupQt]]
106
107 ==== Install Qt
108
109 The main Wireshark application uses the Qt windowing toolkit. To install
110 Qt download the *Qt Online Installer for Windows* from the Qt Project
111 https://www.qt.io/download-open-source/["Download Open Source" page] and
112 select a component that matches your target system and compiler. For
113 example, the ``msvc2015 64-bit'' component is used to build the official
114 64-bit packages.  You can deselect all the Qt xxxx (e.g. Qt Charts)
115 components as they aren't required.
116
117 Note that installation of separate Qt components are required for 32 bit
118 and 64 bit builds, e.g. ``msvc2015 32-bit'' and ``msvc2015 64-bit''. The
119 environment variable `QT5_BASE_DIR` should be set as appropriate for your
120 environment and should point to the Qt directory that contains the bin
121 directory, e.g. _C:\Qt\5.9.1\msvc2015_64_
122
123 The Qt maintenance tool (_C:\Qt\MaintenanceTool.exe_) can be used to
124 upgrade Qt to newer versions.
125
126 [[ChSetupCygwin]]
127
128 ==== Optional: Install Cygwin
129
130 On 32-bit Windows, http://www.cygwin.com/setup-x86.exe[download the
131 32-bit Cygwin installer] and start it. On 64-bit Windows,
132 http://www.cygwin.com/setup-x86_64.exe[download the 64-bit Cygwin
133 installer] and start it.
134
135 Over time the Wireshark development toolchain has been migrating away from Cygwin
136 toward native tools and we hope to eliminate it as a requirement someday.
137
138 At the "Select Packages" page, you'll need to select
139 some additional packages which are not installed by default.
140 Navigate to the required Category/Package row and, if the package
141 has a "Skip" item in the "New" column, click on the "Skip" item
142 so it shows a version number for:
143
144 * Devel/bison (or install Win flex-bison - see Chocolatey below)
145
146 * Devel/flex (or install Win flex-bison - see Chocolatey below)
147
148 * Devel/git (recommended - see discussion about using Git below)
149
150 * Interpreters/perl
151
152 * Utils/patch (only if needed) (may be Devel/patch instead)
153
154 * Web/wget (not needed if using CMake)
155
156 * Text/docbook-xml45
157
158 // Also need: bash/sh, sed
159
160 You might also have to install
161
162 * Interpreters/m4
163
164 if installing Devel/bison doesn't provide a working version of Bison. If
165 m4 is missing bison will fail.
166
167 After clicking the btn:[Next] button several times, the setup
168 will then download and install the selected packages (this
169 may take a while).
170
171 Alternatively you can install Cygwin and its packages using Chocolatey:
172
173 ----
174 PS$>choco install cygwin
175 PS$>choco install cyg-get
176 ----
177 //PS$>choco install sed [...] -source cygwin
178
179 Chocolatey installs Cygwin in _C:\tools\cygwin_ by default.
180
181 You can directly download packages via `cyg-get`
182
183 ----
184 PS$>cyg-get docbook-xml45 [...]
185 ----
186
187 You can use Chocolatey’s Win flex-bison packages rather than the Cygwin
188 Bison and Flex package:
189
190 ----
191 PS$>choco install winflexbison
192 ----
193
194 [[ChSetupPython]]
195
196 ==== Install Python
197
198 Get the Python 3.5 or 2.7 installer from http://python.org/download/[] and
199 install Python into the default location (_C:\Python35_ or _C:\Python27_).
200
201 Why is this recommended? Cygwin’s _/usr/bin/python_ is a Cygwin-specific
202 symbolic link which cannot be run from Windows. The native package is faster
203 as well.
204
205 Alternatively you can install Python using Chocolatey:
206
207 ----
208 PS$>choco install python3
209 ----
210
211 or
212
213 ----
214 PS$>choco install python2
215 ----
216
217 Chocolatey installs Python in _C:\tools\python3_ and _C:\tools\python2_ by default.
218
219 [[ChSetupGit]]
220
221 ==== Install Git
222
223 Please note that the following is not required to build Wireshark but can be
224 quite helpful when working with the sources.
225
226 Working with the Git source repositories is highly recommended, see
227 <<ChSrcObtain>>. It is much easier to update a personal source tree (local repository) with Git
228 rather than downloading a zip file and merging new sources into a personal
229 source tree by hand. It also makes first-time setup easy and enables the
230 Wireshark build process to determine your current source code revision.
231
232 There are several ways in which Git can be installed. Most packages are
233 available at the URLs below or via https://chocolatey.org/[Chocolatey].
234 Note that many of the GUI interfaces depend on the command line version.
235
236 If installing the Windows version of git select the
237 _Use Git from the Windows Command Prompt_ (in chocolatey the _/GitOnlyOnPath_
238 option).  Do *not* select the _Use Git and optional Unix tools from the Windows Command Prompt_
239 option (in chocolatey the _/GitAndUnixToolsOnPath_ option).
240
241 ===== The Official Windows Installer
242
243 The official command-line installer is available at https://git-scm.com/download/win.
244
245 ===== Git Extensions
246
247 Git Extensions is a native Windows graphical Git client for
248 Windows.  You can download the installer from
249 https://github.com/gitextensions/gitextensions/releases/latest.
250
251 ===== TortoiseGit
252
253 TortoiseGit is a native Windows graphical Git
254 similar to TortoiseSVN. You can download the installer from
255 https://tortoisegit.org/download/.
256
257 ===== Command Line client via Chocolatey
258
259 The command line client can be installed (and updated) using Chocolatey:
260 ----
261 PS$> choco install git
262 ----
263
264 ===== Others
265
266 A list of other GUI interfaces for Git can be found at
267 https://git-scm.com/downloads/guis
268
269
270 [[ChSetupCMake]]
271
272 ==== Install CMake
273
274 Get the CMake installer from https://cmake.org/download/[] and install CMake into
275 the default location.  Ensure the directory containing cmake.exe is added to your path.
276
277 Alternatively you can install CMake using Chocolatey:
278
279 ----
280 PS$>choco install cmake.portable
281 ----
282
283 Chocolatey ensures cmake.exe is on your path.
284
285 [[ChSetupAsciidoctor]]
286
287 ==== Install Asciidoctor, Xsltproc, And DocBook
288
289 http://asciidoctor.org/[Asciidoctor] can be run directly as a Ruby
290 script or via a Java wrapper (AsciidoctorJ). It is used in conjuntion
291 with Xsltproc and DocBook to generate the documenation you're reading
292 and the User’s Guide.
293
294 The easiest way to install them on Windows is via Chocolatey:
295
296 ----
297 PS$>choco install asciidoctorj xsltproc docbook-bundle
298 ----
299
300 Chocolatey ensures that asciidoctorj.exe and xsltproc.exe is on your
301 path and that xsltproc uses the DocBook catalog.
302
303 ==== Install and Prepare Sources
304
305 [TIP]
306 .Make sure everything works
307 ====
308 It’s a good idea to make sure Wireshark compiles and runs at least once before
309 you start hacking the Wireshark sources for your own project. This example uses
310 Git Extensions but any other Git client should work as well.
311 ====
312
313 // XXX -
314
315 *Download sources* Download Wireshark sources into
316 _C:\Development\wireshark_ using either the command line or Git Extensions:
317
318 Using the command line:
319
320 ----
321 >cd C:\Development
322 >git clone https://code.wireshark.org/review/wireshark
323 ----
324
325 Using Git extensions:
326
327 . Open the Git Extensions application. By default Git Extensions
328    will show a validation checklist at startup. If anything needs to
329    be fixed do so now. You can bring up the checklist at any time
330    via menu:Tools[Settings].
331
332 . In the main screen select _Clone repository_. Fill in the following:
333 +
334 Repository to clone: *`https://code.wireshark.org/review/wireshark`*
335 +
336 Destination: Your top-level development directory, e.g. _C:\Development_.
337 +
338 Subdirectory to create: Anything you’d like. Usually _wireshark_.
339 +
340 [TIP]
341 .Check your paths
342 ====
343 Make sure your repository path doesn't contain spaces.
344 ====
345
346 . Click the btn:[Clone] button. Git Extensions should start cloning the
347   Wireshark repository.
348
349 [[ChSetupPrepareCommandCom]]
350
351 ==== Open a Visual Studio Command Prompt
352
353 From the Start Menu (or Start Screen), navigate to the `Visual Studio
354 2015' folder and choose the Command Prompt appropriate for
355 the build you wish to make, e.g. `VS2015 x64 Native Tools Command
356 Prompt' for a 64-bit version or `VS2015 x86 Native Tools Command Prompt'
357 for a 32-bit version. Depending on your version of Windows the Command
358 Prompt list might be directly under `Visual Studio 2015' or you might
359 have to dig for it under multiple folders, e.g. `Visual Studio 2015 ->
360 Visual Studio Tools -> Windows Desktop Command Prompts'.
361
362 [TIP]
363 .Pin the items to the Task Bar
364 ====
365 Pin the Command Prompt you use to the Task Bar for easy access.
366 ====
367
368 All subsequent operations take place in this Command Prompt window.
369
370 . Set environment variables to control the build.
371 +
372 --
373 Set the following environment variables, using paths and values suitable for your installation:
374
375 ----
376 > rem Let CMake determine the library download directory name under
377 > rem WIRESHARK_BASE_DIR or set it explicitly by using WIRESHARK_LIB_DIR.
378 > rem Set *one* of these.
379 > set WIRESHARK_BASE_DIR=C:\Development
380 > rem set WIRESHARK_LIB_DIR=c:\wireshark-win64-libs
381 > rem Set the Qt installation directory
382 > set QT5_BASE_DIR=C:\Qt\5.9.1\msvc2015_64
383 > rem Append a custom string to the package version. Optional.
384 > set WIRESHARK_VERSION_EXTRA=-YourExtraVersionInfo
385 ----
386
387 If your Cygwin installation path is not automatically detected by CMake,
388 you can explicitly specify it with the following environment variable:
389
390 ----
391 > rem Chocolatey installs Cygwin in an odd location
392 > set WIRESHARK_CYGWIN_INSTALL_PATH=C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin
393 ----
394
395 If you are using a version of Visual Studio earlier than VS2012 then you must set an additional env var,
396 e.g. for VS2010 set the following:
397 ----
398 > set VisualStudioVersion=10.0
399 ----
400
401 Setting these variables could be added to a batch file to be run after you open
402 the Visual Studio Tools Command Prompt.
403
404 [TIP]
405 ====
406 Qt 5.9 is a "long term support" branch of Qt5. We recommend using it to
407 compile Wireshark on Windows.
408 ====
409
410 --
411
412 . Create and change to the correct build directory.  CMake is best used in an out-of-tree build configuration
413 where the build is done in a separate directory to the source tree, leaving the source tree in a pristine
414 state.  32 and 64 bit builds require a separate build directory.  Create (if required) and change to the appropriate
415 build directory.
416 +
417 --
418 ----
419 > mkdir C:\Development\wsbuild32
420 > cd C:\Development\wsbuild32
421 ----
422 to create and jump into the build directory.
423
424 The build directory can be deleted at any time and the build files regenerated as detailed in <<ChWin32Generate>>.
425 --
426
427 [[ChWin32Generate]]
428
429 ==== Generate the build files
430
431 CMake is used to process the CMakeLists.txt files in the source tree and produce build files appropriate
432 for your system.
433
434 You can generate Visual Studio solution files to build either from within Visual Studio, or from the command
435 line with MSBuild.  CMake can also generate other build types but they aren't supported.
436
437 The initial generation step is only required the first time a build directory is created.  Subsequent
438 builds will regenerate the build files as required.
439
440 If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again.
441
442 To generate the build files enter the following at the Visual Studio command prompt:
443 ----
444 > cmake -G "Visual Studio 14 2015" ..\wireshark
445 ----
446
447 Adjusting the paths as required to Python and the wireshark source tree.
448 To use a different generator modify the `-G` parameter. `cmake -G` lists
449 all the CMake supported generators, but only Visual Studio is supported
450 for Wireshark builds.
451
452 To build an x64 version, the `-G` parameter must have a Win64 suffix,
453 e.g. `-G "Visual Studio 14 2015 Win64"`:
454
455 ----
456 > cmake -DENABLE_CHM_GUIDES=on -G "Visual Studio 14 2015 Win64" ..\wireshark
457 ----
458
459 The CMake generation process will download the required 3rd party libraries (apart from Qt)
460 as required, then test each library for usability before generating the build files.
461
462 At the end of the CMake generation process the following should be displayed:
463 ----
464 -- Configuring done
465 -- Generating done
466 -- Build files have been written to: C:/Development/wsbuild32
467 ----
468
469 If you get any other output, there is an issue in your envirnment that must be rectified before building.
470 Check the parameters passed to CMake, especially the `-G` option and the path to the Wireshark sources and
471 the environment variables `WIRESHARK_BASE_DIR` and `QT5_BASE_DIR`.
472
473 [[ChWin32Build]]
474
475 ==== Build Wireshark
476
477 Now it’s time to build Wireshark!
478
479 . If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again.
480
481 . Run
482 +
483 --
484 ----
485 > msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln
486 ----
487 to build Wireshark.
488 --
489
490 . Wait for Wireshark to compile. This will take a while, and there will be a lot of text output in the command prompt window
491
492 . Run *`C:\Development\wsbuild32\run\RelWithDebInfo\Wireshark.exe`* and make sure it starts.
493
494 . Open menu:Help[About]. If it shows your "private" program
495 version, e.g.: Version {wireshark-version}-myprotocol123
496 congratulations! You have compiled your own version of Wireshark!
497
498 You may also open the Wireshark solution file (_Wireshark.sln_) in the Visual Studio IDE and build there.
499
500 TIP: If compilation fails for suspicious reasons after you changed some source
501 files try to clean the build files by running *`msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln /t:Clean`*
502 and then building the solution again.
503
504 The build files produced by CMake will regenerate themselves if required by changes in the source tree.
505
506 ==== Debug Environment Setup
507
508 You can debug using the Visual Studio Debugger or WinDbg.  See the section
509 on using the <<ChToolsDebugger, Debugger Tools>>.
510
511 ==== Optional: Create User’s and Developer’s Guide
512
513 Detailed information to build these guides can be found in the file
514 _docbook\README.adoc_ in the Wireshark sources.
515
516 ==== Optional: Create a Wireshark Installer
517
518 Note: You should have successfully built Wireshark
519 before doing the following.
520
521 If you want to build your own
522 _Wireshark-win32-{wireshark-version}-myprotocol123.exe_,
523 you'll need NSIS.
524
525 . NSIS:
526 http://nsis.sourceforge.net[Download] and install NSIS
527 +
528 Note that the 32-bit version of NSIS will work for both 32-bit and
529 64-bit versions of Wireshark. NSIS v3 is recommended and may be required
530 in the future.
531
532 Note: If you do not yet have a copy of vcredist_x86.exe or vcredist_x64.exe in _./wireshark-win**XX**-libs_ (where *_XX_* is 32 or 64) you will need to download the appropriate file and place it in _./wireshark-win**XX**-libs_ before starting this step.
533
534 If building an x86 version using a Visual Studio "Express" edition or an x64 version with any edition, then you must have the appropriate vcredist file for your compiler in the support libraries directory (_vcredist_x86.exe_ in _wireshark-32-libs_ or _vcredist_x64.exe_ in _wireshark-win64-libs_).
535
536 The files can be located in the Visual Studio install directory for non-Express edition builds, or downloaded from Microsoft for Expresss edition builds.
537
538 Note you must use the correct version of vcredist for your compiler, unfortunately they all have the same name (_vcredist_x86.exe_ or _vcredist_x64.exe_).  You can use Windows Explorer and examine the `Properties -> Details' tab for a vcredist file to determine which compiler version the file is for use with.
539
540 . If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again.
541
542 . Run
543 +
544 --
545 ----
546 > msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
547 > msbuild /m /p:Configuration=RelWithDebInfo nsis_package.vcxproj
548 ----
549 to build a Wireshark installer.
550 --
551
552 . Run
553 +
554 --
555 ----
556 > C:\Development\wireshark\packaging\nsis\wireshark-win32-{wireshark-version}-myprotocol123.exe
557 ----
558 to test your new installer. It’s a good idea to test on a different machine
559 than the developer machine. Note that if you've built an x64 version, the installer will be named accordingly.
560 --