KDELibs4Support

kdebug.h
1 /* This file is part of the KDE libraries
2  Copyright (C) 1997 Matthias Kalle Dalheimer ([email protected])
3  2000-2002 Stephan Kulow ([email protected])
4  2002 Holger Freyther ([email protected])
5 
6  This library is free software; you can redistribute it and/or
7  modify it under the terms of the GNU Library General Public
8  License as published by the Free Software Foundation; either
9  version 2 of the License, or (at your option) any later version.
10 
11  This library is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  Library General Public License for more details.
15 
16  You should have received a copy of the GNU Library General Public License
17  along with this library; see the file COPYING.LIB. If not, write to
18  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19  Boston, MA 02110-1301, USA.
20 */
21 
22 #ifndef _KDEBUG_H_
23 #define _KDEBUG_H_
24 
25 #include <kdelibs4support_export.h>
26 
27 #ifdef KDELIBS4SUPPORT_NO_DEPRECATED_NOISE
28 #warning "This file is deprecated."
29 #endif
30 
31 #include <QDebug>
32 #include <QElapsedTimer>
33 
34 /**
35  * \addtogroup kdebug Debug message generators
36  * @{
37  * KDE debug message streams let you and the user control just how many debug
38  * messages you see. Debug message printing is controlled by (un)defining
39  * QT_NO_DEBUG when compiling your source. If QT_NO_DEBUG is defined then debug
40  * messages are not printed by default but can still be enabled by runtime
41  * configuration, e.g. via kdebugdialog5 or by editing kdebugrc.
42  *
43  * You can also control what you see: see QT_MESSAGE_PATTERN in the QDebug documentation.
44  * This is new in Qt 5.0 and replaces the KDE_DEBUG_* variables from KDE 4.x.
45  */
46 
47 #if !defined(KDE_NO_DEBUG_OUTPUT)
48 # if defined(QT_NO_DEBUG_OUTPUT) || defined(QT_NO_DEBUG_STREAM)
49 # define KDE_NO_DEBUG_OUTPUT
50 # endif
51 #endif
52 
53 #if !defined(KDE_NO_WARNING_OUTPUT)
54 # if defined(QT_NO_WARNING_OUTPUT)
55 # define KDE_NO_WARNING_OUTPUT
56 # endif
57 #endif
58 
59 #ifdef QT_NO_DEBUG /* The application is compiled in release mode */
60 # define KDE_DEBUG_ENABLED_BY_DEFAULT false
61 #else
62 # define KDE_DEBUG_ENABLED_BY_DEFAULT true
63 #endif
64 
65 /**
66  * An indicator of where you are in a source file, to be used in
67  * warnings (perhaps debug messages too).
68  * @deprecated kDebug takes care of printing the method name automatically now
69  */
70 #define k_funcinfo ""
71 
72 /**
73  * An indicator of where you are in a source file, to be used in
74  * warnings (perhaps debug messages too). Gives an accurate
75  * idea of where the message comes from. Not suitable for
76  * user-visible messages.
77  * @deprecated kDebug takes care of printing the method name automatically now
78  */
79 #define k_lineinfo "[" << __FILE__ << ":" << __LINE__ << "] "
80 
81 /**
82  * @internal
83  * Returns a debug stream that may or may not output anything.
84  */
85 KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE QDebug kDebugStream(QtMsgType level, int area, const char *file = nullptr,
86  int line = -1, const char *funcinfo = nullptr);
87 
88 /**
89  * @internal
90  * Returns a debug stream that goes the way of the blackhole.
91  */
92 KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE QDebug kDebugDevNull();
93 
94 /**
95  * @internal
96  * The actual backtrace.
97  */
98 KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE QString kRealBacktrace(int);
99 
100 /**
101  * \relates KGlobal
102  * Returns a backtrace.
103  * Note: Hidden symbol visibility may negatively affect the information provided
104  * by kBacktrace - you may want to pass -D__KDE_HAVE_GCC_VISIBILITY=0 to cmake
105  * to turn hidden symbol visibility off.
106  * @param levels the number of levels of the backtrace
107  * @return a backtrace
108  */
109 #if !defined(KDE_NO_DEBUG_OUTPUT)
110 inline QString kBacktrace(int levels = -1)
111 {
112  return kRealBacktrace(levels);
113 }
114 #else
115 static inline QString kBacktrace(int = -1)
116 {
117  return QString();
118 }
119 #endif
120 
121 /**
122  * \relates KGlobal
123  * Deletes the kdebugrc cache and therefore forces KDebug to reread the
124  * config file
125  */
126 KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE void kClearDebugConfig();
127 
128 #ifndef KDE_DEFAULT_DEBUG_AREA
129 # define KDE_DEFAULT_DEBUG_AREA 0
130 #endif
131 
132 /*!
133  \macro KDE_DEFAULT_DEBUG_AREA
134  \relates KGlobal
135 
136  Denotes the debug area to use in kDebug/kWarning etc when not
137  explicitly specified. The default is 0 (zero).
138 
139  Define this macro to the debug area of your application/component
140  before including any KDE headers. Usually, you want to add code like
141  this to your \c CMakeLists.txt:
142 
143  \code
144  ...
145  add_definitions( -DKDE_DEFAULT_DEBUG_AREA=1234 )
146  ...
147  \endcode
148 
149  This way, you save repeating the debug area all over your source
150  code, in each debug/warning statement.
151 */
152 
153 #if !defined(KDE_NO_DEBUG_OUTPUT)
154 /**
155  * \relates KGlobal
156  * Returns a debug stream. You can use it to print debug
157  * information.
158  * @param area an id to identify the output, KDE_DEFAULT_DEBUG_AREA for default
159  */
160 static inline QDebug kDebug(int area = KDE_DEFAULT_DEBUG_AREA)
161 {
162  return kDebugStream(QtDebugMsg, area);
163 }
164 static inline QDebug kDebug(bool cond, int area = KDE_DEFAULT_DEBUG_AREA)
165 {
166  return cond ? kDebug(area) : kDebugDevNull();
167 }
168 
169 #else // KDE_NO_DEBUG_OUTPUT
170 static inline QDebug kDebug(int = KDE_DEFAULT_DEBUG_AREA)
171 {
172  return kDebugDevNull();
173 }
174 static inline QDebug kDebug(bool, int = KDE_DEFAULT_DEBUG_AREA)
175 {
176  return kDebugDevNull();
177 }
178 #endif
179 
180 #if !defined(KDE_NO_WARNING_OUTPUT)
181 /**
182  * \relates KGlobal
183  * Returns a warning stream. You can use it to print warning
184  * information.
185  * @param area an id to identify the output, KDE_DEFAULT_DEBUG_AREA for default
186  */
187 static inline QDebug kWarning(int area = KDE_DEFAULT_DEBUG_AREA)
188 {
189  return kDebugStream(QtWarningMsg, area);
190 }
191 static inline QDebug kWarning(bool cond, int area = KDE_DEFAULT_DEBUG_AREA)
192 {
193  return cond ? kWarning(area) : kDebugDevNull();
194 }
195 
196 #else // KDE_NO_WARNING_OUTPUT
197 static inline QDebug kWarning(int = KDE_DEFAULT_DEBUG_AREA)
198 {
199  return kDebugDevNull();
200 }
201 static inline QDebug kWarning(bool, int = KDE_DEFAULT_DEBUG_AREA)
202 {
203  return kDebugDevNull();
204 }
205 #endif
206 
207 /**
208  * \relates KGlobal
209  * Returns an error stream. You can use it to print error
210  * information.
211  * @param area an id to identify the output, KDE_DEFAULT_DEBUG_AREA for default
212  */
213 static inline QDebug kError(int area = KDE_DEFAULT_DEBUG_AREA)
214 {
215  return kDebugStream(QtCriticalMsg, area);
216 }
217 static inline QDebug kError(bool cond, int area = KDE_DEFAULT_DEBUG_AREA)
218 {
219  return cond ? kError(area) : kDebugDevNull();
220 }
221 
222 /**
223  * \relates KGlobal
224  * Returns a fatal error stream. You can use it to print fatal error
225  * information.
226  * @param area an id to identify the output, KDE_DEFAULT_DEBUG_AREA for default
227  */
228 static inline QDebug kFatal(int area = KDE_DEFAULT_DEBUG_AREA)
229 {
230  return kDebugStream(QtFatalMsg, area);
231 }
232 static inline QDebug kFatal(bool cond, int area = KDE_DEFAULT_DEBUG_AREA)
233 {
234  return cond ? kFatal(area) : kDebugDevNull();
235 }
236 
237 struct KDebugTag { }; ///! @internal just a tag class
238 typedef QDebug(*KDebugStreamFunction)(QDebug, KDebugTag); ///< @internal
239 inline QDebug operator<<(QDebug s, KDebugStreamFunction f)
240 {
241  return (*f)(s, KDebugTag());
242 }
243 
244 /**
245  * \relates KGlobal
246  * Print a message describing the last system error.
247  * @param s the debug stream to write to
248  * @return the debug stream (@p s)
249  * @see perror(3)
250  */
251 KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE QDebug perror(QDebug, KDebugTag);
252 
253 // operators for KDE types
254 class QUrl;
255 class KDateTime;
256 class QObject;
257 KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE QDebug operator<<(QDebug s, const KDateTime &time);
258 
259 #if 1 || defined(KDE3_SUPPORT)
260 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED
261 class KDELIBS4SUPPORT_DEPRECATED_NOISE kndbgstream { };
262 typedef QDebug kdbgstream;
263 
264 static inline KDELIBS4SUPPORT_DEPRECATED_NOISE QDebug kdDebug(int area = KDE_DEFAULT_DEBUG_AREA)
265 {
266  return kDebug(area);
267 }
268 static inline KDELIBS4SUPPORT_DEPRECATED_NOISE QDebug kdWarning(int area = KDE_DEFAULT_DEBUG_AREA)
269 {
270  return kWarning(area);
271 }
272 static inline KDELIBS4SUPPORT_DEPRECATED_NOISE QDebug kdError(int area = KDE_DEFAULT_DEBUG_AREA)
273 {
274  return kError(area);
275 }
276 static inline KDELIBS4SUPPORT_DEPRECATED_NOISE QDebug kdFatal(int area = KDE_DEFAULT_DEBUG_AREA)
277 {
278  return kFatal(area);
279 }
280 inline KDELIBS4SUPPORT_DEPRECATED_NOISE QString kdBacktrace(int levels = -1)
281 {
282  return kBacktrace(levels);
283 }
284 
285 static inline KDELIBS4SUPPORT_DEPRECATED_NOISE QDebug kndDebug()
286 {
287  return kDebugDevNull();
288 }
289 #endif
290 #endif
291 
292 class WrongSyntax {};
293 
294 /**
295  * @internal
296  * A class for using operator()
297  */
298 class KDebug //krazy= ?
299 {
300  const char *file;
301  const char *funcinfo;
302  int line;
303  QtMsgType level;
304 public:
305  class Block;
306  KDELIBS4SUPPORT_DEPRECATED explicit inline KDebug(QtMsgType type, const char *f = nullptr, int l = -1, const char *info = nullptr)
307  : file(f), funcinfo(info), line(l), level(type)
308  {
309 #ifdef KDE4_CMAKE_TOPLEVEL_DIR_LENGTH // set by FindKDE4Internal.cmake
310  file = file + KDE4_CMAKE_TOPLEVEL_DIR_LENGTH + 1;
311 #endif
312  }
313 
314  inline QDebug operator()(int area = KDE_DEFAULT_DEBUG_AREA)
315  {
316  return kDebugStream(level, area, file, line, funcinfo);
317  }
318  inline QDebug operator()(bool cond, int area = KDE_DEFAULT_DEBUG_AREA)
319  {
320  if (cond) {
321  return operator()(area);
322  } return kDebugDevNull();
323  }
324 
325  /// @internal
326  static KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE bool hasNullOutput(QtMsgType type,
327  bool condition,
328  int area,
329  bool enableByDefault);
330 
331  /// @internal
332  static inline bool hasNullOutputQtDebugMsg(int area = KDE_DEFAULT_DEBUG_AREA)
333  {
334  return hasNullOutput(QtDebugMsg, true, area, KDE_DEBUG_ENABLED_BY_DEFAULT);
335  }
336  /// @internal
337  static inline bool hasNullOutputQtDebugMsg(bool condition, int area = KDE_DEFAULT_DEBUG_AREA)
338  {
339  return hasNullOutput(QtDebugMsg, condition, area, KDE_DEBUG_ENABLED_BY_DEFAULT);
340  }
341 
342  /**
343  * @since 4.4
344  * Register a debug area dynamically.
345  * @param areaName the name of the area
346  * @param enabled whether debug output should be enabled by default
347  * (users can override this in kdebugdialog5 or with DisableAll=true in kdebugrc)
348  * @return the area code that was allocated for this area
349  *
350  * Typical usage:
351  * If all uses of the debug area are restricted to a single class, add a method like this
352  * (e.g. into the Private class, if there's one)
353  * <code>
354  * static int debugArea() { static int s_area = KDebug::registerArea("areaName"); return s_area; }
355  * </code>
356  * Please do not use a file-static int, it would (indirectly) create KGlobal too early,
357  * create KConfig instances too early (breaking unittests which change QStandardPaths dirs), etc.
358  * By using a function as shown above, you make it all happen on-demand, rather than upfront.
359  *
360  * If all uses of the debug area are restricted to a single .cpp file, do the same
361  * but outside any class, and then use a more specific name for the function.
362  *
363  * If however multiple classes and files need the debug area, then
364  * declare it in one file without static, and use "extern int debugArea();"
365  * in other files (with a better name for the function of course).
366  */
367  static KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE int registerArea(const QByteArray &areaName, bool enabled = true);
368 
369 private:
370  WrongSyntax operator()(const char *)
371  {
372  return WrongSyntax(); // error! Use kDebug() << "..." or kWarning() << "..." instead.
373  }
374 };
375 
376 #if !defined(KDE_NO_DEBUG_OUTPUT)
377 /* __VA_ARGS__ should work with any supported GCC version and MSVC > 2005 */
378 # if defined(Q_CC_GNU) || (defined(Q_CC_MSVC) && _MSC_VER >= 1500)
379 # define kDebug(...) for (bool _k_kDebugDoOutput_ = !KDebug::hasNullOutputQtDebugMsg(__VA_ARGS__); \
380  Q_UNLIKELY(_k_kDebugDoOutput_); _k_kDebugDoOutput_ = false) \
381  KDebug(QtDebugMsg, __FILE__, __LINE__, Q_FUNC_INFO)(__VA_ARGS__)
382 # else
383 # define kDebug KDebug(QtDebugMsg, __FILE__, __LINE__, Q_FUNC_INFO)
384 # endif
385 #else
386 # define kDebug while (false) kDebug
387 #endif
388 #if !defined(KDE_NO_WARNING_OUTPUT)
389 # define kWarning KDebug(QtWarningMsg, __FILE__, __LINE__, Q_FUNC_INFO)
390 #else
391 # define kWarning while (false) kWarning
392 #endif
393 
394 #ifndef KDE_NO_DEBUG_OUTPUT
395 
396 /**
397  * @class KDebug::Block
398  * @short Use this to label sections of your code
399  * @since 4.6
400  *
401  * Usage:
402  * <code>
403  * void function()
404  * {
405  * KDebug::Block myBlock( "section" );
406  *
407  * debug() << "output1" << endl;
408  * debug() << "output2" << endl;
409  * }
410  * </code>
411  *
412  * Will output:
413  *
414  * app: BEGIN: section
415  * app: [prefix] output1
416  * app: [prefix] output2
417  * app: END: section - Took 0.1s
418  *
419  * Alternatively, use the KDEBUG_BLOCK macro, for automatic naming.
420  */
421 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KDebug::Block
422 {
423 public:
424  Block(const char *label, int area = KDE_DEFAULT_DEBUG_AREA);
425  ~Block();
426 
427 private:
428  QElapsedTimer m_startTime;
429  int m_area;
430  class Private;
431  Private *d;
432 };
433 
434 /**
435  * Convenience macro for making a standard KDebug::Block
436  */
437 #define KDEBUG_BLOCK KDebug::Block _kDebugBlock(Q_FUNC_INFO);
438 
439 #else
440 
441 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KDebug::Block
442 {
443 public:
444  Block(const char *, int = KDE_DEFAULT_DEBUG_AREA) {}
445  ~Block() {}
446 };
447 
448 #define KDEBUG_BLOCK
449 
450 #endif
451 
452 /**
453  * Convenience macro, use this to remind yourself to finish the implementation of a function
454  * The function name will appear in the output (unless $KDE_DEBUG_NOMETHODNAME is set)
455  * @since 4.6
456  */
457 #define KWARNING_NOTIMPLEMENTED kWarning() << "NOT-IMPLEMENTED";
458 
459 /**
460  * Convenience macro, use this to alert other developers to stop using a function
461  * The function name will appear in the output (unless $KDE_DEBUG_NOMETHODNAME is set)
462  * @since 4.6
463  */
464 #define KWARNING_DEPRECATED kWarning() << "DEPRECATED";
465 
466 /** @} */
467 
468 #endif
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE QDebug kDebugStream(QtMsgType level, int area, const char *file=nullptr, int line=-1, const char *funcinfo=nullptr)
Definition: kdebug.cpp:800
QDebug(* KDebugStreamFunction)(QDebug, KDebugTag)
!
Definition: kdebug.h:238
static bool hasNullOutputQtDebugMsg(bool condition, int area=KDE_DEFAULT_DEBUG_AREA)
Definition: kdebug.h:337
Use this to label sections of your code.
Definition: kdebug.h:421
KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE QString kRealBacktrace(int)
Definition: kdebug.cpp:768
static bool hasNullOutputQtDebugMsg(int area=KDE_DEFAULT_DEBUG_AREA)
Definition: kdebug.h:332
A class representing a date and time with an associated time zone.
Definition: kdatetime.h:148
Definition: kdebug.h:298
KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE QDebug kDebugDevNull()
Definition: kdebug.cpp:795
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Apr 9 2021 22:58:12 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.