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

WSDG: More CMake updates. 

Switch a build example to CMake + Ninja. Add syntax highlighting
annotations.

Change-Id: I5ee0af548f44ed5be6f6e8367f5167dc499df017
Reviewed-on: https://code.wireshark.org/review/26514
Reviewed-by: Anders Broman <a.broman58@gmail.com>
This commit is contained in:
Gerald Combs 2018-03-16 15:20:18 -07:00 committed by Anders Broman
parent 2e977276c4
commit 2d15d7d51b
2 changed files with 62 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
docbook/wsdg_src/WSDG_chapter_sources.asciidoc
View File

@ -311,6 +311,7 @@ sure the builds are in good shape.
After you clone Wireshark’s Git repository you can update After you clone Wireshark’s Git repository you can update
by running by running
[source,sh]
---- ----
$ git status $ git status
$ git pull $ git pull
@ -374,19 +375,26 @@ Building Wireshark for the first time depends on your platform.
==== Building on Unix ==== Building on Unix
Run the `autogen.sh` script at the top-level wireshark directory to configure The recommended (and fastest) way to build Wireshark is with CMake and
your build directory. Ninja:
[source,sh]
---- ----
$ ./autogen.sh # Starting from your Wireshark source directory, create a build directory
$ ./configure # alongside it.
$ make $ 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 If you need to build with a non-standard configuration, you can run
[source,sh]
---- ----
$ ./configure --help $ cmake -LH ../wireshark
---- ----
to see what options you have. to see what options you have.
@ -430,6 +438,7 @@ Wireshark. If your platform is properly setup, your build directory and
current working directory are not in your PATH, so the current working directory are not in your PATH, so the
command line to launch Wireshark would be: command line to launch Wireshark would be:
[source,sh]
---- ----
$ WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1 ./wireshark $ WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1 ./wireshark
---- ----
@ -468,6 +477,7 @@ the program into your debugger. But loading wireshark into debugger fails
because of the libtool build environment. You'll have to wrap loading because of the libtool build environment. You'll have to wrap loading
wireshark into a libtool command: wireshark into a libtool command:
[source,sh]
---- ----
$ libtool --mode=execute gdb wireshark $ libtool --mode=execute gdb wireshark
---- ----
@ -478,6 +488,7 @@ If you prefer a graphic debugger you can use the Data Display Debugger
Additional traps can be set on GLib by setting the `G_DEBUG` environment variable: Additional traps can be set on GLib by setting the `G_DEBUG` environment variable:
[source,sh]
---- ----
$ G_DEBUG=fatal_criticals libtool --mode=execute ddd wireshark $ G_DEBUG=fatal_criticals libtool --mode=execute ddd wireshark
---- ----
@ -843,6 +854,7 @@ https://code.wireshark.org/review/Documentation/user-upload.html#push_create[mag
in Gerrit. For example, to upload your new Snowcone Machine Protocol dissector in Gerrit. For example, to upload your new Snowcone Machine Protocol dissector
you could push to refs/for/master with the topic "snowcone-machine": you could push to refs/for/master with the topic "snowcone-machine":
[source,sh]
---- ----
$ git push ssh://my.username@code.wireshark.org:29418/wireshark HEAD:refs/for/master/snowcone-machine $ git push ssh://my.username@code.wireshark.org:29418/wireshark HEAD:refs/for/master/snowcone-machine
---- ----
@ -852,6 +864,7 @@ the review system.
If you have `git-review` installed you can upload the change with a lot less typing: If you have `git-review` installed you can upload the change with a lot less typing:
[source,sh]
---- ----
# Note: The "-f" flag deletes your current branch. # Note: The "-f" flag deletes your current branch.
$ git review -f $ git review -f
@ -893,6 +906,7 @@ in Git by cherry-picking the change from one branch to another.
Suppose you want to backport change 1ab2c3d4 from the master branch to Suppose you want to backport change 1ab2c3d4 from the master branch to
master-1.10. Using "pure Git" commands you would do the following: master-1.10. Using "pure Git" commands you would do the following:
[source,sh]
---- ----
# Create a new topic branch for the backport. # Create a new topic branch for the backport.
$ git checkout -b backport-g1ab2c3d4 origin/master-1.10 $ git checkout -b backport-g1ab2c3d4 origin/master-1.10
@ -947,6 +961,7 @@ _new.diff_ look like.
If they're relative to the top-level source directory (for example, if a If they're relative to the top-level source directory (for example, if a
patch to _prefs.c_ just has _prefs.c_ as the file name) you’d run it as: patch to _prefs.c_ just has _prefs.c_ as the file name) you’d run it as:
[source,sh]
---- ----
$ patch -p0 < new.diff $ patch -p0 < new.diff
---- ----
@ -956,6 +971,7 @@ number of higher-level directories in the path, e.g. if the names are
_wireshark.orig/prefs.c_ and _wireshark.orig/prefs.c_ and
_wireshark.mine/prefs.c_, you’d run it with: _wireshark.mine/prefs.c_, you’d run it with:
[source,sh]
---- ----
$ patch -p1 < new.diff $ patch -p1 < new.diff
---- ----
@ -1007,6 +1023,7 @@ more in-depth discussion of the build process.
In the wireshark directory, type: In the wireshark directory, type:
[source,sh]
---- ----
$ dpkg-buildpackage -rfakeroot -us -uc $ dpkg-buildpackage -rfakeroot -us -uc
---- ----
@ -1040,6 +1057,7 @@ usual Wireshark `./configure`. The exceptions to this rule are:
In the wireshark directory, type: In the wireshark directory, type:
[source,sh]
---- ----
$ make rpm-package $ make rpm-package
---- ----
@ -1074,6 +1092,7 @@ The macOS Package is built using macOS packaging tools, based on information
found in the source tree under _packaging/macosx_. It must be built using found in the source tree under _packaging/macosx_. It must be built using
CMake. In your build directory, type: CMake. In your build directory, type:
[source,sh]
---- ----
$ make dmg_package $ make dmg_package
---- ----
@ -1092,6 +1111,7 @@ generation script at _packaging/nsis/wireshark.nsi_.
When building with CMake you must first build the _nsis_package_prep_ target, When building with CMake you must first build the _nsis_package_prep_ target,
followed by the _nsis_package_ target, e.g. followed by the _nsis_package_ target, e.g.
[source,cmd]
---- ----
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj > msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package.vcxproj > msbuild /m /p:Configuration=RelWithDebInfo nsis_package.vcxproj
@ -1129,6 +1149,7 @@ When building with CMake you must first build the _nsis_package_prep_ target
(which takes care of general packaging dependencies), followed by the (which takes care of general packaging dependencies), followed by the
_portableapps_package_ target, e.g. _portableapps_package_ target, e.g.
[source,cmd]
---- ----
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj > msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
> msbuild /m /p:Configuration=RelWithDebInfo portableapps_package.vcxproj > msbuild /m /p:Configuration=RelWithDebInfo portableapps_package.vcxproj

