nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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.7 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=Debug" or
25 "-D ENABLE_GTK3=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 Note that Qt Creator uses output created by the CodeBlocks generator. If
30 you run CMake outside of Qt Creator you should use the "CodeBlocks - Unix
31 Makefiles" or "CodeBlocks - NMake Makefiles" generators, otherwise Qt
32 Creator will prompt you to re-run CMake.
33  
34 2) CMake:
35  
36 Qt (BUILD_wireshark) is enabled by default. Use the "cmake" command to
37 configure a normal out-of-tree or in-tree build, e.g.
38  
39 mkdir cmakebuild
40 cd cmakebuild
41 cmake
42 make
43  
44 Note that CMake builds an application bundle (Wireshark.app) on OS X
45 by default. Use the option "-DENABLE_APPLICATION_BUNDLE=OFF" to create a
46 traditional UNIX/POSIX build.
47  
48 3) Autotools:
49  
50 Qt (--with-qt) is enabled by default.
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 Build the top-level directory using CMake or autotools (see section
64 "Getting up and running" above).
65  
66 1.1.2 Windows
67  
68 Download the Qt online installer from http://www.qt.io/download-open-source/
69 and run it. Install a version of Qt that matches your compiler, e.g.
70 "msvc2013 64-bit OpenGL". Install Qt Creator as well. Wireshark doesn't
71 require anything beyond that.
72  
73 1.1.2.1 Qt Creator
74  
75 Before compiling in Qt Creator select "Projects" in the left toolbar,
76 select "Build Settings" and do the following:
77  
78 - In "Edit build configuration" make sure the "Release" build is selected.
79 (The "Debug" build won't work unless Wireshark is recompiled to link with a "debug"
80 the "debug" C runtime library (using /MDd)).
81  
82 - Make sure "Qt version" matches your version of Visual Studio.
83 - Make sure "Tool chain" matches your Visual C++ version.
84  
85 If you require plugin support select "Run Settings" and add
86 "WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1" to the Run Environment.
87  
88 XXX: (WMeier): I've not had too much satisfaction using the "native Windows debugger" (CDB ?)
89 accessed via Qt Creator. (In fact, a web search turns up some fairly negative comments
90 about the debugger. I've successfully (and pretty easily) been able to use the
91 Visual Studio debugger; See below under "Command Line".
92 ToDo: Investigate "Qt Visual Studio AddIn":
93 http://developer.qt.nokia.com/wiki/QtVSAddin#6112edd2e39a1695c242723d5c764aae
94  
95 1.1.2.2 Command Line
96  
97 - [Create and] Switch to a working dir to be used for .obj files, etc for Wireshark-qt compilation
98  
99 - Use CMake to create Windows Makefile and compile (see README.cmake)
100  
101 - Run:
102 <working-dir>\wireshark-qt-debug
103  
104 - Debug (with Visual Studio debugger)
105 Start Visual Studio;
106 File ! Open ! Project/Solution ! .../<working-dir>/wireshark-qt-debug/wireshark.exe
107 (Using Solution Explorer ! Properties ! Environment to
108 add PATH=C:\Qt\4.8.0\bin;%PATH% will probably be required).
109 ... Debug in the usual manner
110  
111  
112 1.1.3 Linux
113  
114 Install the Qt libraries and Qt Creator via your package manager or from
115 http://qt-project.org/downloads/. On Debian, Ubuntu, and other Debian
116 derivatives, the "qt-sdk" (and qttools5-dev when use Qt5) meta-package
117 should provide everything you need.
118  
119 Build the top-level directory using CMake or autotools (see section
120 "Getting up and running" above).
121  
122 1.1.4 Other UN*Xes
123  
124 For the *BSDs, if the ports collection/packages collection has Qt,
125 install the Qt libraries and Qt Creator via packages.
126  
127 For Solaris, install the Qt libraries and Qt Creator via OpenCSW or, for
128 Solaris 11, the Image Packaging System.
129  
130 Otherwise, download the source from http://qt-project.org/downloads/ and
131 compile and install it.
132  
133 Build the top-level directory using CMake or autotools (see section
134 "Getting up and running" above).
135  
136 1.2 Other tools
137  
138 GammaRay lets you inspect the internals of a running Qt application
139 similar to Spy++ on Windows.
140  
141 http://www.kdab.com/kdab-products/gammaray/
142  
143 2. Going forward
144  
145 DO NOT simply port things over. Much of the GTK+ interface reflects historical
146 UI conventions and API restrictions which are either no longer relevant or have
147 been superseded. Every feature, window, and element should be re-thought. When
148 porting a feature, consider the following:
149  
150 - Workflow. Excessive navigation and gratuitous dialogs should be avoided or
151 reduced. For example, the two GTK+ flow graph dialogs have been combined into
152 one in Qt. Many alert dialogs have been replaced with status bar messages.
153  
154 - Feedback. Most of the Qt dialogs provide a "hint" area near the bottom which
155 shows useful information. For example, the "Follow Stream" dialog shows the
156 packet corresponding to the text under the mouse. The profile management
157 dialog shows a clickable path to the current profile.
158  
159 2.1 Coding guidelines
160  
161 Moved to the Developer's Guide:
162  
163 https://www.wireshark.org/docs/wsdg_html_chunked/ChUIQt.html
164  
165  
166 2.2 Changes
167  
168 - The display filter entry has been significantly reworked.
169  
170 - The welcome screen has been reworked. The interface list includes sparklines
171  
172 - "Go to packet" pops up a text entry in the main window instead of a separate dialog.
173  
174 - Preferences are complete, and are arguably more useful than the GTK+ version.
175 An "Advanced" preference pane exists, which lets you edit everything. They use
176 the proper menu placement and keyboard shortcut on OS X.
177  
178 - Some dialogs (file sets, profiles, and UATs) provide a link to filesystem paths
179 where appropriate.
180  
181 3. Translations (i18n)
182  
183 3.1 Make translation
184  
185 Qt makes translating the Wireshark UI into different languages easy.
186  
187 - Add your translation (ui/qt/wireshark_XX.ts) in ui/qt/Makefile.am and ui/qt/CMakeLists.txt
188 - Please add flag (image) for your language in images/languages/XX.svg and image/languages/languages.qrc
189 - Run "lupdate ui/qt -ts ui/qt/wireshark_XX.ts" to generate/update your translation file.
190 - Translate with Qt Linguist (in console: "linguist ui/qt/wireshark_XX.ts")
191 - Do a test build and make sure the generated wireshark_XX.qm binary file is included.
192 - Push your translation to Gerrit for review ("git push").
193  
194 Alternatively you can only put your QM and flag files in "languages" directory in
195 Wireshark user configuration directory (~/.wireshark/languages/ on unix)
196  
197 More information about Qt Linguist
198 http://qt-project.org/doc/qt-4.8/linguist-manual.html
199  
200 3.2 Translate !
201  
202 You can now directly translate with Transifex Website
203 https://www.transifex.com/projects/p/wireshark/
204  
205 Every week, translation is automatically resynced with the source code through the following steps
206 * pull ts from Transifex
207 * lupdate ts file
208 * push and commit on Gerrit
209 * push ts on Transifex
210  
211 4 Developing
212  
213 Moved to the Developer's Guide:
214  
215 https://www.wireshark.org/docs/wsdg_html_chunked/ChUIQt.html