Updated 29 February 2024 (leap year!)

Libdwarf has been focused for years on both providing access to DWARF2 through DWARF5 data in a portable way while also detecting and reporting if the DWARF is corrupted and avoiding run-time crashes or memory leakage regardless how corrupted the DWARF being read may be. The intent is to provide ABI independent access to DWARF data and ensure that data returned by the library is meaningful.

When the DWARF6 standard is released by the DWARF committee support will be added (as soon as reasonably possible) to libdwarf for all changes/additions while continuing to support previous versions.

ci runs builds on Linux, Freebsd, msys2, and MacOS using configure,cmake, and meson.

Version 0.9.1 Released 27 January   2024.
Version 0.9.0 Released  8 December  2023.
Version 0.8.0 Released 20 September 2023.
Version 0.7.0 Released 20 May       2023.
Version 0.6.0 Released 20 February  2023.
Version 0.5.0 Released 22 November  2022.

If you are linking code against a static library libdwarf.a You must arrange to define the macro LIBDWARF_STATIC in compiling your code that does a #include "libdwarf.h". See also READMEwin-msys2.md

Mentioning some that might not be automatically in your base OS release. Restricting attention here to just building libdwarf and dwarfdump.

Nothing in the project requires or references elf.h, libelf.h, or libelf as of 29 June 2023, version 0.8.0.

If the objects you work with do not have section content compressed with zlib(libz) or libzstd neither those libraries nor their header files are required for building/using libdwarf/dwarfdump.

Ubuntu:
sudo apt install xz pkgconf zlib1g zlib1g-dev libzstd1
sudo apt install libzstd-dev

# Use of libzstd1 is new in 0.4.3
# zlib1g zlib1g-dev libzstd1 are all optional but
# are required to read any DWARF data in compressed
# sections. libzstd1 was used by many linux system utilities
# in Ubuntu 20.04.
optional add: cmake meson ninja doxygen

FreeBSD:
pkg install bash xz python3 gmake liblz4 zstd
# libzstd is likely in /usr/local/lib and zstd.h
# in /usr/local/include and the compiler may not look there
# by default. All will still build fine without it and
# without lzib too, though compressed DWARF sections
# may not be readable.
# example:
CPPFLAGS="-I/usr/local/include/" LDFLAGS="-L/usr/local/lib" ./configure
optional add: binutils cmake meson ninja doxygen

Ensure that all the needed programs are in $PATH,
including python3.
# candidate command to make python3 visible (as root)
# something like:
cd /usr/local/bin ; ln -s python3.9 python3

This is always recommended as it's not necessary to have GNU autotools installed. These examples show doing a build in a directory different than the source as that is generally recommended practice.

Note: if you get a build failure that mentions something about test/ and missing .Po object files add --disable-dependency-tracking to the configure command.

rm -rf /tmp/build
mkdir /tmp/build
cd /tmp
tar xf <path to>/libdwarf-0.4.2.tar.xz
cd  /tmp/build
/tmp/libdwarf-0.4.2/configure
make
make check

READMEcmake.md has details on the available cmake options.

We suggest that you will find meson a more satisfactory tool.

meson 0.45.1  on Ubuntu 18.04 fails.
meson 0.55.2  on Ubuntu 20.04 works.
meson 0.60.3  on Freebsd 12.2 and Freebsd 13.0 works.

See READMEwin-msys2.md for the mingw64 msys2 packages to install and the command(s) to do that in msys2. The tools listed there are also for msys2 meson and autotools/configure.

The msys2 meson ninja install not only installs libdwarf-0.dll and dwarfdump.exe it updates the executables in the build tree linking to that dll so all such executables in the build tree work too.

For example (all build environments):

meson /tmp/libdwarf-0.4.2
ninja
ninja install
ninja test

For a faster build, adding additional checks:

export CFLAGS="-g -pipe"
export CXXFLAGS="-g -pipe"
meson /tmp/libdwarf-0.4.2 -Ddwarfexample=true
ninja -j8
ninja install
ninja test

To build a libdwarf that does not refer to or link with decompression libraries zstd or zlib, add the meson option "-Ddecompression=false"

This checks for the existence critical executables such as cmake,meson,and ninja and only runs builds that could work. Useful in any supported environment.

sh scripts/allsimplebuilds.sh

Ignore this section if using meson (or cmake).

This is not recommended as it requires you have more software installed.

For Ubuntu configure, install additional packages:

autoconf
automake
libtool
pkg-config

For FreeBSD configure, install additional packages: autoconf automake libtool pkgconf

Here we assume the source is in a directory named /path/to/code

For example, on Ubuntu 20.04

    sudo apt-get install autoconf libtool pkg-config

Note: if you get a build failure that mentions something about test/ and missing .Po object files add --disable-dependency-tracking to the configure command.

Using the source/build directories from above as examples, do :

