Name Date Size #Lines LOC

..13-Nov-2023-

abi/H14-Feb-2021-

auditd_plugins/H17-Apr-2023-

brand/H14-Feb-2021-

c_synonyms/H17-Apr-2023-

cfgadm_plugins/H14-Feb-2021-

commpage/H17-Apr-2023-

crt/H17-Apr-2023-

crypt_modules/H14-Feb-2021-

extendedFILE/H14-Feb-2021-

fm/H17-Apr-2023-

getloginx/H14-Feb-2021-

gss_mechs/H14-Feb-2021-

hal/H04-May-2023-

hbaapi/H14-Feb-2021-

iconv_modules/H14-Feb-2021-

json_nvlist/H14-Feb-2021-

krb5/H14-Feb-2021-

lib9p/H10-Dec-2021-

libadm/H14-Feb-2021-

libads/H14-Feb-2021-

libadt_jni/H14-Feb-2021-

libadutils/H14-Feb-2021-

libaio/H14-Feb-2021-

libavl/H14-Feb-2021-

libbe/H14-Feb-2021-

libbrand/H14-Feb-2021-

libbsdmalloc/H12-Jul-2022-

libbsm/H12-Jul-2022-

libc/H17-Apr-2023-

libc_db/H17-Apr-2023-

libcfgadm/H17-Apr-2023-

libcmdutils/H14-Feb-2021-

libcommputil/H14-Feb-2021-

libcontract/H14-Feb-2021-

libcpc/H17-Apr-2023-

libcrypt/H14-Feb-2021-

libcryptoutil/H12-Jul-2022-

libctf/H14-Feb-2021-

libcurses/H12-Jul-2022-

libcustr/H14-Feb-2021-

libdemangle/H10-Dec-2021-

libdevice/H17-Apr-2023-

libdevid/H17-Apr-2023-

libdevinfo/H17-Apr-2023-

libdhcpagent/H14-Feb-2021-

libdhcputil/H12-Jul-2022-

libdiagcode/amd64/H14-Feb-2021-

libdisasm/H17-Apr-2023-

libdiskmgt/H14-Feb-2021-

libdladm/H17-Apr-2023-

libdlpi/H14-Feb-2021-

libdns_sd/H10-Dec-2021-

libdoor/H14-Feb-2021-

libds/H14-Feb-2021-

libdscp/H17-Apr-2023-

libdtrace/H01-Jun-2023-

libdtrace_jni/H14-Feb-2021-

libdwarf/H14-Feb-2021-

libefi/H14-Feb-2021-

libelfsign/H12-Jul-2022-

libeti/H17-Apr-2023-

libexacct/H12-Jul-2022-

libfakekernel/H25-May-2023-

libfcoe/H14-Feb-2021-

libfdisk/H14-Feb-2021-

libficl/H17-Apr-2023-

libfru/H03-Jan-2024-

libfruutils/H10-Dec-2021-

libfsmgt/H14-Feb-2021-

libfstyp/H14-Feb-2021-

libgen/H14-Feb-2021-

libgrubmgmt/H14-Feb-2021-

libgss/H23-Aug-2023-

libhotplug/H14-Feb-2021-

libidmap/H14-Feb-2021-

libidspace/H10-Dec-2021-

libilb/H14-Feb-2021-

libima/H01-Jun-2023-

libinetsvc/H01-Jun-2023-

libinetutil/H14-Feb-2021-

libinstzones/H01-Jun-2023-

libintl/H14-Feb-2021-

libipadm/H10-Dec-2021-

libipd/H14-Feb-2021-

libipmi/H14-Feb-2021-

libipmp/H10-Dec-2021-

libipp/H17-Apr-2023-

libipsecutil/H14-Feb-2021-

libiscsit/H14-Feb-2021-

libjedec/H20-Nov-2023-

libkmf/H17-Apr-2023-

libkrb5/H14-Feb-2021-

libkstat/H12-Jul-2022-

libkvm/H14-Feb-2021-

libldap5/H01-Jun-2023-

liblgrp/H14-Feb-2021-

