.. $Id: RELEASE-NOTES 2592 2012-09-16 15:20:13Z jkoshy $

Release Notes for Elftoolchain Software Version 0.6.1
=====================================================

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 is the first release on the v0.6 "stable" code line.

Since our prior v0.5.1 release, we have added support for building the
project on additional operating systems, namely DragonFlyBSD, Minix
and OpenBSD.  A number of bugs were fixed, and the project's
documentation has been improved.

No new utilities are being introduced in this release.

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 a reference manual entry.
We currently offer 330 manual entries, documented in 189 manual pages.

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**
  --------------------  -----------  ---------------------------
  `DragonFly BSD`_      2.10.1       i386
  FreeBSD_              v8.2         amd64 & i386
  Minix_                3.0.2        i386
  NetBSD_               v5.0.2       i386
  OpenBSD_              v5.0         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".

Upgrading
---------

There are no special considerations for upgrading from the prior
(v0.5.1) release.

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

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

The source tree has been ported to DragonFlyBSD, Minix and OpenBSD.

Other significant changes include:

* **ar**

  * A file descriptor exhaustion bug was fixed [`ticket #388`_].
  * Support for building with newer versions of **libarchive**.
  * Memory errors were corrected.

* **brandelf**

  * The **brandelf** utility will try to preserve the layout of the
    ELF object being updated [`ticket #375`_].

* **elfcopy/strip/mcs**

  * Fixed a critical bug: when stripping an object, properly handle a
    segment containing exactly one section of type SHT_NOBITS
    [`changeset 2540`_].
  * A few memory leaks were fixed.

* **elfdump**

  * Compatibility with Solaris(TM) **elfdump** was improved.
  * Memory errors were corrected.

* **libdwarf**

  * Partial support for DWARF4 has been added [`ticket #394`_]
  * An infinite loop bug was fixed [`ticket #396`_].
  * Memory related errors were fixed.

* **libelf**

  * Extension APIs have been added, for the internal use of the project.
  * Memory related errors were fixed.

* **libelf-by-example**

  * The diagrams in the tutorial have been reworked and the text has
    been improved.

* **libelftc**

  * New helper functions were added, for the internal use of the
    project.

* **nm**

  * The behavior of the ``-o`` option was brought in line with POSIX.
  * Memory leaks were fixed.

* **readelf**

  * Compatibility with GNU **readelf** was improved.
  * The ``-x`` and ``-p`` options now accept section names in addition
    to section numbers.
  * A crash when dumping sections of type SHT_NOBITS was corrected.

* **size**

  * Memory leaks were fixed.

All our utilities now accept ``--help`` and ``--version`` command-line
options.

Apart from code changes, a number of manual pages were 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 is still
    partial.
:Performance and Memory Use:
    Our tools have not been fully analyzed for their memory use or for
    their performance characteristics.

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

The test summary for this release is presented below:

 ========= ==========  ===============  ===============  ================  ===================
 **Suite** **Tests**   **DragonFly**    **FreeBSD**      **NetBSD**        **Ubuntu 10.04LTS**
           (32&64bit)  (i386)           (i386 & amd64)   (i386)            (i386 & x86_64)
 ========= ==========  ===============  ===============  ================  ===================
 ar        235 & 230   P:235            P:235 & P:230    P:235             P:235 & P:230
 elfcopy   156         P:156            P:156            P:156             P:156
 elfdump   155         P:155            P:155            P:155             P:155
 libdwarf  133         P:133            P:133            P:133             P:133
 libelf    1024        P:1020, U:4      P:1020, U:4      P:1020, U:4       P:1020, U:4
 nm        183         P:183            P:183            P:183             P:183
 ========= ==========  ===============  ===============  ================  ===================

Key:

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

Notes
~~~~~

* The test suite for **ar** contains five tests that are 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/.

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
.. _DragonFly BSD: http://www.dragonflybsd.org/
.. _Elftoolchain project: http://elftoolchain.sourceforge.net/
.. _FreeBSD: http://www.freebsd.org/
.. _Minix:   http://www.minix3.org/
.. _NetBSD:  http://www.netbsd.org/
.. _OpenBSD: http://www.openbsd.org/
.. _`Trac instance`: http://sourceforge.net/apps/trac/elftoolchain/report
.. _Ubuntu:  http://www.ubuntu.com/
.. _changeset 2540: http://sourceforge.net/apps/trac/elftoolchain/changeset/2540
.. _ticket #375: http://sourceforge.net/apps/trac/elftoolchain/ticket/375
.. _ticket #388: http://sourceforge.net/apps/trac/elftoolchain/ticket/388
.. _ticket #394: http://sourceforge.net/apps/trac/elftoolchain/ticket/394
.. _ticket #396: http://sourceforge.net/apps/trac/elftoolchain/ticket/396

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