diff --git a/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc b/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc index c6d9961559..a27cf8bfcf 100644 --- a/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc +++ b/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc @@ -40,21 +40,6 @@ Known traps are: ==== -[[ChSetupChocolatey]] - -==== Recommended: Install Chocolatey - -https://chocolatey.org/[Chocolatey] is a native package manager for Windows. -There are https://chocolatey.org/packages[packages] for most of the software -listed below. Along with traditional Windows packages it supports Cygwin and -the Python Package Index. - -// ...such as: -// - Active Perl and/or StrawberryPerl -// - Devbox-UnZip and/or 7zip and/or peazip -// - Wget -// - Git (a native win32 (MSYS) version) - [[ChSetupMSVC]] ==== Install Microsoft C compiler and SDK @@ -123,6 +108,36 @@ directory, e.g. _C:\Qt\5.9.1\msvc2015_64_ The Qt maintenance tool (_C:\Qt\MaintenanceTool.exe_) can be used to upgrade Qt to newer versions. +[[ChSetupChocolatey]] + +==== Recommended: Install Chocolatey + +https://chocolatey.org/[Chocolatey] is a native package manager for +Windows. There are https://chocolatey.org/packages[packages] for most of +the software listed below. Along with traditional Windows packages it +supports the Python Package Index and Cygwin. + +Chocolatey tends to install packages into its own path (%ChocolateyInstall%). +In most cases this is OK, but in some instances (Python in particular) +this might not be what you want. You can install Chocolatey packages +using the command `choco install`. + +[source,cmd] +---- +> rem Flex and Bison are required. +> choco install winflexbison +> rem Git, CMake, Perl, Python, etc are also required, but can be installed +> rem via their respective installation packages. +> choco install git cmake +> rem Choose one of Strawberry... +> choco install strawberryperl +> rem ...or ActiveState Perl +> choco install activeperl +> rem This will likely install Python in a non-standard location, but +> rem should otherwise work. +> choco install python3 +---- + [[ChSetupCygwin]] ==== Optional: Install Cygwin @@ -132,8 +147,14 @@ On 32-bit Windows, http://www.cygwin.com/setup-x86.exe[download the http://www.cygwin.com/setup-x86_64.exe[download the 64-bit Cygwin installer] and start it. -Over time the Wireshark development toolchain has been migrating away from Cygwin -toward native tools and we hope to eliminate it as a requirement someday. +[NOTE] +.Cygwin is no longer required +==== +In the past the Wireshark development toolchain depended on Cygwin, but +it it no longer required. Although you can often use the Cygwin version +of a particular tool for Wireshark development that's not always the +case. +==== At the "Select Packages" page, you'll need to select some additional packages which are not installed by default. @@ -141,19 +162,17 @@ Navigate to the required Category/Package row and, if the package has a "Skip" item in the "New" column, click on the "Skip" item so it shows a version number for: -* Devel/bison (or install Win flex-bison - see Chocolatey below) +* Devel/bison (or install Win flex-bison -- see Chocolatey above) -* Devel/flex (or install Win flex-bison - see Chocolatey below) +* Devel/flex (or install Win flex-bison -- see Chocolatey above) -* Devel/git (recommended - see discussion about using Git below) +* Devel/git (recommended, but it's also available via Chocolatey -- see the Git discussion below) * Interpreters/perl * Utils/patch (only if needed) (may be Devel/patch instead) -* Web/wget (not needed if using CMake) - -* Text/docbook-xml45 +* Text/docbook-xml45 (only needed if you're building the documenation) // Also need: bash/sh, sed @@ -184,13 +203,6 @@ You can directly download packages via `cyg-get` PS$>cyg-get docbook-xml45 [...] ---- -You can use Chocolatey’s Win flex-bison packages rather than the Cygwin -Bison and Flex package: - ----- -PS$>choco install winflexbison ----- - [[ChSetupPython]] ==== Install Python @@ -223,7 +235,7 @@ Chocolatey installs Python in _C:\tools\python3_ and _C:\tools\python2_ by defau Please note that the following is not required to build Wireshark but can be quite helpful when working with the sources. -Working with the Git source repositories is highly recommended, see +Working with the Git source repositories is highly recommended, as described in <>. It is much easier to update a personal source tree (local repository) with Git rather than downloading a zip file and merging new sources into a personal source tree by hand. It also makes first-time setup easy and enables the @@ -277,7 +289,7 @@ the default location. Ensure the directory containing cmake.exe is added to you Alternatively you can install CMake using Chocolatey: ---- -PS$>choco install cmake.portable +PS$>choco install cmake ---- Chocolatey ensures cmake.exe is on your path. @@ -287,7 +299,7 @@ Chocolatey ensures cmake.exe is on your path. ==== Install Asciidoctor, Xsltproc, And DocBook http://asciidoctor.org/[Asciidoctor] can be run directly as a Ruby -script or via a Java wrapper (AsciidoctorJ). It is used in conjuntion +script or via a Java wrapper (AsciidoctorJ). It is used in conjunction with Xsltproc and DocBook to generate the documenation you're reading and the User’s Guide. diff --git a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc index e7c269733c..b17f950ebd 100644 --- a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc +++ b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc @@ -8,23 +8,21 @@ === Introduction -This chapter will provide you with information about the -various tools needed for Wireshark development. +This chapter will provide you with information about the various tools +needed for Wireshark development. None of the tools mentioned in this +chapter are needed to run Wireshark. They are only needed to build it. -None of the tools mentioned in this chapter are needed to -run Wireshark; they are only needed to build it. +Most of these tools have their roots on UNIX or UNIX-like platforms such +as Linux, but Windows ports are also available. Therefore the tools are +available in different "flavours": -Most of these tools have their roots on UNIX like -platforms, but Windows ports are also available. Therefore the -tools are available in different "flavours": - -* UNIX (or Windows Cygwin): the tools should be commonly available on the - supported UNIX platforms, and for Windows platforms by using the Cygwin UNIX - emulation -* Windows native: some tools are available as native Windows tools, no special - emulation is required. Many of these tools can be installed (and updated) - using http://chocolatey.org[Chocolatey], a Windows package manager similar - to the Linux package managers apt-get or yum. +* UNIX: The tools should be commonly available on the supported UNIX + platforms and for Windows platforms by using an emulation layer such + as Cygwin. +* Windows native: Some tools are available as native Windows tools, no + special emulation is required. Many of these tools can be installed + (and updated) using http://chocolatey.org[Chocolatey], a Windows + package manager similar to the Linux package managers apt-get or yum. [WARNING] .Follow the directions @@ -64,106 +62,36 @@ or a Powershell prompt: PS:\>iex ((new-object net.webclient).DownloadString(_https://chocolatey.org/install.ps1_)) ---- -Chocolatey sometimes installs packages in unexpected locations. Cygwin is a notable -example -- recent versions of the Cygwin package are installed in _C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin_ instead of Cygwin’s default location -(_C:\cygwin_ or _C:\cygwin64_). +Chocolatey sometimes installs packages in unexpected locations. Python +is a notable example. While it's typically installed in a top-level +directory, e.g. _C:\Python27_ or in %PROGRAMFILES%, e.g. _C:\Program +Files\Python36_, Chocolatey tends to install it under +_C:\ProgramData\chocolatey_ or _C:\Tools_. If you want to avoid this +behavior you'll probabaly want to install Python using the packages from +python.org. [[ChToolsCygwin]] === Windows: Cygwin -Cygwin provides a lot of UNIX based tools on the Windows platform. It uses a UNIX -emulation layer which might be a bit slower compared to the native Windows tools, -but at an acceptable level. The installation and update is pretty easy and done -through a single utility, _setup-x86.exe_ for 32-bit Windows and -_setup-x86_64.exe_ for 64-bit Windows. +Cygwin provides a lot of UNIX based tools on the Windows platform. It +uses a UNIX emulation layer which might be a bit slower compared to the +native Windows tools, but at an acceptable level. The installation and +update is pretty easy and done through a single utility, _setup-x86.exe_ +for 32-bit Windows and _setup-x86_64.exe_ for 64-bit Windows. However, +it can also be problematic. Cygwin utilities have a non-standard view of +the filesystem, and sometimes things don't work as expected. For +example, many files in _/usr/bin_ are symlinks which can't be run +directly from Windows. -Over time the Wireshark development toolchain has been migrating away from Cygwin -toward native tools and we hope to eliminate it as a requirement someday. - -Although Cygwin consists of several separate packages, the installation -and update is done through a single utility, _setup-x86.exe_ or -_setup-x86_64.exe_, which acts similarly to other web based installers. -You can install Cygwin and its packages using Chocolatey, but this is not -recommended due to Chocolatey’s default installation location, described -in the previous section. - -==== Installing Cygwin using the Cygwin installer - -You will find _setup-x86.exe_, for 32-bit systems, and -_setup-x86_64.exe_, for 64-bit systems, at -http://www.cygwin.com/install.html[]. Click on the link for the -appropriate setup utility to download it. After the download completes, -run it. - -All tools will be installed into one base folder. The default is -_C:\cygwin_ for the 32-bit installer and _C:\cygwin64_ for the 64-bit -installer. - -The setup utility will ask you for some settings. The defaults -should usually work well, at least initially. - -If, at the "Choose A Download Source" page, you use the default "Install -from Internet" setting, you will need to choose a download site at the -"Choose A Download Site" page. See the list of mirror sites at -http://cygwin.com/mirrors.html[] to choose a download site appropriate -to your location. - -At the "Select Packages" page, you'll need to select some additional -packages, which are not installed by default. Navigate to the required -Category/Package row and click on the "Skip" item in the "New" column so -it shows a version number for the required package. - -After clicking the Next button several times the setup -will then download and install the selected packages (this may -take a while, depending on the package size). - -Under menu:Start[Programs,Cygwin,Cygwin Bash Shell] you should now be able to start -a new Cygwin bash shell, which is similar to the standard Windows Command Prompt -(cmd.exe) but much more powerful. - -[[ChToolsCygwinPackages]] - -==== Add/Update/Remove Cygwin Packages - -If you want to add, update, or remove packages later you can do so by -running the setup utility again. At the "Select Packages" page, the -entry in the "New" column will control what is done (or not) with the -package. If a new version of a package is available, the new version -number will be displayed, so it will be automatically updated. You can -change the current setting by simply clicking at it, it will change -between: - -* _A specific version number._ This specific package version will be installed. - -* _Skip._ Not installed, no changes. - -* _Keep._ Already installed, no changes. - -* _Uninstall._ Uninstall this package. - -* _Reinstall._ Reinstall this package. - -==== Installing Cygwin using Chocolatey - -Chocolatey supports Cygwin as an external package source. -To install Cygwin itself run - -[source,cmd] ----- -PS$>choco install cygwin -# You might also need to install cyg-get: -PS$>choco install cyg-get ----- - -Chocolatey installs Cygwin in _C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin_ by default. - -One or more Cygwin packages can be installed using `cyg-get`: - -[source,cmd] ----- -PS$>cyg-get sed asciidoc ----- +[NOTE] +.Cygwin is no longer required +==== +In the past the Wireshark development toolchain depended on Cygwin, but +it it no longer required. Although you can often use the Cygwin version +of a particular tool for Wireshark development that's not always the +case. +==== [[ChToolsCMake]] @@ -213,7 +141,7 @@ optional libraries have xxx_INCLUDE_DIR and xxx_LIB flags that let you control their discovery. --DPYTHON_EXECUTABLE=c:/Python27/python:: Force the Python path. Useful on Windows since Cygwin’s /usrbin/python is a symlink. +-DPYTHON_EXECUTABLE=c:/Python36/python:: Force the Python path. Useful on Windows since Cygwin’s _/usr/bin/python_ is a symlink. -DENABLE_APPLICATION_BUNDLE=OFF:: Disable building an application bundle (Wireshark.app) on macOS @@ -774,14 +702,11 @@ The bash shell is needed to run several shell scripts. [[ChToolsGNUBash]] -==== UNIX and Cygwin: GNU bash +==== UNIX: GNU Bash -The bash shell is available for most of the UNIX-like -platforms and as the bash package from the -<>. - -If bash isn't already installed or -available as a package for your platform, you can get it at +Bash (the GNU Bourne-Again SHell) is available for most UNIX and +UNIX-like platforms. If it isn't already installed or available as a +package for your platform, you can get it at http://www.gnu.org/software/bash/bash.html[]. After correct installation, typing at the bash command line prompt: @@ -794,13 +719,11 @@ $ bash --version should result in something like: ---- -GNU bash, version 3.1.17(6)-release (i686-pc-cygwin) -Copyright (C) 2005 Free Software Foundation, Inc. +GNU bash, version 4.4.12(1)-release (x86_64-pc-linux-gnu) +Copyright (C) 2016 Free Software Foundation, Inc. ---- -However, the version string may vary. - -[[ChToolsWindowsBash]] +Your version string will likely vary. [[ChToolsPython]] @@ -808,9 +731,8 @@ However, the version string may vary. http://python.org/[Python] is an interpreted programming language. It is used to generate some source files, documenation, and other tasks. -Python 2.5 or later (including Python 3) should work fine and Python 3.5 and -2.7 are recommended. If you're building documentation you must have Python -2 installed since AsciiDoc doesn't support Python 3. +Python 2.5 or later (including Python 3) should work fine and Python 3 is +recommended. It may be required in the future. Python is either included or available as a package on most UNIX-like platforms. Windows packages and source are available at http://python.org/download/[]. @@ -872,15 +794,11 @@ and above should work fine. [[ChToolsUnixPerl]] -==== UNIX and Cygwin: Perl +==== UNIX: Perl -Perl is available for most of the UNIX-like platforms -and as the perl package from the -<>. - -If perl isn't already installed or available -as a package for your platform, you can get it at -http://www.perl.com/[]. +Perl is available for most UNIX and UNIX-like platforms. If perl isn't +already installed or available as a package for your platform, you can +get it at http://www.perl.com/[]. After correct installation, typing at the bash command line prompt: @@ -893,62 +811,62 @@ $ perl --version should result in something like: ---- -This is perl, v5.8.7 built for cygwin-thread-multi-64int -(with 1 registered patch, see perl -V for more detail) +This is perl 5, version 26, subversion 0 (v5.26.0) built for x86_64-linux-gnu-thread-multi +(with 62 registered patches, see perl -V for more detail) -Copyright 1987-2005, Larry Wall +Copyright 1987-2017, Larry Wall Perl may be copied only under the terms of either the Artistic License or the GNU General Public License, which may be found in the Perl 5 source kit. Complete documentation for Perl, including FAQ lists, should be found on -this system using *`man perl'* or *`perldoc perl'*. If you have access to the -Internet, point your browser at http://www.perl.com/, the Perl Home Page. +this system using "man perl" or "perldoc perl". If you have access to the +Internet, point your browser at http://www.perl.org/, the Perl Home Page. ---- However, the version string may vary. -//[[ChToolsWindowsPerl]] -// -//==== Windows native: Perl -// -//A native Windows Perl package can be obtained from -//http://www.ActiveState.com[Active State] or http://strawberryperl.com/[Strawberry Perl]. The installation -//should be straightforward. -// -//You may also use Chocolatey to install either package: -// -//---- -//PS:\> choco install ActivePerl -//---- -// -//or -// -//---- -//PS:\> choco install StrawberryPerl -//---- -// -//After correct installation, typing at the command -//line prompt (cmd.exe): -// -//---- -//> perl -v -//---- -// -//should result in something like: -// -//---- -//This is perl, v5.8.0 built for MSWin32-x86-multi-thread -//(with 1 registered patch, see perl -V for more detail) -// -//Copyright 1987-2002, Larry Wall -// -//Binary build 805 provided by ActiveState Corp. http://www.ActiveState.com -//Built 18:08:02 Feb 4 2003 -//... -//---- -// -//However, the version string may vary. +[[ChToolsWindowsPerl]] + +==== Windows Native: Perl + +A native Windows Perl package can be obtained from +http://www.ActiveState.com[Active State] or http://strawberryperl.com/[Strawberry Perl]. The installation +should be straightforward. + +You may also use Chocolatey to install either package: + +---- +PS:\> choco install ActivePerl +---- + +or + +---- +PS:\> choco install StrawberryPerl +---- + +After correct installation, typing at the command +line prompt (cmd.exe): + +---- +> perl -v +---- + +should result in something like: + +---- +This is perl, v5.8.0 built for MSWin32-x86-multi-thread +(with 1 registered patch, see perl -V for more detail) + +Copyright 1987-2002, Larry Wall + +Binary build 805 provided by ActiveState Corp. http://www.ActiveState.com +Built 18:08:02 Feb 4 2003 +... +---- + +However, the version string may vary. // Sed is no longer required. //[[ChToolsSed]] @@ -961,10 +879,10 @@ Bison is a parser generator used for some of Wireshark’s file format support. [[ChToolsUnixBison]] -==== UNIX or Cygwin: bison +==== UNIX: Bison -Bison is available for most UNIX-like platforms and as the bison package from -<>. See the next section for native Windows options. +Bison is available for most UNIX and UNIX-like platforms. See the next +section for native Windows options. If GNU Bison isn't already installed or available as a package for your platform you can get it at: http://www.gnu.org/software/bison/bison.html[]. @@ -998,8 +916,8 @@ https://chocolatey.org/[Chocolatey] package. Note that the executable is named _win_bison_. Native packages are available from other sources such as -http://gnuwin32.sourceforge.net/packages/bison.htm[GnuWin]. They aren't -officially supported but _should_ work. +http://gnuwin32.sourceforge.net/packages/bison.htm[GnuWin] and Cygwin. +They aren't officially supported but _should_ work. [[ChToolsFlex]] @@ -1010,10 +928,10 @@ file formats, and other features. [[ChToolsUnixFlex]] -==== UNIX or Cygwin: flex +==== UNIX: flex -Flex is available for most UNIX-like platforms and as the flex package from -<>. See the next section for native Windows options. +Flex is available for most UNIX and UNIX-like platforms. See the next +section for native Windows options. If GNU flex isn't already installed or available as a package for your platform you can get it at http://www.gnu.org/software/flex/[]. @@ -1068,14 +986,11 @@ client. [[ChToolsUnixGit]] -==== UNIX or Cygwin: git +==== UNIX: git -Git is available for most of the UNIX-like platforms -and as the Git package from the -<> - -If Git isn't already installed or available as a package for your platform, you -can get it at: http://git-scm.com/[]. +Git is available for most UNIX and UNIX-like platforms. If Git isn't +already installed or available as a package for your platform, you can +get it at: http://git-scm.com/[]. After correct installation, typing at the bash command line prompt: @@ -1161,15 +1076,11 @@ tool. [[ChToolsUnixPatch]] -==== UNIX and Cygwin: patch +==== UNIX: patch -Patch is available for most of the UNIX-like platforms -and as the patch package from the -<>. - -If GNU patch isn't already installed or -available as a package for your platform, you can get it at -http://www.gnu.org/software/patch/patch.html[]. +Patch is available for most UNIX and UNIX-like platforms. If GNU patch +isn't already installed or available as a package for your platform, you +can get it at http://www.gnu.org/software/patch/patch.html[]. After correct installation, typing at the bash command line prompt: