libdwarf

libdwarf provides portable, ABI-independent access to DWARF2 through DWARF5 data. Its primary goals are:

• Data Integrity: Detecting and reporting corrupted DWARF data while avoiding runtime crashes or memory leaks.
• Portability: Providing a consistent interface across different ABIs.
• Future Proofing: Adding support for new standards (like DWARF6) as soon as they are released.

Note: libdwarf reads files from disk; it does not read running programs or shared objects directly.

When linking your own code against the static library libdwarf.a, you must define the LIBDWARF_STATIC macro in your code whenever you #include "libdwarf.h".

#define LIBDWARF_STATIC
#include "libdwarf.h"

To avoid collisions with user code or other libraries, Libdwarf uses specific prefixes:

• DW_: From the DWARF Standard (used in dwarf.h).
• Dwarf_: Used for types.
• dwarf_: Used for public functions.
• _dwarf_: Used for non-static functions internal to the library (not for user calls).
• dw_: Used for public function argument names (to support Doxygen).

Other naming rules:

• Functions: All lower-case with underscores (under_score).
• Local Variables: All lower-case with underscores.
• Struct Members: Should have a 2-character prefix specific to that struct followed by an underscore (e.g., ns_x in struct Dwarf_Nothing_Special_s) to facilitate grep searches.

If DWARF data is located in memory or in a custom file system that libdwarf does not natively support, use the dwarf_object_init_b() workflow. This requires implementing source functions and data for three specific interface structures to provide access to the DWARF data.

Workflow:

1. Initialize the object with dwarf_object_init_b().
2. Perform your required libdwarf operations.
3. Finalize the object with dwarf_object_finish().

Required Interface Structures:

• struct Dwarf_Obj_Access_Interface_a_s
• struct Dwarf_Obj_Access_Methods_a_s
• struct Dwarf_Obj_Access_Section_a_s

For a complete implementation example, refer to src/bin/dwarfexample/jitreader.c in the repository.

dwarf_object_init_b();
// ... call libdwarf functions ...
dwarf_object_finish();

Libdwarf is architecturally split into two conceptual sides:

1. Left-Hand Side (LHS): Contains all the public DWARF-related API functions. The LHS is agnostic of the specific object file format.
2. Right-Hand Side (RHS): Contains the object-file-specific logic (ELF, PE, or MacOS Mach-O). The RHS provides a set of function pointers that the LHS uses to access the object file.

This separation allows the API functions to work on any object regardless of the ABI, and all functions automatically account for endianness. All code blocks (Elf, PE, and MacOS) are available at runtime; there is no selection required at library-build time.

Deeply nested blocks make code hard to read and often indicate that functionality should be split into separate functions.

Avoid Gratuitous Nesting: Instead of nesting the entire logic inside an if (pointer_is_valid) block, handle the error case early and return. This keeps the primary logic at the top level of the function.

Bad Pattern (Gratuitous Nesting):

foo = malloc (sizeof (foo_t));
if (foo) {
    /* lots of code to initialize foo */
    return DW_DLV_OK;
}
_dwarf_error(dbg,error,DW_DLE_MALLOC_RETURNS_NULL);
return DW_DLV_ERROR;

Good Pattern (Early Return):

foo = malloc (sizeof (foo_t));
if (!foo) {
    _dwarf_error(dbg,error,DW_DLE_MALLOC_RETURNS_NULL);
    return DW_DLV_ERROR;
}
/* lots of code to initialize foo */
return DW_DLV_OK;

To pass the LIBDWARF_STATIC macro to the preprocessor in Visual Studio:

1. Right-click your project in the Solution Explorer.
2. Select Properties.
3. Navigate to C/C++ > Preprocessor.
4. Click on Preprocessor Definitions, click the down arrow, and select Modify.
5. Add LIBDWARF_STATIC to the list and click OK.

Library maintainers use this program to update name definitions whenever a DWARF tag (e.g., DW_TAG_subprogram), attribute (e.g., DW_AT), or other identifier is added, deleted, or changed.

To run the process, execute the following command from the top level of the repository:

make rebuild

Important: After a successful rebuild, you must re-run configure on the project because critical headers may have changed.

Once dependencies are installed via MacPorts, standard build systems like configure, cmake, or meson should function correctly, including make check.

To run a simplified build process from the source directory, you can use the provided shell script. Note that the full libdwarf-regressiontests suite is available but typically not required for standard validation.

sh scripts/allsimplebuilds.sh