git.saurik.com Git - wxWidgets.git/blame_incremental - docs/doxygen/overviews/debugging.h

... / ...

Commit	Line	Data
	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: debugging
	3	// Purpose: topic overview
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/*!
	10
	11	@page debugging_overview Debugging overview
	12
	13	Classes, functions and macros: #wxDebugContext, #wxObject, #wxLog,
	14	@ref logfunctions_overview, @ref debugmacros_overview
	15	Various classes, functions and macros are provided in wxWidgets to help you debug
	16	your application. Most of these are only available if you compile both wxWidgets,
	17	your application and @e all libraries that use wxWidgets with the __WXDEBUG__ symbol
	18	defined. You can also test the __WXDEBUG__ symbol in your own applications to execute
	19	code that should be active only in debug mode.
	20	@b wxDebugContext
	21	#wxDebugContext is a class that never gets instantiated, but ties together
	22	various static functions and variables. It allows you to dump all objects to that stream, write statistics about object allocation, and
	23	check memory for errors.
	24	It is good practice to define a wxObject::Dump member function for each class you derive
	25	from a wxWidgets class, so that wxDebugContext::Dump can call it and
	26	give valuable information about the state of the application.
	27	If you have difficulty tracking down a memory leak, recompile
	28	in debugging mode and call wxDebugContext::Dump and wxDebugContext::PrintStatistics at
	29	appropriate places. They will tell you what objects have not yet been
	30	deleted, and what kinds of object they are. In fact, in debug mode wxWidgets will automatically
	31	detect memory leaks when your application is about to exit, and if there are any leaks,
	32	will give you information about the problem. (How much information depends on the operating system
	33	and compiler -- some systems don't allow all memory logging to be enabled). See the
	34	memcheck sample for example of usage.
	35	For wxDebugContext to do its work, the @e new and @e delete
	36	operators for wxObject have been redefined to store extra information
	37	about dynamically allocated objects (but not statically declared
	38	objects). This slows down a debugging version of an application, but can
	39	find difficult-to-detect memory leaks (objects are not
	40	deallocated), overwrites (writing past the end of your object) and
	41	underwrites (writing to memory in front of the object).
	42	If debugging mode is on and the symbols wxUSE_GLOBAL_MEMORY_OPERATORS and
	43	wxUSE_DEBUG_NEW_ALWAYS are set to 1 in setup.h, 'new' is defined to be:
	44
	45
	46	@code
	47	#define new new(__FILE__,__LINE__)
	48	@endcode
	49
	50	All occurrences of 'new' in wxWidgets and your own application will use
	51	the overridden form of the operator with two extra arguments. This means that the debugging
	52	output (and error messages reporting memory problems) will tell you what
	53	file and on what line you allocated the object. Unfortunately not all
	54	compilers allow this definition to work properly, but most do.
	55	@b Debug macros
	56	You should also use @ref debugmacros_overview as part of a 'defensive programming' strategy,
	57	scattering wxASSERTs liberally to test for problems in your code as early as possible. Forward thinking
	58	will save a surprising amount of time in the long run.
	59	#wxASSERT is used to pop up an error message box when a condition
	60	is not @true. You can also use #wxASSERT_MSG to supply your
	61	own helpful error message. For example:
	62
	63
	64	@code
	65	void MyClass::MyFunction(wxObject* object)
	66	{
	67	wxASSERT_MSG( (object != @NULL), "object should not be @NULL in MyFunction!" );
	68
	69	...
	70	};
	71	@endcode
	72
	73
	74	The message box allows you to continue execution or abort the program. If you are running
	75	the application inside a debugger, you will be able to see exactly where the problem was.
	76	@b Logging functions
	77	You can use the #wxLogDebug and #wxLogTrace functions to output debugging information in debug mode;
	78	it will do nothing for non-debugging code.
	79	@ref debugcontext_overview
	80
	81
	82	@section wxdebugcontextoverview wxDebugContext overview
	83
	84	@ref debugging_overview
	85	Class: #wxDebugContext
	86	wxDebugContext is a class for performing various debugging and memory tracing
	87	operations.
	88	This class has only static data and function members, and there should be
	89	no instances. Probably the most useful members are SetFile (for directing output
	90	to a file, instead of the default standard error or debugger output);
	91	Dump (for dumping the dynamically allocated objects) and PrintStatistics
	92	(for dumping information about allocation of objects). You can also call
	93	Check to check memory blocks for integrity.
	94	Here's an example of use. The SetCheckpoint ensures that only the
	95	allocations done after the checkpoint will be dumped.
	96
	97	@code
	98	wxDebugContext::SetCheckpoint();
	99
	100	wxDebugContext::SetFile("c:\\temp\\debug.log");
	101
	102	wxString *thing = new wxString;
	103
	104	char *ordinaryNonObject = new char[1000];
	105
	106	wxDebugContext::Dump();
	107	wxDebugContext::PrintStatistics();
	108	@endcode
	109
	110	You can use wxDebugContext if __WXDEBUG__ is defined, or you can use it
	111	at any other time (if wxUSE_DEBUG_CONTEXT is set to 1 in setup.h). It is not disabled
	112	in non-debug mode because you may not wish to recompile wxWidgets and your entire application
	113	just to make use of the error logging facility.
	114	Note: wxDebugContext::SetFile has a problem at present, so use the default stream instead.
	115	Eventually the logging will be done through the wxLog facilities instead.
	116
	117	*/
	118
	119