liblm/H12-Jul-2022-

libm/H01-Jun-2023-

libm1/H14-Feb-2021-

libmail/H12-Jul-2022-

libmalloc/H12-Jul-2022-

libmapid/H26-Dec-2023-

libmapmalloc/H12-Jul-2022-

libmd/H16-Feb-2024-

libmd5/H14-Feb-2021-

libmlrpc/H14-Feb-2021-

libmp/H14-Feb-2021-

libmtmalloc/H10-Dec-2021-

libmvec/H01-Jun-2023-

libndmp/H14-Feb-2021-

libnisdb/H17-Apr-2023-

libnls/H12-Jul-2022-

libnsl/H01-Jun-2023-

libnvpair/H17-Apr-2023-

libnwam/H16-Feb-2024-

libofmt/H14-Feb-2021-

libpam/H22-May-2023-

libpcidb/H10-Dec-2021-

libpcp/H14-Feb-2021-

libpcsc/H08-May-2023-

libpctx/H14-Feb-2021-

libpicl/H17-Apr-2023-

libpicltree/H17-Apr-2023-

libpkg/H14-Feb-2021-

libpool/H14-Feb-2021-

libppt/H10-Dec-2021-

libpri/H14-Feb-2021-

libproc/H12-Jul-2022-

libproject/H14-Feb-2021-

libprtdiag/H10-Dec-2021-

libprtdiag_psr/H14-Feb-2021-

libpthread/H14-Feb-2021-

libraidcfg/H14-Feb-2021-

librcm/H17-Apr-2023-

librename/H10-Dec-2021-

libreparse/H14-Feb-2021-

libresolv/H23-Aug-2023-

libresolv2/H12-Jul-2022-

librestart/H01-Jun-2023-

librpcsvc/H14-Feb-2021-

librsc/H14-Feb-2021-

librsm/H14-Feb-2021-

librstp/H14-Feb-2021-

librt/H14-Feb-2021-

libsasl/H01-Jun-2023-

libsaveargs/H17-Apr-2023-

libscf/H01-Jun-2023-

libsched/H14-Feb-2021-

libsctp/H14-Feb-2021-

libsec/H14-Feb-2021-

libsecdb/H17-Apr-2023-

libsendfile/H14-Feb-2021-

libsff/H14-Feb-2021-

libshare/H26-Dec-2023-

libsip/H12-Jul-2022-

libsldap/H17-Apr-2023-

libslp/H10-Dec-2021-

libsmbfs/H14-Feb-2021-

libsmbios/H14-Feb-2021-

libsmedia/H14-Feb-2021-

libsocket/H01-Jun-2023-

libsqlite/H01-Jun-2023-

libsrpt/H14-Feb-2021-

libstmf/H14-Feb-2021-

libstmfproxy/H14-Feb-2021-

libsun_ima/H14-Feb-2021-

libsysevent/H12-Jul-2022-

libtecla/H17-Apr-2023-

libtermcap/H14-Feb-2021-

libthread/H14-Feb-2021-

libtsalarm/H14-Feb-2021-

libtsnet/H14-Feb-2021-

libtsol/H14-Feb-2021-

libumem/H17-Apr-2023-

libutempter/H14-Feb-2021-

libuuid/H04-May-2023-

libuutil/H17-Apr-2023-

libv12n/H14-Feb-2021-

libvmm/H09-Jan-2024-

libvmmapi/H09-Jan-2024-

libvolmgt/H17-Apr-2023-

libvrrpadm/H14-Feb-2021-

libvscan/H14-Feb-2021-

libw/H14-Feb-2021-

libwrap/H23-Aug-2023-

libxcurses/H14-Feb-2021-

libxcurses2/H17-Apr-2023-

libxnet/H14-Feb-2021-

libzfs/H12-Jul-2022-

libzfs_core/H12-Jul-2022-

libzfs_jni/H14-Feb-2021-

libzfsbootenv/H14-Feb-2021-

libzonecfg/H10-Dec-2021-

libzoneinfo/H14-Feb-2021-

libzonestat/H14-Feb-2021-

