1.. $Id: RELEASE-NOTES 3416 2016-02-17 21:41:20Z jkoshy $
2
3Release Notes for Elftoolchain Software Version 0.7.1
4=====================================================
5
6About The Project
7-----------------
8
9The `Elftoolchain project`_ develops BSD-licensed implementations of
10essential compilation tools and libraries for handling ELF based program
11objects.
12
13About The Release
14-----------------
15
16This is the first release on the v0.7 "stable" code line.
17
18Since the prior v0.6.1 release, we have added support for a few more
19machine architectures, improved our support of the DWARF4 debug format,
20and have added experimental support for the Microsoft (TM) Portable
21Executable format.  A number of bugs have been fixed, and the project's
22documentation has been improved.  An implementation of a link editor
23**ld** is in progress.
24
25Libraries and Utilities
26~~~~~~~~~~~~~~~~~~~~~~~
27
28This release comprises the following libraries and utilities.
29
30  =================       ==========================================
31  **Name**                **Description**
32  =================       ==========================================
33  **ar**                  Archive manager.
34  **addr2line**           Debug tool.
35  **brandelf**            Manage the ELF brand on executables.
36  **c++filt**             Translate encoded symbols.
37  **elfcopy**             Copy and translate between object formats.
38  **elfdump**             Diagnostic tool.
39  **findtextrel**         Find undesired text relocations.
40  **libdwarf**            DWARF access library.
41  **libelf**              ELF access library.
42  **mcs**                 Manage comment sections.
43  **nm**                  List symbols in an ELF object.
44  **ranlib**              Add archive symbol tables to an archive.
45  **readelf**             Display ELF information.
46  **size**                List object sizes.
47  **strings**             Extract printable strings.
48  **strip**               Discard information from ELF objects.
49  =================       ==========================================
50
51This release also contains the following software that is under
52development:
53
54  =================       ==========================================
55  **Name**                **Description**
56  =================       ==========================================
57  **ld**                  Program linker.
58  **libpe**               PE (Portable Executable) access library.
59  =================       ==========================================
60
61Documentation
62~~~~~~~~~~~~~
63
64Each public API and invocable utility has a reference manual entry.
65We currently offer 355 manual entries, documented in 197 manual pages.
66
67Additionally, this release contains the following documentation:
68
69  =================       ==========================================
70  **Name**                **Description**
71  =================       ==========================================
72  libelf-by-example       A tutorial introduction to **libelf**.
73  =================       ==========================================
74
75Test Suites
76~~~~~~~~~~~
77
78The release contains the following test suites:
79
80  =================       ==========================================
81  **Name**                **Description**
82  =================       ==========================================
83  ar                      Test the **ar** utility.
84  elfcopy                 Test the **elfcopy** utility.
85  elfdump                 Test the **elfdump** utility.
86  libdwarf                Test the **libdwarf** library.
87  libelf                  Test the **libelf** library.
88  libelftc                Test the **libelftc** support library.
89  nm                      Test the **nm** utility.
90  =================       ==========================================
91
92
93System Requirements
94-------------------
95
96This software is designed to run on Unix(TM)-like operating systems
97such as the BSD-family of operating systems and GNU/Linux.
98
99This release has been built and tested on the following operating
100systems:
101
102  ====================  ===========  ===========================
103  **Operating System**  **Version**  **Supported Architectures**
104  --------------------  -----------  ---------------------------
105  FreeBSD_              10.2         amd64 & i386
106  NetBSD_               7.0          i386
107  Ubuntu_ GNU/Linux     14.04LTS     x86_64
108  ====================  ===========  ===========================
109
110
111Installation and Upgrades
112=========================
113
114Installation
115------------
116
117Instructions for building and installing this software from source are
118described in the file "INSTALL".
119
120Upgrading
121---------
122
123* Consumers of the libdwarf API should note that the `Dwarf_Off` type
124  has changed to an unsigned type, so as to be compatible with other
125  open-source libdwarf implementations.
126* Three functions in the libdwarf API have been deprecated and two
127  extension APIs have been added.
128
129Release Information
130===================
131
132Changes in this release
133-----------------------
134
135Significant changes include:
136
137* **addr2line**
138
139  - Support the ``DW_AT_ranges`` debug attribute.
140  - Improve DWARF4 compatibility.
141  - **addr2line** supports new options ``-a``, ``-i``, ``-p``.
142  - Compilation units lacking debug information are handled more robustly.
143  - Memory leaks were fixed.
144
145* **ar/ranlib**
146
147  - The **ranlib** utility is now documented in its own manual page.
148  - The handling of corrupt archives has been improved.
149  - **ar** now supports a ``-U`` option that disables its
150    deterministic (``-D``) mode.
151  - **ar** no longer allows extraction of archive entries whose
152    pathnames contain ``..``, or whose target directory would be
153    altered by a symbolic link.
154
155* **brandelf**
156
157  - The documentation for **brandelf** has been improved.
158
159* **elfcopy/strip/mcs**
160
161  - **strip** no longer strips local debugging symbols when the ``-x``
162    option is specified.
163  - Compatibility with GNU binutils has been improved.
164  - The **elfcopy** and **strip** utilities will now preserve hard
165    links when modifying an object file.
166  - Support for new functionality controlled by options
167    ``--localize-hidden``, ``--extract-dwo`` and ``--strip-dwo`` has
168    been added.
169  - Bugs in the behavior of the ``-N`` and ``-X`` options were fixed.
170  - Nameless global symbols are now handled correctly.
171  - ``SHT_GROUP`` handling has been fixed in **elfcopy** and
172    **strip**.
173  - **elfcopy** now supports the conversion of ELF objects to PE images.
174
175* **elfdump**
176
177  - **elfdump** can now dump multiple GOT sections.
178  - **elfdump** now understands the ``EM_AARCH64``, ``EM_IAMCU``,
179    ``EM_PPC64``, and ``EM_RISCV`` machine types and the
180    ``STT_SPARC_REGISTER`` section type.
181  - Symbols with ``STB_GNU_UNIQUE`` are now supported.
182
183* **findtextrel**
184
185  - The manual pages were improved.
186
187* **ld**
188
189  - This utility is new in this release.  This utility is currently under
190    development, and should be considered unstable.
191
192* **libdwarf**
193  - The line number program generated by **libdwarf** has been improved.
194  - Support for the DWARF4 ``.debug_types`` section was added.
195  - Parsing of DWARF4 line sections was fixed.
196  - New APIs ``dwarf_attroffset()``,
197    ``dwarf_get_cu_die_offset_given_cu_header_offset_b()``,
198    ``dwarf_get_die_infotypes_flag()``,
199    ``dwarf_get_section_max_offsets()``,
200    ``dwarf_get_section_max_offsets_b()``, ``dwarf_highpc_b()``,
201    ``dwarf_loclist_from_expr_b()``, ``dwarf_next_types_section()``,
202    ``dwarf_offdie_b()``, and ``dwarf_siblingof_b()`` have been added.
203    Of these, ``dwarf_attroffset()`` and ``dwarf_next_types_section()``
204    are extensions to the SGI libdwarf API.
205  - Support for operators ``DW_OP_GNU_addr_index``,
206    ``DW_OP_GNU_const_index``, ``DW_OP_GNU_const_type``,
207    ``DW_OP_GNU_convert``, ``DW_OP_GNU_deref_type``,
208    ``DW_OP_GNU_encoded_addr``, ``DW_OP_GNU_entry_value``,
209    ``DW_OP_GNU_implicit_pointer``, ``DW_OP_GNU_parameter_ref``,
210    ``DW_OP_GNU_regval_type``, ``DW_OP_GNU_reinterpret``,
211    ``DW_OP_GNU_uninit`` and ``DW_OP_push_object_address`` have been
212    added.
213  - APIs ``dwarf_get_cu_die_offset_given_cu_header_offset()``,
214    ``dwarf_offdie()``, ``dwarf_siblingof()`` have been deprecated.
215  - **libdwarf** now supports relocation for the ``aarch64``
216    architecture.
217  - **libdwarf** now handles architectures that use ".rel" relocations
218    for debug data correctly.
219  - The ``EM_IAMCU`` architecture is now recognized.
220  - Documentation has been improved, memory leaks and other bugs have
221    been fixed.
222
223* **libelf**
224
225  - Reference documentation has been improved.
226  - Support building on the AARCH64 architecture has added.
227  - Bug fixes have been applied.
228
229* **libelf-by-example**
230
231  - No changes since the prior release.
232
233* **libelftc**
234
235  - Support for the Portable Executable format has been added.
236  - Overview documentation for this support library has been added.
237  - New APIs ``elftc_string_table_from_section()``.
238    ``elftc_string_table_image()``, ``elftc_string_table_insert()``,
239    ``elftc_string_table_lookup()``, ``elftc_string_table_remove()``
240    and ``elftc_string_table_to_string()`` have been added.
241  - The demangling support functions now support IEEE floating point
242    types, TLS special names and various GNU extensions.
243  - Other bugs have fixed.
244
245* **libpe**
246
247  - This library is new in this release.  This library is currently
248    under development, and should be considered unstable.
249
250* **nm**
251
252  - A new alias ``--extern-only`` for option ``-g`` is now supported.
253  - Bugs have been fixed.
254
255* **readelf**
256
257  - The handling of objects with missing symbol names was improved.
258  - **readelf** now supports dumping ``.debug_types`` sections.
259  - The ``DW_AT_language``, ``DW_FORM_exprloc``,
260    ``DW_FORM_flag_present``, ``DW_FORM_ref_sig8`` and
261    ``DW_FORM_sec_offset`` types are now supported.
262  - GNU DWARF operator extensions are now recognized by **readelf**.
263  - **readelf** can now display architecture specific register names on
264    some architectures.
265  - **readelf** now handles AArch64 types and relocations and
266    recognizes the ``RISC-V`` and ``IAMCU`` architectures.
267  - Support has been added for printing binary notes for FreeBSD, Xen
268    and Linux, and for printing core notes for FreeBSD and Linux.
269  - Support for dumping symbols with the ``STB_GNU_UNIQUE`` binding
270    has been added.
271  - Support for dumping symbols with the ``STT_SPARC_REGISTER``
272    register type has been added.
273
274* **size**
275
276  - The manual page for **size** has been improved.
277
278* **strings**
279
280  - The manual page for **strings** has been improved.
281
282Outstanding Issues
283------------------
284
285There were no outstanding issues at the time of the release.
286
287Known Limitations
288-----------------
289
290This release has the following limitations:
291
292:Test coverage:
293    Our test suites are being developed; test coverage is still
294    partial.
295:Performance and Memory Use:
296    Our tools have not been fully analyzed for their memory use or for
297    their performance characteristics.
298
299Test Statistics
300---------------
301
302The test summary for this release is presented below:
303
304 ========= ========== =============== ================ ===================
305 **Suite** **Tests**  **FreeBSD**     **NetBSD**       **Ubuntu 10.04LTS**
306           (32&64bit) (i386 & amd64)  (i386)           (x86_64)
307 ========= ========== =============== ================ ===================
308 ar        235 & 230  P:235 & 230     P:235            P:230
309 elfcopy   160        P:160           P:160            P:160
310 elfdump   155        P:155           P:155            P:155
311 libdwarf  153        P:153           P:153            P:153
312 libelf    1030       P:1026, U:4     P:1026, U:4      P:1026, U:4
313 libelftc  16         P:16            P:16             P:16
314 nm        183        P:183           P:183            P:183
315 ========= ========== =============== ================ ===================
316
317Key:
318
319  :P:
320      Test successes.
321  :F:
322      Test failures.
323  :U:
324      Unresolved tests.
325
326Notes
327~~~~~
328
329More Information
330================
331
332The project's website is at http://elftoolchain.sourceforge.net/.
333
334Developer Community
335-------------------
336
337The project's developers may be contacted using the mailing list:
338``<elftoolchain-developers@lists.sourceforge.net>``.
339
340Reporting Bugs
341--------------
342
343Please use our `bug tracker`_ for viewing existing bug reports and
344for submitting new bug reports.
345
346Copyright and License
347=====================
348
349This software is copyright its authors, and is distributed under the
350`BSD License`_.
351
352.. _BSD License: http://www.opensource.org/licenses/bsd-license.php
353.. _`bug tracker`: https://sourceforge.net/p/elftoolchain/tickets/
354.. _Elftoolchain project: http://elftoolchain.sourceforge.net/
355.. _FreeBSD: http://www.freebsd.org/
356.. _NetBSD:  http://www.netbsd.org/
357.. _Ubuntu:  http://www.ubuntu.com/
358
359.. Local Variables:
360.. mode: rst
361.. End:
362