.. $Id: RELEASE-NOTES 2165 2011-11-13 11:27:49Z jkoshy $

Release Notes for Elftoolchain Software Version 0.5
===================================================

These release notes document version 0.5 of the software released by
the Elftoolchain project.

About The Project
-----------------

The `Elftoolchain project`_ develops BSD-licensed implementations of
essential compilation tools and libraries for handling ELF based program
objects.

About The Release
-----------------

This release is the first public release of the software developed by
the Elftoolchain project.


Libraries and Utilities
~~~~~~~~~~~~~~~~~~~~~~~

This release comprises the following libraries and utilities.

  =================       ==========================================
  **Name**	          **Description**
  =================       ==========================================
  ar	                  Archive manager.
  addr2line	          Debug tool.
  brandelf	          Manage the ELF brand on executables.
  c++filt	          Translate encoded symbols.
  elfcopy	          Copy and translate between object formats.
  elfdump	          Diagnostic tool.
  findtextrel	          Find undesired text relocations.
  libdwarf	          DWARF access library.
  libelf	          ELF access library.
  mcs	                  Manage comment sections.
  nm	                  List symbols in an ELF object.
  ranlib	          Add archive symbol tables to an archive.
  readelf	          Display ELF information.
  size	                  List object sizes.
  strings	          Extract printable strings.
  strip	                  Discard information from ELF objects.
  =================       ==========================================

Documentation
~~~~~~~~~~~~~

Each public API and invocable utility has its own manual page (327
manual entries, documented in 186 files).

Additionally, this release contains the following documentation:

  =================       ==========================================
  **Name**	          **Description**
  =================       ==========================================
  libelf-by-example       A tutorial introduction to ``libelf``.
  =================       ==========================================

Test Suites
~~~~~~~~~~~

The release contains the following test suites:

  =================       ==========================================
  **Name**	          **Description**
  =================       ==========================================
  ar			  Test the ``ar`` utility.
  elfcopy		  Test the ``elfcopy`` utility.
  elfdump		  Test the ``elfdump`` utility.
  libdwarf		  Test the ``libdwarf`` library.
  libelf		  Test the ``libelf`` library.
  nm			  Test the ``nm`` utility.
  =================       ==========================================


System Requirements
-------------------

This software is designed to run on Unix(TM)-like operating systems
such as the BSD-family of operating systems and GNU/Linux.

This release has been built and tested on the following operating
systems:

  ====================  ===========  ===========================
  **Operating System**  **Version**  **Supported Architectures**
  --------------------  -----------  ---------------------------
  FreeBSD_              v8.2         amd64 & i386
  NetBSD_               v5.0.2       i386
  Ubuntu_ GNU/Linux     10.04LTS     i386 & x86_64
  ====================  ===========  ===========================


Installation and Upgrades
=========================

Installation
------------

Instructions for building and installing this software from source are
described in the file "INSTALL".


Release Information
===================

Changes in this release
-----------------------

This is the first public release of the Elftoolchain sources.

Differences with prior FreeBSD versions of some components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some of the libraries and utilities in this release were originally
developed at the FreeBSD_ project.  These components differ from their
prior versions in FreeBSD source tree in the following ways:

:ar:
    - ``ar`` supports BSD-style archives.
:brandelf:
    - ``brandelf`` supports additional ELF brands.
:libdwarf:
    - The ``libdwarf`` library implements the complete DWARF(3)
      producer and consumer API set.  Each public API has been
      documented in the form of a manual page.
:libelf:
    - ``libelf`` supports operations on special devices in addition to
      regular files.
    - ``libelf`` supports opening of ELF objects in read/write mode.
    - The archive handling APIs in ``libelf`` can process BSD-style archives.
    - ELF sections containing GNU-style hash tables are supported.
    - ELF sections containing GNU-style symbol versioning information
      are supported.
    - Numerous bugs in the code have been fixed.

Additionally, the manual pages associated with these components have
been improved.

Outstanding Issues
------------------

There were no outstanding issues at the time of the release.

Known Limitations
-----------------

This release has the following limitations:

:Test coverage:
    Our test suites are being developed; test coverage for this
    release is partial.

:Performance and Memory Use:
    Our tools have not been characterized for their memory usage or for
    their performance characteristics.

We hope to address these limitations in future releases.


Test Statistics
---------------

The test summary for this release is presented below:

 ========= =========== ===============  ================  ===================
 **Suite** **Tests**   **FreeBSD 8.2**  **NetBSD 5.0.2**  **Ubuntu 10.04LTS**
           (32&64 bit) (i386 & amd64)   (i386)            (i386 & x86_64)
 ========= =========== ===============  ================  ===================
 ar 	   51 & 50     P: 51 & 50	P: 51		  P: 51 & 50
 elfcopy   39	       P: 39	        P: 39		  P: 39
 elfdump   155	       P: 155	        P: 155		  P: 155
 libdwarf  133	       P: 133	        P: 133		  P: 133
 libelf    1024	       P: 1020, U: 4    P: 1020, U: 4	  P: 1020, U: 4       
 ========= =========== ===============  ================  ===================

Key:

  :F:
      Test failures.
  :P:
      Test successes.
  :U:
      Unresolved tests.

Notes
~~~~~

 - The test suite for ``ar`` contains one test that is applicable only
   on 32-bit systems.
 - Four test cases in the libelf test suite cannot be tested on
   account of shortcomings in the test infrastructure in the current
   release.

More Information
================

The project's website is at http://elftoolchain.sourceforge.net/.

The source code for this software and for its associated documentation
is open-source under the BSD license.

Developer Community
-------------------

The project's developers may be contacted using the mailing list:
``<elftoolchain-developers@lists.sourceforge.net>``.

Reporting Bugs
--------------

Please use our `Trac instance`_ for viewing existing bug reports and
for submitting new bug reports.


Copyright and License
=====================

This software is copyright its authors, and is distributed under the
`BSD License`_.

.. _BSD License: http://www.opensource.org/licenses/bsd-license.php
.. _Elftoolchain project: http://elftoolchain.sourceforge.net/
.. _FreeBSD: http://www.freebsd.org/
.. _NetBSD:  http://www.netbsd.org/
.. _`Trac instance`: http://sourceforge.net/apps/trac/elftoolchain/report
.. _Ubuntu:  http://www.ubuntu.com/

.. Local Variables:
.. mode: rst
.. End:
