diff options
Diffstat (limited to 'usr/src/lib/README.mapfiles')
| -rw-r--r-- | usr/src/lib/README.mapfiles | 301 |
1 files changed, 172 insertions, 129 deletions
diff --git a/usr/src/lib/README.mapfiles b/usr/src/lib/README.mapfiles index c94ffe8b91..560226938e 100644 --- a/usr/src/lib/README.mapfiles +++ b/usr/src/lib/README.mapfiles @@ -22,8 +22,8 @@ # Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved. # -Mapfiles and versioning in ON -============================= +Mapfiles and versioning in illumos +================================== 1.0 Objective of this README @@ -57,12 +57,11 @@ you must do as a shared library developer if you: Mapfiles are used to tell the link-editor ("ld") all sorts of things about how to generate an executable file or a shared object from a collection of relocatable objects, such as generated by a compiler. For all the gory -details, see the Solaris Linker and Libraries Guide, which can be found -under http://docs.sun.com. +details, see the Solaris Linker and Libraries Guide. There are two versions of the mapfile language accepted by the link-editor. Version 1 derives from AT&T System V Release 4 Unix. Version 2 is a newer -syntax specific to Solaris. All mapfiles in the OSnet (ON consolidation) are +syntax specific to Solaris and derivatives. All mapfiles in illumos are required to use version 2 syntax. Note that every mapfile using version 2 syntax must start with the line: @@ -100,6 +99,16 @@ for brevity): $mapfile_version 2 +SYMBOL_VERSION ILLUMOS_0.2 { # Second interface change in illumos + global: + wb_notify; +} ILLUMOS_0.1; + +SYMBOL_VERSION ILLUMOS_0.1 { # First interface change in illumos + global: + wb_poll; +} SUNW_1.2; + SYMBOL_VERSION SUNW_1.2 { # update to libwombat, Solaris 10 global: wb_readv; @@ -122,34 +131,58 @@ SYMBOL_VERSION SUNWprivate { # private libwombat symbols *; }; -The SUNW_1.* names are the Public version names for the library. -There should be at most one version name for each release of Solaris, -with the minor number incremented by one over the previous version. - -If no update to the Public-visible names in the library is made -in a given Solaris release, no new version name should be generated -for that release. If multiple updates are made to the library at -different points in the development of a given release of Solaris, -only one version should be used for the entire release. - -So, for example, if an update to libwombat is made in Solaris 11, -you would add "SUNW_1.3" at the start of the mapfile: - -SYMBOL_VERSION SUNW_1.3 { # update to libwombat, Solaris 11 +Each of these sections is a version declaration describing an ABI version of +the library containing the set of symbols exposed by the library to +external callers. + +ABI versions must be constant, that is version ILLUMOS_0.2 in a given +library must always describe the same interface such that applications may +safely state their dependencies in terms of these versions and have a +constant and predictable ABI be exposed. This in effect means that once a +version is publicly visible, it may never be removed or have symbols added +to or removed from it. + +ABI versions with the same major number should be upward compatible, that is +ILLUMOS_0.3 of a given library must contain all the interfaces in +ILLUMOS_0.2, and they must be compatible. + +The private version, however, is special, and describes any private yet +exposed symbols within a library, and may change at any time (and without +notice). It exists purely to allow certain symbols to be of global scope +but not Public. Similarly, any symbols scoped local are private and may +change safely, even if the local statement happens to be within a public +version. + +Interface changes made in illumos should be done with ILLUMOS_0.* versions, +introducing one version per interface change. In illumos, unlike Solaris, +symbol versions are not release-specific because of the requirement that +each be constant. No change should be made to add or remove symbols from +any pre-existing Public version. + +The SUNW_*.* names were the Public version names of the library in Solaris. +There should be at most one version name for each release of Solaris, with +the minor number incremented by one over the previous version. No changes +should ever be made to SUNW_1.* versions. + +So, for example, to add a new interface to libwombat in illumos one would add: + +SYMBOL_VERSION ILLUMOS_0.3 { # Third update to libwombat in illumos global: wb_lseek; -} SUNW_1.2; +} ILLUMOS_0.2; -Each version must inherit all symbols from its preceding version, -specified at the ending "}" for each version. SUNW_1.1 does not -inherit any symbols. SUNWprivate, if present, stands alone. +Each version must inherit all symbols from its preceding version, specified at +the ending "}" for each version. The initial public version does not inherit +any symbols. The private version named either "SUNWprivate" for libraries +with private symbols pre-existing illumos, or "ILLUMOSprivate" otherwise +stands alone, inheriting nothing and being inherited by nothing. The two lines in SUNWprivate: local: *; -ensure that no symbols other than those listed in the mapfile are -visible to clients of the library. If there is no SUNWprivate, -these two lines should appear in SUNW_1.1. +ensure that no symbols other than those listed in the mapfile are visible to +clients of the library. If there is no private version, these two lines should +appear in the first public version. For maintainability, the list of names in each version block should be sorted in dictionary order (sort -d). Please comply. @@ -173,7 +206,8 @@ Conditional input can be used if there are ISA-specific library interfaces not common to all instances of the library. It is the preferred method for expressing platform specific items, as long as the differences are simple (which is almost always the case). For example, see libproc, or, if you -are masochistic, libc or libnsl. +are masochistic, libc or libnsl. In general, use of this feature should be +minimal. In addition to conditional input, there is a second heavier weight mechanism for expressing ISA-specific differences. In addition to the common mapfile: @@ -202,68 +236,74 @@ carefully, or the resulting mapfile can be extremly difficult to read. 4.1 Adding a Public interface -The first engineer to update the existing mapfile-vers file in a release needs -to identify the current highest version name and properly increment the minor -version number by 1 to be the new version name. If this is the first Public -interface in the shared object, a new SUNW_1.1 version name must be introduced. +Public interfaces should be added to a new ILLUMOS_ symbol version, with the +minor number incremented by one from the current highest version name. If +this is the first Public interface in the shared object, a new ILLUMOS_0.1 +version name must be introduced. The major revision number is incremented whenever an incompatible change is -made to an interface. This could be the case if an API changes so dramatically -as to invalidate dependencies. This rarely occurs in practice. It also -requires changing the suffix of the shared object from, say, .so.1 to .so.2 -and introducing code to continue to ship the .so.1 version of the library. +made to an interface. This could be the case if an API changes so +dramatically as to invalidate dependencies. This should almost never occur +in practice. It also requires changing the suffix of the shared object +from, say, .so.1 to .so.2 and introducing code to continue to ship the .so.1 +version of the library. The minor revision number is incremented whenever one or more new interfaces -is added to a library. Note that the minor number is not incremented on every -putback that makes an interface addition to the library. Rather, it is -incremented at most once per (external to Sun) release of the library. +is added to a library. Once a version comes to exist in illumos, it is from +that point onward considered to be immutable. 4.2 Adding a Private interface Private interfaces are the non-ABI interfaces of the library. Unlike introducing a Public interface, a new entry is simply added to the -SUNWprivate version. No minor number increment is necessary. - -If this interface happens to be the first Private interface introduced -into the library, the SUNWprivate version must be created (no major.minor -version numbers). It inherits nothing and nothing inherits from it. - -If the library already has Private interfaces, they may have numbered version -names like SUNWprivate_m.n (due to errors of the past). If so, just use the -highest numbered private version name to version the new interface. There -is no need to introduce a new private version name. Be careful not to use -a lower numbered private version name; doing so can cause runtime errors -(as opposed to load time errors) when running an application with older -versions of the library. - -There are libraries in the OSnet consolidation that contain only private -interfaces. In such libraries, the SUNWprivate_m.n may be incremented -to ensure that the programs that depend on them are built and delivered as a -integrated unit. A notable example of this is libld.so (usr/src/cmd/sgs/libld), -which contains the implementation of the link-editor, the public interface to -which is provided by the ld command. When making a modification to the interface -of such a library, you should follow the convention already in place. - -4.3 Adding new public interfaces in an update release - -Adding new public interfaces in an update release requires careful -coordination with the next marketing release currently under development. -Multiple updates ship during the period before the next marketing release -ships, and since it is generally impossible to know the full set of new -interfaces in the next marketing release until late in its development -(after multiple updates have shipped) it must be assumed that not all -interfaces added to the next marketing release will be added to an update. +private version. No minor number increment is necessary. + +If this interface happens to be the first Private interface introduced into +the library, the private version must be created (with no major.minor +version numbers). It inherits nothing, nothing inherits from it and it +should be named ILLUMOSprivate. + +If the library already has Private interfaces in a SUNWprivate version, you +should use that. They may have numbered version names like SUNWprivate_m.n +(due to errors of the past). If so, just use the highest numbered private +version name to version the new interface. There is no need to introduce a +new private version name. Be careful not to use a lower numbered private +version name; doing so can cause runtime errors (as opposed to load time +errors) when running an application with older versions of the library. + +There are also libraries in illumos that contain only private interfaces. In +such libraries, the private versions maybe legitimately be versioned and +they may be incremented to ensure that the programs that depend on them are +built and delivered as a integrated unit. A notable example of this is +libld.so (usr/src/cmd/sgs/libld), which contains the implementation of the +link-editor, the public interface to which is provided by the ld +command. When making a modification to the interface of such a library, you +should follow the convention already in place. + +4.3 Historical handling of Solaris update releases. + +To aid the understanding of our existing mapfiles, it is useful to note how +interface versions were handled as they interacted with update releases of +Solaris. Solaris update releases required careful coordination with the full +release currently under development to keep symbol versions constant between +releases. + +Multiple update releases were generally shipped during the development of the +next full release of Solaris. It was impossible to know in advance the full +set of new interfaces in the next full release until it was complete. Some, +though not all, new interfaces were included in the intervening update +releases between full releases. Consequently, the new version number for an update cannot be a minor -increment, but must be a micro increment. For example, if Release N -has version number SUNW_1.3 and Release N+1 will have SUNW_1.4, then -interfaces added to an update of Release N must have micro numbers such -as SUNW_1.3.1, SUNW_1.3.2, etc. (note that the micro number is not -directly tied to the update number: SUNW_1.3.1 may appear in Update 2). -The micro versions form an inheritance chain that is inserted between -two successive minor versions. For example, the mapfile-vers file for -minor release "N+1" to reflect its inclusion of micro releases will -look like the following: +increment, but must be a micro increment to ensure that was a distinct +version between the two releases. For example, if Release N had version +number SUNW_1.3 and Release N+1 had SUNW_1.4, then interfaces added to +an update of Release N must have micro numbers such as SUNW_1.3.1, +SUNW_1.3.2, etc. (note that the micro number is not directly tied to the +update number: SUNW_1.3.1 may have appeared in Update 2). The micro versions form +an inheritance chain that is inserted between two successive minor versions. +For example, the mapfile-vers file for minor release "N+1" to reflect its +inclusion of micro releases will look like the following: $mapfile_version 2 @@ -310,12 +350,12 @@ except for the exclusion of SUNW_1.4. Those interfaces which are only present in Release N+1 are always put into the next minor version set, SUNW_1.4. -Thus when adding a new public interface to an update, both the mapfiles -of the update release and next marketing release must be modified to be -consistent. The update versions should not be added to the marketing -release until the putback to the update release has occurred, to avoid -timing problems with the update releases (it's all too easy for projects -to slip out of updates, or to change ordering). +Thus when adding a new Public interface to an update release, both the mapfiles +of the update release and next full release should have been modified to be +consistent. + +There have been several cases of accidental deviation from this scheme, and +existing mapfiles sometimes reflect this unfortunate state of affairs. ------------------------------------------------------------------------------- @@ -325,7 +365,8 @@ to slip out of updates, or to change ordering). 5.1.1 Moving a Public interface -No Public interfaces should ever be removed from any mapfile. +No Public interfaces should ever be removed from any mapfile, as this will +break all existing consumers of that interface. To move an interface from one library to (say) libc, the code has to be deleted from the library and added to libc, then the mapfile for the @@ -333,21 +374,29 @@ library has to have the interface's entry changed from: getfoobar; to: getfoobar { TYPE = FUNCTION; FILTER = libc.so.1 }; -See, for example, libnsl's common/mapfile-vers file. +This is an exception to the immutability of public symbol versions. See, +for example, libnsl's common/mapfile-vers file. Follow the rules for adding a new interface for the necessary changes -to libc's mapfile to accommodate the moved interface. In particular, -the new interface must be added to the current highest libc version. +to libc's mapfile to accommodate the moved interface, including creating a +new version in libc for the symbol. -To move an entire library into libc, look at what has already been done -for libthread, libaio, and librt. +When merging an entire library into libc, the mapfile is changed to specify +the type of each public symbol similarly to the above: + getfoobar; +to: + getfoobar { TYPE = FUNCTION }; + +But rather than specifying the library on which we filter for each symbol, +the link-editor is invoked with '-F libc.so.1' to specify that our entire +symbol table is a filter on libc. For examples, see libaio and librt. 5.1.2 Removing a Private interface Deletion of Private interfaces is allowed, but caution should be taken; it should first be established that the interface is not being used. To remove a Private interface, simply delete the corresponding entry -for that symbol from the mapfile's SUNWprivate section. +for that symbol from the mapfile's private version section. Do not forget to delete these Public or Private interfaces from the library's header files as well as from the code that implements the interfaces. @@ -356,17 +405,18 @@ header files as well as from the code that implements the interfaces. This is similar to what's done when adding a Public interface. Promoting an existing Private interface to a Public one only requires a change to the -existing interface definition. Private interfaces have the symbol version name -"SUNWprivate" associated with them. To make the interface a Public one, the -interface must be put into a set associated with the current Public release -level of the library. - -As an example, if we were modifying libwombat.so.1 and its version in the -last release of Solaris was SUNW_1.23, any new ABI introduced in the next -release would be put into a version called SUNW_1.24. Therefore, whether -you wish to promote an existing Private interface to Public, or to introduce -a new Public interface, this (next successive minor numbered version level) -would be the version that it would be associated with. +existing interface definition. Private interfaces have the symbol version +name "ILLUMOSprivate" or "SUNWprivate" associated with them. To make the +interface a Public one, the interface must be added as if it were a new +public symbol, following those same rules and removed from the private +version. + +As an example, if we were modifying libwombat.so.1 and its existing latest +version were ILLUMOS_0.3, any new ABI would be put into a version called +ILLUMOS_0.4. Therefore, whether you wish to promote an existing Private +interface to Public, or to introduce a new Public interface, this (next +successive minor numbered version level) would be the version that it would +be associated with. 5.3 Scoping a Private interface local @@ -379,7 +429,7 @@ outside the library. To move an interface from Private to local scope, simply remove the Private interface from the mapfile-vers file and the header file to prevent it from being exported. This may require moving the Private interface into a library-private header file. Scope reduction of Public -interfaces is not allowed without specific ARC review and approval. +interfaces is forbidden. For the interface to be used in more than one file within the library, it should be in a header file that can be included by each file in the library @@ -393,10 +443,10 @@ that uses the interface. For example: SYSVABI and SISCD are reserved version names for interfaces listed in the System V Interface Definition and the Sparc Compliance Definition. Avoid using these version names when copying the implementation of standard interfaces to -another library. Instead, use SUNW_1.1 for a new library, and SUNW_m.n for -an existing library (where m.n is the next release version; i.e., if the -last version was SUNW_1.18, then you should version the interfaces with -SUNW_1.19). +another library. Instead, use ILLUMOS_0.1 for a new library, and ILLUMOS_m.n for +an existing library (where m.n is the next version; i.e., if the +last version was ILLUMOS_0.8, then you should version the interfaces with +ILLUMOS_0.9). ------------------------------------------------------------------------------- @@ -404,10 +454,10 @@ SUNW_1.19). 6.1 Directories -The normal discipline for introducing a new library in OS/Net is to create a -new subdirectory of /usr/src/lib. The interface definition discipline is to +The normal discipline for introducing a new library in illumos is to create a +new subdirectory of usr/src/lib. The interface definition discipline is to create a common/mapfile-vers file for the new library. If we were introducing -a new foo library, libfoo, we'd create /usr/src/lib/libfoo containing: +a new foo library, libfoo, we'd create usr/src/lib/libfoo containing: Makefile amd64/ i386/ sparcv9/ Makefile.com common/ sparc/ The common subdirectory would contain the normal source files plus the @@ -420,31 +470,29 @@ The new common/mapfile-vers file would contain: $mapfile_version 2 -SYMBOL_VERSION SUNW_1.1 { # first release of libfoo +SYMBOL_VERSION ILLUMOS_0.1 { # first release of libfoo global: ... }; -SYMBOL_VERSION SUNWprivate { +SYMBOL_VERSION ILLUMOSprivate { global: ... local: *; }; -If there are no Public interfaces, the SUNW_1.1 section would be omitted. -If there are no Private interfaces, the SUNWprivate section would be +If there are no Public interfaces, the ILLUMOS_0.1 section would be omitted. +If there are no Private interfaces, the ILLUMOSprivate section would be omitted and the two lines: local: *; would be moved into SUNW_1.1 -To decide which interfaces are Public (part of the ABI) and which are Private -(unstable interfaces not intended to be used by third party applications or -unbundled products), the heuristic which works to a first approximation is -that if it has a man page then it's Public. Also, it is really the ARC case -for the new interfaces that prescribes which interfaces are Public and -which are not (hence, which interfaces have man pages and which do not). +To decide which interfaces are Public (part of the ABI) and which are +Private (unstable interfaces not intended to be used by third parties), the +heuristic which works to a first approximation is that if it has a man page +then it's Public. For maintainability, the list of names in each version block should be sorted in dictionary order (sort -d). Please comply. @@ -468,20 +516,15 @@ SYMBOL_VERSION SUNWobsolete { SUNWobsolete; # This is the only way to do it. } SUNW_1.2; -SYMBOL_VERSION SUNW_1.2 { +SYMBOL_VERSION ILLUMOS_0.2 { ... +You should continue to use the name SUNWobsolete even in illumos. + ------------------------------------------------------------------------------- 8.0 Documentation For further information, please refer to the following documents: - "Solaris Linker and Libraries Guide", http://docs.sun.com - /shared/ON/general_docs/scoping-rules.fm.ps - -For information on the now-obsolete spec files, used in Solaris releases -7 through 10, see: - /shared/ON/general_docs/README.spec - /shared/ON/general_docs/libspec-rules.ps - /shared/ON/general_docs/spectrans/* + "Solaris Linker and Libraries Guide" |