42
docbook/wsdg_src/WSDG_chapter_tools.asciidoc
View File

@ -40,8 +40,8 @@ tested.
Documentation for these tools is outside the scope of this document. If you need Documentation for these tools is outside the scope of this document. If you need
further information on using a specific tool you should find lots of useful further information on using a specific tool you should find lots of useful
information on the web, as these tools are commonly used. You can also get help information on the web, as these tools are commonly used. You can also get help
for the UNIX based tools with +**toolname** --help+ or the man page via +man for the UNIX based tools with `**toolname** --help` or the man page via `man
**toolname**+. **toolname**`.
You will find explanations of the tool usage for some of the specific You will find explanations of the tool usage for some of the specific
development tasks in <<ChapterSources>>. development tasks in <<ChapterSources>>.
@ -52,12 +52,14 @@ Chocolatey is a Windows package manager that can be used to install (and update)
many of the packages required for Wireshark development. Chocolatey can be many of the packages required for Wireshark development. Chocolatey can be
obtained from the http://chocolatey.org[website] or from a Command Prompt: obtained from the http://chocolatey.org[website] or from a Command Prompt:
[source,cmd]
---- ----
C:\>@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString(_https://chocolatey.org/install.ps1_))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin C:\>@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString(_https://chocolatey.org/install.ps1_))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin
---- ----
or a Powershell prompt: or a Powershell prompt:
[source,cmd]
---- ----
PS:\>iex ((new-object net.webclient).DownloadString(_https://chocolatey.org/install.ps1_)) PS:\>iex ((new-object net.webclient).DownloadString(_https://chocolatey.org/install.ps1_))
---- ----
@ -147,6 +149,7 @@ between:
Chocolatey supports Cygwin as an external package source. Chocolatey supports Cygwin as an external package source.
To install Cygwin itself run To install Cygwin itself run
[source,cmd]
---- ----
PS$>choco install cygwin PS$>choco install cygwin
# You might also need to install cyg-get: # You might also need to install cyg-get:
@ -157,6 +160,7 @@ Chocolatey installs Cygwin in _C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin
One or more Cygwin packages can be installed using `cyg-get`: One or more Cygwin packages can be installed using `cyg-get`:
[source,cmd]
---- ----
PS$>cyg-get sed asciidoc PS$>cyg-get sed asciidoc
---- ----
@ -178,6 +182,7 @@ specifying a *generator*, aka a build tool. For example, to build
Wireshark using Ninja in the directory _wireshark-ninja_ you might Wireshark using Ninja in the directory _wireshark-ninja_ you might
run the following commands: run the following commands:
[source,sh]
---- ----
# Starting from your Wireshark source directory, create a build directory # Starting from your Wireshark source directory, create a build directory
# alongside it. # alongside it.
@ -260,6 +265,7 @@ http://gcc.gnu.org/[].
After correct installation, typing at the After correct installation, typing at the
bash command line prompt: bash command line prompt:
[source,sh]
---- ----
$ gcc --version $ gcc --version
---- ----
@ -292,6 +298,7 @@ http://www.gnu.org/software/gdb/gdb.html[].
After correct installation: After correct installation:
[source,sh]
---- ----
$ gdb --version $ gdb --version
---- ----
@ -347,6 +354,7 @@ http://www.gnu.org/software/make/[].
After correct installation: After correct installation:
[source,sh]
---- ----
$ make --version $ make --version
---- ----
@ -458,6 +466,7 @@ requires a a {cpp} redistributable
You can use Chocolatey to install Visual Studio, e.g: You can use Chocolatey to install Visual Studio, e.g:
[source,cmd]
---- ----
PS:\> choco install VisualStudioCommunity2013 PS:\> choco install VisualStudioCommunity2013
---- ----
@ -479,6 +488,7 @@ versions ordered by release date.
After correct installation of the toolchain, typing After correct installation of the toolchain, typing
at the Visual Studio Command line prompt (cmd.exe): at the Visual Studio Command line prompt (cmd.exe):
[source,cmd]
---- ----
> cl > cl
---- ----
@ -501,6 +511,7 @@ http://msdn.microsoft.com/en-us/library/wk21sfcf.aspx[Microsoft MSDN]
After correct installation, typing at the Visual Studio Command line prompt (cmd.exe): After correct installation, typing at the Visual Studio Command line prompt (cmd.exe):
[source,cmd]
---- ----
> link > link
---- ----
@ -522,7 +533,6 @@ http://msdn.microsoft.com/en-us/library/t2fck18t.aspx[Microsoft MSDN]
[[msvc-runtime-redistributable]] [[msvc-runtime-redistributable]]
==== C-Runtime "Redistributable" Files ==== C-Runtime "Redistributable" Files
Please note: The following is not legal advice - ask your preferred lawyer Please note: The following is not legal advice - ask your preferred lawyer
@ -695,6 +705,7 @@ To set the correct paths for Visual Studio when running Wireshark under the
debugger, add the build output directory to the path before opening Visual debugger, add the build output directory to the path before opening Visual
Studio from the same command prompt, e.g. Studio from the same command prompt, e.g.
[source,cmd]
---- ----
C:\Development\wsbuild32>set PATH="%PATH%;C:\Development\wsbuild32\run\RelwithDebInfo" C:\Development\wsbuild32>set PATH="%PATH%;C:\Development\wsbuild32\run\RelwithDebInfo"
C:\Development\wsbuild32>wireshark.sln C:\Development\wsbuild32>wireshark.sln
@ -702,6 +713,7 @@ C:\Development\wsbuild32>wireshark.sln
for PowerShell use for PowerShell use
[source,cmd]
---- ----
PS C:\Development\wsbuild32>$env:PATH += ";$(Convert-Path run\RelWithDebInfo)" PS C:\Development\wsbuild32>$env:PATH += ";$(Convert-Path run\RelWithDebInfo)"
PS C:\Development\wsbuild32>wireshark.sln PS C:\Development\wsbuild32>wireshark.sln
@ -738,6 +750,7 @@ http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063%28v=vs.85%29.a
You can also use Chocolatey to install WinDbg: You can also use Chocolatey to install WinDbg:
[source,cmd]
---- ----
PS:\> choco install windbg PS:\> choco install windbg
---- ----
@ -773,6 +786,7 @@ http://www.gnu.org/software/bash/bash.html[].
After correct installation, typing at the bash command line prompt: After correct installation, typing at the bash command line prompt:
[source,sh]
---- ----
$ bash --version $ bash --version
---- ----
@ -805,12 +819,14 @@ a symbolic link, which causes confusion outside Cygwin.
You can also use Chocolatey to install Python: You can also use Chocolatey to install Python:
[source,cmd]
---- ----
PS:\> choco install Python3 PS:\> choco install Python3
---- ----
or or
[source,cmd]
---- ----
PS:\> choco install Python2 PS:\> choco install Python2
---- ----
@ -818,12 +834,14 @@ PS:\> choco install Python2
Chocolatey installs Python into _C:\tools\python3_ or _C:\tools\python2_ by Chocolatey installs Python into _C:\tools\python3_ or _C:\tools\python2_ by
default. You can verify your Python version by running default. You can verify your Python version by running
[source,sh]
---- ----
$ python --version $ python --version
---- ----
on UNIX and Linux and on UNIX and Linux and
[source,cmd]
---- ----
rem Official package rem Official package
C:> cd python35 C:> cd python35
@ -867,6 +885,7 @@ http://www.perl.com/[].
After correct installation, typing at the After correct installation, typing at the
bash command line prompt: bash command line prompt:
[source,sh]
---- ----
$ perl --version $ perl --version
---- ----
@ -952,6 +971,7 @@ platform you can get it at: http://www.gnu.org/software/bison/bison.html[].
After correct installation running the following After correct installation running the following
[source,sh]
---- ----
$ bison --version $ bison --version
---- ----
@ -1000,6 +1020,7 @@ you can get it at http://www.gnu.org/software/flex/[].
After correct installation running the following After correct installation running the following
[source,sh]
---- ----
$ flex --version $ flex --version
---- ----
@ -1020,6 +1041,7 @@ A native Windows version of flex is available in the _winflexbison_
https://chocolatey.org/[Chocolatey] package. Note that the executable is named https://chocolatey.org/[Chocolatey] package. Note that the executable is named
_win_flex_. _win_flex_.
[source,cmd]
---- ----
PS:\>choco install winflexbison PS:\>choco install winflexbison
---- ----
@ -1057,6 +1079,7 @@ can get it at: http://git-scm.com/[].
After correct installation, typing at the bash command line prompt: After correct installation, typing at the bash command line prompt:
[source,sh]
---- ----
$ git --version $ git --version
---- ----
@ -1064,18 +1087,19 @@ $ git --version
should result in something like: should result in something like:
---- ----
git version 1.8.3.4 git version 2.14.1
---- ----
Your version will likely be different. Your version will likely be different.
[[ChToolsWindowsGit]] [[ChToolsWindowsGit]]
==== Windows native: git ==== Windows Native: git
The Git command line tools for Windows can be found at The Git command line tools for Windows can be found at
http://git-scm.com/download/win[] and can also be installed using Chocolatey: http://git-scm.com/download/win[] and can also be installed using Chocolatey:
[source,cmd]
---- ----
PS:\> choco install git PS:\> choco install git
---- ----
@ -1083,14 +1107,15 @@ PS:\> choco install git
After correct installation, typing at the command After correct installation, typing at the command
line prompt (cmd.exe): line prompt (cmd.exe):
[source,cmd]
---- ----
$ git --version > git --version
---- ----
should result in something like: should result in something like:
---- ----
git version 1.8.3.4 git version 2.16.1.windows.1
---- ----
However, the version string may vary. However, the version string may vary.
@ -1103,6 +1128,7 @@ A useful tool for command line git on Windows is https://github.com/dahlbyk/posh
Poshgit provides git command completion and alters the prompt to indicate the local working Poshgit provides git command completion and alters the prompt to indicate the local working
copy status. You can install it using Chocolatey: copy status. You can install it using Chocolatey:
[source,cmd]
---- ----
PS:\>choco install poshgit PS:\>choco install poshgit
---- ----
@ -1148,6 +1174,7 @@ http://www.gnu.org/software/patch/patch.html[].
After correct installation, typing at the After correct installation, typing at the
bash command line prompt: bash command line prompt:
[source,sh]
---- ----
$ patch --version $ patch --version
---- ----
@ -1190,6 +1217,7 @@ To install it, download the latest released version from
http://nsis.sourceforge.net[]. NSIS v3 is recommended and may be http://nsis.sourceforge.net[]. NSIS v3 is recommended and may be
required in the future. You can also install it using Chocolatey: required in the future. You can also install it using Chocolatey:
[source,cmd]
---- ----
PS$> choco install nsis PS$> choco install nsis
---- ----