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. Every feature, window, and element should be
 155 re-thought. For example, should the user have to navigate two dialogs to get
 156 HTTP request statistics?
 157
 158 2.1 Coding guidelines
 159
 160 2.1.1 Name conventions
 161
 162 Most of the code in the ui/qt directory uses three APIs: Qt (which uses
 163 InterCapConvention), GLib (which uses underscore_convention), and the Wireshark
 164 API (which also uses underscore_convention). As a general rule Wireshark's Qt
 165 code uses InterCapConvention for class names and methods and
 166 underscore_convention for variables, with a trailing underscore for member
 167 variables.
 168
 169 2.1.2 Mixing C and C++
 170
 171 Sometimes we have to call C++ functions from one of Wireshark's C callbacks and
 172 pass C++ objects to or from C. The C++ FAQ describes how to do this safely:
 173
 174 http://www.parashift.com/c++-faq/mixing-c-and-cpp.html
 175
 176 2.2 Changes
 177
 178 - The display filter entry has been significantly reworked.
 179
 180 - The welcome screen has been reworked. The interface list includes sparklines
 181
 182 - "Go to packet" pops up a text entry in the main window instead of a separate dialog.
 183
 184 - Preferences are complete, and are arguably more useful than the GTK+ version.
 185   An "Advanced" preference pane exists, which lets you edit everything. They use
 186   the proper menu placement and keyboard shortcut on OS X.
 187
 188 - Some dialogs (file sets, profiles, and UATs) provide a link to filesystem paths
 189   where appropriate.
 190
 191 3. Translations (i18n)
 192 For make your own translation of QtShark ! it is easy !
 193
 194 - Add your translation (qtshark_XX.ts) in QtShark.pro, i18n.qrc, ui/qt/Makefile.common
 195     and ui/qt/CMakeList.txt
 196 - Add also in epan/prefs.c, in ui/qt/main.cpp add case in switch(prefs_p->gui_qt_language)
 197     and in main_windows_preferences_frame.ui (use qt-design) to add in prefs
 198 - Launch "lupdate QtShark.pro" to generate/update your translation file
 199 - Translate with Qt Linguist
 200 - Launch "lrelease QtShark.pro" to create/update qtshark_xx.qm file
 201 - Attach your modification ("svn diff") in Wireshark Bug Tracker
 202
 203 More information about Qt Linguist
 204 http://qt-project.org/doc/qt-4.8/linguist-manual.html