This document discusses support for debugging your Chapel program and a set of experimental settings to enable task monitoring and memory tracking.
The compiler-generated executable has a
--gdb flag that can be used to
launch the program within a
gdb session. A similar flag,
exists to launch the program within a
lldb session. For best results, you
should follow Best Known Configuration to build Chapel and build your
When using almost any launcher, you can launch
gdb by setting the
CHPL_COMM_USE_GDB when running the program.
This will open up a separate terminal emulator window for each locale,
each running the debugger on that locale’s program instance. On the Mac
OS X (darwin) platform, you can launch
lldb instead, by setting the
CHPL_COMM_USE_LLDB environment variable. This works in all of these
amudprun aprun gasnetrun_ibv gasnetrun_mpi gasnetrun_ofi mpirun4ofi pbs-aprun smp
The default terminal emulator program is
but by setting the environment variable
you can force use of
Whichever terminal emulator is used must be in your
on the compute node or an error will result.
Note that it is the user’s responsibility to make sure things are set up
so the terminal emulator run in the target environment can open its
display window in the launch environment.
The current best practice for debugging Chapel source code is to use the C backend and use a series of flags to improve the debuggability of the generated executable. This can be done in two steps.
Build the compiler with
Build the executable from Chapel source code:
chpl -g --target-compiler=gnu --savec <dir> --preserve-inlined-line-numbers --no-munge-user-idents <source_file>
For more details on these settings, read the rest of this section.
For best results while debugging, we recommend building the compiler with
CHPL_TARGET_COMPILER set to
clang if on Mac). See
Setting up Your Environment for Chapel for more information on building the compiler.
With two invocations of the build command, both backends can be built. First
make (which uses the LLVM backend by default) and then execute
CHPL_TARGET_COMPILER=gnu make. This will keep the default as LLVM and allow
switching to the C backend as needed for debugging. This can be done for a
particular invocation of the compiler with
chpl --target-compiler=gnu ....
The following flags can be useful for making the generated C more amenable to debugging.
Generate debug symbols in the executable
Target the C backend
Write out the generated C to a given directory
When code gets inlined (e.g. replacing a function call with the function body) maintain the filename and line number information of the original function call.
Don’t munge user identifiers (e.g. variable or function names). Munging typically prevents conflicts with identifiers in external code but makes debugging harder.
The utility of using a debugger with Chapel depends greatly on your familiarity
with the Chapel generated code. However, if your program is crashing or running
into a runtime error, you can often determine where that is taking place by
looking at a stack trace within
When debugging Chapel, it is useful to know that in generating its code,
the Chapel compiler renames user identifiers. By default, the Chapel
compiler munges all user identifiers, such that a variable named
would be code generated as
x_chpl. This munging can be controlled
--[no-]munge-user-idents flag (see the
chpl man page
for more information). In some cases, additional munging may be
required or applied that cannot be turned off.
The net effect of this is that Chapel variables can often be inspected
_chpl<TAB> in cases
where the compiler has further renamed the variable). If the
--no-munge-user-idents flag is used,
p name or
<TAB> should work in most cases.
See Why are my identifiers renamed in the generated code? for more information on munging.
Over time, we plan to improve our ability to debug the generated C code for a Chapel program. If you find yourself debugging the generated code a lot and need help or have requests for better support, please let us know so that we can prioritize accordingly.
For certain tasking layers, Chapel supports an experimental
capability for tracking the status of tasks, primarily designed for
use in a single-locale execution. To enable this capability, your
program must be compiled with the
The feature itself is enabled at execution time by setting the boolean
CHPL_RT_ENABLE_TASK_REPORTING to any of the
values “1”, “yes”, or “true”. If this is done, then when
is entered while a program is executing, a list of pending and executing
tasks will be printed to the console, giving an indication of which
tasks are at which source locations. This is only supported with
Note that task tracking adds a fair amount of runtime overhead to task-parallel programs.
Chapel supports a number of configuration constants related to dynamic memory allocation for the compiler-generated executable, currently designed for use primarily by the development team to track memory usage in tests. Please note that our generated code currently contains memory leaks, so you should not be surprised if your program requires more memory than it seems it should.
For full information on these configuration constants consult
A brief synopsis of these configuration constants is as follows:
turn on memory tracking and enable reporting
printMemAllocStats()on normal termination
printMemAllocsByType()on normal termination
printMemAllocs()on normal termination
set maximum level of allocatable memory
set minimum threshold for memory tracking
file to contain all memory reporting
if set, append final stats and leaks-by-type here