Unit to send commands to a debug server process

Use dbugintf to add debug messages to your application. The messages are not sent to standard output, but are sent to a debug server process which collects messages from various clients and displays them somehow on screen.

The unit is transparant in its use: it does not need initialization, it will start the debug server by itself if it can find it: the program should be called debugserver and should be in the PATH. When the first debug message is sent, the unit will initialize itself.

The FCL contains a sample debug server (dbugsvr) which can be started in advance, and which writes debug message to the console (both on Windows and Linux). The Lazarus project contains a visual application which displays the messages in a GUI.

The dbugintf unit relies on the mechanism to communicate with the debug server, hence it works on all platforms that have a functional version of that unit. It also uses TProcess to start the debug server if needed, so the unit should also be functional.

Writing a debug server

Writing a debug server is relatively easy. It should instantiate a TSimpleIPCServer class from the unit, and use the DebugServerID as ServerID identification. This constant, as well as the record containing the message which is sent between client and server is defined in the msgintf unit.

The dbugintf unit relies on the mechanism to communicate with the debug server, hence it works on all platforms that have a functional version of that unit. It also uses TProcess to start the debug server if needed, so the unit should also be functional.

Level of the message. TDebugLevel indicates the severity level of the debug message to be sent. By default, an informational message is sent. Informational message Warning message Error message Send the value of a boolean variable SendBoolean is a simple wrapper around which sends the name and value of a boolean value as an informational message. None. Name of the boolean variable Value of the boolean variable. Send the value of a TDateTime variable. SendDateTime is a simple wrapper around which sends the name and value of an integer value as an informational message. The value is converted to a string using the DateTimeToStr call. None. Name of the TDateTime variable The actual date/time Send the value of an integer variable. SendInteger is a simple wrapper around which sends the name and value of an integer value as an informational message. If HexNotation is True, then the value will be displayed using hexadecimal notation. None. Name of the integer variable The actual value Format integer using hexadecimal notation Send the value of a pointer variable. SendInteger is a simple wrapper around which sends the name and value of a pointer value as an informational message. The pointer value is displayed using hexadecimal notation. None. Name of the pointer variable The actual pointer value Send debug message other than informational messages

SendDebugEx allows to specify the debug level of the message to be sent in MType. By default, uses informational messages.

Other than that the function of SendDebugEx is equal to that of SendDebug

None. Message to be sent Debug level of the message to be sent Send a message to the debug server.

SendDebug sends the message Msg to the debug server as an informational message (debug level dlInformation). If no debug server is running, then an attempt will be made to start the server first.

The binary that is started is called debugserver and should be somewhere on the PATH. A sample binary which writes received messages to standard output is included in the FCL, it is called dbugsrv. This binary can be renamed to debugserver or can be started before the program is started.

Errors are silently ignored, any exception messages are stored in . The message to be sent to the server. Send method enter message

SendMethodEnter sends a "Entering MethodName" message to the debug server. After that it increases the message indentation (currently 2 characters). By sending a corresponding , the indentation of messages can be decreased again.

By using the SendMethodEnter and SendMethodExit methods at the beginning and end of a procedure/method, it is possible to visually trace program execution.

None. Name of the entered method Send method exit message

SendMethodExit sends a "Exiting MethodName" message to the debug server. After that it decreases the message indentation (currently 2 characters). By sending a corresponding , the indentation of messages can be increased again.

By using the SendMethodEnter and SendMethodExit methods at the beginning and end of a procedure/method, it is possible to visually trace program execution.

Note that the indentation level will not be made negative.

None. Name of the method that is entered Send a separator message SendSeparator is a simple wrapper around which sends a short horizontal line to the debug server. It can be used to visually separate execution of blocks of code or blocks of values. None. Format and send a debug message SendDebugFmt is a utility routine which formats a message by passing Msg and Args to Format and sends the result to the debug server using . It exists mainly to avoid the Format call in calling code. None. Template for message Arguments to be inserted in template Format and send message with alternate type SendDebugFmtEx is a utility routine which formats a message by passing Msg and Args to Format and sends the result to the debug server using with Debug level MType. It exists mainly to avoid the Format call in calling code. None. Message template Arguments to insert in template Debug level of message Start the debug server

StartDebugServer attempts to start the debug server. The process started is called debugserver and should be located in the PATH.

Normally this function should not be called. The call will attempt to start the server by itself if it is not yet running.

On error, False is returned. True if started succesfully, false otherwise Initialize the debug client.

InitDebugClient starts the debug server and then performs all necessary initialization of the debug IPC communication channel.

Normally this function should not be called. The call will initialize the debug client when it is first called.

None. Last error in the debug system. Whenever a call encounteres an exception, the exception message is stored in this variable. String used when sending identification message to the server. String used when sending method enter message. String used when sending method exit message. String used when sending a separator line. Temporary enables or disables debugging

SetDebuggingEnabled can be used to temporarily enable or disable sending of debug messages: this allows to control the amount of messages sent to the debug server without having to remove the statements. By default, debugging is enabled. If set to false, debug messages are simply discarded till debugging is enabled again.

A value of True enables sending of debug messages. A value of False disables sending.

None. Should sending of debug messages be enabled or not Check if sending of debug messages is enabled. GetDebuggingEnabled returns the value set by the last call to SetDebuggingEnabled. It is True by default. True if sending debug messages is currently enabled. True if the client was successfully started. String used to display an error message when the start of the debug server failed