Updated 19 September 2021 
for release libdwarf-0.2.0

Library Documentation is in the doc directory.
See 
  BUILD_REQUIREMENTS
  LIBRARY AND HEADER BUILD REQUIREMENT
  BUILDING ALL THE TOOLS
  INCOMPATIBILITIES
below if you wonder what is required.
=========
As of 1 June 2021 we are using semanantic
versions (not a date version)
and dwarfdump no longer uses libelf
and cannot report libelf (or any other) object data
section details.
Normally your builds will be from a
libdwarf-n.n.n.tar.xz (for example 0.1.0)
Not from cloning the library.
README.md may be helpful to read.
=========
As of May 22, 2020 libdwarf and dwarfdump
support DWARF5 .debug_rnglists section content,
and do much better at containing malloc
use (dwarf_finish() still cleans up,but
it's not so crucial now).

=========
As of September 29, 2018 you will find difficulties
on FreeBSD 11.2 running make, as default make is not
gnu-make compatible. The 2018 configure change
to fully use autoconf/automake requires GNU make
to build executables.

========= gcc on windows with MSYS2 + mingw-w64
Under MinGW the gcc CFLAGS
 -fno-dwarf2-cfi-asm
has helped some people, though for my MinGW tests
these are not necessary or appropriate.

We have had success with MinGW without setting CFLAGS with (to
save space in this example we do not show checking for errors):
The option --enable-wall is optional. Though, static library is
not supported, only shared library is supported.

    #assuming a clean directory.
    #download libdwarf-0.1.2.tar.xz (or a later version)
    tar xf libdwarf-*.tar.xz
    cd libdwarf*
    $ ./configure --enable-shared --disable-static --disable-libelf --enable-wall
    make
    make check
========= End of gcc on windows with MSYS2 + mingw-w64

========= Standard Builds non-Windows
Standard builds are done by configure/make as described below.
Cross-Compiles are described below, see CROSS COMPILES.
One need not --enable-dwarfgen --enable-dwarfexample.
The option --enable-wall is also optional.

BUILDING in UNIX/Linux
    The same as MinGW

BUILDING in MacOS (tried on Catalina)
    The same as Linux
========= End of Standard Builds non-Windows

BUILD REQUIREMENTs
As of July 2021 configure needs pkg-config installed.
On Ubuntu linux do 'sudo apt-get install pkg-config'.

LIBRARY AND HEADER REQUIREMENTS
zlib has to be installed
to handle zlib compressed sections
(common in linux, not normally found with Windows).
in Ubuntu 16.04,18.04,20.04, install using:
    sudo apt-get install zlib1g zlib1g-dev
To be able to run autogen.sh (to generate
configure etc)
    sudo apt-get install autoconf libtool
zlib is available in source from
    http://zlib.net
libelf is unnecessary (unless you wish to build
dwarfgen).

BUILDING ALL THE TOOLS
To build basic Makefile.in etc
     sh autogen.sh
version 1.16.1 of automake reports:
"warning: source file '$(top_srcdir)...' is in a subdirectory"
many times. Bug reports suggest this is an automake bug.
Just ignore the annoying warnings.

A tar.gz or tar.xz 'tarball' has the configure
file already created.  The git source code
from github does not have configure, so running autogen.sh
is a necessary first step.

To build all the programs (including dwarfgen and dwarfexample)
use:
    ./configure --enable-dwarfgen --enable-dwarfexample ; make

To see all the available options to configure do
   ./configure --help

By default configure compiles and uses libdwarf.a.

With
    ./configure --enable-shared
both libdwarf.a and libdwarf.so are built. The runtimes built
will reference libdwarf.so.

With
    ./configure --enable-shared --disable-nonshared
libdwarf.so is built and used; libdwarf.a is not built.

THE USUAL ENVIRONMENT VARIABLES
The following default to sensible values
you may set environment variables as usual
with GNU configure.
CPPFLAGS
CFLAGS
LDFLAGS

DEBUGGING MAKE

To see what compile/link commands are actually
being used by the generated Makefiles try V=1, as in
    make V=1

INSTALL AND UNINSTALL

The default install is to /usr/local

To change the install location use --prefix.
For example:
    mkdir /tmp/testinst
    configure --prefix=/tmp/testinst

So 'make install' (sudo make install) installs into
/usr/local/bin, /usr/local/lib, /usr/local/include, and
/usr/local/share/libdwarf.

Doing 'make uninstall' (sudo make uninstall) deletes
what 'make install' added but does not delete the
/usr/local/share/libdwarf directory that the 'make install'
created.

cmake here does not support make install.

CHECKING FOR MEMORY CORRUPTION

Recent gcc has some checks that can be done at runtime.
  -fsanitize=address
  -fsanitize=leak
  -fsanitize=undefined
which are turned on here by '<path>/configure --enable-sanitize'.

The --enable-sanitize option unlikely to work when
cross-compiling.

CROSS-COMPILES

For those wishing to build libdwarf (and possibly dwarfdump)
for a different host machine than the build machine
it is now possible to do that.

It has been tested with host and target set to an ARM with
build on X86_64.  See
  https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html
for standard GNU usage of build, host, and target.  See also:
  https://www.gnu.org/software/autoconf/manual/\
  autoconf.html#Specifying-Target-Triplets

The autoconf documentation strongly suggests adding --build
to the configure commands and in the example below adding
--build=i686-pc-linux-gnu is known to work on the test machine.

The following is an example. Currently configure figures out
the build environment for itself so we don't use --build here.

On build machine:
sudo apt-get install gcc-arm-linux-gnueabihf
#  Install zlib (libz) into
#  the gcc cross-build tree too.
#  I cheated: copied from arm machine into
#  gcc-arm-linux-gnueabihf.

mkdir emptycross
cd emptycross
# Download a tarfile
# Extract the contents
tar xf libdwarf-0.1.0.tar.xz (or a later version)
cd libdwarf*
$src/configure --host=arm-linux-gnueabihf
make


------------------ notes on working with git cloned source  ------
    If you want to work with the git tree do the following:
    rm -rf code
    git clone https://github.com/davea42/libdwarf-code code
    cd code
    sh autogen.sh
    # we set a local place to install: /tmp/libdw
    rm -rf /tmp/libdw
    mkdir /tmp/libdw
    ./configure --prefix=/tmp/libdw
    make
    make check
    make install

==================================================
==================================================
A further set of tests is available.
    sh scripts/buildandreleasetest.sh
which does configure, make check, make install (in
temporary directories), make dist, and cmake.
This script will not work on Windows.

A full set of tests is
   sh scripts/run-all-tests.sh
which requires the regressiontests directory also be
present and if readelfobj is present
will run its 'make check'.
These tests outside the scope of this README.
This script will not work on Windows.

To create a release file on Linux do:
    ./configure
    make
    make dist
will generate a libdwarf-<n>.<n>.<n>.tar.xz file with the files
needed in a release

See the configure.ac v_maj,v_min,v_mic
or CMakeLists.txt VERSION for the version in use.

INCOMPATIBILITIES

Comparing libdwarf-0.2.0 to libdwarf-20210528
there are significant changes in interfaces.

Many functions that only supported
DWARF before DWARF5 have been dropped
in favor of functions that support all
DWARF versions through DWARF5.
The later versions add a _a_
(or _b_ or _c_ or _d_)
to the end of the function name.
In nearly all cases the libdwarf-0.2.0 interface
was already available in libdwarf-20210528
along with older interfaces that only
worked with earlier DWARF.

Specific functions whose argument lists changed:
Some arguments to
dwarf_init_b(),
dwarf_init_path(),
dwarf_init_path_dl(),
dwarf_object_init_b(), and
dwarf_finish()
have been removed, they were unused and unnecessary.
The argument list to dwarf_bitoffset()
changed to allow use with DWARF5.

The function dwarf_expand_frame_instructions()
and the Dwarf_Frame_Op structure
are still present but will be dropped
since they only work with DWARF2.
A usable interface is not yet available.


David Anderson.
