Rework Windows Wireshark Qt build configuration a bit:
[obnox/wireshark/wip.git] / 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.6
14 (XCode gcc), Windows 7 x86 (Visual C++ 2010), and Ubuntu 10.04 (gcc).
15 Compilation via Qt Creator has been tested but command-line compilation using
16 QMake and make or nmake should work.
17
18 The ui/qt directory is loosely coupled with the rest of the codebase. The main
19 Wireshark sources must be built beforehand using CMake on Linux and OS X and
20 nmake on Windows. Autotools + QMake is a basket full of crazy that hasn't yet
21 been sorted and folded.  (Autotools + Boring Old Make, without using
22 QMake at all, might actually be simpler:
23
24         http://www.mail-archive.com/automake@gnu.org/msg11149.html
25
26 Work is in progress on this.)
27
28 1.1 Prerequisites
29
30 Before compiling you need the Qt SDK and Qt Creator.
31
32 1.1.1 OS X
33
34 Download the latest Qt SDK (currently 1.1.4) and install it. Build the
35 top-level directory using CMake.
36
37 1.1.2 Windows
38
39 The default Qt SDK libraries are built using MinGW, which isn't supported for
40 Wireshark. Instead of downloading the Qt SDK all-in-one package, download the
41 Qt Libraries package that matches your compiler (VS 2008 or VS 2010) and Qt
42 Creator for Windows.
43
44 Settings in config.nmake are passed to the Qt environment via
45 ui/qt/config.pri. This file should be created automatically when you
46 compile Wireshark in the top-level source directory. You can create it
47 by hand by running "nmake -f Makefile.nmake ui\qt\config.pri".
48
49 Qt Creator can be used to compile and run Wireshark.
50 Alternatively qmake and nmake at the cmd line can be used.
51
52 The Windows Qt version of Wireshark will be compiled and linked with essentially
53 the same options as that used when building the Gtk version of Wireshark.
54
55 1.1.2.1 Qt Creator
56
57 Before compiling in Qt Creator select "Projects" in the left toolbar,
58 select "Build Settings" and do the following:
59
60 - In "Edit build configuration" make sure the "Release" build is selected.
61   (The "Debug" build won't work unless Wireshark is recompiled to link with a "debug"
62    the "debug" C runtime library (using /MDd). See ui\qt\QtShark.pro for details).
63
64 - Make sure "Qt version" matches your version of Visual Studio.
65 - Make sure "Tool chain" matches your Visual C++ version.
66
67 If you require plugin support select "Run Settings" and add
68 "WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1" to the Run Environment.
69
70 XXX: (WMeier): I've not had too much satisfaction using the "native Windows debugger" (CDB ?)
71      accessed via Qt Creator. (In fact, a web search turns up some fairly negative comments
72      about the debugger. I've successfully (and pretty easily) been able to use the
73      Visual Studio debugger; See below under "Command Line".
74      ToDo: Investigate "Qt Visual Studio AddIn":
75            http://developer.qt.nokia.com/wiki/QtVSAddin#6112edd2e39a1695c242723d5c764aae
76
77 1.1.2.2 Command Line
78
79 - Setup environment:
80     c:\qt\4.8.0\bin\qtvars.bat [vsvars]     ;;; optional 'vsvars' to also setup VC env vars
81
82 - [Create and] Switch to a working dir to be used for .obj files, etc for Wireshark-qt compilation
83
84 - Use qmake to create Windows Makefile (based upon info in ui\qt\QtShark.pro and config.pri)
85     qmake -o Makefile.nmake ...\ui\qt\QtShark.pro
86                                   ;; (Only needs to be run once;
87                                   ;; nmake -f Makefile.nmake  will redo qmake if any
88                                   ;; dependendencies (e.g., QtShark.pro) change.
89
90 - Compile & Build
91     nmake -f Makefile.nmake       ;; Wireshark.exe + all DLL's will be in <working-dir>\wireshark-qt
92 - Run:
93     <working-dir>\wireshark
94
95 - Debug (with Visual Studio debugger)
96     Start Visual Studio;
97     File ! Open ! Project/Solution  ! .../<working-dir>/wireshark-qt/wireshark.exe
98     (Using  Solution Explorer ! Properties ! Environment to
99      add PATH=C:\Qt\4.8.0\bin;%PATH% will pobably be required).
100     ... Debug in the usual manner
101
102
103 1.1.3 Linux
104
105 Install the Qt libraries and Qt Creator via your package manager or from
106 http://qt.nokia.com/downloads/. On Debian and Ubuntu the "qt-sdk" meta-package
107 should provide everything you need. Build the top-level directory using CMake
108 (no out of tree builds yet). Inside ui/qt/ do "qtcreate QtShark.pro".
109
110
111 2. Going forward
112
113 DO NOT simply port things over. Every feature, window, and element should be
114 re-thought. For example, should the user have to navigate two dialogs to get
115 HTTP request statistics?