diff --git a/docbook/wsdg_src/WSDG_chapter_sources.asciidoc b/docbook/wsdg_src/WSDG_chapter_sources.asciidoc index 6a464d3639..b77535b6ee 100644 --- a/docbook/wsdg_src/WSDG_chapter_sources.asciidoc +++ b/docbook/wsdg_src/WSDG_chapter_sources.asciidoc @@ -311,6 +311,7 @@ sure the builds are in good shape. After you clone Wireshark’s Git repository you can update by running +[source,sh] ---- $ git status $ git pull @@ -374,19 +375,26 @@ Building Wireshark for the first time depends on your platform. ==== Building on Unix -Run the `autogen.sh` script at the top-level wireshark directory to configure -your build directory. +The recommended (and fastest) way to build Wireshark is with CMake and +Ninja: +[source,sh] ---- -$ ./autogen.sh -$ ./configure -$ make +# 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] ---- -$ ./configure --help +$ cmake -LH ../wireshark ---- 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 command line to launch Wireshark would be: +[source,sh] ---- $ 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 wireshark into a libtool command: +[source,sh] ---- $ 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: +[source,sh] ---- $ 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 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 ---- @@ -852,6 +864,7 @@ the review system. 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. $ 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 master-1.10. Using "pure Git" commands you would do the following: +[source,sh] ---- # Create a new topic branch for the backport. $ 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 patch to _prefs.c_ just has _prefs.c_ as the file name) you’d run it as: +[source,sh] ---- $ 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.mine/prefs.c_, you’d run it with: +[source,sh] ---- $ patch -p1 < new.diff ---- @@ -1007,6 +1023,7 @@ more in-depth discussion of the build process. In the wireshark directory, type: +[source,sh] ---- $ dpkg-buildpackage -rfakeroot -us -uc ---- @@ -1040,6 +1057,7 @@ usual Wireshark `./configure`. The exceptions to this rule are: In the wireshark directory, type: +[source,sh] ---- $ 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 CMake. In your build directory, type: +[source,sh] ---- $ 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, 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.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 _portableapps_package_ target, e.g. +[source,cmd] ---- > msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj > msbuild /m /p:Configuration=RelWithDebInfo portableapps_package.vcxproj diff --git a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc index 953e58dc29..bebdfb4d95 100644 --- a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc +++ b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc @@ -40,8 +40,8 @@ tested. 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 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 -**toolname**+. +for the UNIX based tools with `**toolname** --help` or the man page via `man +**toolname**`. You will find explanations of the tool usage for some of the specific development tasks in <>. @@ -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 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 ---- or a Powershell prompt: +[source,cmd] ---- 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. To install Cygwin itself run +[source,cmd] ---- PS$>choco install cygwin # 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`: +[source,cmd] ---- 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 run the following commands: +[source,sh] ---- # Starting from your Wireshark source directory, create a build directory # alongside it. @@ -260,6 +265,7 @@ http://gcc.gnu.org/[]. After correct installation, typing at the bash command line prompt: +[source,sh] ---- $ gcc --version ---- @@ -292,6 +298,7 @@ http://www.gnu.org/software/gdb/gdb.html[]. After correct installation: +[source,sh] ---- $ gdb --version ---- @@ -347,6 +354,7 @@ http://www.gnu.org/software/make/[]. After correct installation: +[source,sh] ---- $ make --version ---- @@ -458,6 +466,7 @@ requires a a {cpp} redistributable You can use Chocolatey to install Visual Studio, e.g: +[source,cmd] ---- PS:\> choco install VisualStudioCommunity2013 ---- @@ -479,6 +488,7 @@ versions ordered by release date. After correct installation of the toolchain, typing at the Visual Studio Command line prompt (cmd.exe): +[source,cmd] ---- > 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): +[source,cmd] ---- > link ---- @@ -522,7 +533,6 @@ http://msdn.microsoft.com/en-us/library/t2fck18t.aspx[Microsoft MSDN] [[msvc-runtime-redistributable]] - ==== C-Runtime "Redistributable" Files 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 Studio from the same command prompt, e.g. +[source,cmd] ---- C:\Development\wsbuild32>set PATH="%PATH%;C:\Development\wsbuild32\run\RelwithDebInfo" C:\Development\wsbuild32>wireshark.sln @@ -702,6 +713,7 @@ C:\Development\wsbuild32>wireshark.sln for PowerShell use +[source,cmd] ---- PS C:\Development\wsbuild32>$env:PATH += ";$(Convert-Path run\RelWithDebInfo)" 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: +[source,cmd] ---- 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: +[source,sh] ---- $ bash --version ---- @@ -805,12 +819,14 @@ a symbolic link, which causes confusion outside Cygwin. You can also use Chocolatey to install Python: +[source,cmd] ---- PS:\> choco install Python3 ---- or +[source,cmd] ---- PS:\> choco install Python2 ---- @@ -818,12 +834,14 @@ PS:\> choco install Python2 Chocolatey installs Python into _C:\tools\python3_ or _C:\tools\python2_ by default. You can verify your Python version by running +[source,sh] ---- $ python --version ---- on UNIX and Linux and +[source,cmd] ---- rem Official package C:> cd python35 @@ -867,6 +885,7 @@ http://www.perl.com/[]. After correct installation, typing at the bash command line prompt: +[source,sh] ---- $ 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 +[source,sh] ---- $ bison --version ---- @@ -1000,6 +1020,7 @@ you can get it at http://www.gnu.org/software/flex/[]. After correct installation running the following +[source,sh] ---- $ 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 _win_flex_. +[source,cmd] ---- 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: +[source,sh] ---- $ git --version ---- @@ -1064,18 +1087,19 @@ $ git --version should result in something like: ---- -git version 1.8.3.4 +git version 2.14.1 ---- Your version will likely be different. [[ChToolsWindowsGit]] -==== Windows native: git +==== Windows Native: git The Git command line tools for Windows can be found at http://git-scm.com/download/win[] and can also be installed using Chocolatey: +[source,cmd] ---- PS:\> choco install git ---- @@ -1083,14 +1107,15 @@ PS:\> choco install git After correct installation, typing at the command line prompt (cmd.exe): +[source,cmd] ---- -$ git --version +> git --version ---- should result in something like: ---- -git version 1.8.3.4 +git version 2.16.1.windows.1 ---- 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 copy status. You can install it using Chocolatey: +[source,cmd] ---- PS:\>choco install poshgit ---- @@ -1148,6 +1174,7 @@ http://www.gnu.org/software/patch/patch.html[]. After correct installation, typing at the bash command line prompt: +[source,sh] ---- $ 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 required in the future. You can also install it using Chocolatey: +[source,cmd] ---- PS$> choco install nsis ----