ocamldebug

ocamldebug [options] [program_name [args ...]]

-I directory
    Adds directory to the list of paths searched for source files and compiled interfaces (.cmi). Multiple -I options can be specified.

-c channel
    Connects to a remote process using the specified channel. Examples include inet:host:port for network connections or file:path for local sockets.

-output-channel channel
    Redirects all debugger output to the specified channel instead of standard output.

-port number
    Sets the TCP port number for remote debugging when ocamldebug acts as a server, listening for incoming connections from the debugged program.

-s
    Disables searching the standard library directory for source files. Only directories specified with -I will be searched.

-version
    Prints the OCaml debugger version string and exits.

-vnum
    Prints the major version number of the OCaml debugger and exits.

-help | --help
    Displays a short usage summary of command-line options and exits.

-stdlib
    Prints the path to the standard library directory and exits.

ocamldebug is the standard source-level debugger for OCaml bytecode programs. It empowers developers to meticulously execute their OCaml applications step-by-step, inspect the values of variables, set conditional breakpoints, and navigate the call stack. This interactive, command-line driven tool is indispensable for controlling program execution flow, navigating through source code, and diagnosing intricate runtime issues.

It exclusively operates on bytecode executables that have been compiled with the -g flag using ocamlc, which embeds the necessary debugging information. ocamldebug is a critical utility for understanding program behavior, identifying logical errors, and refining code within the OCaml development ecosystem.

ocamldebug primarily works with bytecode executables compiled by ocamlc -g. Debugging native code produced by ocamlopt is generally more complex and often requires tools like gdb with specific OCaml extensions or other specialized debuggers. Its interactive command-line interface, while powerful, may require a learning curve for users accustomed to graphical debugging environments.

Once launched, ocamldebug offers a comprehensive set of commands for interacting with the debugged program. These include flow control commands like run, break, step, and next to execute and navigate code; inspection commands such as print, display, and where to examine variable values and the call stack; and utility commands like list to view source code and quit to exit the debugger.

In addition to local debugging, ocamldebug fully supports remote debugging scenarios. This advanced feature enables developers to debug an OCaml bytecode program executing on a different machine or within a distinct process. The debugger can operate as a server, awaiting a connection from the debugged program, or conversely, connect to a program that is acting as a debugging server. This capability is exceptionally valuable for diagnosing issues in deployed applications, on embedded systems, or within complex distributed environments.

ocamldebug has been an indispensable component of the OCaml distribution since its inception, serving as the primary debugging utility for bytecode programs. Its evolution has closely paralleled that of the OCaml language and its bytecode interpreter, consistently providing developers with a robust mechanism to inspect and understand their programs' runtime behavior within the OCaml ecosystem.

ocamlc(1), ocamlopt(1), ocaml(1), gdb(1)