A Causal-Consistent Reversible Debugger for Erlang.

This tool is still under development

In 2020, we decided to rewrite CauDEr to work directly with Erlang instead of Core Erlang. The main reasons for this change where simplicity, user-friendliness and breaking changes introduced in newer version of Erlang/OTP.

The old version of CauDEr developed for Core Erlang is still available at mistupv/cauder-core, however it is no longer being actively maintained.

• Erlang 23 or higher

To build the project, type:

./rebar3 compile

To create an escript, type:

./rebar3 escriptize

To create a release for your platform, type:

./rebar3 reltool

To run a success typing analysis, type:

./rebar3 dialyzer

To run a cross-reference analysis, type:

./rebar3 xref

To run the code formatter, type:

./rebar3 fmt

To run the style reviewer, type:

./rebar3 lint

To run the unit tests, type:

./rebar3 eunit

To run the common tests, type:

./rebar3 ct

To clean-up the build files, type:

./rebar3 clean

To start an Erlang shell with all the required dependencies, type:

./rebar3 shell

There are multiples ways to run CauDEr from the Erlang shell:

Eshell V11.0  (abort with ^G)
1> cauder:main().
ok

ℹ️ This function will wait for the CauDEr window to close before returning, which means the shell will be blocked.

Eshell V11.0  (abort with ^G)
1> application:start(wx), application:start(cauder).
ok

ℹ️ To stop CauDEr you can use application:stop(cauder), or simply close the window.

Eshell V11.0  (abort with ^G)
1> cauder:start(). % Starting the debugger
{ok,<0.80.0>}
2> cauder_wx:start(). % Starting the GUI
{ok,<0.82.0>,{wx_ref,35,wxFrame,<0.82.0>}}

⚠️ If you try to start the GUI without previously starting the debugger, it will fail with the following error: {error,{not_started,cauder}}

./_build/default/bin/cauder

ℹ️ This will block the current shell until the CauDEr window is closed.

In Unix systems a symbolic link pointing to ./_build/default/bin/cauder will be created in the root of the project.

./_build/default/reltool/cauder

ℹ️ This script will start CauDEr in detached mode.

To trace the execution of a function call you should use either the cauder_tracer:trace/3 or cauder_tracer:trace/4 function. Both functions accept as their first three argument the components of a function application, i.e. to trace apply(Module, Function, Arguments) you should call cauder_tracer:trace(Module, Function, Arguments), they also return the trace in case you want to use it directly.

The optional fourth argument is a collection of configuration options for the trace process, these options can be provider either as a proplist or as a map. The available options are:

• {dir, Dir}: the directory where the source code is located. Default is the current directory (".").
• {modules, Modules}: a list of additional modules to instrument. Default is an empty list ([]).
• {timeout, Timeout}: the number of milliseconds the tracer can run, or the atom infinity to run forever (this is however not recommended as there is currently no way to stop the tracer without losing the trace). Default is 10000.
• {stamp_mode, Mode}: the policy through which stamps in messages are managed. Default is centralized.
• {output, Dir}: the directory where the trace will be saved, or an empty list ([]) to not save the trace to disk. Default is [].

For distributed programs simply start the Erlang runtime system as a distributed node, using the -name or -sname options.

The available stamp modes are:

• centralized: There is a central authority that distributes the stamp, it can always be considered safe.
• distributed: Every send generates its own stamp, more lightweight but safe only if one system instance is involved.

Suppose that you want to trace the barber case study located in the case-studies/barber/ folder, and you would also like to store the results in a new folder called trace/.

If you prefer using a proplist for options, type:

cauder_tracer:trace(barber, main, [], [{dir, "case-studies/barber"}, {output, "case-studies/barber/trace"}]).

Or if you prefer using a map for options, type:

cauder_tracer:trace(barber, main, [], #{dir => "case-studies/barber", output => "case-studies/barber/trace"}).

To learn how to use CauDEr you can check the Wiki (Under construction!)

Announcements as well as questions and discussion among users and developers of the causal consistent reversible debugger CauDEr for Erlang programs are carried out in the Mailing List

Please read the Contributing guide.

This project is available under the terms of the MIT license. See the LICENSE file for the copyright information and licensing terms.