osmith
/
wireshark
forked from osmocom/wireshark
1
0
Fork 0
Code Pull Requests Releases Wiki Activity

Update some documentation to prefer CMake. 

Change-Id: I8140edaee152ce1e9978d8df8a0f0e3dd077322e
Reviewed-on: https://code.wireshark.org/review/26490
Reviewed-by: Anders Broman <a.broman58@gmail.com>
This commit is contained in:
Gerald Combs 2018-03-15 17:19:06 -07:00 committed by Anders Broman
parent 1690e6e75a
commit 45a50ef41e
3 changed files with 120 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
INSTALL
View File

@ -17,31 +17,31 @@ README.windows for those instructions.
0. This is software. Beware.
1. If you wish to build Wireshark, make sure you have GTK+ and GLib
installed. Try running 'pkg-config glib-2.0 --modversion' to see if
you have GLib 2.x installed. Then try running
'pkg-config gtk+-3.0 --modversion' to see if you
have GTK+ 3.x installed and, if that fails, try running
'pkg-config gtk+-2.0 --modversion' to see if you have GTK+ 2.x installed.
Wireshark needs version 3.0.0 or above of gtk+-3.0 or 2.12.0 or above of
gtk+-2.0 and version 2.16.0 or above of glib-2.0. If you need to install
or re-install GTK+ or GLIB, you can find the packages at:
1. If you wish to build Wireshark, make sure you have the Qt and GLib
development packages installed. Try running
'pkg-config glib-2.0 --modversion' to see if you have GLib 2.x
installed. Then try running 'pkg-config Qt5Widgets --modversion'
to see if you have Qt installed. Wireshark needs version 4.8 or above
of Qt, although 5.2 and above are strongly recommended. It needs
version 2.22.0 or above of glib-2.0. If you need to install or
re-install GLIB, you can find the packages at:
http://www.gtk.org
https://www.gtk.org
If you installed GTK+ from a binary package, you may have to
install a "development" package; there may be separate "user's"
and "developer's" packages, with the former not including
header files and the like. For example, Red Hat users will
need to install a "gtk-devel" .rpm.
You can find Qt at:
https://www.qt.io/download
If you installed Qt or GLib from binary packages, you may have to
install corresponding "development" packages; there may be separate
"user's" and "developer's" packages, with the former not including
header files and the like. For example, Red Hat users will need to
install a "glib2-devel" .rpm.
Note also that Wireshark configuration defaults to using GTK+ 3.x;
you need to configure with --disable-gtk3 to use GTK+ 2.x.
2. If you wish to build TShark, the line-mode version of Wireshark,
make sure you have GLIB installed. See note #1 above for instructions
on checking if you have GLIB installed. You can download GLIB from
the same site as GTK.
make sure you have GLib installed. See note #1 above for instructions
on checking if you have GLib installed.
3. If you want to capture packets, make sure you have libpcap
installed. The latest "official" version can be found at
@ -62,122 +62,98 @@ README.windows for those instructions.
5. Building Wireshark requires Python.
6. Run './configure' in the Wireshark distribution directory.
Running './configure --help' displays a complete list of options.
The file 'INSTALL.configure' contains general instructions for
using 'configure' and 'make'. Some of the Wireshark non-generic
configure options are as follows:
6. Create a build directory separate from the source directory. It can
be anywhere, but you might run into issues if the path contains
spaces.
--disable-usr-local
By default 'configure' will look in /usr/local/{include,lib} for
additional header files and libraries. Using this switch keeps
'configure' from looking there
7. Run 'cmake <options> <path/to/the/wireshark/sources>' in your build
directory. Running 'cmake -L' displays a complete list of options.
The "Tool Reference" section of Developer's Guide contains general
instructions for using CMake. Some of the Wireshark-specific options
are as follows:
--disable-wireshark
By default 'configure' tries to find the GTK+ libraries so Wireshark,
the GUI packet analyzer, can be built. You can disable the build of
the GUI version of Wireshark with this switch.
-G Ninja
CMake supports many different build systems, including UNIX
Make, MSBuild, and Ninja. UNIX Make is the default, but Ninja
tends to be faster.
--without-gtk3
Don't try to build a Gtk+ 3.x-based Wireshark. If given in
conjunction with --disable-gtk2 then the Gtk+ GUI is disabled (and
only the Qt GUI is built).
-DBUILD_wireshark=OFF
By default CMake tries to find the Qt libraries so Wireshark,
the GUI packet analyzer, can be built. You can disable the
build of the GUI version of Wireshark with this switch.
--without-gtk2
Don't try to build a Gtk+ 2.x-based Wireshark. If given in
conjunction with --disable-gtk3 then the Gtk+ GUI is disabled (and
only the Qt GUI is built).
--without-qt
Don't try to build a Qt-based Wireshark.
--disable-tshark
-DBUILD_tshark=OFF
By default the line-mode packet analyzer, TShark, is built.
Use this switch to avoid building it.
--disable-editcap
-DBUILD_editcap=OFF
By default the capture-file editing program is built.
Use this switch to avoid building it.
--disable-capinfos
-DBUILD_capinfos=OFF
By default the capture-file statistics reporting pogram
is built. Use this switch to avoid building it.
--disable-captype
-DBUILD_captype=OFF
By default the capture-type reporting pogram is built. Use this
switch to avoid building it.
--disable-mergecap
-DBUILD_mergecap=OFF
By default the capture-file merging program is built.
Use this switch to avoid building it.
--disable-reordercap
-DBUILD_reordercap=OFF
By default the capture-file reordering program is built.
Use this switch to avoid building it.
--disable-text2pcap
-DBUILD_text2pcap=OFF
By default the hex-dump-to-capture file conversion program
is built. Use this switch to avoid building it.
--disable-dftest
-DBUILD_dftest=OFF
By default the display-filter-compiler test program is built.
Use this switch to avoid building it.
--disable-randpkt
-DBUILD_randpkt=OFF
By default the program which creates random packet-capture files
is built. Use this switch to avoid building it.
--disable-dumpcap
-DBUILD_dumpcap=OFF
By default the network traffic capture program is built.
Use this switch to avoid building it.
--disable-rawshark
-DBUILD_rawshark=OFF
By default the program used to dump and analyze raw libpcap data
is built. Use this switch to avoid building it.
--disable-ipv6
If 'configure' finds support for IPv6 name resolution on
your system, the packet analyzers will make use of it.
To avoid using IPv6 name resolution if you have the support for it,
use this switch.
--enable-setuid-install
Wireshark and TShark rely on dumpcap for packet capture. Setting this
flag installs dumpcap with setuid root permissions, which lets any user
on the system capture live traffic. If this is not desired, you can
restrict dumpcap's permissions so that only a single user or group can
run it. This can be used in conjunction with --with-libcap described
below.
-DDUMPCAP_INSTALL_OPTION=suid
-DDUMPCAP_INSTALL_OPTION=capabilities
Wireshark and TShark rely on dumpcap for packet capture. Setting
this flag to "suid" installs dumpcap with setuid root
permissions, which lets any user on the system capture live
traffic. If this is not desired, you can restrict dumpcap's
permissions so that only a single user or group can run it and
set the "capabilities" flag.
Running Wireshark or TShark as root is not recommended.
--without-libcap
By default, if 'configure' finds libcap (the POSIX capabilities
-DENABLE_CAP=OFF
By default, if 'cmake' finds libcap (the POSIX capabilities
library) dumpcap will be built so that if it is installed setuid
root, it will attempt to retain CAP_NET_RAW and CAP_NET_ADMIN
before dropping root privileges. Use this option to disable this
behavior.
--with-libcap=DIR
Use this option to tell 'configure' where libcap is installed,
if it is installed in a non-standard location. Note that libcap
(the POSIX capabilities library, sans "p") and libpcap (the
packet capture library, avec "p") are two very different things.
--without-pcap
-DENABLE_PCAP=OFF
If you choose to build a packet analyzer that can analyze
capture files but cannot capture packets on its own, but you
*do* have libpcap installed, or if you are trying to build
Wireshark on a system that doesn't have libpcap installed (in
which case you have no choice but to build a version that can
analyze capture files but cannot capture packets on its own),
use --without-pcap to avoid using libpcap.
use -DENABLE_PCAP=OFF to avoid using libpcap.
--with-pcap=DIR
Use this to tell Wireshark where you have libpcap installed, if
it is installed in a non-standard location.
--without-zlib
-DENABLE_ZLIB=OFF
By default, if 'configure' finds zlib (a.k.a, libz), the
wiretap library will be built so that it can read compressed
capture files. If you have zlib but do not wish to build
@ -185,43 +161,29 @@ README.windows for those instructions.
the capture-file utilities that come in this package, use
this switch.
--with-zlib=DIR
Use this to tell Wireshark where you have zlib installed, if it
is installed in a non-standard location.
--without-plugins
-DENABLE_PLUGINS=OFF
By default, if your system can support run-time loadable modules,
the packet analyzers are build with support for plugins.
Use this switch to build packet analyzers without plugin support.
--with-plugins=DIR
By default, plugins are installed in
${LIBDIR}/wireshark/plugins/${VERSION}
${LIBDIR} can be set with --libdir, or defaults to ${EPREFIX/lib}
${EPREFIX} can be set with --exec-prefix, or defaults to ${PREFIX}
${VERSION} is the Wireshark version.
Use this switch to change the location where plugins
are installed.
7. After running './configure', you will see a summary of some
8. After running 'cmake', you will see a summary of some
of the options you chose. Ensure that the summary reflects
what you want. If it doesn't, re-run './configure' with new options.
what you want. If it doesn't, re-run 'cmake' with new options.
8. Run 'make'. Hopefully, you won't run into any problems.
9. Run 'make', or 'ninja' if you chose to create Ninja build files.
Hopefully, you won't run into any problems.
9. Run './wireshark' or './tshark' or ./dumpcap, and make sure things are
10. Run './wireshark' or './tshark' or ./dumpcap, and make sure things are
working. You must have root privileges in order to capture live data.
10./a. Run 'make install'. If you're running a system that supports
11./a. Run 'make install'. If you're running a system that supports
the RPM packaging systems you can run
make rpm-package
to make an installable package for your system.
10/b. If you 're running a system that supports APT (Debian/Ubuntu/etc.)
11/b. If you 're running a system that supports APT (Debian/Ubuntu/etc.)
run
dpkg-buildpackage -us -uc -rfakeroot

