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 has been compiled and tested on Mac OS X 10.8
  14 (XCode LLVM/clang), Windows 7 x86 (Visual C++ 2010), and Ubuntu 12.04 (gcc).
  15 Compilation via Qt Creator and via the command line compilation using QMake and
  16 make or nmake should work.
  17
  18 There are several ways of building qtshark:
  19
  20 1) Using qtcreator:
  21
  22    The ui/qt directory is loosely coupled with the rest of the codebase.
  23    The main Wireshark sources must be built beforehand using CMake on Linux
  24    and OS X and nmake on Windows. Autotools + QMake is a basket full of
  25    crazy that hasn't yet been sorted and folded.  (Autotools + Boring Old
  26    Make, without using QMake at all, might actually be simpler:
  27
  28     http://www.mail-archive.com/automake@gnu.org/msg11149.html
  29
  30 2) Using cmake:
  31    set BUILD_qtshark to ON (default: OFF) in CmakeOptions.txt (may be set
  32    in parallel with BUILD_wireshark) or add -DBUILD_qtshark=YES flag
  33    Do the normal out-of-tree or in-tree build.
  34    To build with Qt5 instead of Qt4, add the following option set ENABLE_QT5
  35    to ON. Note: Qt5 requires cmake 2.8.3 or newer.
  36    This has only been tested on a current openSUSE Linux system with fairly
  37    current QT and cmake. It may be necessary to copy the FindQt4.cmake and
  38    supporting files from cmake to Wireshark's cmake/modules/
  39    If using cmake installing qtcreator is not required. Basically almost
  40    all stuff below can be ignored ;-)
  41
  42 3) Using autotools:
  43
  44    Pass --with-qt to the configure script and build.
  45
  46 Work is in progress on this.)
  47
  48 1.1 Prerequisites
  49
  50 Before compiling you need the Qt SDK and Qt Creator.
  51
  52 1.1.1 OS X
  53
  54 Download the latest Qt Library + Qt Creator (currently 5.1) from
  55 http://qt-project.org/downloads/ and install it. For a more native
  56 look and feel you should also install Qt Mac Extras:
  57
  58     git clone http://qt.gitorious.org/qt/qtmacextras.git
  59     cd qtmacextras
  60     /path/to/qt5/qmake qtmacextras.pro
  61     make
  62     make -n install
  63     # Make sure install output looks sensible
  64     make install
  65
  66 This may or may not work for you; see
  67
  68     https://bugreports.qt-project.org/browse/QTBUG-32594
  69
  70 1.1.2 Windows
  71
  72 The default Qt SDK libraries are built using MinGW, which isn't supported for
  73 Wireshark. Instead of downloading the Qt SDK all-in-one package, download the Qt
  74 Libraries package from http://qt-project.org/downloads/ that matches your
  75 compiler (VS 2010 or VS 2012) and Qt Creator for Windows.
  76
  77 Settings in config.nmake are passed to the Qt environment via
  78 ui/qt/config.pri. This file should be created automatically when you
  79 compile Wireshark in the top-level source directory. You can create it by
  80 hand by running "nmake -f Makefile.nmake ui\qt\config.pri".
  81
  82 Qt Creator can be used to compile and run Wireshark.  Alternatively qmake
  83 and nmake at the cmd line can be used.
  84
  85 The Windows Qt version of Wireshark will be compiled and linked with
  86 essentially the same options as that used when building the Gtk version of
  87 Wireshark.
  88
  89 1.1.2.1 Qt Creator
  90
  91 Before compiling in Qt Creator select "Projects" in the left toolbar,
  92 select "Build Settings" and do the following:
  93
  94 - In "Edit build configuration" make sure the "Release" build is selected.
  95   (The "Debug" build won't work unless Wireshark is recompiled to link with a "debug"
  96    the "debug" C runtime library (using /MDd). See ui\qt\QtShark.pro for details).
  97
  98 - Make sure "Qt version" matches your version of Visual Studio.
  99 - Make sure "Tool chain" matches your Visual C++ version.
 100
 101 If you require plugin support select "Run Settings" and add
 102 "WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1" to the Run Environment.
 103
 104 XXX: (WMeier): I've not had too much satisfaction using the "native Windows debugger" (CDB ?)
 105      accessed via Qt Creator. (In fact, a web search turns up some fairly negative comments
 106      about the debugger. I've successfully (and pretty easily) been able to use the
 107      Visual Studio debugger; See below under "Command Line".
 108      ToDo: Investigate "Qt Visual Studio AddIn":
 109            http://developer.qt.nokia.com/wiki/QtVSAddin#6112edd2e39a1695c242723d5c764aae
 110
 111 1.1.2.2 Command Line
 112
 113 - Setup environment:
 114     c:\qt\4.8.0\bin\qtvars.bat [vsvars]     ;;; optional 'vsvars' to also setup VC env vars
 115
 116 - [Create and] Switch to a working dir to be used for .obj files, etc for Wireshark-qt compilation
 117
 118 - Use qmake to create Windows Makefile (based upon info in ui\qt\QtShark.pro and config.pri)
 119     qmake -o Makefile.nmake ..\..\ui\qt\QtShark.pro
 120                                   ;; (Only needs to be run once;
 121                                   ;; nmake -f Makefile.nmake  will redo qmake if any
 122                                   ;; dependendencies (e.g., QtShark.pro) change.
 123
 124 - Compile & Build
 125     nmake -f Makefile.nmake       ;; qtshark.exe + all DLL's will be in <working-dir>\wireshark-qt-debug
 126 - Run:
 127     <working-dir>\wireshark-qt-debug
 128
 129 - Debug (with Visual Studio debugger)
 130     Start Visual Studio;
 131     File ! Open ! Project/Solution  ! .../<working-dir>/wireshark-qt-debug/qtshark.exe
 132     (Using  Solution Explorer ! Properties ! Environment to
 133      add PATH=C:\Qt\4.8.0\bin;%PATH% will pobably be required).
 134     ... Debug in the usual manner
 135
 136
 137 1.1.3 Linux
 138
 139 Install the Qt libraries and Qt Creator via your package manager or from
 140 http://qt-project.org/downloads/. On Debian and Ubuntu the "qt-sdk" (and qttools5-dev when use Qt5) meta-package
 141 should provide everything you need. Build the top-level directory using CMake
 142 (see section "Using cmake" above). As an alternative do an in-tree build without
 143 QT and then inside ui/qt/ do "qtcreate QtShark.pro".
 144
 145 1.2 Other tools
 146
 147 GammaRay lets you inspect the internals of a running Qt application
 148 similar to Spy++ on Windows.
 149
 150 http://www.kdab.com/kdab-products/gammaray/
 151
 152 2. Going forward
 153
 154 DO NOT simply port things over. Much of the GTK+ interface reflects historical
 155 UI conventions and API restrictions which are either no longer relevant or have
 156 been superseded. Every feature, window, and element should be re-thought. When
 157 porting a feature, consider the following:
 158
 159 - Workflow. Excessive navigation and gratuitous dialogs should be avoided or
 160   reduced. For example, the two GTK+ flow graph dialogs have been combined into
 161   one in Qt. Many alert dialogs have been replaced with status bar messages.
 162
 163 - Feedback. Most of the Qt dialogs provide a "hint" area near the bottom which
 164   shows useful information. For example, the "Follow Stream" dialog shows the
 165   packet corresponding to the text under the mouse. The profile management
 166   dialog shows a clickable path to the current profile.
 167
 168 2.1 Coding guidelines
 169
 170 2.1.1 Name conventions
 171
 172 Most of the code in the ui/qt directory uses three APIs: Qt (which uses
 173 InterCapConvention), GLib (which uses underscore_convention), and the Wireshark
 174 API (which also uses underscore_convention). As a general rule Wireshark's Qt
 175 code uses InterCapConvention for class names and methods and
 176 underscore_convention for variables, with a trailing underscore for member
 177 variables.
 178
 179 2.1.2 Mixing C and C++
 180
 181 Sometimes we have to call C++ functions from one of Wireshark's C callbacks and
 182 pass C++ objects to or from C. The C++ FAQ describes how to do this safely:
 183
 184 http://www.parashift.com/c++-faq/mixing-c-and-cpp.html
 185
 186 2.2 Changes
 187
 188 - The display filter entry has been significantly reworked.
 189
 190 - The welcome screen has been reworked. The interface list includes sparklines
 191
 192 - "Go to packet" pops up a text entry in the main window instead of a separate dialog.
 193
 194 - Preferences are complete, and are arguably more useful than the GTK+ version.
 195   An "Advanced" preference pane exists, which lets you edit everything. They use
 196   the proper menu placement and keyboard shortcut on OS X.
 197
 198 - Some dialogs (file sets, profiles, and UATs) provide a link to filesystem paths
 199   where appropriate.
 200
 201 3. Translations (i18n)
 202 For make your own translation of QtShark ! it is easy !
 203
 204 - Add your translation (qtshark_XX.ts) in QtShark.pro, i18n.qrc, ui/qt/Makefile.common
 205     and ui/qt/CMakeList.txt
 206 - Add also in epan/prefs.c, in ui/qt/main.cpp add case in switch(prefs_p->gui_qt_language)
 207     and in main_windows_preferences_frame.ui (use qt-design) to add in prefs
 208 - Launch "lupdate QtShark.pro" to generate/update your translation file
 209 - Translate with Qt Linguist
 210 - Launch "lrelease QtShark.pro" to create/update qtshark_xx.qm file
 211 - Attach your modification ("svn diff") in Wireshark Bug Tracker
 212
 213 More information about Qt Linguist
 214 http://qt-project.org/doc/qt-4.8/linguist-manual.html