| README.mapfiles (cd3e933325e68e23516a196a8fea7f49b1e497c3) | README.mapfiles (0409b95313ea0f1170e12bceddd2b14e70665a63) |
|---|---|
| 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 --- 8 unchanged lines hidden (view full) --- 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 | 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 --- 8 unchanged lines hidden (view full) --- 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 ON 26============================= | 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: --- 17 unchanged lines hidden (view full) --- 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 | 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: --- 17 unchanged lines hidden (view full) --- 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, which can be found 61under http://docs.sun.com. | 60details, see the Solaris Linker and Libraries Guide. |
| 62 63There are two versions of the mapfile language accepted by the link-editor. 64Version 1 derives from AT&T System V Release 4 Unix. Version 2 is a newer | 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 |
| 65syntax specific to Solaris. All mapfiles in the OSnet (ON consolidation) are | 64syntax specific to Solaris and derivatives. All mapfiles in illumos are |
| 66required to use version 2 syntax. Note that every mapfile using version 2 67syntax must start with the line: 68 69 $mapfile_version 2 70 71Here, we are only concerned with specifying externally-visible interfaces 72for shared libraries (shared objects) and with specifying their versions 73for ABI (Application Binary Interface) purposes. For these purposes, we --- 21 unchanged lines hidden (view full) --- 953.0 Contents of mapfile-vers 96 97The structure of mapfile-vers is best explained by an example 98(the license notification and copyright notice is omitted here 99for brevity): 100 101$mapfile_version 2 102 | 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 --- 21 unchanged lines hidden (view full) --- 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 |
|
| 103SYMBOL_VERSION SUNW_1.2 { # update to libwombat, Solaris 10 104 global: 105 wb_readv; 106 wb_stat; 107 wb_writev; 108} SUNW_1.1; 109 110SYMBOL_VERSION SUNW_1.1 { # first release of libwombat, Solaris 9 --- 6 unchanged lines hidden (view full) --- 117 global: 118 wb_add; 119 wb_delete; 120 wb_search; 121 local: 122 *; 123}; 124 | 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 --- 6 unchanged lines hidden (view full) --- 126 global: 127 wb_add; 128 wb_delete; 129 wb_search; 130 local: 131 *; 132}; 133 |
| 125The SUNW_1.* names are the Public version names for the library. 126There should be at most one version name for each release of Solaris, 127with the minor number incremented by one over the previous version. | 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. |
| 128 | 137 |
| 129If no update to the Public-visible names in the library is made 130in a given Solaris release, no new version name should be generated 131for that release. If multiple updates are made to the library at 132different points in the development of a given release of Solaris, 133only one version should be used for the entire release. | 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. |
| 134 | 144 |
| 135So, for example, if an update to libwombat is made in Solaris 11, 136you would add "SUNW_1.3" at the start of the mapfile: | 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. |
| 137 | 148 |
| 138SYMBOL_VERSION SUNW_1.3 { # update to libwombat, Solaris 11 | 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 |
| 139 global: 140 wb_lseek; | 170 global: 171 wb_lseek; |
| 141} SUNW_1.2; | 172} ILLUMOS_0.2; |
| 142 | 173 |
| 143Each version must inherit all symbols from its preceding version, 144specified at the ending "}" for each version. SUNW_1.1 does not 145inherit any symbols. SUNWprivate, if present, stands alone. | 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. |
| 146 147The two lines in SUNWprivate: 148 local: 149 *; | 179 180The two lines in SUNWprivate: 181 local: 182 *; |
| 150ensure that no symbols other than those listed in the mapfile are 151visible to clients of the library. If there is no SUNWprivate, 152these two lines should appear in SUNW_1.1. | 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. |
| 153 154For maintainability, the list of names in each version block should 155be sorted in dictionary order (sort -d). Please comply. 156 157The version 2 mapfile language supports a simple mechanism for conditional 158input, in which lines in the mapfile apply only to a specific platform or 159ELFCLASS (32/64-bit). This mechanism works very much like the #if/#endif 160feature of the C preprocessor. For instance, the following mapfile declares --- 7 unchanged lines hidden (view full) --- 168 bar; 169$endif 170}; 171 172Conditional input can be used if there are ISA-specific library interfaces 173not common to all instances of the library. It is the preferred method for 174expressing platform specific items, as long as the differences are simple 175(which is almost always the case). For example, see libproc, or, if you | 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 --- 7 unchanged lines hidden (view full) --- 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 |
| 176are masochistic, libc or libnsl. | 209are masochistic, libc or libnsl. In general, use of this feature should be 210minimal. |
| 177 178In addition to conditional input, there is a second heavier weight mechanism 179for expressing ISA-specific differences. In addition to the common mapfile: 180 common/mapfile-vers 181some libraries may have ISA-specific supplemental mapfiles, one in each 182of the ISA directories: 183 amd64/mapfile-vers 184 i386/mapfile-vers --- 12 unchanged lines hidden (view full) --- 197carefully, or the resulting mapfile can be extremly difficult to read. 198 199------------------------------------------------------------------------------- 200 2014.0 Making interface additions to an existing library 202 2034.1 Adding a Public interface 204 | 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 --- 12 unchanged lines hidden (view full) --- 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 |
| 205The first engineer to update the existing mapfile-vers file in a release needs 206to identify the current highest version name and properly increment the minor 207version number by 1 to be the new version name. If this is the first Public 208interface in the shared object, a new SUNW_1.1 version name must be introduced. | 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. |
| 209 210The major revision number is incremented whenever an incompatible change is | 243 244The major revision number is incremented whenever an incompatible change is |
| 211made to an interface. This could be the case if an API changes so dramatically 212as to invalidate dependencies. This rarely occurs in practice. It also 213requires changing the suffix of the shared object from, say, .so.1 to .so.2 214and introducing code to continue to ship the .so.1 version of the library. | 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. |
| 215 216The minor revision number is incremented whenever one or more new interfaces | 250 251The minor revision number is incremented whenever one or more new interfaces |
| 217is added to a library. Note that the minor number is not incremented on every 218putback that makes an interface addition to the library. Rather, it is 219incremented at most once per (external to Sun) release of the library. | 252is added to a library. Once a version comes to exist in illumos, it is from 253that point onward considered to be immutable. |
| 220 2214.2 Adding a Private interface 222 223Private interfaces are the non-ABI interfaces of the library. Unlike 224introducing a Public interface, a new entry is simply added to the | 254 2554.2 Adding a Private interface 256 257Private interfaces are the non-ABI interfaces of the library. Unlike 258introducing a Public interface, a new entry is simply added to the |
| 225SUNWprivate version. No minor number increment is necessary. | 259private version. No minor number increment is necessary. |
| 226 | 260 |
| 227If this interface happens to be the first Private interface introduced 228into the library, the SUNWprivate version must be created (no major.minor 229version numbers). It inherits nothing and nothing inherits from it. | 261If this interface happens to be the first Private interface introduced into 262the library, the private version must be created (with no major.minor 263version numbers). It inherits nothing, nothing inherits from it and it 264should be named ILLUMOSprivate. |
| 230 | 265 |
| 231If the library already has Private interfaces, they may have numbered version 232names like SUNWprivate_m.n (due to errors of the past). If so, just use the 233highest numbered private version name to version the new interface. There 234is no need to introduce a new private version name. Be careful not to use 235a lower numbered private version name; doing so can cause runtime errors 236(as opposed to load time errors) when running an application with older 237versions of the library. | 266If the library already has Private interfaces in a SUNWprivate version, you 267should use that. They may have numbered version names like SUNWprivate_m.n 268(due to errors of the past). If so, just use the highest numbered private 269version name to version the new interface. There is no need to introduce a 270new private version name. Be careful not to use a lower numbered private 271version name; doing so can cause runtime errors (as opposed to load time 272errors) when running an application with older versions of the library. |
| 238 | 273 |
| 239There are libraries in the OSnet consolidation that contain only private 240interfaces. In such libraries, the SUNWprivate_m.n may be incremented 241to ensure that the programs that depend on them are built and delivered as a 242integrated unit. A notable example of this is libld.so (usr/src/cmd/sgs/libld), 243which contains the implementation of the link-editor, the public interface to 244which is provided by the ld command. When making a modification to the interface 245of such a library, you should follow the convention already in place. | 274There are also libraries in illumos that contain only private interfaces. In 275such libraries, the private versions maybe legitimately be versioned and 276they may be incremented to ensure that the programs that depend on them are 277built and delivered as a integrated unit. A notable example of this is 278libld.so (usr/src/cmd/sgs/libld), which contains the implementation of the 279link-editor, the public interface to which is provided by the ld 280command. When making a modification to the interface of such a library, you 281should follow the convention already in place. |
| 246 | 282 |
| 2474.3 Adding new public interfaces in an update release | 2834.3 Historical handling of Solaris update releases. |
| 248 | 284 |
| 249Adding new public interfaces in an update release requires careful 250coordination with the next marketing release currently under development. 251Multiple updates ship during the period before the next marketing release 252ships, and since it is generally impossible to know the full set of new 253interfaces in the next marketing release until late in its development 254(after multiple updates have shipped) it must be assumed that not all 255interfaces added to the next marketing release will be added to an update. | 285To aid the understanding of our existing mapfiles, it is useful to note how 286interface versions were handled as they interacted with update releases of 287Solaris. Solaris update releases required careful coordination with the full 288release currently under development to keep symbol versions constant between 289releases. |
| 256 | 290 |
| 291Multiple update releases were generally shipped during the development of the 292next full release of Solaris. It was impossible to know in advance the full 293set of new interfaces in the next full release until it was complete. Some, 294though not all, new interfaces were included in the intervening update 295releases between full releases. 296 |
|
| 257Consequently, the new version number for an update cannot be a minor | 297Consequently, the new version number for an update cannot be a minor |
| 258increment, but must be a micro increment. For example, if Release N 259has version number SUNW_1.3 and Release N+1 will have SUNW_1.4, then 260interfaces added to an update of Release N must have micro numbers such 261as SUNW_1.3.1, SUNW_1.3.2, etc. (note that the micro number is not 262directly tied to the update number: SUNW_1.3.1 may appear in Update 2). 263The micro versions form an inheritance chain that is inserted between 264two successive minor versions. For example, the mapfile-vers file for 265minor release "N+1" to reflect its inclusion of micro releases will 266look like the following: | 298increment, but must be a micro increment to ensure that was a distinct 299version between the two releases. For example, if Release N had version 300number SUNW_1.3 and Release N+1 had SUNW_1.4, then interfaces added to 301an update of Release N must have micro numbers such as SUNW_1.3.1, 302SUNW_1.3.2, etc. (note that the micro number is not directly tied to the 303update number: SUNW_1.3.1 may have appeared in Update 2). The micro versions form 304an inheritance chain that is inserted between two successive minor versions. 305For example, the mapfile-vers file for minor release "N+1" to reflect its 306inclusion of micro releases will look like the following: |
| 267 268$mapfile_version 2 269 270SYMBOL_VERSION SUNW_1.4 { # release N+1 271 global: 272 ... 273} SUNW_1.3.2; 274 --- 30 unchanged lines hidden (view full) --- 305}; 306 307The corresponding update/patch mapfile-vers file will be identical 308except for the exclusion of SUNW_1.4. 309 310Those interfaces which are only present in Release N+1 are always put 311into the next minor version set, SUNW_1.4. 312 | 307 308$mapfile_version 2 309 310SYMBOL_VERSION SUNW_1.4 { # release N+1 311 global: 312 ... 313} SUNW_1.3.2; 314 --- 30 unchanged lines hidden (view full) --- 345}; 346 347The corresponding update/patch mapfile-vers file will be identical 348except for the exclusion of SUNW_1.4. 349 350Those interfaces which are only present in Release N+1 are always put 351into the next minor version set, SUNW_1.4. 352 |
| 313Thus when adding a new public interface to an update, both the mapfiles 314of the update release and next marketing release must be modified to be 315consistent. The update versions should not be added to the marketing 316release until the putback to the update release has occurred, to avoid 317timing problems with the update releases (it's all too easy for projects 318to slip out of updates, or to change ordering). | 353Thus when adding a new Public interface to an update release, both the mapfiles 354of the update release and next full release should have been modified to be 355consistent. |
| 319 | 356 |
| 357There have been several cases of accidental deviation from this scheme, and 358existing mapfiles sometimes reflect this unfortunate state of affairs. 359 |
|
| 320------------------------------------------------------------------------------- 321 3225.0 How to update an interface in an existing library 323 3245.1 Removing an existing interface 325 3265.1.1 Moving a Public interface 327 | 360------------------------------------------------------------------------------- 361 3625.0 How to update an interface in an existing library 363 3645.1 Removing an existing interface 365 3665.1.1 Moving a Public interface 367 |
| 328No Public interfaces should ever be removed from any mapfile. | 368No Public interfaces should ever be removed from any mapfile, as this will 369break all existing consumers of that interface. |
| 329 330To move an interface from one library to (say) libc, the code has to be 331deleted from the library and added to libc, then the mapfile for the 332library has to have the interface's entry changed from: 333 getfoobar; 334to: 335 getfoobar { TYPE = FUNCTION; FILTER = libc.so.1 }; | 370 371To move an interface from one library to (say) libc, the code has to be 372deleted from the library and added to libc, then the mapfile for the 373library has to have the interface's entry changed from: 374 getfoobar; 375to: 376 getfoobar { TYPE = FUNCTION; FILTER = libc.so.1 }; |
| 336See, for example, libnsl's common/mapfile-vers file. | 377This is an exception to the immutability of public symbol versions. See, 378for example, libnsl's common/mapfile-vers file. |
| 337 338Follow the rules for adding a new interface for the necessary changes | 379 380Follow the rules for adding a new interface for the necessary changes |
| 339to libc's mapfile to accommodate the moved interface. In particular, 340the new interface must be added to the current highest libc version. | 381to libc's mapfile to accommodate the moved interface, including creating a 382new version in libc for the symbol. |
| 341 | 383 |
| 342To move an entire library into libc, look at what has already been done 343for libthread, libaio, and librt. | 384When merging an entire library into libc, the mapfile is changed to specify 385the type of each public symbol similarly to the above: 386 getfoobar; 387to: 388 getfoobar { TYPE = FUNCTION }; |
| 344 | 389 |
| 390But rather than specifying the library on which we filter for each symbol, 391the link-editor is invoked with '-F libc.so.1' to specify that our entire 392symbol table is a filter on libc. For examples, see libaio and librt. 393 |
|
| 3455.1.2 Removing a Private interface 346 347Deletion of Private interfaces is allowed, but caution should be taken; 348it should first be established that the interface is not being used. 349To remove a Private interface, simply delete the corresponding entry | 3945.1.2 Removing a Private interface 395 396Deletion of Private interfaces is allowed, but caution should be taken; 397it should first be established that the interface is not being used. 398To remove a Private interface, simply delete the corresponding entry |
| 350for that symbol from the mapfile's SUNWprivate section. | 399for that symbol from the mapfile's private version section. |
| 351 352Do not forget to delete these Public or Private interfaces from the library's 353header files as well as from the code that implements the interfaces. 354 3555.2 Promoting a Private interface to Public 356 357This is similar to what's done when adding a Public interface. Promoting an 358existing Private interface to a Public one only requires a change to the | 400 401Do not forget to delete these Public or Private interfaces from the library's 402header files as well as from the code that implements the interfaces. 403 4045.2 Promoting a Private interface to Public 405 406This is similar to what's done when adding a Public interface. Promoting an 407existing Private interface to a Public one only requires a change to the |
| 359existing interface definition. Private interfaces have the symbol version name 360"SUNWprivate" associated with them. To make the interface a Public one, the 361interface must be put into a set associated with the current Public release 362level of the library. | 408existing interface definition. Private interfaces have the symbol version 409name "ILLUMOSprivate" or "SUNWprivate" associated with them. To make the 410interface a Public one, the interface must be added as if it were a new 411public symbol, following those same rules and removed from the private 412version. |
| 363 | 413 |
| 364As an example, if we were modifying libwombat.so.1 and its version in the 365last release of Solaris was SUNW_1.23, any new ABI introduced in the next 366release would be put into a version called SUNW_1.24. Therefore, whether 367you wish to promote an existing Private interface to Public, or to introduce 368a new Public interface, this (next successive minor numbered version level) 369would be the version that it would be associated with. | 414As an example, if we were modifying libwombat.so.1 and its existing latest 415version were ILLUMOS_0.3, any new ABI would be put into a version called 416ILLUMOS_0.4. Therefore, whether you wish to promote an existing Private 417interface to Public, or to introduce a new Public interface, this (next 418successive minor numbered version level) would be the version that it would 419be associated with. |
| 370 3715.3 Scoping a Private interface local 372 373Any interfaces not present in the mapfile-vers file will be scoped local 374due to the presence of the 375 local: 376 *; 377lines discussed earlier. This ensures that such interfaces will not be visible 378outside the library. To move an interface from Private to local scope, simply 379remove the Private interface from the mapfile-vers file and the header file 380to prevent it from being exported. This may require moving the Private 381interface into a library-private header file. Scope reduction of Public | 420 4215.3 Scoping a Private interface local 422 423Any interfaces not present in the mapfile-vers file will be scoped local 424due to the presence of the 425 local: 426 *; 427lines discussed earlier. This ensures that such interfaces will not be visible 428outside the library. To move an interface from Private to local scope, simply 429remove the Private interface from the mapfile-vers file and the header file 430to prevent it from being exported. This may require moving the Private 431interface into a library-private header file. Scope reduction of Public |
| 382interfaces is not allowed without specific ARC review and approval. | 432interfaces is forbidden. |
| 383 384For the interface to be used in more than one file within the library, it 385should be in a header file that can be included by each file in the library 386that uses the interface. For example: 387 388 #include "libprivate.h" 389 3905.4 How to copy interfaces which are part of a standard to a new or existing 391 library 392 393SYSVABI and SISCD are reserved version names for interfaces listed in the 394System V Interface Definition and the Sparc Compliance Definition. Avoid using 395these version names when copying the implementation of standard interfaces to | 433 434For the interface to be used in more than one file within the library, it 435should be in a header file that can be included by each file in the library 436that uses the interface. For example: 437 438 #include "libprivate.h" 439 4405.4 How to copy interfaces which are part of a standard to a new or existing 441 library 442 443SYSVABI and SISCD are reserved version names for interfaces listed in the 444System V Interface Definition and the Sparc Compliance Definition. Avoid using 445these version names when copying the implementation of standard interfaces to |
| 396another library. Instead, use SUNW_1.1 for a new library, and SUNW_m.n for 397an existing library (where m.n is the next release version; i.e., if the 398last version was SUNW_1.18, then you should version the interfaces with 399SUNW_1.19). | 446another library. Instead, use ILLUMOS_0.1 for a new library, and ILLUMOS_m.n for 447an existing library (where m.n is the next version; i.e., if the 448last version was ILLUMOS_0.8, then you should version the interfaces with 449ILLUMOS_0.9). |
| 400 401------------------------------------------------------------------------------- 402 4036.0 Introducing a new library 404 4056.1 Directories 406 | 450 451------------------------------------------------------------------------------- 452 4536.0 Introducing a new library 454 4556.1 Directories 456 |
| 407The normal discipline for introducing a new library in OS/Net is to create a 408new subdirectory of /usr/src/lib. The interface definition discipline is to | 457The normal discipline for introducing a new library in illumos is to create a 458new subdirectory of usr/src/lib. The interface definition discipline is to |
| 409create a common/mapfile-vers file for the new library. If we were introducing | 459create a common/mapfile-vers file for the new library. If we were introducing |
| 410a new foo library, libfoo, we'd create /usr/src/lib/libfoo containing: | 460a new foo library, libfoo, we'd create usr/src/lib/libfoo containing: |
| 411 Makefile amd64/ i386/ sparcv9/ 412 Makefile.com common/ sparc/ 413The common subdirectory would contain the normal source files plus the 414mapfile-vers file. See usr/src/lib/README.Makefiles for directions on 415how to organize the Makefiles. 416 4176.2 The mapfile 418 419The new common/mapfile-vers file would contain: 420 421$mapfile_version 2 422 | 461 Makefile amd64/ i386/ sparcv9/ 462 Makefile.com common/ sparc/ 463The common subdirectory would contain the normal source files plus the 464mapfile-vers file. See usr/src/lib/README.Makefiles for directions on 465how to organize the Makefiles. 466 4676.2 The mapfile 468 469The new common/mapfile-vers file would contain: 470 471$mapfile_version 2 472 |
| 423SYMBOL_VERSION SUNW_1.1 { # first release of libfoo | 473SYMBOL_VERSION ILLUMOS_0.1 { # first release of libfoo |
| 424 global: 425 ... 426}; 427 | 474 global: 475 ... 476}; 477 |
| 428SYMBOL_VERSION SUNWprivate { | 478SYMBOL_VERSION ILLUMOSprivate { |
| 429 global: 430 ... 431 local: 432 *; 433}; 434 | 479 global: 480 ... 481 local: 482 *; 483}; 484 |
| 435If there are no Public interfaces, the SUNW_1.1 section would be omitted. 436If there are no Private interfaces, the SUNWprivate section would be | 485If there are no Public interfaces, the ILLUMOS_0.1 section would be omitted. 486If there are no Private interfaces, the ILLUMOSprivate section would be |
| 437omitted and the two lines: 438 local: 439 *; 440would be moved into SUNW_1.1 441 | 487omitted and the two lines: 488 local: 489 *; 490would be moved into SUNW_1.1 491 |
| 442To decide which interfaces are Public (part of the ABI) and which are Private 443(unstable interfaces not intended to be used by third party applications or 444unbundled products), the heuristic which works to a first approximation is 445that if it has a man page then it's Public. Also, it is really the ARC case 446for the new interfaces that prescribes which interfaces are Public and 447which are not (hence, which interfaces have man pages and which do not). | 492To decide which interfaces are Public (part of the ABI) and which are 493Private (unstable interfaces not intended to be used by third parties), the 494heuristic which works to a first approximation is that if it has a man page 495then it's Public. |
| 448 449For maintainability, the list of names in each version block should 450be sorted in dictionary order (sort -d). Please comply. 451 452------------------------------------------------------------------------------- 453 4547.0 Make an entire library obsolete 455 --- 7 unchanged lines hidden (view full) --- 463 464$mapfile_version 2 465 466SYMBOL_VERSION SUNWobsolete { 467 global: 468 SUNWobsolete; # This is the only way to do it. 469} SUNW_1.2; 470 | 496 497For maintainability, the list of names in each version block should 498be sorted in dictionary order (sort -d). Please comply. 499 500------------------------------------------------------------------------------- 501 5027.0 Make an entire library obsolete 503 --- 7 unchanged lines hidden (view full) --- 511 512$mapfile_version 2 513 514SYMBOL_VERSION SUNWobsolete { 515 global: 516 SUNWobsolete; # This is the only way to do it. 517} SUNW_1.2; 518 |
| 471SYMBOL_VERSION SUNW_1.2 { | 519SYMBOL_VERSION ILLUMOS_0.2 { |
| 472... 473 | 520... 521 |
| 522You should continue to use the name SUNWobsolete even in illumos. 523 |
|
| 474------------------------------------------------------------------------------- 475 4768.0 Documentation 477 478For further information, please refer to the following documents: 479 | 524------------------------------------------------------------------------------- 525 5268.0 Documentation 527 528For further information, please refer to the following documents: 529 |
| 480 "Solaris Linker and Libraries Guide", http://docs.sun.com 481 /shared/ON/general_docs/scoping-rules.fm.ps 482 483For information on the now-obsolete spec files, used in Solaris releases 4847 through 10, see: 485 /shared/ON/general_docs/README.spec 486 /shared/ON/general_docs/libspec-rules.ps 487 /shared/ON/general_docs/spectrans/* | 530 "Solaris Linker and Libraries Guide" |