1# 2# CDDL HEADER START 3# 4# The contents of this file are subject to the terms of the 5# Common Development and Distribution License (the "License"). 6# You may not use this file except in compliance with the License. 7# 8# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9# or http://www.opensolaris.org/os/licensing. 10# See the License for the specific language governing permissions 11# and limitations under the License. 12# 13# When distributing Covered Code, include this CDDL HEADER in each 14# file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15# If applicable, add the following below this CDDL HEADER, with the 16# fields enclosed by brackets "[]" replaced with your own identifying 17# information: Portions Copyright [yyyy] [name of copyright owner] 18# 19# CDDL HEADER END 20# 21# 22# Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved. 23# 24 25Mapfiles and versioning in illumos 26================================== 27 281.0 Objective of this README 29 30This README describes the engineering practices of creating and updating 31visible library interfaces. It describes various kinds of actions that 32typically occur as libraries are evolved, and shows how interface 33specifications are affected or updated in accordance. It tells you what 34you must do as a shared library developer if you: 35 36 1. Make interface additions to an existing library 37 - add a Public interface 38 - add a Private interface 39 2. Update an interface in an existing library 40 - remove an existing interface 41 - promote a Private interface to Public 42 - scope a Private interface to local 43 - move an interface from one library to another 44 - copy interfaces which are part of the standard to a new or 45 existing library 46 3. Introduce a new library 47 - source directory hierarchy 48 - creation of the "mapfile-vers" file 49 - Makefiles 50 4. Make an entire library obsolete before end-of-life 51 - introduce SUNWobsolete to the "mapfile-vers" file 52 53------------------------------------------------------------------------------- 54 552.0 What's a mapfile? 56 57Mapfiles are used to tell the link-editor ("ld") all sorts of things about 58how to generate an executable file or a shared object from a collection of 59relocatable objects, such as generated by a compiler. For all the gory 60details, see the Solaris Linker and Libraries Guide. 61 62There are two versions of the mapfile language accepted by the link-editor. 63Version 1 derives from AT&T System V Release 4 Unix. Version 2 is a newer 64syntax specific to Solaris and derivatives. All mapfiles in illumos are 65required to use version 2 syntax. Note that every mapfile using version 2 66syntax must start with the line: 67 68 $mapfile_version 2 69 70Here, we are only concerned with specifying externally-visible interfaces 71for shared libraries (shared objects) and with specifying their versions 72for ABI (Application Binary Interface) purposes. For these purposes, we 73only need to deal with a subset of the mapfile language. 74 75There should be a "mapfile-vers" file associated with every shared library 76and it should reside in the common source directory for that library, most 77often in a "common" directory. This is the usual layout of a library's 78top-level directory (usr/src/lib/libwombat): 79 Makefile amd64/ i386/ sparcv9/ 80 Makefile.com common/ sparc/ 81 82The "common" directory contains the source files and other common files 83for the library: 84 bat.c libwombat_impl.h mapfile-vers wom.c 85 libwombat.h llib-lwombat util.c wombat.c 86 87The mapfile's name is, by convention, "mapfile-vers" because it is used 88for only two purposes: to specify externally-visible interface names while 89suppressing visibility of all other names, and to specify their respective 90unique version names. 91 92------------------------------------------------------------------------------- 93 943.0 Contents of mapfile-vers 95 96The structure of mapfile-vers is best explained by an example 97(the license notification and copyright notice is omitted here 98for brevity): 99 100$mapfile_version 2 101 102SYMBOL_VERSION ILLUMOS_0.2 { # Second interface change in illumos 103 global: 104 wb_notify; 105} ILLUMOS_0.1; 106 107SYMBOL_VERSION ILLUMOS_0.1 { # First interface change in illumos 108 global: 109 wb_poll; 110} SUNW_1.2; 111 112SYMBOL_VERSION SUNW_1.2 { # update to libwombat, Solaris 10 113 global: 114 wb_readv; 115 wb_stat; 116 wb_writev; 117} SUNW_1.1; 118 119SYMBOL_VERSION SUNW_1.1 { # first release of libwombat, Solaris 9 120 global: 121 wb_read; 122 wb_write; 123}; 124 125SYMBOL_VERSION SUNWprivate { # private libwombat symbols 126 global: 127 wb_add; 128 wb_delete; 129 wb_search; 130 local: 131 *; 132}; 133 134Each of these sections is a version declaration describing an ABI version of 135the library containing the set of symbols exposed by the library to 136external callers. 137 138ABI versions must be constant, that is version ILLUMOS_0.2 in a given 139library must always describe the same interface such that applications may 140safely state their dependencies in terms of these versions and have a 141constant and predictable ABI be exposed. This in effect means that once a 142version is publicly visible, it may never be removed or have symbols added 143to or removed from it. 144 145ABI versions with the same major number should be upward compatible, that is 146ILLUMOS_0.3 of a given library must contain all the interfaces in 147ILLUMOS_0.2, and they must be compatible. 148 149The private version, however, is special, and describes any private yet 150exposed symbols within a library, and may change at any time (and without 151notice). It exists purely to allow certain symbols to be of global scope 152but not Public. Similarly, any symbols scoped local are private and may 153change safely, even if the local statement happens to be within a public 154version. 155 156Interface changes made in illumos should be done with ILLUMOS_0.* versions, 157introducing one version per interface change. In illumos, unlike Solaris, 158symbol versions are not release-specific because of the requirement that 159each be constant. No change should be made to add or remove symbols from 160any pre-existing Public version. 161 162The SUNW_*.* names were the Public version names of the library in Solaris. 163There should be at most one version name for each release of Solaris, with 164the minor number incremented by one over the previous version. No changes 165should ever be made to SUNW_1.* versions. 166 167So, for example, to add a new interface to libwombat in illumos one would add: 168 169SYMBOL_VERSION ILLUMOS_0.3 { # Third update to libwombat in illumos 170 global: 171 wb_lseek; 172} ILLUMOS_0.2; 173 174Each version must inherit all symbols from its preceding version, specified at 175the ending "}" for each version. The initial public version does not inherit 176any symbols. The private version named either "SUNWprivate" for libraries 177with private symbols pre-existing illumos, or "ILLUMOSprivate" otherwise 178stands alone, inheriting nothing and being inherited by nothing. 179 180The two lines in SUNWprivate: 181 local: 182 *; 183ensure that no symbols other than those listed in the mapfile are visible to 184clients of the library. If there is no private version, these two lines should 185appear in the first public version. 186 187For maintainability, the list of names in each version block should 188be sorted in dictionary order (sort -d). Please comply. 189 190The version 2 mapfile language supports a simple mechanism for conditional 191input, in which lines in the mapfile apply only to a specific platform or 192ELFCLASS (32/64-bit). This mechanism works very much like the #if/#endif 193feature of the C preprocessor. For instance, the following mapfile declares 194a version SUNW_1.1 that always exports a symbol foo, and also exports 195the symbol bar on 32-bit sparc platforms: 196 197$mapfile_version 2 198SYMBOL_VERSION SUNW_1.1 { 199 foo; 200$if _sparc && _ELF32 201 bar; 202$endif 203}; 204 205Conditional input can be used if there are ISA-specific library interfaces 206not common to all instances of the library. It is the preferred method for 207expressing platform specific items, as long as the differences are simple 208(which is almost always the case). For example, see libproc, or, if you 209are masochistic, libc or libnsl. In general, use of this feature should be 210minimal. 211 212In addition to conditional input, there is a second heavier weight mechanism 213for expressing ISA-specific differences. In addition to the common mapfile: 214 common/mapfile-vers 215some libraries may have ISA-specific supplemental mapfiles, one in each 216of the ISA directories: 217 amd64/mapfile-vers 218 i386/mapfile-vers 219 sparc/mapfile-vers 220 sparcv9/mapfile-vers 221The ISA-specific mapfiles look like the common mapfile, except that only 222the ISA-specific names appear. The version names are the same as those 223in the common mapfile, but only non-empty version instances are present 224and no inheritance specification is present. The link-editor reads the 225information from the common and ISA-specific mapfiles and merges them 226in memory into a single description used to create the resulting object. 227 228ISA-specific mapfiles were used with the version 1 mapfile language, which 229lacked conditional input. Their use is rare now, as conditional input is 230generally preferred. However, it is important to use conditional input 231carefully, or the resulting mapfile can be extremly difficult to read. 232 233------------------------------------------------------------------------------- 234 2354.0 Making interface additions to an existing library 236 2374.1 Adding a Public interface 238 239Public interfaces should be added to a new ILLUMOS_ symbol version, with the 240minor number incremented by one from the current highest version name. If 241this is the first Public interface in the shared object, a new ILLUMOS_0.1 242version name must be introduced. 243 244The major revision number is incremented whenever an incompatible change is 245made to an interface. This could be the case if an API changes so 246dramatically as to invalidate dependencies. This should almost never occur 247in practice. It also requires changing the suffix of the shared object 248from, say, .so.1 to .so.2 and introducing code to continue to ship the .so.1 249version of the library. 250 251The minor revision number is incremented whenever one or more new interfaces 252is added to a library. Once a version comes to exist in illumos, it is from 253that point onward considered to be immutable. 254 255While strongly discouraged, if it is necessary to add global data symbols to a 256library (which become part of the ABI), an assertion that specifies the size 257of the object must be added. 258 2594.2 Adding a Private interface 260 261Private interfaces are the non-ABI interfaces of the library. Unlike 262introducing a Public interface, a new entry is simply added to the 263private version. No minor number increment is necessary. 264 265If this interface happens to be the first Private interface introduced into 266the library, the private version must be created (with no major.minor 267version numbers). It inherits nothing, nothing inherits from it and it 268should be named ILLUMOSprivate. 269 270If the library already has Private interfaces in a SUNWprivate version, you 271should use that. They may have numbered version names like SUNWprivate_m.n 272(due to errors of the past). If so, just use the highest numbered private 273version name to version the new interface. There is no need to introduce a 274new private version name. Be careful not to use a lower numbered private 275version name; doing so can cause runtime errors (as opposed to load time 276errors) when running an application with older versions of the library. 277 278There are also libraries in illumos that contain only private interfaces. In 279such libraries, the private versions maybe legitimately be versioned and 280they may be incremented to ensure that the programs that depend on them are 281built and delivered as a integrated unit. A notable example of this is 282libld.so (usr/src/cmd/sgs/libld), which contains the implementation of the 283link-editor, the public interface to which is provided by the ld 284command. When making a modification to the interface of such a library, you 285should follow the convention already in place. 286 287As with public interfaces, the size of global objects must be asserted in 288private versions (though it will be less problematic to change them later). 289 2904.3 Historical handling of Solaris update releases. 291 292To aid the understanding of our existing mapfiles, it is useful to note how 293interface versions were handled as they interacted with update releases of 294Solaris. Solaris update releases required careful coordination with the full 295release currently under development to keep symbol versions constant between 296releases. 297 298Multiple update releases were generally shipped during the development of the 299next full release of Solaris. It was impossible to know in advance the full 300set of new interfaces in the next full release until it was complete. Some, 301though not all, new interfaces were included in the intervening update 302releases between full releases. 303 304Consequently, the new version number for an update cannot be a minor 305increment, but must be a micro increment to ensure that was a distinct version 306between the two releases. For example, if Release N had version number 307SUNW_1.3 and Release N+1 had SUNW_1.4, then interfaces added to an update of 308Release N must have micro numbers such as SUNW_1.3.1, SUNW_1.3.2, etc. (note 309that the micro number is not directly tied to the update number: SUNW_1.3.1 310may have appeared in Update 2). The micro versions form an inheritance chain 311that is inserted between two successive minor versions. For example, the 312mapfile-vers file for minor release "N+1" to reflect its inclusion of micro 313releases will look like the following: 314 315$mapfile_version 2 316 317SYMBOL_VERSION SUNW_1.4 { # release N+1 318 global: 319 ... 320} SUNW_1.3.2; 321 322SYMBOL_VERSION SUNW_1.3.2 { # micro release 2 (e.g., release NU3) 323 global: 324 ... 325} SUNW_1.3.1; 326 327SYMBOL_VERSION SUNW_1.3.1 { # micro release 1 (e.g., release NU2) 328 global: 329 ... 330} SUNW_1.3; 331 332SYMBOL_VERSION SUNW_1.3 { # release N 333 global: 334 ... 335} SUNW_1.2; 336 337SYMBOL_VERSION SUNW_1.2 { # release N-1 338 global: 339 ... 340} SUNW_1.1; 341 342SYMBOL_VERSION SUNW_1.1 { # first release 343 global: 344 ... 345}; 346 347SYMBOL_VERSION SUNW_private { # same in all releases 348 global: 349 ... 350 local: 351 *; 352}; 353 354The corresponding update/patch mapfile-vers file will be identical 355except for the exclusion of SUNW_1.4. 356 357Those interfaces which are only present in Release N+1 are always put 358into the next minor version set, SUNW_1.4. 359 360Thus when adding a new Public interface to an update release, both the mapfiles 361of the update release and next full release should have been modified to be 362consistent. 363 364There have been several cases of accidental deviation from this scheme, and 365existing mapfiles sometimes reflect this unfortunate state of affairs. 366 367------------------------------------------------------------------------------- 368 3695.0 How to update an interface in an existing library 370 3715.1 Removing an existing interface 372 3735.1.1 Moving a Public interface 374 375No Public interfaces should ever be removed from any mapfile, as this will 376break all existing consumers of that interface. 377 378To move an interface from one library to (say) libc, the code has to be 379deleted from the library and added to libc, then the mapfile for the 380library has to have the interface's entry changed from: 381 getfoobar; 382to: 383 getfoobar { TYPE = FUNCTION; FILTER = libc.so.1 }; 384This is an exception to the immutability of public symbol versions. See, 385for example, libnsl's common/mapfile-vers file. 386 387Follow the rules for adding a new interface for the necessary changes 388to libc's mapfile to accommodate the moved interface, including creating a 389new version in libc for the symbol. 390 391When merging an entire library into libc, the mapfile is changed to specify 392the type of each public symbol similarly to the above: 393 getfoobar; 394to: 395 getfoobar { TYPE = FUNCTION }; 396 397But rather than specifying the library on which we filter for each symbol, 398the link-editor is invoked with '-F libc.so.1' to specify that our entire 399symbol table is a filter on libc. For examples, see libaio and librt. 400 4015.1.2 Removing a Private interface 402 403Deletion of Private interfaces is allowed, but caution should be taken; 404it should first be established that the interface is not being used. 405To remove a Private interface, simply delete the corresponding entry 406for that symbol from the mapfile's private version section. 407 408Do not forget to delete these Public or Private interfaces from the library's 409header files as well as from the code that implements the interfaces. 410 4115.2 Promoting a Private interface to Public 412 413This is similar to what's done when adding a Public interface. Promoting an 414existing Private interface to a Public one only requires a change to the 415existing interface definition. Private interfaces have the symbol version 416name "ILLUMOSprivate" or "SUNWprivate" associated with them. To make the 417interface a Public one, the interface must be added as if it were a new 418public symbol, following those same rules and removed from the private 419version. 420 421As an example, if we were modifying libwombat.so.1 and its existing latest 422version were ILLUMOS_0.3, any new ABI would be put into a version called 423ILLUMOS_0.4. Therefore, whether you wish to promote an existing Private 424interface to Public, or to introduce a new Public interface, this (next 425successive minor numbered version level) would be the version that it would 426be associated with. 427 4285.3 Scoping a Private interface local 429 430Any interfaces not present in the mapfile-vers file will be scoped local 431due to the presence of the 432 local: 433 *; 434lines discussed earlier. This ensures that such interfaces will not be visible 435outside the library. To move an interface from Private to local scope, simply 436remove the Private interface from the mapfile-vers file and the header file 437to prevent it from being exported. This may require moving the Private 438interface into a library-private header file. Scope reduction of Public 439interfaces is forbidden. 440 441For the interface to be used in more than one file within the library, it 442should be in a header file that can be included by each file in the library 443that uses the interface. For example: 444 445 #include "libprivate.h" 446 4475.4 How to copy interfaces which are part of a standard to a new or existing 448 library 449 450SYSVABI and SISCD are reserved version names for interfaces listed in the 451System V Interface Definition and the Sparc Compliance Definition. Avoid 452using these version names when copying the implementation of standard 453interfaces to another library. Instead, use ILLUMOS_0.1 for a new library, 454and ILLUMOS_m.n for an existing library (where m.n is the next version; i.e., 455if the last version was ILLUMOS_0.8, then you should version the interfaces 456with ILLUMOS_0.9). 457 458------------------------------------------------------------------------------- 459 4606.0 Introducing a new library 461 4626.1 Directories 463 464The normal discipline for introducing a new library in illumos is to create a 465new subdirectory of usr/src/lib. The interface definition discipline is to 466create a common/mapfile-vers file for the new library. If we were introducing 467a new foo library, libfoo, we'd create usr/src/lib/libfoo containing: 468 Makefile amd64/ i386/ sparcv9/ 469 Makefile.com common/ sparc/ 470The common subdirectory would contain the normal source files plus the 471mapfile-vers file. See usr/src/lib/README.Makefiles for directions on 472how to organize the Makefiles. 473 4746.2 The mapfile 475 476The new common/mapfile-vers file would contain: 477 478$mapfile_version 2 479 480SYMBOL_VERSION ILLUMOS_0.1 { # first release of libfoo 481 global: 482 ... 483}; 484 485SYMBOL_VERSION ILLUMOSprivate { 486 global: 487 ... 488 local: 489 *; 490}; 491 492If there are no Public interfaces, the ILLUMOS_0.1 section would be omitted. 493If there are no Private interfaces, the ILLUMOSprivate section would be 494omitted and the two lines: 495 local: 496 *; 497would be moved into ILLUMOS_0.1. 498 499To decide which interfaces are Public (part of the ABI) and which are 500Private (unstable interfaces not intended to be used by third parties), the 501heuristic which works to a first approximation is that if it has a man page 502then it's Public. 503 504For maintainability, the list of names in each version block should 505be sorted in dictionary order (sort -d). Please comply. 506 507------------------------------------------------------------------------------- 508 5097.0 Make an entire library obsolete 510 5117.1 Introduce SUNWobsolete version 512 513Use this version name not for specific interfaces but for marking an entire 514library as obsolete. The existing public/private version names are left 515unchanged, but a new SUNWobsolete version is created with no symbols in it. 516This becomes a tag by which the obsolescence of the library can be recognized. 517There is no numbering of this version name. 518 519$mapfile_version 2 520 521SYMBOL_VERSION SUNWobsolete { 522 global: 523 SUNWobsolete; # This is the only way to do it. 524} SUNW_1.2; 525 526SYMBOL_VERSION ILLUMOS_0.2 { 527... 528 529You should continue to use the name SUNWobsolete even in illumos. 530 531------------------------------------------------------------------------------- 532 5338.0 Documentation 534 535For further information, please refer to the following documents: 536 537 "Solaris Linker and Libraries Guide" 538