From 9f153fbfec0fb9c9ce38e749a7c6f4a5e115d4e9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 19 Sep 2024 06:14:33 +0200 Subject: Merging upstream version 4.4.0. Signed-off-by: Daniel Baumann --- doc/wsdg_src/wsdg_env_intro.adoc | 525 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 525 insertions(+) create mode 100644 doc/wsdg_src/wsdg_env_intro.adoc (limited to 'doc/wsdg_src/wsdg_env_intro.adoc') diff --git a/doc/wsdg_src/wsdg_env_intro.adoc b/doc/wsdg_src/wsdg_env_intro.adoc new file mode 100644 index 00000000..2bf6a922 --- /dev/null +++ b/doc/wsdg_src/wsdg_env_intro.adoc @@ -0,0 +1,525 @@ +// WSDG Chapter Introduction + +[#ChapterIntroduction] + +== Introduction + +[#ChIntroIntro] + +=== Introduction + +This chapter will provide a general overview of Wireshark development. + +[#ChIntroWhatIs] + +=== What Is Wireshark? + +Well, if you want to start Wireshark development, you might already +know what Wireshark is doing. If not, please have a look at the +link:{wireshark-users-guide-url}[Wireshark User’s Guide], +which will provide a lot of general information about it. + +[#ChIntroPlatforms] + +=== Supported Platforms + +Wireshark currently runs on most UNIX-like platforms and various Windows +platforms. It requires Qt, GLib, libpcap and some other libraries in +order to run. + +As Wireshark is developed in a platform independent way and uses libraries (such +as the Qt GUI library) which are available for many different platforms, +it’s thus available on a wide variety of platforms. + +If a binary package is not available for your platform, you should +download the source and try to build it. Please report your experiences +to mailto:{wireshark-dev-list-email}[]. + +Binary packages are available for the following platforms along with many +others: + +==== Unix And Unix-like Platforms + +* Apple macOS + +* FreeBSD + +* HP-UX + +* IBM AIX + +* NetBSD + +* OpenBSD + +* Oracle Solaris + +===== Linux + +* Arch Linux + +* Debian GNU/Linux + +* Ubuntu + +* Fedora + +* Gentoo Linux + +* IBM S/390 Linux (Red Hat) + +* Mandriva Linux + +* PLD Linux + +* Red Hat Linux + +* Slackware Linux + +* Suse Linux + +==== Microsoft Windows + +Wireshark supports Windows natively via the https://en.wikipedia.org/wiki/Windows_API[Windows API]. +Note that in this documentation and elsewhere we tend to use the terms “Win32”, “Win”, and “Windows” interchangeably to refer to the Windows API. +“Win64” refers to the Windows API on 64-bit platforms. +Wireshark runs on and can be compiled on the following Windows versions: + +* Windows 11 / Windows Server 2022 + +* Windows 10 / Windows Server 2016 / Windows Server 2019 + +* Windows 8.1 / Windows Server 2012 R2 + +* Windows 8 / Windows Server 2012 + +Development on Windows 7, Server 2008 R2, Vista, Server 2008, and older versions may be possible but is not supported. + +Some versions of Windows support https://devblogs.microsoft.com/commandline/per-directory-case-sensitivity-and-wsl/[case sensitive directories]. +We don’t officially support building or running Wireshark in this environment, but we will accept patches to fix any issues that might arise. + +[#ChIntroDevelopment] + +=== Development And Maintenance Of Wireshark + +Wireshark was initially developed by Gerald Combs. Ongoing development +and maintenance of Wireshark is handled by the Wireshark core developers, +a loose group of individuals who fix bugs and provide new functionality. + +There have also been a large number of people who have contributed +protocol dissectors and other improvements to Wireshark, and it is +expected that this will continue. You can find a list of the people who +have contributed code to Wireshark by checking the About dialog box of +Wireshark, or have a look at the {wireshark-authors-url} page on the +Wireshark web site. + +The communication between the developers is usually done through the developer +mailing list, which can be joined by anyone interested in the development +activities. At the time this document was written, more than 500 persons were +subscribed to this mailing list! + +It is strongly recommended to join the developer mailing list, if you are going +to do any Wireshark development. See <> about the different +Wireshark mailing lists available. + +==== Programming Languages Used + +Most of Wireshark is implemented in C. +A notable exception is the code in _ui/qt_, which is written in {cpp}. + +The typical task for a new Wireshark developer is to extend an existing dissector, or write a new dissector for a specific network protocol. +Most dissectors are written in C11, so a good knowledge of C will be sufficient for Wireshark development in almost any case. +Dissectors can also be written in Lua, which might be more suitable for your specific needs. +As noted above, if you’re going to modify Wireshark’s user interface you will need a knowledge of {cpp}. + +Modifying the build system and support tooling might requires knowledge of CMake, Python, PowerShell, Bash, or Perl. +Note that these are required to build Wireshark, but not to run it. +If Wireshark is installed from a binary package, none of these helper tools are needed on the target system. + +==== Open Source Software + +Wireshark is an https://opensource.org/[open source] software (OSS) project, and is released under +the link:{gplv2-url}[GNU General Public License] (GPL). +You can freely use Wireshark on any number of computers you like, without +worrying about license keys or fees or such. In addition, all source +code is freely available under the GPL. Because of that, it is very easy +for people to add new protocols to Wireshark, either as plugins, or built +into the source, and they often do! + +You are welcome to modify Wireshark to suit your own needs, and it would be +appreciated if you contribute your improvements back to the Wireshark community. + +You gain three benefits by contributing your improvements back to the +community: + +* Other people who find your contributions useful will appreciate them, and you + will know that you have helped people in the same way that the developers of + Wireshark have helped you and other people. + +* The developers of Wireshark might improve your changes even more, as there’s + always room for improvement. Or they may implement some advanced things on top + of your code, which can be useful for yourself too. + +* The maintainers and developers of Wireshark will maintain your code as well, + fixing it when API changes or other changes are made, and generally keeping it + in tune with what is happening with Wireshark. So if Wireshark is updated + (which is done often), you can get a new Wireshark version from the website + and your changes will already be included without any effort for you. + + +The Wireshark source code and binary packages for some platforms are all +available on the download page of the Wireshark website: +{wireshark-download-url}. + + +[#ChIntroReleases] + +=== Releases And Distributions + +Official Wireshark releases can be found at {wireshark-download-url}. +Minor releases typically happen every six weeks and typically include bug fixes and security updates. +Major releases happen about once a year and include new features and new protocol support. +Official releases include binary packages for Windows and macOS along with source code. + +[#ChIntroReleaseBinary] + +==== Binary Distributions + +The Wireshark development team would like to make it as easy as possible for people to obtain and use Wireshark. +This means that we need to support the software installation systems that different operating systems provide. +We currently offer the following types of precompiled packages as part of each official release: + +* Windows .exe installer. + This is an executable file that installs Wireshark, and optionally Npcap and USBPcap, created using https://nsis.sourceforge.io/Main_Page[NSIS]. + It is the most popular installation method on Windows. + +* Windows https://portableapps.com/[PortableApps] .paf.exe file. + This is a self-contained package that can be run from anywere, either standalone or under the PortableApps.com Platform. + +* Windows .msi installer. + This installs Wireshark using Microsoft’s https://docs.microsoft.com/en-us/windows/win32/msi/installer-database[Installer Database], created using the https://wixtoolset.org/[WiX toolset]. + It does not yet include Npcap or USBPcap and is somewhat https://gitlab.com/wireshark/wireshark/-/issues/8814[experimental]. + +* macOS .dmg. + This is a disk image which includes a drag-installable Wireshark application bundle along with utility packages for installing ChmodBPF and adding Wireshark to your PATH environment variable. + +Most Linux and UNIX distributions have their own packaging systems which usually include Wireshark. +The Wireshark sources include support for creating the following types of packages: + +* Debian .deb files. + Packaging assets can be found in the _debian_ directory in the Wireshark sources. + +* Red Hat .rpm files. + Packaging assets can be found in the _packaging/rpm_ directory in the Wireshark sources. + +You can also create your own binary packages. See <> for details. + +[#ChIntroReleaseSource] + +==== The Source Code Distribution + +Wireshark is and will always be https://opensource.org/[open source]. +You’re welcome to download a source tarball, build it, and modify it under the terms of the {gplv2-url}[GPLv2]. +However, it’s usually much easier to use a binary package if you want to get up and running quickly in a production environment. + +Source tarballs are commonly used for building the binary packages for UNIX and UNIX-like platforms. +However, if you are going to modify the Wireshark sources, e.g. to contribute changes back or to develop an in-house version of Wireshark we recommend that you use the latest Git sources. +For details about the different ways to get the Wireshark source code see <>. + +Before building Wireshark from a source distribution, make sure you have all the tools and libraries required to build. +Later chapters describe the required tools and libraries in detail. + +[#ChIntroAutomated] + +=== Automated Builds (GitLab CI) + +The Wireshark development team uses GitLab’s continuous integration (CI) system to automatically build Wireshark for each Git merge request and commit. +Automated builds provide several useful services: + +* Cross-platform testing. + Inbound merge requests and commits can be tested on each of our supported platforms, which ensures that a developer on one platform doesn’t break the build on other platforms. + +* A health indicator for the source code. + The CI badges at {wireshark-gitlab-project-url} can quickly tell you how healthy the latest code is. + Green is good, red is bad. + +* Fast code delivery. + After a change is committed to the repository, an installer is usually available within an hour at https://www.wireshark.org/download/automated/. + This can be quite helpful for resolving issues, e.g. a bug reporter can easily verify a bugfix by installing a recent build. + +* Automated regression tests. + We run a comprehensive test suite as part of each build and continuously run fuzz tests that try to crash the dissection engine. + +==== What Do The Automated Builds Do? + +GitLab’s CI operates by running a series of steps and reporting success or failure. +A typical CI job might do the following: + +. Check out Wireshark from the source repository. + +. Build Wireshark. + +. Create a source tarball, binary package, or installer. + +. Run regression tests. + +GitLab’s CI marks successful jobs with a green checkmark and failed jobs with a red “X”. +Jobs provide a link to the corresponding console logfile which provides additional information. + +Release packages are built on the following platforms: + +* Windows Server 2022 x64, Visual Studio 2022 + +* Windows 11 Arm64, Visual Studio 2022 + +* Ubuntu 22.04 x64, gcc + +* macOS x64, clang + +* macOS Arm64, clang + +Static code analysis and fuzz tests are run on the following platforms: + +* Visual Studio Code Analysis, Visual Studio 2022 + +* Clang Code Analysis, Coverity Scan, and fuzz tests, clang + +[#ChIntroHelp] + +=== Reporting problems and getting help + +If you have problems, or need help with Wireshark, there are several +places that may be of interest to you (well, beside this guide of +course). + +[#ChIntroHomepage] + +==== Website + +You will find lots of useful information on the Wireshark homepage at +{wireshark-main-url}. + +[#ChIntroWiki] + +==== Wiki + +The Wireshark Wiki at {wireshark-wiki-url} provides a wide range +of information related to Wireshark and packet capturing in general. +You will find a lot of information not part of this developer’s guide. For +example, there is an explanation how to capture on a switched network, +an ongoing effort to build a protocol reference and a lot more. + +And best of all, if you would like to contribute your knowledge on a +specific topic (maybe a network protocol you know well), you can edit the +Wiki pages by simply using your webbrowser. + +[#ChIntroFAQ] + + +==== FAQ + +The "Frequently Asked Questions" will list often asked questions and +the corresponding answers. + +Before sending any mail to the mailing lists below, be sure to read the +FAQ, as it will often answer any questions you might have. This will save +yourself and others a lot of time. Keep in mind that a lot of people are +subscribed to the mailing lists. + +You will find the FAQ inside Wireshark by clicking the menu item +Help/Contents and selecting the FAQ page in the upcoming dialog. + +An online version is available at the Wireshark website: +{wireshark-faq-url}. You might prefer this online version as it’s +typically more up to date and the HTML format is easier to use. + +[#ChIntroOtherSources] + +==== Other sources + +If you don't find the information you need inside this book, there are +various other sources of information: + +* The file _doc/README.developer_ and all the other README.xxx files in the + source code. These are various documentation files on different topics + +[NOTE] +.Read the README +==== +_README.developer_ is packed full with all kinds of details relevant +to the developer of Wireshark source code. Its companion file +_README.dissector_ advises you around common +pitfalls, shows you basic layout of dissector code, shows details of the +APIs available to the dissector developer, etc. +==== + +* The Wireshark source code + +* Tool documentation of the various tools used +(e.g. manpages of sed, gcc, etc.) + +* The different mailing lists. See <> + +[#ChIntroQA] + +==== Q&A Site + +The Wireshark Q&A site at {wireshark-qa-url} offers a resource where +questions and answers come together. You have the option to search what +questions were asked before and what answers were given by people who +knew about the issue. Answers are graded, so you can pick out the best +ones easily. If your issue isn't discussed before you can post one +yourself. + +[#ChIntroMailingLists] + +==== Mailing Lists + +There are several mailing lists available on specific Wireshark topics: + +wireshark-announce:: This mailing list will inform you about new program +releases, which usually appear about every 4-8 weeks. + +wireshark-users:: This list is for users of Wireshark. People post +questions about building and using Wireshark, others (hopefully) +provide answers. + +wireshark-dev:: This list is for Wireshark developers. People post questions about +the development of Wireshark, others (hopefully) provide answers. +If you want to start developing a protocol dissector, join this list. + +wireshark-bugs:: This list is for Wireshark developers. Every time a change to the bug +database occurs, a mail to this mailing list is generated. +If you want to be notified about all the changes to the bug +database, join this list. Details about the bug database can be +found in <>. + +wireshark-commits:: This list is for Wireshark developers. Every time a change to the Git +repository is checked in, a mail to this mailing list is generated. +If you want to be notified about all the changes to the Git +repository, join this list. Details about the Git repository can be +found in <>. + +You can subscribe to each of these lists from the Wireshark web site: +{wireshark-mailing-lists-url}. From there, you can choose which mailing +list you want to subscribe to by clicking on the +Subscribe/Unsubscribe/Options button under the title of the relevant +list. The links to the archives are included on that page as well. + +[TIP] +.The archives are searchable +==== +You can search in the list archives to see if someone previously asked the same +question and maybe already got an answer. That way you don't have to wait until +someone answers your question. +==== + +[#ChIntroBugDatabase] + +==== Bug Database (GitLab Issues) + +The Wireshark community collects bug reports in an issues database at {wireshark-bugs-url}. +This database is filled with manually filed bug reports, usually after some discussion on wireshark-dev, and automatic bug reports from continuous integration jobs. + +[#ChIntroReportProblems] + +==== Reporting Problems + +[NOTE] +.Test with the latest version +==== +Before reporting any problems, please make sure you have installed the +latest version of Wireshark. Reports on older maintenance releases are +usually met with an upgrade request. +==== + +If you report problems, provide as much information as possible. In general, +just think about what you would need to find that problem, if someone else sends +you such a problem report. Also keep in mind that people compile/run Wireshark +on a lot of different platforms. + +When reporting problems with Wireshark, it is helpful if you supply the +following information: + +. The version number of Wireshark and the dependent libraries linked with +it, e.g. Qt, GLib, etc. You can obtain this with the command +`wireshark -v`. + +. Information about the platform you run Wireshark on. + +. A detailed description of your problem. + +. If you get an error/warning message, copy the text of that message (and +also a few lines before and after it, if there are some), so others may +find the build step where things go wrong. +Please don't give something like: "I get a warning when compiling x" +as this won't give any direction to look at. + +[NOTE] +.Don't send large files +==== +Do not send large files (>100KB) to the mailing lists, just place a note +that further data is available on request. Large files will only annoy a +lot of people on the list who are not interested in your specific problem. +If required, you will be asked for further data by the persons who really +can help you. +==== + +[WARNING] +.Don't send confidential information +==== +If you send captured data to the mailing lists, or add it to your bug report, +be sure it doesn't contain any sensitive or confidential information, +such as passwords. Visibility of such files can be limited to certain +groups in the GitLab Issues database by marking the issue confidential. +==== + +==== Reporting Crashes on UNIX-like platforms + +When reporting crashes with Wireshark, it is helpful if you supply the +traceback information (besides the information mentioned in +<>). + +You can obtain this traceback information with the following commands: + +---- +$ gdb `whereis wireshark | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt +backtrace +^D +$ +---- + +[NOTE] +.Using GDB +==== +Type the characters in the first line verbatim. Those are +back-tics there. + +`backtrace` is a `gdb` command. You should +enter it verbatim after the first line shown above, but it will not be +echoed. The ^D +(Control-D, that is, press the Control key and the D key +together) will cause `gdb` to exit. This will +leave you with a file called +_bt.txt_ in the current directory. +Include the file with your bug report. + +If you do not have `gdb` available, you +will have to check out your operating system’s debugger. +==== + +You should mail the traceback to mailto:{wireshark-dev-list-email}[] or attach it +to your bug report. + +==== Reporting Crashes on Windows platforms + +You can download Windows debugging symbol files (.pdb) from the following locations: + +* 64-bit Windows: https://www.wireshark.org/download/win64/all-versions/ + +Files are named "Wireshark-pdb-win__bits__-_x_._y_._z_.zip" to match their +corresponding "Wireshark-win__bits__-_x_._y_._z_.exe" installer packages. + +// XXX Show how to use the Visual Studio debugger + +// End of WSDG Chapter Introduction -- cgit v1.2.3