libzpool/H01-Jun-2023-

libzutil/H12-Jul-2022-

madv/H14-Feb-2021-

mergeq/H14-Feb-2021-

mpapi/H14-Feb-2021-

mpss/H14-Feb-2021-

nametoaddr/H14-Feb-2021-

nsswitch/H14-Feb-2021-

pam_modules/H14-Feb-2021-

passwdutil/H17-Apr-2023-

pkcs11/H14-Feb-2021-

policykit/H04-May-2023-

print/H14-Feb-2021-

pylibbe/H17-Apr-2023-

pysolaris/H17-Apr-2023-

pyzfs/H17-Apr-2023-

raidcfg_plugins/H14-Feb-2021-

rpcsec_gss/H01-Jun-2023-

sasl_plugins/H01-Jun-2023-

scsi/H14-Feb-2021-

smbclnt/H14-Feb-2021-

smbsrv/H14-Feb-2021-

smhba/H14-Feb-2021-

ssp_ns/H14-Feb-2021-

storage/H14-Feb-2021-

sun_fc/H01-Jun-2023-

sun_sas/H14-Feb-2021-

udapl/H14-Feb-2021-

varpd/H12-Jul-2022-

watchmalloc/H14-Feb-2021-

MakefileH A D28-Nov-202314.6 KiB733624

Makefile.filter.comH A D14-Feb-20212.8 KiB815

Makefile.filter.targH A D14-Feb-20211.4 KiB4334

Makefile.libH A D01-Jun-20239.3 KiB273124

Makefile.lib.64H A D04-May-20231.1 KiB4036

Makefile.machH A D14-Feb-20211.8 KiB6419

Makefile.rootfsH A D14-Feb-20211.6 KiB4712

Makefile.targH A D04-May-20233.2 KiB12870

README.MakefilesH A D12-Jul-202220.6 KiB618425

README.mapfilesH A D10-Dec-202120.6 KiB538425

inc.flgH A D14-Feb-20211.3 KiB383

req.flgH A D14-Feb-20211.2 KiB358

