osmocom
/
wireshark
11
0
Fork 1
Code Issues Pull Requests Projects Releases Wiki Activity

WSDG: Stop recommending Cygwin. 

Note in the quick setup and tools documentation that we no longer
require or recommend Cygwin.

Change-Id: Ie0eb92c5817ae1d786136035adf8fa3988c8b98d
Reviewed-on: https://code.wireshark.org/review/27244
Reviewed-by: Guy Harris <guy@alum.mit.edu>
This commit is contained in:
Gerald Combs 2018-05-01 17:33:27 -07:00 committed by Anders Broman
parent 46b0099588
commit ef4080bc3a
2 changed files with 158 additions and 235 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc
View File

@ -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
<<ChSrcObtain>>. 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.

315
docbook/wsdg_src/WSDG_chapter_tools.asciidoc
View File

@ -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
<<ChToolsCygwin,Cygwin setup>>.
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
<<ChToolsCygwin,Cygwin setup>>.
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
<<ChToolsCygwin,Cygwin>>. 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
<<ChToolsCygwin,Cygwin>>. 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
<<ChToolsCygwin,Cygwin setup>>
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
<<ChToolsCygwin,Cygwin setup>>.
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: