doc/README.qt

   1 0. Abstract
   2
   3 Wireshark's user interface is showing its age. While GTK+ is wonderful on
   4 Linux and BSD its low-tier status on Windows and even-lower-tier status on OS
   5 X makes it hard to deliver a good product to users on those platforms.
   6
   7 The Qt port is an attempt at an updated UI which will better serve our users
   8 and let us add features more easily.
   9
  10
  11 1. Getting up and running
  12
  13 The Qt interface for Wireshark should compile out of the box on Windows, OS
  14 X, and Linux using Qt 4.6 or later (including Qt 5) and Visual C++, gcc/g++,
  15 and clang/clang++. The Qt UI is continuously built and tested at
  16 https://buildbot.wireshark.org/trunk/waterfall .
  17
  18 There are several ways of building the Qt UI:
  19
  20 1) Qt Creator + CMake (recommended if adding features):
  21
  22    Open the top-level CMakeLists.txt within Qt Creator. It should ask you to
  23    choose a build location. Do so. It should then ask you to run CMake. Fill in
  24    any desired build arguments (e.g. "-D CMAKE_BUILD_TYPE:STRING=Debug" or
  25    "-D ENABLE_GTK3:BOOL=OFF") and click the "Run CMake" button. When that
  26    completes select "Build → Open Build and Run Kit Selector..." and make
  27    sure wireshark is selected.
  28
  29 2) CMake:
  30
  31    Qt (BUILD_wireshark) is enabled by default. Use the "cmake" command to
  32    configure a normal out-of-tree or in-tree build, e.g.
  33
  34     mkdir cmakebuild
  35     cd cmakebuild
  36     cmake
  37     make
  38
  39    Note that CMake builds an application bundle (Wireshark.app) on Mac OS X
  40    by default. Use the option "-DENABLE_APPLICATION_BUNDLE=OFF" to create a
  41    traditional UNIX/POSIX build.
  42
  43 3) Autotools:
  44
  45    Qt (--with-qt) is enabled by default.
  46
  47 4) Qt Creator + Wireshark.pro:
  48
  49    Wireshark.pro (formerly QtShark.pro) was used to bootstrap the UI porting
  50    effort. It is still used by Nmake but will likely be removed at some point.
  51
  52 1.1 Prerequisites
  53
  54 Before compiling you need the Qt SDK and Qt Creator.
  55
  56 1.1.1 OS X
  57
  58 Download the latest Qt Library + Qt Creator from
  59 http://www.qt.io/download-open-source/. Qt 5.2 and later include
  60 Qt Mac Extras (http://doc.qt.io/qt-5/qtmacextras-index.html), which
  61 provides a better look and feel.
  62
  63 1.1.2 Windows
  64
  65 Download the Qt online installer from http://www.qt.io/download-open-source/
  66 and run it. Install a version of Qt that matches your compiler, e.g.
  67 "msvc2013 64-bit OpenGL". Install Qt Creator as well. Wireshark doesn't
  68 require anything beyond that.
  69
  70 1.1.2.1 Qt Creator
  71
  72 Before compiling in Qt Creator select "Projects" in the left toolbar,
  73 select "Build Settings" and do the following:
  74
  75 - In "Edit build configuration" make sure the "Release" build is selected.
  76   (The "Debug" build won't work unless Wireshark is recompiled to link with a "debug"
  77    the "debug" C runtime library (using /MDd). See ui\qt\Wireshark.pro for details).
  78
  79 - Make sure "Qt version" matches your version of Visual Studio.
  80 - Make sure "Tool chain" matches your Visual C++ version.
  81
  82 If you require plugin support select "Run Settings" and add
  83 "WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1" to the Run Environment.
  84
  85 XXX: (WMeier): I've not had too much satisfaction using the "native Windows debugger" (CDB ?)
  86      accessed via Qt Creator. (In fact, a web search turns up some fairly negative comments
  87      about the debugger. I've successfully (and pretty easily) been able to use the
  88      Visual Studio debugger; See below under "Command Line".
  89      ToDo: Investigate "Qt Visual Studio AddIn":
  90            http://developer.qt.nokia.com/wiki/QtVSAddin#6112edd2e39a1695c242723d5c764aae
  91
  92 1.1.2.2 Command Line
  93
  94 - Setup environment:
  95     c:\qt\4.8.0\bin\qtvars.bat [vsvars]     ;;; optional 'vsvars' to also setup VC env vars
  96
  97 - [Create and] Switch to a working dir to be used for .obj files, etc for Wireshark-qt compilation
  98
  99 - Use qmake to create Windows Makefile (based upon info in ui\qt\Wireshark.pro and config.pri)
 100     qmake -o Makefile.nmake ..\..\ui\qt\QtShark.pro
 101                                   ;; (Only needs to be run once;
 102                                   ;; nmake -f Makefile.nmake  will redo qmake if any
 103                                   ;; dependendencies (e.g., Wireshark.pro) change.
 104
 105 - Compile & Build
 106     nmake -f Makefile.nmake       ;; wireshark.exe + all DLL's will be in <working-dir>\wireshark-qt-debug
 107 - Run:
 108     <working-dir>\wireshark-qt-debug
 109
 110 - Debug (with Visual Studio debugger)
 111     Start Visual Studio;
 112     File ! Open ! Project/Solution  ! .../<working-dir>/wireshark-qt-debug/wireshark.exe
 113     (Using  Solution Explorer ! Properties ! Environment to
 114      add PATH=C:\Qt\4.8.0\bin;%PATH% will pobably be required).
 115     ... Debug in the usual manner
 116
 117
 118 1.1.3 Linux
 119
 120 Install the Qt libraries and Qt Creator via your package manager or from
 121 http://qt-project.org/downloads/. On Debian and Ubuntu the "qt-sdk" (and qttools5-dev when use Qt5) meta-package
 122 should provide everything you need. Build the top-level directory using CMake
 123 (see section "Using cmake" above). As an alternative do an in-tree build without
 124 QT and then inside ui/qt/ do "qtcreate Wireshark.pro".
 125
 126 1.2 Other tools
 127
 128 GammaRay lets you inspect the internals of a running Qt application
 129 similar to Spy++ on Windows.
 130
 131 http://www.kdab.com/kdab-products/gammaray/
 132
 133 2. Going forward
 134
 135 DO NOT simply port things over. Much of the GTK+ interface reflects historical
 136 UI conventions and API restrictions which are either no longer relevant or have
 137 been superseded. Every feature, window, and element should be re-thought. When
 138 porting a feature, consider the following:
 139
 140 - Workflow. Excessive navigation and gratuitous dialogs should be avoided or
 141   reduced. For example, the two GTK+ flow graph dialogs have been combined into
 142   one in Qt. Many alert dialogs have been replaced with status bar messages.
 143
 144 - Feedback. Most of the Qt dialogs provide a "hint" area near the bottom which
 145   shows useful information. For example, the "Follow Stream" dialog shows the
 146   packet corresponding to the text under the mouse. The profile management
 147   dialog shows a clickable path to the current profile.
 148
 149 2.1 Coding guidelines
 150
 151 Moved to the Developer's Guide:
 152
 153 https://www.wireshark.org/docs/wsdg_html_chunked/ChUIQt.html
 154
 155
 156 2.2 Changes
 157
 158 - The display filter entry has been significantly reworked.
 159
 160 - The welcome screen has been reworked. The interface list includes sparklines
 161
 162 - "Go to packet" pops up a text entry in the main window instead of a separate dialog.
 163
 164 - Preferences are complete, and are arguably more useful than the GTK+ version.
 165   An "Advanced" preference pane exists, which lets you edit everything. They use
 166   the proper menu placement and keyboard shortcut on OS X.
 167
 168 - Some dialogs (file sets, profiles, and UATs) provide a link to filesystem paths
 169   where appropriate.
 170
 171 3. Translations (i18n)
 172
 173 3.1 Make translation
 174
 175 Qt makes translating the Wireshark UI into different languages easy.
 176
 177 - Add your translation (ui/qt/wireshark_XX.ts) in ui/qt/Wireshark.pro, ui/qt/i18n.qrc,
 178     ui/qt/Makefile.common and ui/qt/CMakeLists.txt
 179 - Please add flag (image) for your language in images/languages/XX.svg and image/languages/languages.qrc
 180 - Run "lupdate ui/qt/Wireshark.pro" to generate/update your translation file.
 181   or "lupdate ui/qt -ts ui/qt/wireshark_XX.ts" for specified translation
 182 - Translate with Qt Linguist (in console: "linguist ui/qt/wireshark_XX.ts")
 183 - Run "lrelease Wireshark.pro" or
 184   "lrelease ui/qt/wireshark_XX.ts -qm ui/qt/wireshark_XX.qm" to create/update wireshark_XX.qm file.
 185 - Push your translation to Gerrit for review ("git push").
 186
 187 Alternatively you can only put your QM and flag files in "languages" directory in
 188 Wireshark user configuration directory (~/.wireshark/languages/ on unix)
 189
 190 More information about Qt Linguist
 191 http://qt-project.org/doc/qt-4.8/linguist-manual.html
 192
 193 3.2 Translate !
 194
 195 You can now directly translate with Transifex Website
 196 https://www.transifex.com/projects/p/wireshark/
 197
 198 Every week, translation is automatically resynced with the source code through the following steps
 199 * pull ts from Transifex
 200 * lupdate ts file
 201 * push and commit on Gerrit
 202 * push ts on Transifex
 203
 204 4 Developing
 205
 206 Moved to the Developer's Guide:
 207
 208 https://www.wireshark.org/docs/wsdg_html_chunked/ChUIQt.html