.. _readme-debugging-bkc: ======================================= Best Known Configurations for Debugging ======================================= ---------------------- Using the LLVM Backend ---------------------- When debugging Chapel using the default LLVM backend, make sure to use the ``-g`` flag to generate debug symbols in the executable. This will allow you to use a debugger like ``gdb`` or ``lldb`` to step through the code and inspect variables. There are a few flags that may be useful for debugging with the LLVM backend. For example, the following is the current best configuration which results in generated code with the best possible debug information: .. code-block:: bash chpl -g --preserve-inlined-line-numbers \ --no-return-by-ref --no-inline \ --no-copy-propagation --no-scalar-replacement If you intend to use ``gdb`` to debug your Chapel program, you may also want to use the ``--ccflags -gdwarf-4``, as ``gdb`` has been found to have issues with DWARF 5 debug information generated by the LLVM backend. .. code-block:: bash chpl -g --ccflags -gdwarf-4 --preserve-inlined-line-numbers \ --no-return-by-ref --no-inline \ --no-copy-propagation --no-scalar-replacement The following table summarizes the flags that can be used to improve the debuggability of the generated executable: =================================== ========================================= Flag Description =================================== ========================================= ``-g`` Generate debug symbols in the executable ``--ccflags -gdwarf-4`` Use DWARF 4 debug information (useful for ``gdb``) ``--preserve-inlined-line-numbers`` 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. ``--no-return-by-ref`` Don't use an extra reference argument when compiling a Chapel function that returns a record. ``--no-inline`` Avoid inlining in many cases. ``--no-copy-propagation`` Disables a Chapel optimization pass that can make debugging harder. ``--no-scalar-replacement`` Disables a Chapel optimization pass that can make debugging harder. =================================== ========================================= ------------------- Using the C Backend ------------------- It may be useful to debug Chapel programs using the C backend. The current best practice for debugging Chapel source code with the C backend is to use a series of flags to improve the debuggability of the generated executable. While debugging with just ``-g`` is possible, these flags (explained in step 2 below) result in generated code with debug information that most closely matches the Chapel source code. This can be done in two steps. 1) Build the compiler with ``CHPL_TARGET_COMPILER`` set to ``gnu`` (or ``clang`` if on Mac): .. code-block:: bash CHPL_TARGET_COMPILER=gnu make # On MacOS # CHPL_TARGET_COMPILER=clang make 2) Build the executable from Chapel source code: .. code-block:: bash chpl -g --target-compiler=gnu --preserve-inlined-line-numbers \ --no-munge-user-idents --no-return-by-ref --no-inline \ --no-copy-propagation --no-scalar-replacement # On MacOS # chpl -g --target-compiler=clang --preserve-inlined-line-numbers \ # --no-munge-user-idents --no-return-by-ref --no-inline \ # --no-copy-propagation --no-scalar-replacement For more details on these settings, read the rest of this section. Building the Compiler ~~~~~~~~~~~~~~~~~~~~~ For best results while debugging, we recommend building the compiler with ``CHPL_TARGET_COMPILER`` set to ``gnu`` (or ``clang`` if on Mac). See :ref:`readme-chplenv` for more information on building the compiler. With two invocations of the build command, both backends can be built. First execute ``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 ...``. Building the Application ~~~~~~~~~~~~~~~~~~~~~~~~ The following flags can be useful for making the generated C more amenable to debugging. Any of them can be omitted as desired. =================================== ========================================= Flag Description =================================== ========================================= ``-g`` Generate debug symbols in the executable ``--target-compiler=gnu`` Target the C backend with GCC ``--target-compiler=clang`` Target the C backend with Clang ``--savec `` Write out the generated C to a given directory ``--preserve-inlined-line-numbers`` 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. ``--no-munge-user-idents`` Don't munge user identifiers (e.g. variable or function names). Munging typically prevents conflicts with identifiers in external code but makes debugging harder. ``--no-return-by-ref`` Don't use an extra reference argument when compiling a Chapel function that returns a record. ``--no-inline`` Avoid inlining in many cases. ``--no-copy-propagation`` Disables a Chapel optimization pass that can make debugging harder. ``--no-scalar-replacement`` Disables a Chapel optimization pass that can make debugging harder. =================================== ========================================= Notes on Munging '''''''''''''''' 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 ``gdb``. 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 ``x`` would be code-generated as ``x_chpl``. This munging can be controlled using the ``--[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 using ``p`` *name*\ ``_chpl`` (or ``p`` *name*\ ``_chpl`` in cases where the compiler has further renamed the variable). If the ``--no-munge-user-idents`` flag is used, ``p`` *name* or ``p`` *name*\ ```` should work in most cases. See :ref:`more-munging-info` for more information on munging.