diff options
Diffstat (limited to 'doc/wsdg_src/wsdg_libraries.adoc')
| -rw-r--r-- | doc/wsdg_src/wsdg_libraries.adoc | 353 |
1 files changed, 353 insertions, 0 deletions
diff --git a/doc/wsdg_src/wsdg_libraries.adoc b/doc/wsdg_src/wsdg_libraries.adoc new file mode 100644 index 00000000..28bc52d5 --- /dev/null +++ b/doc/wsdg_src/wsdg_libraries.adoc @@ -0,0 +1,353 @@ +// WSDG Chapter Libraries + +[#ChapterLibraries] + +== Library Reference + +[#ChLibIntro] + +=== Introduction + +Like most applications, Wireshark depends on libraries provided by your operating system and by third parties, including the C runtime library, GLib, libpcap, and Qt. +While running Wireshark only requires the libraries themselves, building it requires header files, import libraries, and related resources. + +Binary libraries are available in different formats and are specific to the target operating system, platform, and compiler. +They can be compiled by hand, but are most often installed as pre-built packages. + +On most Linux systems, the required binary and development libraries can be installed using your package manager. +We provide setup scripts that will install the required packages for most distributions. +See <<ChSetupUNIXBuildEnvironmentSetup>> for details. + +On macOS, you can install pre-built packages using a third party package manager such as Homebrew or MacPorts. +As with Linux, we provide `tools/macos-setup-brew.sh`, which will install the required Homebrew packages. +We also provide `tools/macos-setup.sh`, which will download, build, and install required packages. +Note that `tools/macos-setup.sh` installs into _/usr/local_ by default; you can change this with the `-p` flag. + +Windows doesn't have a good library package manager at the present time, so we provide our own pre-built libraries. +They can be installed using `tools/win-setup.ps1` and are automatically installed when you run CMake. +With the exception of Qt, all libraries required to build Wireshark on Windows are available for download at +https://dev-libs.wireshark.org/windows/[]. +See <<ChLibsSetup>> for details. + +[#ChLibsSetup] + +=== Windows Automated Library Download + +The required libraries (apart from Qt) are automatically downloaded as part of +the CMake generation step, and subsequently as required when libraries are updated. + +The libraries are downloaded into the directory indicated by the environment +variable WIRESHARK_BASE_DIR, this must be set appropriately for your environment. +The libraries are downloaded and extracted into WIRESHARK_BASE_DIR\wireshark-x64-libs or WIRESHARK_BASE_DIR\wireshark-arm64-libs depending on your target platform. + +You may also set the library directory to a custom value with the environment variable WIRESHARK_LIB_DIR, but you may run into problems if you switch between major versions or target platforms. + +[#ChLibsQt] + +=== Qt + +The Qt library is used to build the UI for Wireshark and is used to provide a platform independent UI. +Wireshark can be built with Qt 5.12 or later, but looks for Qt 6 as the default version. + +To enable builds with Qt 5.x, the command-line option `-DUSE_qt6=OFF` has to be set for cmake. + +For more information on the Qt libraries, see <<ChUIQt>>. + +[#ChLibsUnixQt] + +[discrete] +==== Unix + +Most Linux distributions provide Qt and its development libraries as standard packages. +The required libraries and tools will likely be split across several packages. For example, +building on Ubuntu requires _qt6-tools-dev_, _qt6-tools-dev-tools_, _libqt6svg6-dev_, +_qt6-multimedia-dev_, and possibly others. + +The Qt Project provides an installation tool for macOS, similar to Windows. +It is available at https://www.qt.io/download-open-source/#section-2[]. + +[#ChLibsWindowsQt] + +[discrete] +==== Windows + +Qt 6 must be installed manually from the Qt installers page https://www.qt.io/download-open-source/#section-2[] using the version of Qt appropriate for your compiler. + +The CMake variable CMAKE_PREFIX_PATH (see `https://doc.qt.io/qt-6/cmake-get-started.html`) should be set to your Qt installation directory, e.g. _C:\Qt{backslash}{qt6-lts-version}\msvc2019_64_. +Alternatively you can also use the environment variable WIRESHARK_QT6_PREFIX_PATH. + +[#ChLibsGLib] + +=== GLib And Supporting Libraries + +The GLib library is used as a basic platform abstraction library and can +be used in both CLI and GUI applications. For a detailed description +about GLib see <<ChCodeGLib>>. + +GLib depends on GNU libiconv, GNU gettext, and other libraries. You will +typically not come into contact with these while doing Wireshark +development. Wireshark's build system check for and require both GLib +and its dependencies. + +[#ChLibsUnixGLib] + +[discrete] +==== Unix + +The GLib library is available for most Linux distributions and UNIX +flavors. If it isn't already installed and isn't available as a package +for your platform, you can get it at https://wiki.gnome.org/Projects/GLib[]. + +[#ChLibsWindowsGLib] + +[discrete] +==== Windows + +GLib is part of our vcpkg-export bundles and is available at +https://dev-libs.wireshark.org/windows/packages/[]. + +[#ChLibsCares] + +=== c-ares + +C-Ares is used for asynchronous DNS resolution and lets us resolve names with a minimal performance impact. + +[#ChLibsUnixCares] + +[discrete] +==== Unix + +If this library isn't already installed or available as a package for your +platform, you can get it at https://c-ares.org/[]. + +[#ChLibsWindowsCares] + +[discrete] +==== Windows + +C-Ares is built using {vcpkg-main-url}[vcpkg] and is available at +https://dev-libs.wireshark.org/windows/packages/[]. + +[#ChLibsSMI] + +=== SMI (Optional) + +LibSMI is used for MIB and PIB parsing and for OID resolution. + +[#ChLibsUnixSMI] + +[discrete] +==== Unix + +If this library isn't already installed or available as a +package for your platform, you can get it at +https://www.ibr.cs.tu-bs.de/projects/libsmi/[]. + +[#ChLibsWindowsSMI] + +[discrete] +==== Windows + +Wireshark uses the source libSMI distribution at +https://www.ibr.cs.tu-bs.de/projects/libsmi/[]. +LibSMI is cross-compiled using MinGW32. +It’s stored in the libsmi zip archives at +https://dev-libs.wireshark.org/windows/packages/[]. + +[#ChLibsZlib] + +=== zlib (Optional) + +[quote, The zlib web site, https://www.zlib.net/] +____ +zlib is designed to be a +https://www.zlib.net/zlib_license.html[free], +general-purpose, legally unencumbered -- that is, not covered by any +patents -- lossless data-compression library for use on virtually any computer +hardware and operating system. +____ + +[#ChLibsUnixZlib] + +[discrete] +==== Unix + +This library is almost certain to be installed on your system. If it isn't or +you don't want to use the default library you can download it from +https://www.zlib.net/[]. + +[#ChLibsWindowsZlib] + +[discrete] +==== Windows + +zlib is part of our vcpkg-export bundles and is available at +https://dev-libs.wireshark.org/windows/packages/[]. + +[#ChLibsPcap] + +=== libpcap or Npcap (Optional, But Strongly Recommended) + +Libpcap and Npcap provide the packet capture capabilities that are central +to Wireshark’s core functionality. + +[#ChLibsLibpcap] + +[discrete] +==== Unix: libpcap + +If this library isn't already installed or available as a package for your +platform, you can get it at {tcpdump-main-url}. + +[#ChLibsWinpPcap] + +[discrete] +==== Windows: Npcap + +The Windows build environment compiles and links against a libpcap SDK built using {vcpkg-main-url}[vcpkg] and includes the {npcap-main-url}[Npcap packet capture driver] with the .exe installer. +Both are <<ChLibsSetup,automatically downloaded by CMake>>. + +You can download the Npcap Windows packet capture library manually from +{npcap-main-url}. + +[WARNING] +.Npcap has its own license with its own restrictions +==== +Insecure.Com LLC, aka “The Nmap Project” has granted the Wireshark +Foundation the right to include Npcap with the installers that we +distribute from wireshark.org. If you wish to distribute your own +Wireshark installer or any other package that includes Npcap you must +comply with the {npcap-license-url}[Npcap license] and may be required +to purchase a redistribution license. Please see {npcap-main-url} for +more details. +==== + +[#ChLibsGNUTLS] + +=== GnuTLS (Optional) + +The GNU Transport Layer Security Library is used to enable TLS decryption +using an RSA private key. + +[#ChLibsUnixGNUTLS] + +[discrete] +==== Unix + +If this library isn't already installed or available as a +package for your platform, you can get it at +https://gnutls.org/[]. + +[#ChLibsWindowsGNUTLS] + +[discrete] +==== Windows + +We provide packages cross-compiled using MinGW32 at +https://dev-libs.wireshark.org/windows/packages/[]. + +[#ChLibsGcrypt] + +=== Gcrypt + +The Gcrypt Library is a low-level cryptographic library that provides +support for many ciphers and message authentication codes, such as DES, 3DES, +AES, Blowfish, SHA-1, SHA-256, and others. + +[#ChLibsUnixGcrypt] + +[discrete] +==== Unix + +If this library isn't already installed or available as a +package for your platform, you can get it at +https://directory.fsf.org/wiki/Libgcrypt[]. + +[#ChLibsWindowsGcrypt] + +[discrete] +==== Windows + +We provide packages for Windows at +https://dev-libs.wireshark.org/windows/packages/[]. + +[#ChLibsKerberos] + +=== Kerberos (Optional) + +The Kerberos library is used to dissect Kerberos, sealed DCERPC and +secure LDAP protocols. + +[#ChLibsUnixKerberos] + +[discrete] +==== Unix + +If this library isn't already installed or available as a +package for your platform, you can get it at +https://web.mit.edu/Kerberos/dist/[]. + +[#ChLibsWindowsKerberos] + +[discrete] +==== Windows + +We provide packages for Windows at +https://dev-libs.wireshark.org/windows/packages/[]. + +[#ChLibsLua] + +=== Lua (Optional) + +The Lua library is used to add scripting support to Wireshark. +Wireshark 4.2.x and earlier support Lua versions 5.1 and 5.2. +Recent versions of Wireshark have added support for Lua 5.3 and 5.4 +as well. + +[#ChLibsUnixLua] + +[discrete] +==== Unix + +If this library isn't already installed or available as a +package for your platform, you can get it at +https://www.lua.org/download.html[]. + +[#ChLibsWindowsLua] + +[discrete] +==== Windows + +We provide packages for Windows, patched for UTF-8 support, at +https://dev-libs.wireshark.org/windows/packages/[]. + +[#ChLibsMaxMindDB] + +=== MaxMindDB (Optional) + +MaxMind Inc. publishes a set of IP geolocation databases and related +open source libraries. They can be used to map IP addresses to +geographical locations and other information. + +If libmaxminddb library isn't already installed or available as a +package for your platform, you can get it at +https://github.com/maxmind/libmaxminddb[]. + +We provide packages for Windows at +https://dev-libs.wireshark.org/windows/packages/[]. + +[#ChLibsSparkle] + +=== WinSparkle (Optional) + +WinSparkle is an easy-to-use software update library for Windows developers. + +[#ChLibsWinSparkle] + +[discrete] +==== Windows + +We provide copies of the WinSparkle package at +https://dev-libs.wireshark.org/windows/packages/[]. + +// End of WSDG Chapter Libraries |