28
doc/README.packaging
View File

@ -13,7 +13,7 @@ The canonical location for every Wireshark source release is
https://www.wireshark.org/download/src/all-versions/, e.g.
https://www.wireshark.org/download/src/all-versions/wireshark-2.4.5.tar.xz
https://www.wireshark.org/download/src/all-versions/wireshark-2.6.5.tar.xz
If your packaging system downloads a copy of the Wireshark sources, use
this location. Don't use https://www.wireshark.org/download/src.
@ -32,10 +32,7 @@ newer. Make sure your package complies with this license.
3. Privileges.
In versions up to and including 0.99.6, it was necessary to run
Wireshark with elevated privileges in order to be able to capture
traffic. With version 0.99.7, all function calls that require elevated
privileges have been moved out of the GUI to dumpcap.
All function calls that require elevated privileges are in dumpcap.
WIRESHARK CONTAINS OVER TWO MILLION LINES OF SOURCE CODE. DO NOT RUN
THEM AS ROOT.
@ -46,25 +43,20 @@ There are several configure-time options on non-Windows systems that
affect the privileges a normal user needs to capture traffic and list
interfaces:
--enable-setcap-install Install dumpcap with cap_net_admin and
cap_net_raw capabilities. Linux only.
-DDUMPCAP_INSTALL_OPTION=capabilities
Install dumpcap with cap_net_admin and cap_net_raw capabilities.
Linux only.
--enable-setuid-install Install dumpcap setuid root.
--with-libcap If running as root, try to grab
CAP_NET_ADMIN and CAP_NET_RAW, then drop
privileges. Linux only.
--with-dumpcap-group=... Restricts dumpcap execution to the
specified group.
-DDUMPCAP_INSTALL_OPTION=suid
Install dumpcap setuid root.
These are necessary for non-root users to be able to capture on most
systems, e.g. on Linux or FreeBSD if the user doesn't have permissions
to access /dev/bpf*. Setcap installation is preferred over setuid on
Linux. If "--enable-setcap-install" is used it will override any setuid
settings.
Linux. If "-DDUMPCAP_INSTALL_OPTION=capabilities" is used it will
override any setuid settings.
The "--with-libcap" option is only useful when dumpcap is installed
The "-DENABLE_CAP" option is only useful when dumpcap is installed
setuid. If it is enabled dumpcap will try to drop any setuid privileges
it may have while retaining the CAP_NET_ADMIN and CAP_NET_RAW
capabilities. It is enabled by default, if the Linux capabilities

