forked from osmocom/wireshark
DOC: Remove redundancy in build instructions.
Consolidate build instructions and troubleshooting into WSDG chapter 2. Remove (moved) troubleshooting note that libpcap is required. Link from WSUG build instructions to the WSDG chapters. Reorder WSUG to have install instructions before build instructions for both Windows and Unix. Link from WSDG build instructions in WSDG sources chapter back to WSDG chapter 2. Offer options to the 'git clone' lines in obtaining sources: '--depth' and '--shallow-since' Add brief descriptions of new options mentioned.
This commit is contained in:
Berk Akinci
Wireshark GitLab Utility
parent
5076aee044
commit
9d65d3f889
|
|
@ -80,6 +80,10 @@ these sources.
|
|||
|
||||
==== Building
|
||||
|
||||
The recommended (and fastest) way to build Wireshark is with CMake
|
||||
and Ninja. Building with make took nearly 2x time as Ninja in one
|
||||
experiment.
|
||||
|
||||
CMake builds are best done in a separate build directory, such as a
|
||||
`build` subdirectory of the top-level source directory. If that
|
||||
directory is a subdirectory of the top-level source directory, to
|
||||
|
|
@ -114,7 +118,36 @@ $ cmake -G Ninja ../{source directory}
|
|||
to use Ninja as the build tool. `{source directory}` is the name of the
|
||||
top-level Wireshark source directory.
|
||||
|
||||
You can then run make or Ninja to build Wireshark.
|
||||
If you need to build with a non-standard configuration, you can run
|
||||
|
||||
[source,sh]
|
||||
----
|
||||
$ cmake -LH ../{source directory}
|
||||
----
|
||||
|
||||
to see what options you have.
|
||||
|
||||
You can then run Ninja or make to build Wireshark.
|
||||
|
||||
----
|
||||
$ ninja
|
||||
$ # or
|
||||
$ make
|
||||
----
|
||||
|
||||
Once you have build Wireshark with `ninja` or `make` above, you should be able to test it
|
||||
by entering `run/wireshark`.
|
||||
|
||||
==== Optional: Install
|
||||
|
||||
Install Wireshark in its final destination:
|
||||
|
||||
----
|
||||
make install
|
||||
----
|
||||
|
||||
Once you have installed Wireshark with `make install` above, you should be able
|
||||
to run it by entering `wireshark`.
|
||||
|
||||
==== Optional: Create User’s and Developer’s Guide
|
||||
|
||||
|
|
@ -136,6 +169,26 @@ To create an installable package after successfully building Wireshark:
|
|||
* to build a macOS dmg package containing am application bundle, build
|
||||
the `dmg_package` target.
|
||||
|
||||
==== Troubleshooting during the build and install on Unix
|
||||
|
||||
A number of errors can occur during the build and installation process.
|
||||
Some hints on solving these are provided here.
|
||||
|
||||
If the `cmake` stage fails you will need to find out why. You can check the
|
||||
file `CMakeOutput.log` and `CMakeError.log` in the build directory to find
|
||||
out what failed. The last few lines of this file should help in determining the
|
||||
problem.
|
||||
|
||||
The standard problems are that you do not have a required development package on
|
||||
your system or that the development package isn’t new enough. Note that
|
||||
installing a library package isn’t enough. You need to install its development
|
||||
package as well.
|
||||
|
||||
If you cannot determine what the problems are, send an email to the
|
||||
_wireshark-dev_ mailing list explaining your problem. Include the output from
|
||||
`cmake` and anything else you think is relevant such as a trace of the
|
||||
`make` stage.
|
||||
|
||||
[[ChSetupWin32]]
|
||||
|
||||
=== Win32/64: Step-by-Step Guide
|
||||
|
|
|
|||
|
|
@ -140,11 +140,18 @@ $ git config --global user.email henry.perry@example.com
|
|||
$ git clone -o upstream git@gitlab.com:wireshark/wireshark.git
|
||||
# If you don't you can use the HTTPS URL:
|
||||
$ git clone -o upstream https://gitlab.com/wireshark/wireshark.git
|
||||
# You can speed up cloning in either case by adding --shallow-since=1year or --depth=5000.
|
||||
----
|
||||
The clone only has to be done once.
|
||||
This will copy all the sources (including directories) from the server to your machine and check out the latest version.
|
||||
|
||||
The `-o upstream` flag uses the origin name “upstream” for the repository instead of the default “origin” as described in the https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html[GitLab documentation].
|
||||
|
||||
Cloning may take some time depending on the speed of your internet connection.
|
||||
|
||||
The `--shallow-since=1year` option limits cloned commits to the last 1 year.
|
||||
|
||||
The `--depth=5000` option limits cloned commits to the last 5000.
|
||||
--
|
||||
|
||||
[[ChSrcBuildbot]]
|
||||
|
|
@ -214,33 +221,11 @@ Building Wireshark for the first time depends on your platform.
|
|||
|
||||
==== Building on Unix
|
||||
|
||||
The recommended (and fastest) way to build Wireshark is with CMake and
|
||||
Ninja:
|
||||
|
||||
[source,sh]
|
||||
----
|
||||
# Starting from your Wireshark source directory, create a build directory
|
||||
# alongside it.
|
||||
$ cd ..
|
||||
$ mkdir wireshark-ninja
|
||||
$ cd wireshark-ninja
|
||||
# Assumes your source directory is named "wireshark".
|
||||
$ cmake -G Ninja ../wireshark
|
||||
$ ninja (or cmake --build .)
|
||||
----
|
||||
|
||||
If you need to build with a non-standard configuration, you can run
|
||||
|
||||
[source,sh]
|
||||
----
|
||||
$ cmake -LH ../wireshark
|
||||
----
|
||||
|
||||
to see what options you have.
|
||||
Follow the build procedure in <<ChSetupUNIX>> to build Wireshark.
|
||||
|
||||
==== Windows Native
|
||||
|
||||
Follow the build procedure in <<ChWin32Build>> to build Wireshark.
|
||||
Follow the build procedure in <<ChSetupWin32>> to build Wireshark.
|
||||
|
||||
After the build process has successfully finished, you should find a
|
||||
`Wireshark.exe` and some other files in the `run\RelWithDebInfo` directory.
|
||||
|
|
|
|||
|
|
@ -250,8 +250,12 @@ Npcap you won’t be able to capture anything with Wireshark.
|
|||
We strongly recommended using the binary installer for Windows unless you
|
||||
want to start developing Wireshark on the Windows platform.
|
||||
|
||||
For further information how to build Wireshark for Windows from the sources
|
||||
see the Developer’s Guide at {wireshark-developers-guide-url}.
|
||||
For further information how to obtain sources and build Wireshark for Windows
|
||||
from the sources see the Developer’s Guide at:
|
||||
|
||||
* {wireshark-developers-guide-url}ChSrcObtain
|
||||
|
||||
* {wireshark-developers-guide-url}ChSetupWin32
|
||||
|
||||
You may also want to have a look at the Development Wiki
|
||||
({wireshark-wiki-url}Development) for the latest available development
|
||||
|
|
@ -274,67 +278,6 @@ You can do so by opening the _Install ChmodBPF.pkg_ file in the Wireshark .dmg o
|
|||
The installer package includes Wireshark along with ChmodBPF and system path packages.
|
||||
See the included _Read me first.html_ file for more details.
|
||||
|
||||
[[ChBuildInstallUnixBuild]]
|
||||
|
||||
=== Building Wireshark from source under UNIX
|
||||
|
||||
Building Wireshark requires the proper build environment including a
|
||||
compiler and many supporting libraries. See the Developer’s Guide at
|
||||
{wireshark-developers-guide-url} for more information.
|
||||
|
||||
Use the following general steps to build Wireshark from source under UNIX
|
||||
or Linux:
|
||||
|
||||
. Unpack the source from its compressed `tar` file. If you are using Linux or
|
||||
your version of UNIX uses GNU `tar` you can use the following command:
|
||||
+
|
||||
--
|
||||
----
|
||||
tar xJf wireshark-2.9.0.tar.xz
|
||||
----
|
||||
In other cases you will have to use the following commands:
|
||||
----
|
||||
xz -d wireshark-2.9.0.tar.xz
|
||||
tar xf wireshark-2.9.0.tar
|
||||
----
|
||||
--
|
||||
|
||||
. Create a directory to build Wireshark in and change to it.
|
||||
+
|
||||
----
|
||||
mkdir build
|
||||
cd build
|
||||
----
|
||||
|
||||
. Configure your source so it will build correctly for your version of UNIX. You
|
||||
can do this with the following command:
|
||||
+
|
||||
----
|
||||
cmake ../wireshark-2.9.0
|
||||
----
|
||||
+
|
||||
If this step fails you will have to look into the logs and rectify the problems,
|
||||
then rerun `cmake`.
|
||||
Troubleshooting hints are provided in <<ChBuildInstallUnixTrouble>>.
|
||||
|
||||
. Build the sources.
|
||||
+
|
||||
----
|
||||
make
|
||||
----
|
||||
+
|
||||
Once you have build Wireshark with `make` above, you should be able to run it
|
||||
by entering `run/wireshark`.
|
||||
|
||||
. Install the software in its final destination.
|
||||
+
|
||||
----
|
||||
make install
|
||||
----
|
||||
|
||||
Once you have installed Wireshark with `make install` above, you should be able
|
||||
to run it by entering `wireshark`.
|
||||
|
||||
[[ChBuildInstallUnixInstallBins]]
|
||||
|
||||
=== Installing the binaries under UNIX
|
||||
|
|
@ -411,28 +354,19 @@ pkg_add -r wireshark
|
|||
|
||||
pkg_add should take care of all of the dependency issues for you.
|
||||
|
||||
[[ChBuildInstallUnixTrouble]]
|
||||
[[ChBuildInstallUnixBuild]]
|
||||
|
||||
=== Troubleshooting during the build and install on Unix
|
||||
=== Building from source under UNIX or Linux
|
||||
|
||||
A number of errors can occur during the build and installation process.
|
||||
Some hints on solving these are provided here.
|
||||
We recommended using the binary installer for your platform unless you
|
||||
want to start developing Wireshark.
|
||||
|
||||
If the `cmake` stage fails you will need to find out why. You can check the
|
||||
file `CMakeOutput.log` and `CMakeError.log` in the build directory to find
|
||||
out what failed. The last few lines of this file should help in determining the
|
||||
problem.
|
||||
Building Wireshark requires the proper build environment including a
|
||||
compiler and many supporting libraries. For more information, see the Developer’s Guide at:
|
||||
|
||||
The standard problems are that you do not have a required development package on
|
||||
your system or that the development package isn’t new enough. Note that
|
||||
installing a library package isn’t enough. You need to install its development
|
||||
package as well. `cmake` will also fail if you do not have libpcap (at least
|
||||
the required include files) on your system.
|
||||
* {wireshark-developers-guide-url}ChSrcObtain
|
||||
|
||||
If you cannot determine what the problems are, send an email to the
|
||||
_wireshark-dev_ mailing list explaining your problem. Include the output from
|
||||
`cmake` and anything else you think is relevant such as a trace of the
|
||||
`make` stage.
|
||||
* {wireshark-developers-guide-url}ChapterSetup#ChSetupUNIX
|
||||
|
||||
// End of WSUG Chapter 2
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue