Debugging Techniques

Development Environment

To debug a plugin during development start Cinema 4D from the used development environment. See Development for Windows, Development for macOS and Development for Linux.

IDE Console

When running in debug mode, Cinema 4D will print various debug messages to the IDE output console. These messages will include information on any issues with loaded modules and components.

Command Line Arguments

The behaviour of Cinema 4D can be configured using various command line arguments. An overview can be found in <C4D install dir>/resource/config.txt.

Custom command line arguments can be defined using configuration variables. See Configuration Variables.

Debug Mode

Cinema 4D can be run in debug mode using the command line argument g_alloc=debug. In debug mode Cinema 4D will provide all kinds of additional runtime information on the system console. For example it will check for and print out memory leaks. This will slow down Cinema 4D considerably, so the debug mode might only be enabled temporarily.

Note
It is advised for every plugin developer to use debug mode at least once before releasing a plugin, just to be sure about memory leaks.

Log File

The command line argument g_logfile is used to define a log file. All debug output will be written into that log file.

Console

The command line argument g_console can be set to "true" to open a debug console window.

Note
If Cinema 4D is attached to a parent process (e.g. stared from Visual Studio) one has to set g_consoleDebugger=true as well.

Debug Breaks

The argument g_enableDebugBreak can be used to disable debug stops. See Debug Stops below.

Printing Debug Messages

Message Functions

Several "output" functions allow to print debug messages:

Conversion To String

To print data to the console window it must be converted to a maxon::String. Most MAXON API data types already provide a ToString() function so they can simply be used with DiagnosticOutput(). Primitive data types can be converted to strings using dedicated functions of the maxon::String class.

See also FormatString(), String Manual and Output Syntax.

Error System

The MAXON API error system allows functions to return explicit error states. With this error system it is possible to:

  • handle errors returned by MAXON API functions.
  • print such errors to the debug console of the IDE.
  • create custom error types and to return errors from custom functions.

For an overview see Error System.

Asserts

Assert functions like DebugAssert() allow to simply check a given condition. If the condition is not fulfilled, an error is returned automatically. See Debug and Output Functions.

Memory Handling

It is advised to always use the Cinema 4D memory system. Allocated objects should be stored with smart pointers to avoid memory leaks. See Memory Allocation, References and Entity Creation and Destruction Manual (Classic).

Active Object Dialog Plugin

The example.main example project contains the Active Object Dialog plugin. This plugin allows to inspect the currently active scene in detail. It gives access to the used scene hooks and objects inside generator caches as well as dirty flags.

Debug Stops

When running in debug mode, Cinema 4D might trigger a debug stop in certain situations. Such a debug stop indicates a some wrong behaviour and is typically caused by incorrect arguments given to some functions. Such a debug stop is no crash; it can simply be skipped to continue a debugging sessions.

Source Processor

The Source Processor analyses the source code and creates new code. If the source processor detects certain errors it will print a message to the IDE's output console.

Compile Errors

The Source Processor automatically creates code needed for interfaces and other features of the MAXON API. A programming error can result in some issues with this automatically created code and some unintuitive compile and linker errors. Typical compile errors related to such issues are collected here:

ErrorPossible Cause
Ambiguous SymbolWhen mixing classic and MAXON API code certain symbols might not be unique. Use namespaces and take a look at the order of includes.
cannot access private member declared in class 'XXX'A function in an implementation class is not public.
hxx include missing for 'XXX'A header file defining some interface must include the automatically generated .hxx files.
Use of undeclared identifier 'tmperr_0'Within an error scope iferr_scope; is missing. See Error Handling.
Ignoring return value of function declared with warn_unused_result attributeThis typically means that an maxon::Result return value is not handled correctly. See Object Use and Error Handling.
Unused variable 'tmperr_0'::iferr_handle; is used without iferr_scope_handler. See Error Handling.

See also API Transition and Interface Basics.

Further Reading