82
docbook/wsdg_src/WSDG_chapter_tools.asciidoc
View File

@ -161,48 +161,17 @@ One or more Cygwin packages can be installed using `cyg-get`:
PS$>cyg-get sed asciidoc
----
[[ChToolsGNUChain]]
=== GNU compiler toolchain (UNIX only)
[[ChToolsGCC]]
==== gcc (GNU compiler collection)
The GCC C compiler is available for most of the
UNIX-like platforms.
If GCC isn't already installed or available
as a package for your platform, you can get it at:
http://gcc.gnu.org/[].
After correct installation, typing at the
bash command line prompt:
----
$ gcc --version
----
should result in something like
----
gcc (Ubuntu 4.9.1-16ubuntu6) 4.9.1
Copyright (C) 2014 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
----
Your version string may vary, of course.
[[ChToolsCMake]]
Wireshark’s build environment can be configured using CMake on Windows
and either CMake or Autotools on Linux, macOS, and UNIX. CMake is designed
to support out of tree builds. So much so, that in tree builds do not work
properly in all cases. Along with being cross-platform, CMake supports
many build tools and environments including traditional make, Ninja, and
MSBuild. Our Buildbot runs CMake steps on Ubuntu, Win32, Win64, and macOS.
In particular, the macOS and Windows packages are built using CMake.
=== CMake
Wireshark’s build environment can be configured using CMake on Windows,
Linux, macOS, and UNIX. CMake is designed to support out of tree builds.
So much so, that in tree builds do not work properly in all cases. Along
with being cross-platform, CMake supports many build tools and
environments including traditional make, Ninja, and MSBuild. Our
Buildbot runs CMake steps on Ubuntu, Win32, Win64, and macOS. In
particular, the macOS and Windows packages are built using CMake.
Building with CMake typically includes creating a build directory and
specifying a *generator*, aka a build tool. For example, to build
@ -267,6 +236,39 @@ Frequently Asked Questions: http://www.cmake.org/Wiki/CMake_FAQ
// 2017-08-04 dead
//Additional cmake modules: http://code.google.com/p/cmake-modules/
[[ChToolsGNUChain]]
=== GNU compiler toolchain (UNIX only)
[[ChToolsGCC]]
==== gcc (GNU compiler collection)
The GCC C compiler is available for most of the
UNIX-like platforms.
If GCC isn't already installed or available
as a package for your platform, you can get it at:
http://gcc.gnu.org/[].
After correct installation, typing at the
bash command line prompt:
----
$ gcc --version
----
should result in something like
----
gcc (Ubuntu 4.9.1-16ubuntu6) 4.9.1
Copyright (C) 2014 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
----
Your version string may vary, of course.
[[ChToolsGDB]]
==== gdb (GNU project debugger)