README.Makefiles

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 2006 Sun Microsystems, Inc.  All rights reserved.
23# Use is subject to license terms.
24
25Writing Library Makefiles in ON
26===============================
27
28Introduction
29------------
30
31This document guides you through the gnarly process of writing library
32Makefiles for the ON consolidation.  It assumes that you're comfortable with
33make(1) and are somewhat familiar with the ON Makefile standards outlined in
34/shared/ON/general_docs/make_std.txt.
35
36Makefile Overview
37-----------------
38
39Your library should consist of a hierarchical collection of Makefiles:
40
41	lib/<library>/Makefile:
42
43	  This is your library's top-level Makefile.  It should contain rules
44	  for building any ISA-independent targets, such as installing header
45	  files and building message catalogs, but should defer all other
46	  targets to ISA-specific Makefiles.
47
48	lib/<library>/Makefile.com
49
50	  This is your library's common Makefile.  It should contain rules
51	  and macros which are common to all ISAs. This Makefile should never
52	  be built explicitly, but instead should be included (using the make
53	  include mechanism) by all of your ISA-specific Makefiles.
54
55	lib/<library>/<isa>/Makefile
56
57	  These are your library's ISA-specific Makefiles, one per ISA
58	  (usually sparc and i386, and often sparcv9 and amd64).  These
59	  Makefiles should include your common Makefile and then provide any
60	  needed ISA-specific rules and definitions, perhaps overriding those
61	  provided in your common Makefile.
62
63To simplify their maintenance and construction, $(SRC)/lib has a handful of
64provided Makefiles that yours must include; the examples provided throughout
65the document will show how to use them.  Please be sure to consult these
66Makefiles before introducing your own custom build macros or rules.
67
68	lib/Makefile.lib:
69
70	  This contains the bulk of the macros for building shared objects.
71
72	lib/Makefile.lib.64
73
74	  This contains macros for building 64-bit objects, and should be
75	  included in Makefiles for 64-bit native ISAs.
76
77	lib/Makefile.rootfs
78
79	  This contains macro overrides for libraries that install into /lib
80	  (rather than /usr/lib).
81
82	lib/Makefile.targ
83
84	  This contains rules for building shared objects.
85
86The remainder of this document discusses how to write each of your Makefiles
87in detail, and provides examples from the libinetutil library.
88
89The Library Top-level Makefile
90------------------------------
91
92As described above, your top-level library Makefile should contain
93rules for building ISA-independent targets, but should defer the
94building of all other targets to ISA-specific Makefiles.  The
95ISA-independent targets usually consist of:
96
97	install_h
98
99	  Install all library header files into the proto area.
100	  Can be omitted if your library has no header files.
101
102	check
103
104	  Check all library header files for hdrchk compliance.
105	  Can be omitted if your library has no header files.
106
107	_msg
108
109	  Build and install a message catalog.
110	  Can be omitted if your library has no message catalog.
111
112Of course, other targets (such as `cstyle') are fine as well, as long as
113they are ISA-independent.
114
115The ROOTHDRS and CHECKHDRS targets are provided in lib/Makefile.lib to make
116it easy for you to install and check your library's header files.  To use
117these targets, your Makefile must set the HDRS to the list of your library's
118header files to install and HDRDIR to the their location in the source tree.
119In addition, if your header files need to be installed in a location other
120than $(ROOT)/usr/include, your Makefile must also set ROOTHDRDIR to the
121appropriate location in the proto area.  Once HDRS, HDRDIR and (optionally)
122ROOTHDRDIR have been set, your Makefile need only contain
123
124	  install_h: $(ROOTHDRS)
125
126	  check: $(CHECKHDRS)
127
128to bind the provided targets to the standard `install_h' and `check' rules.
129
130Similar rules are provided (in $(SRC)/Makefile.msg.targ) to make it easy for
131you to build and install message catalogs from your library's source files.
132
133To install a catalog into the catalog directory in the proto area, define the
134POFILE macro to be the name of your catalog, and specify that the _msg target
135depends on $(MSGDOMAINPOFILE).  The examples below should clarify this.
136
137To build a message catalog from arbitrarily many message source files, use
138the BUILDPO.msgfiles macro.
139
140	  include ../Makefile.lib
141
142	  POFILE =	  libfoo.po
143	  MSGFILES =	  $(OBJECTS:%.o=%.i)
144
145	  # ...
146
147	  $(POFILE): $(MSGFILES)
148		$(BUILDPO.msgfiles)
149
150	  _msg: $(MSGDOMAINPOFILE)
151
152	  include $(SRC)/Makefile.msg.targ
153
154Note that this example doesn't use grep to find message files, since that can
155mask unreferenced files, and potentially lead to the inclusion of unwanted
156messages or omission of intended messages in the catalogs.  As such, MSGFILES
157should be derived from a known list of objects or sources.
158
159It is usually preferable to run the source through the C preprocessor prior
160to extracting messages.  To do this, use the ".i" suffix, as shown in the
161above example.  If you need to skip the C preprocessor, just use the native
162(.[ch]) suffix.
163
164The only time you shouldn't use BUILDPO.msgfiles as the preferred means of
165extracting messages is when you're extracting them from shell scripts; in
166that case, you can use the BUILDPO.pofiles macro as explained below.
167
168To build a message catalog from other message catalogs, or from source files
169that include shell scripts, use the BUILDPO.pofiles macro:
170
171	  include ../Makefile.lib
172
173	  SUBDIRS =	  $(MACH)
174
175	  POFILE =	  libfoo.po
176	  POFILES =	  $(SUBDIRS:%=%/_%.po)
177
178	  _msg :=	  TARGET = _msg
179
180	  # ...
181
182	  $(POFILE): $(POFILES)
183		$(BUILDPO.pofiles)
184
185	  _msg: $(MSGDOMAINPOFILE)
186
187	  include $(SRC)/Makefile.msg.targ
188
189The Makefile above would work in conjunction with the following in its
190subdirectories' Makefiles:
191
192	  POFILE =	  _thissubdir.po
193	  MSGFILES =	  $(OBJECTS:%.o=%.i)
194
195	  $(POFILE):	  $(MSGFILES)
196		  $(BUILDPO.msgfiles)
197
198	  _msg:		  $(POFILE)
199
200	  include $(SRC)/Makefile.msg.targ
201
202Since this POFILE will be combined with those in other subdirectories by the
203parent Makefile and that merged file will be installed into the proto area
204via MSGDOMAINPOFILE, there is no need to use MSGDOMAINPOFILE in this Makefile
205(in fact, using it would lead to duplicate messages in the catalog).
206
207When using any of these targets, keep in mind that other macros, like
208XGETFLAGS and TEXT_DOMAIN may also be set in your Makefile to override or
209augment the defaults provided in higher-level Makefiles.
210
211As previously mentioned, you should defer all ISA-specific targets to your
212ISA-specific Makefiles.  You can do this by:
213
214	1. Setting SUBDIRS to the list of directories to descend into:
215
216		SUBDIRS = $(MACH)
217
218	   Note that if your library is also built 64-bit, then you should
219	   also specify
220
221		$(BUILD64)SUBDIRS += $(MACH64)
222
223	   so that SUBDIRS contains $(MACH64) if and only if you're compiling
224	   on a 64-bit ISA.
225
226	2. Providing a common "descend into SUBDIRS" rule:
227
228		$(SUBDIRS): FRC
229			@cd $@; pwd; $(MAKE) $(TARGET)
230
231		FRC:
232
233	3. Providing a collection of conditional assignments that set TARGET
234	   appropriately:
235
236		all	:= TARGET= all
237		clean	:= TARGET= clean
238		clobber := TARGET= clobber
239		install := TARGET= install
240
241	   The order doesn't matter, but alphabetical is preferable.
242
243	4. Having the aforementioned targets depend on SUBDIRS:
244
245		all clean clobber install: $(SUBDIRS)
246
247	   The `all' target must be listed first so that make uses it as the
248	   default target; the others might as well be listed alphabetically.
249
250As an example of how all of this goes together, here's libinetutil's
251top-level library Makefile (license notice and copyright omitted):
252
253	include ../Makefile.lib
254
255	HDRS =		libinetutil.h
256	HDRDIR =	common
257	SUBDIRS =	$(MACH)
258	$(BUILD64)SUBDIRS += $(MACH64)
259
260	all :=		TARGET = all
261	clean :=	TARGET = clean
262	clobber :=	TARGET = clobber
263	install :=	TARGET = install
264
265	.KEEP_STATE:
266
267	all clean clobber install: $(SUBDIRS)
268
269	install_h:	$(ROOTHDRS)
270
271	check:		$(CHECKHDRS)
272
273	$(SUBDIRS): FRC
274		@cd $@; pwd; $(MAKE) $(TARGET)
275
276	FRC:
277
278	include ../Makefile.targ
279
280The Common Makefile
281-------------------
282
283In concept, your common Makefile should contain all of the rules and
284definitions that are the same on all ISAs.  However, for reasons of
285maintainability and cleanliness, you're encouraged to place even
286ISA-dependent rules and definitions, as long you express them in an
287ISA-independent way (e.g., by using $(MACH), $(TARGETMACH), and their kin).
288(TARGETMACH is the same as MACH for 32-bit targets, and the same as MACH64
289for 64-bit targets).
290
291The common Makefile can be conceptually split up into four sections:
292
293	1. A copyright and comments section.  Please see the prototype
294	   files in usr/src/prototypes for examples of how to format the
295	   copyright message properly.  For brevity and clarity, this
296	   section has been omitted from the examples shown here.
297
298	2. A list of macros that must be defined prior to the inclusion of
299	   Makefile.lib.  This section is conceptually terminated by the
300	   inclusion of Makefile.lib, followed, if necessary, by the
301	   inclusion of Makefile.rootfs (only if the library is to be
302	   installed in /lib rather than the default /usr/lib).
303
304	3. A list of macros that need not be defined prior to the inclusion
305	   of Makefile.lib (or which must be defined following the inclusion
306	   of Makefile.lib, to override or augment its definitions).  This
307	   section is conceptually terminated by the .KEEP_STATE directive.
308
309	4. A list of targets.
310
311The first section is self-explanatory.  The second typically consists of the
312following macros:
313
314	LIBRARY
315
316	  Set to the name of the static version of your library, such
317	  as `libinetutil.a'.  You should always specify the `.a' suffix,
318	  since pattern-matching rules in higher-level Makefiles rely on it,
319	  even though static libraries are not normally built in ON, and
320	  are never installed in the proto area.  Note that the LIBS macro
321	  (described below) controls the types of libraries that are built
322	  when building your library.
323
324	  If you are building a loadable module (i.e., a shared object that
325	  is only linked at runtime with dlopen(3dl)), specify the name of
326	  the loadable module with a `.a' suffix, such as `devfsadm_mod.a'.
327
328	VERS
329
330	  Set to the version of your shared library, such as `.1'.  You
331	  actually do not need to set this prior to the inclusion of
332	  Makefile.lib, but it is good practice to do so since VERS and
333	  LIBRARY are so closely related.
334
335	OBJECTS
336
337	  Set to the list of object files contained in your library, such as
338	  `a.o b.o'.  Usually, this will be the same as your library's source
339	  files (except with .o extensions), but if your library compiles
340	  source files outside of the library directory itself, it will
341	  differ.  We'll see an example of this with libinetutil.
342
343The third section typically consists of the following macros:
344
345	LIBS
346
347	  Set to the list of the types of libraries to build when building
348	  your library.  For dynamic libraries, you should set this to
349	  `$(DYNLIB)' so that a dynamic library is built.
350
351	  If your library needs to be built as a static library (typically
352	  to be used in other parts of the build), you should set LIBS to
353	  `$(LIBRARY)'.  However, you should do this only when absolutely
354	  necessary, and you must *never* ship static libraries to customers.
355
356	ROOTLIBDIR (if your library installs to a nonstandard directory)
357
358	  Set to the directory your 32-bit shared objects will install into
359	  with the standard $(ROOTxxx) macros.  Since this defaults to
360	  $(ROOT)/usr/lib ($(ROOT)/lib if you included Makefile.rootfs),
361	  you usually do not need to set this.
362
363	ROOTLIBDIR64 (if your library installs to a nonstandard directory)
364
365	  Set to the directory your 64-bit shared objects will install into
366	  with the standard $(ROOTxxx64) macros.  Since this defaults to
367	  $(ROOT)/usr/lib/$(MACH64) ($(ROOT)/lib/$(MACH64) if you included
368	  Makefile.rootfs), you usually do not need to set this.
369
370	SRCDIR
371
372	  Set to the directory containing your library's source files, such
373	  as `../common'.  Because this Makefile is actually included from
374	  your ISA-specific Makefiles, make sure you specify the directory
375	  relative to your library's <isa> directory.
376
377	SRCS (if necessary)
378
379	  Set to the list of source files required to build your library.
380	  This defaults to $(OBJECTS:%.o=$(SRCDIR)/%.c) in Makefile.lib, so
381	  you only need to set this when source files from directories other
382	  than SRCDIR are needed.  Keep in mind that SRCS should be set to a
383	  list of source file *pathnames*, not just a list of filenames.
384
385
386	LDLIBS
387
388	  Appended with the list of libraries and library directories needed
389	  to build your library; minimally "-lc".  Note that this should
390	  *never* be set, since that will inadvertently clear the library
391	  search path, causing the linker to look in the wrong place for
392	  the libraries.
393
394	MAPFILES (if necessary)
395
396	  Set to the list of mapfiles used to link each ISA-specific version
397	  of your library.  This defaults to `$(SRCDIR)/mapfile-vers' in
398	  Makefile.lib, so you only need to change this if you have additional
399	  mapfiles or your mapfile doesn't follow the standard naming
400	  convention.  If you have supplemental ISA-dependent mapfiles that
401	  reside in the respective <isa> directories, you can augment
402	  MAPFILES like this:
403
404		MAPFILES += mapfile-vers
405
406	CPPFLAGS (if necessary)
407
408	   Appended with any flags that need to be passed to the C
409	   preprocessor (typically -D and -I flags).  When compiling MT-safe
410	   code, CPPFLAGS *must* include -D_REENTRANT.  When compiling large
411	   file aware code, CPPFLAGS *must* include -D_FILE_OFFSET_BITS=64.
412
413	CFLAGS
414
415	   Appended with any flags that need to be passed to the C compiler.
416	   Minimally, append `$(CCVERBOSE)'.  Keep in mind that you should
417	   add any C preprocessor flags to CPPFLAGS, not CFLAGS.
418
419	CFLAGS64 (if necessary)
420
421	   Appended with any flags that need to be passed to the C compiler
422	   when compiling 64-bit code.  Since all 64-bit code is compiled
423	   $(CCVERBOSE), you usually do not need to modify CFLAGS64.
424
425	COPTFLAG (if necessary)
426
427	   Set to control the optimization level used by the C compiler when
428	   compiling 32-bit code.  You should only set this if absolutely
429	   necessary, and it should only contain optimization-related
430	   settings (or -g).
431
432	COPTFLAG64 (if necessary)
433
434	   Set to control the optimization level used by the C compiler when
435	   compiling 64-bit code.  You should only set this if absolutely
436	   necessary, and it should only contain optimization-related
437	   settings (or -g).
438
439	COMPATLINKS (if necessary)
440
441	  Set to a list of symbolic links that should also be provided for
442	  this library.  Each should also have a target-specific assignment to
443	  COMPATLINKTARGET stating what the target of each link should be
444
445          COMPATLINKS= usr/lib/libfoo.so
446          $(ROOT)/usr/lib/libfoo.so := COMPATLINKTARGET= libbar.so
447
448	COMPATLINKS64 (if necessary)
449
450          As COMPATLINKS, above, for 64bit objects.
451
452Of course, you may use other macros as necessary.
453
454The fourth section typically consists of the following targets:
455
456	all
457
458	  Build all of the types of the libraries named by LIBS.  Must always
459	  be the first real target in common Makefile.  Since the
460	  higher-level Makefiles already contain rules to build all of the
461	  different types of libraries, you can usually just specify
462
463		all: $(LIBS)
464
465	  though it should be listed as an empty target if LIBS is set by your
466	  ISA-specific Makefiles (see above).
467
468
469Conspicuously absent from this section are the `clean' and `clobber' targets.
470These targets are already provided by lib/Makefile.targ and thus should not
471be provided by your common Makefile.  Instead, your common Makefile should
472list any additional files to remove during a `clean' and `clobber' by
473appending to the CLEANFILES and CLOBBERFILES macros.
474
475Once again, here's libinetutil's common Makefile, which shows how many of
476these directives go together.  Note that Makefile.rootfs is included to
477cause libinetutil.so.1 to be installed in /lib rather than /usr/lib:
478
479	LIBRARY =	libinetutil.a
480	VERS =		.1
481	OBJECTS =	octet.o inetutil4.o ifspec.o ifaddrlist.o eh.o tq.o
482
483	include ../../Makefile.lib
484	include ../../Makefile.rootfs
485
486	LIBS =		$(DYNLIB)
487
488	SRCDIR =	../common
489	COMDIR =	$(SRC)/common/net/dhcp
490	SRCS =		$(COMDIR)/octet.c $(SRCDIR)/inetutil4.c \
491			$(SRCDIR)/ifspec.c $(SRCDIR)/eh.c $(SRCDIR)/tq.c \
492			$(SRCDIR)/ifaddrlist.c
493
494	LDLIBS +=	-lsocket -lc
495
496	CFLAGS +=	$(CCVERBOSE)
497	CPPFLAGS +=	-I$(SRCDIR)
498
499	.KEEP_STATE:
500
501	all: $(LIBS)
502
503	pics/%.o: $(COMDIR)/%.c
504		$(COMPILE.c) -o $@ $<
505		$(POST_PROCESS_O)
506
507	include ../../Makefile.targ
508
509The mapfile for libinetutil is named `mapfile-vers' and resides in $(SRCDIR),
510so the MAPFILES definition is omitted, defaulting to $(SRCDIR)/mapfile-vers.
511
512Note that for libinetutil, not all of the object files come from SRCDIR.  To
513support this, an alternate source file directory named COMDIR is defined, and
514the source files listed in SRCS are specified using both COMDIR and SRCDIR.
515Additionally, a special build rule is provided to build object files from the
516sources in COMDIR; the rule uses COMPILE.c and POST_PROCESS_O so that any
517changes to the compilation and object-post-processing phases will be
518automatically picked up.
519
520The ISA-Specific Makefiles
521--------------------------
522
523As the name implies, your ISA-specific Makefiles should contain macros and
524rules that cannot be expressed in an ISA-independent way.  Usually, the only
525rule you will need to put here is `install', which has different dependencies
526for 32-bit and 64-bit libraries.  For instance, here are the ISA-specific
527Makefiles for libinetutil:
528
529	sparc/Makefile:
530
531		include ../Makefile.com
532
533		install: all $(ROOTLIBS) $(ROOTLINKS)
534
535	sparcv9/Makefile:
536
537		include ../Makefile.com
538		include ../../Makefile.lib.64
539
540		install: all $(ROOTLIBS64) $(ROOTLINKS64)
541
542	i386/Makefile:
543
544		include ../Makefile.com
545
546		install: all $(ROOTLIBS) $(ROOTLINKS)
547
548	amd64/Makefile:
549
550		include ../Makefile.com
551		include ../../Makefile.lib.64
552
553		install: all $(ROOTLIBS64) $(ROOTLINKS64)
554
555If you included Makefile.rootfs to install your library into /lib, you should
556also add $(ROOTCOMPATLINKS) and $(ROOTCOMPATLINKS64) to your install: target
557to install compatibility symlinks into /usr/lib.
558
559Observe that there is no .KEEP_STATE directive in these Makefiles, since all
560of these Makefiles include libinetutil/Makefile.com, and it already has a
561.KEEP_STATE directive.  Also, note that the 64-bit Makefiles also include
562Makefile.lib.64, which overrides some of the definitions contained in the
563higher level Makefiles included by the common Makefile so that 64-bit
564compiles work correctly.
565
566CTF Data in Libraries
567---------------------
568
569By default, all position-independent objects are built with CTF data using
570ctfconvert, which is then merged together using ctfmerge when the shared
571object is built.  All C-source objects processed via ctfmerge need to be
572processed via ctfconvert or the build will fail.  Objects built from non-C
573sources (such as assembly or C++) are silently ignored for CTF processing.
574
575Filter libraries that have no source files will need to explicitly disable
576CTF by setting CTFMERGE_LIB to ":"; see libw/Makefile.com for an example.
577
578More Information
579----------------
580
581Other issues and questions will undoubtedly arise while you work on your
582library's Makefiles.  To help in this regard, a number of libraries of
583varying complexity have been updated to follow the guidelines and practices
584outlined in this document:
585
586	lib/libdhcputil
587
588	  Example of a simple 32-bit only library.
589
590	lib/libdhcpagent
591
592	  Example of a simple 32/64-bit library that obtains its sources
593	  from multiple directories.
594
595	lib/nametoaddr/straddr
596
597	  Example of a simple loadable module.
598
599	lib/libipmp
600
601	  Example of a simple library that builds a message catalog.
602
603	lib/libdhcpsvc
604
605	  Example of a Makefile hierarchy for a library and a collection
606	  of related pluggable modules.
607
608	lib/lvm
609
610	  Example of a Makefile hierarchy for a collection of related
611	  libraries and pluggable modules.
612
613	  Also an example of a Makefile hierarchy that supports the
614	  _dc target for domain and category specific messages.
615
616Of course, if you still have questions, please do not hesitate to send email
617to the ON gatekeepers.
618

README.mapfiles

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