1. Summary

International Components for Unicode (ICU) is a multi-platform, multi-locale, and MT-safe I18N API with C and C++ bindings. It comes from the ICU open source community. This project is to deliver the latest and stable ICU libraries and header files to Solaris.

2. Decision & Precedence Information

The project is approved as specified in [1] and [2].

The project may be delivered in any release of Solaris.

3. Interfaces

Interfaces Exported
Interface Name	Classification	Comment
/usr/lib/libicudata.so	Contracted Consolidation Private	[2]
/usr/lib/libicui18n.so	Contracted Consolidation Private	[2]
/usr/lib/libicule.so	Contracted Consolidation Private	[2]
/usr/lib/libicutoolutil.so	Contracted Consolidation Private	[2]
/usr/lib/libicuuc.so	Contracted Consolidation Private	[2]
/usr/lib/libustdio.so	Contracted Consolidation Private	[2]
/usr/include/unicode/*.h	Contracted Consolidation Private	[2]
/usr/include/layout/*.h	Contracted Consolidation Private	[2]

4. Opinion

There were two major areas of concern.

4.1 C++ ABI

The semantics of C++ make it much harder to maintain binary compatibility while evolving a library which presents a C++ interface. In particular, the committee is concerned that clients of an older shared library can safely use a newer version and that the constraints on library maintenance required to meet that goal can be expressed without undue complexity.

4.1.1 Problem Areas

The following elements are among those which contribute to the ABI of a library whose API is defined in C++:
• template definitions visible to application
• inline function definitions visible to application
• Standard Library version (if used inside the library)
• compiler version and options
• complete class/struct definitions visible to application

where visible to the application means present in any include file specified to define the libraries API and any nested includes.

All these elements must only evolve in a compatible way.

This whole discussion assumes that any evolution of the API maintains compatibility - i.e. none of the elements of the ABI change their meaning. Also everything in this description is worthless if the library API lies - i.e. the definitions referenced when building the library don't match those in the API.

4.1.2 Sameness

Several of the sections below require that various definitions be the same. The simplest definition of "same" is textually identical. However, two definitions that scan into the same token stream after preprocessing also are the same.

Another loop hole in the definition of sameness is that the ABI is not affected when function arguments, local variables, data members, or enumeration constants are renamed.

4.1.3 Templates and inline functions

Use of either of those two facilities incorporates details of the library implementation into the application. The consequence is that from the perspective of the ABI no C++ object is opaque. Any change to a library data structure may invalidate the application.

Having template/inline definitions be the same between library versions obviously preserves compatibility. However, changing a function's implementation is O.K. in those cases in which the old version would still work.

4.1.4 Standard Library

The standard library is heavily based on inline and/or template functions (some implementations have almost no shared library component) and different vendor's libraries use very different internal structures. As a result all C++ code that will end up running in the same process should be built using compatible versions of the same shared library.

The Forte default standard library is guaranteed to be stable across releases.

4.1.5 Compiler differences

Name mangling, implementation of virtual functions, and class layout are among the areas not covered by any standard. No two vendors agree. Some, like GNU, make changes release to release. Also code generated by different compilers require separate run-time support code. Frequently the different support libraries don't coexist.

While exceptions are possible, the safest constraint is to require that all C++ code that executes in the same process be compiled with the same compiler.

All Forte C++ compilers - compiler version 5.1 or newer - can be considered as the "same" when run with option "-compat=5" (currently the default). (The one exception is that Forte doesn't support linking code generated by a later compiler than the one doing the linking - a limitation that isn't relevant to use of shared libraries.)

4.1.6 Modification of Class definitions

Because of the way inheritance and virtual functions are implemented few changes to class definitions can be guaranteed compatible. For example: adding a private data member to the end of a class may affect child classes. You can add non-virtual member functions and static function and data members to a class without breaking binary compatibility. You might break source compatibility if added functions overload existing class members.

Again keeping class definitions the same between versions of the library is the safest strategy.

4.1.7 Safe Additions

Adding new class, function, or data declarations at file or namespace scope will not break binary compatability. You might break source compatibility if added functions overload existing ones and adding a new declaration at file scope might cause name collisions.

(Note: the C++ namespace mechanism is a much better way to avoid name collisions than the C technique of starting every function name with a unique prefix. No C++ library intended for wide use should export file scope definitions.)

4.1.8 A Practical Policy for Binary Compatibility

A library presenting a C++ API can maintain a stable ABI if the following restrictions are obeyed:
1. compile with the Sun C++ compiler in standard mode (-compat=5)
2. when building the library include all files which define the external API
3. keep the files defining the external API the "same" or augment them only as described just above.

These restrictions are sufficiently straight-forward that the committee recommends that any project willing to formally agree to accept these requirements be permitted to supply a library with a C++ interface. Any user of the library must be willing to accept restriction 1.

The committee was concerned about how the restrictions enumerated above could be communicated and enforced. It was decided to establish a policy that a library exporting a C++ interface not be allowed to classify that interface either "Evolving" or "Stable". The stability level recommended for use of the library within Sun should be "Contracted Consolidation Private" with the contract (see [6]) enumerating the restrictions.

4.2 External?

The ICU code has two conflicting characteristics:
• The intended usage is by Sun internal groups, spread across multiple consolidations. There isn't intended to be public (customer) visibility or usage of these interfaces.
• The support model is to pass-thru the public sources with as little change as possible.

As discussed in [5], the two characteristics lead to different choices of stability level and file location. Priority was given to the intended usage and the project deliverables will be located in /usr/lib not /usr/sfw/lib.

5. Minority Opinion(s)

None.

6. Advisory Information

The change in policy on the use of C++ (partially superseding [7]) should be widely communicated.

Appendices

Appendix A: Technical Changes Required

None

Appendix B: Technical Changes Advised

None

Appendix C: Reference Material

Unless otherwise stated, path names are relative to the case directory (PSARC/2002/348).
1. materials/fasttrack-case4.txt
   Project Specification
2. materials/APIREF-2.1/index.html
   ICU 2.1 Reference Usage and User's Guide.
3. materials/man-2.1
   ICU 2.1 Utility Man Pages (For future reference only the utilities are not delivered into Solaris.)
4. http://oss.software.ibm.com/icu/
   ICU Open Source Community URL
5. mail
   Case mail log.
6. contract_template.txt
   Sample contract.
7. /shared/sac/LSARC/1993/571/opinion.txt
   LSARC Guidelines for C++.