# Standard Linux Build
cd /path/to/code
sh autogen.sh
cd /tmp/build
/path/to/code/configure
make
make check

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install autoconf automake libtool
# Then use the  Standard Linux Build lines above.

For the basic configuration options list , do: meson configure /path/to/code

To set options and show the resulting actual options:

# Here  just setting one option.
meson setup  -Ddwarfexample=true  .  /home/davea/dwarf/code
meson configure .

The meson configure output is very wide (just letting you know).

For the full options list , do:

/path/to/code/configure --help

By default configure compiles and uses libdwarf.a. With `--enable-shared --disable-static" appended to the configure step, libdwarf.so is built and the runtimes built will reference libdwarf.so.

As of version 0.9.1 the configure option "--disable-decompression" tells the build to compile libdwarf and dwarfdump with no reference to the zlib or zstd libraries.

If you get a build failure that mentions something about test/ and missing .Po object files add --disable-dependency-tracking to the configure command. With that option do not assume you can alter source files and have make rebuild all necessary.

See: https://www.gnu.org/savannah-checkouts/gnu/automake/history/automake-history.html#Dependency-Tracking-Evolution

Other options of possible interest:

--enable-wall to turn on compiler diagnostics
--enable-dwarfexample to compile the example programs.

configure -h     shows the options available.

Sanity checking:

gcc has some checks that can be done at runtime. -fsanitize=undefined is turned on for configure by --enable-sanitize

As of 0.9.0 meson builds default to be shared-library builds. These options go on the meson setup command line. the default can be explicitly chosen with:

--default-library shared

A static libdwarf (archive) libdwarf.a can be built with

--default-library static

By default compiler warnings are errors. Add the following to let compilations continue:

-Dwerror=false

By default compiles look for C/C++ language issues. Add the following to add gcc -fsanitize checking in the build to catch various memory errors (the generated code is larger and slower than normal).

-Dsanitize=true

All libdwarf builds are automatically shared object (dll) builds. No static libdwarf.a can be built. If you need static libdwarf.a use meson or cmake.

Has the same meson setup reporting as on Linux (above).

See READMEwin-msys2.md

When ready to create a new source distribution do a build and then

make distcheck

New interfaces allow full support for Mach-O (Apple) universal binaries: dwarf_init_path_a(), dwarf_init_path_dl_a(), and dwarf_get_universalbinary_count().

The default build (with meson) is shared-library. to build with static (archive) libdwarf add

--default-library static

to the meson command line (applies to meson builds in Linux,Macos, and Windows-mingw).

On Windows-mingw one can build static libdwarf when using cmake or meson (configure will not allow a static libdwarf to be built on Windows).

See Options to meson on Windows (Msys2) above.

struct Dwarf_Obj_Access_Methods_a_s changed for extended ELF so the library can handle section count values larger than 16bits. dwarf_dnames_abbrev_by_code() and dwarf_dnames_abbrev_form_by_index() were removed from the API, better alternatives already existed.

The dealloc required by dwarf_offset_list() was wrong, use dwarf_dealloc(dbg, offsetlistptr, DW_DLA_UARRAY). The function dwarf_dietype_offset() has a revised argument list so it can work correctly with DWARF4. dwarf_get_pubtypes() and similar changed to eliminate messy code duplication. Fixed memory leaks and treatment of DW_FORM_strx3 and DW_FORM_addrx3.

dwarf_get_globals() is compatible but it now returns data from .debug_names in addition to .debug_pubnames (either or both could be in an object file). New function dwarf_global_tag_number() makes the data from .debug_names a bit more useful (if a library user wants it). Three new functions were added to enable printing of the .debug_addr section independent of other sections and the new dwarfdump option --print-debug-addr prints that section.

No incompatibilities.

Added a new function dwarf_suppress_debuglink_crc() which speeds up gnu debuglink (only use it if you are sure the debuglink name-check alone is sufficient).

A few dealloc() functions changed name to have a consistent pattern for all such. Access to the DWARF5 .debug_names section is now fully implemented.

See the Recent Changes section in libdwarf.pdf (in the release).

Or see the latest online html version dwhtml for the details.. Or see (via download) the latest pdf html version dwpdf.

Notice the table of contents at the right edge of the html page.

If one has DWARF bytes in memory or in a kind of file system libdwarf cannot understand one should use

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

and create source to provide functions and data for the three struct types:

struct Dwarf_Obj_Access_Interface_a_s
struct Dwarf_Obj_Access_Methods_a_s
struct Dwarf_Obj_Access_Section_a_s

These functions and structs now seem complete (unlike the earlier libdwarf versions), hence the name and content changes.

For a worked out example of reading DWARF direct from memory with no file system involved see

src/bin/dwarfexample/jitreader.c

and see the html dwhtml (www.prevanders.net/libdwarfdoc/index.html).

The latest pdf is dwpdf (www.prevanders.net/libdwarf.pdf)

David Anderson.