17c478bd9Sstevel@tonic-gate# 27c478bd9Sstevel@tonic-gate# CDDL HEADER START 37c478bd9Sstevel@tonic-gate# 47c478bd9Sstevel@tonic-gate# The contents of this file are subject to the terms of the 5*f808c858Sraf# Common Development and Distribution License (the "License"). 6*f808c858Sraf# You may not use this file except in compliance with the License. 77c478bd9Sstevel@tonic-gate# 87c478bd9Sstevel@tonic-gate# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 97c478bd9Sstevel@tonic-gate# or http://www.opensolaris.org/os/licensing. 107c478bd9Sstevel@tonic-gate# See the License for the specific language governing permissions 117c478bd9Sstevel@tonic-gate# and limitations under the License. 127c478bd9Sstevel@tonic-gate# 137c478bd9Sstevel@tonic-gate# When distributing Covered Code, include this CDDL HEADER in each 147c478bd9Sstevel@tonic-gate# file and include the License file at usr/src/OPENSOLARIS.LICENSE. 157c478bd9Sstevel@tonic-gate# If applicable, add the following below this CDDL HEADER, with the 167c478bd9Sstevel@tonic-gate# fields enclosed by brackets "[]" replaced with your own identifying 177c478bd9Sstevel@tonic-gate# information: Portions Copyright [yyyy] [name of copyright owner] 187c478bd9Sstevel@tonic-gate# 197c478bd9Sstevel@tonic-gate# CDDL HEADER END 207c478bd9Sstevel@tonic-gate# 21*f808c858Sraf# 22*f808c858Sraf# Copyright 2006 Sun Microsystems, Inc. All rights reserved. 23*f808c858Sraf# Use is subject to license terms. 24*f808c858Sraf# 25*f808c858Sraf# ident "%Z%%M% %I% %E% SMI" 26*f808c858Sraf# 27*f808c858Sraf 287c478bd9Sstevel@tonic-gateWriting Library Makefiles in ON 297c478bd9Sstevel@tonic-gate=============================== 307c478bd9Sstevel@tonic-gate 317c478bd9Sstevel@tonic-gateIntroduction 327c478bd9Sstevel@tonic-gate------------ 337c478bd9Sstevel@tonic-gate 347c478bd9Sstevel@tonic-gateThis document guides you through the gnarly process of writing library 357c478bd9Sstevel@tonic-gateMakefiles for the ON consolidation. It assumes that you're comfortable with 367c478bd9Sstevel@tonic-gatemake(1) and are somewhat familiar with the ON Makefile standards outlined in 377c478bd9Sstevel@tonic-gate/shared/ON/general_docs/make_std.txt. 387c478bd9Sstevel@tonic-gate 397c478bd9Sstevel@tonic-gateMakefile Overview 407c478bd9Sstevel@tonic-gate----------------- 417c478bd9Sstevel@tonic-gate 427c478bd9Sstevel@tonic-gateYour library should consist of a hierarchical collection of Makefiles: 437c478bd9Sstevel@tonic-gate 447c478bd9Sstevel@tonic-gate lib/<library>/Makefile: 457c478bd9Sstevel@tonic-gate 467c478bd9Sstevel@tonic-gate This is your library's top-level Makefile. It should contain rules 477c478bd9Sstevel@tonic-gate for building any ISA-independent targets, such as installing header 487c478bd9Sstevel@tonic-gate files and building message catalogs, but should defer all other 497c478bd9Sstevel@tonic-gate targets to ISA-specific Makefiles. 507c478bd9Sstevel@tonic-gate 517c478bd9Sstevel@tonic-gate lib/<library>/Makefile.com 527c478bd9Sstevel@tonic-gate 537c478bd9Sstevel@tonic-gate This is your library's common Makefile. It should contain rules 547c478bd9Sstevel@tonic-gate and macros which are common to all ISAs. This Makefile should never 557c478bd9Sstevel@tonic-gate be built explicitly, but instead should be included (using the make 567c478bd9Sstevel@tonic-gate include mechanism) by all of your ISA-specific Makefiles. 577c478bd9Sstevel@tonic-gate 587c478bd9Sstevel@tonic-gate lib/<library>/<isa>/Makefile 597c478bd9Sstevel@tonic-gate 607c478bd9Sstevel@tonic-gate These are your library's ISA-specific Makefiles, one per ISA 61*f808c858Sraf (usually sparc and i386, and often sparcv9 and amd64). These 627c478bd9Sstevel@tonic-gate Makefiles should include your common Makefile and then provide any 637c478bd9Sstevel@tonic-gate needed ISA-specific rules and definitions, perhaps overriding those 647c478bd9Sstevel@tonic-gate provided in your common Makefile. 657c478bd9Sstevel@tonic-gate 667c478bd9Sstevel@tonic-gateTo simplify their maintenance and construction, $(SRC)/lib has a handful of 677c478bd9Sstevel@tonic-gateprovided Makefiles that yours must include; the examples provided throughout 687c478bd9Sstevel@tonic-gatethe document will show how to use them. Please be sure to consult these 697c478bd9Sstevel@tonic-gateMakefiles before introducing your own custom build macros or rules. 707c478bd9Sstevel@tonic-gate 717c478bd9Sstevel@tonic-gate lib/Makefile.lib: 727c478bd9Sstevel@tonic-gate 737c478bd9Sstevel@tonic-gate This contains the bulk of the macros for building shared objects. 747c478bd9Sstevel@tonic-gate 757c478bd9Sstevel@tonic-gate lib/Makefile.lib.64 767c478bd9Sstevel@tonic-gate 777c478bd9Sstevel@tonic-gate This contains macros for building 64-bit objects, and should be 78*f808c858Sraf included in Makefiles for 64-bit native ISAs. 797c478bd9Sstevel@tonic-gate 807c478bd9Sstevel@tonic-gate lib/Makefile.rootfs 817c478bd9Sstevel@tonic-gate 827c478bd9Sstevel@tonic-gate This contains macro overrides for libraries that install into /lib 837c478bd9Sstevel@tonic-gate (rather than /usr/lib). 847c478bd9Sstevel@tonic-gate 857c478bd9Sstevel@tonic-gate lib/Makefile.targ 867c478bd9Sstevel@tonic-gate 877c478bd9Sstevel@tonic-gate This contains rules for building shared objects. 887c478bd9Sstevel@tonic-gate 897c478bd9Sstevel@tonic-gateThe remainder of this document discusses how to write each of your Makefiles 907c478bd9Sstevel@tonic-gatein detail, and provides examples from the libinetutil library. 917c478bd9Sstevel@tonic-gate 927c478bd9Sstevel@tonic-gateThe Library Top-level Makefile 937c478bd9Sstevel@tonic-gate------------------------------ 947c478bd9Sstevel@tonic-gate 957c478bd9Sstevel@tonic-gateAs described above, your top-level library Makefile should contain 967c478bd9Sstevel@tonic-gaterules for building ISA-independent targets, but should defer the 977c478bd9Sstevel@tonic-gatebuilding of all other targets to ISA-specific Makefiles. The 987c478bd9Sstevel@tonic-gateISA-independent targets usually consist of: 997c478bd9Sstevel@tonic-gate 1007c478bd9Sstevel@tonic-gate install_h 1017c478bd9Sstevel@tonic-gate 102*f808c858Sraf Install all library header files into the proto area. 103*f808c858Sraf Can be omitted if your library has no header files. 1047c478bd9Sstevel@tonic-gate 1057c478bd9Sstevel@tonic-gate check 1067c478bd9Sstevel@tonic-gate 107*f808c858Sraf Check all library header files for hdrchk compliance. 108*f808c858Sraf Can be omitted if your library has no header files. 1097c478bd9Sstevel@tonic-gate 1107c478bd9Sstevel@tonic-gate _msg 1117c478bd9Sstevel@tonic-gate 112*f808c858Sraf Build and install a message catalog. 113*f808c858Sraf Can be omitted if your library has no message catalog. 1147c478bd9Sstevel@tonic-gate 115*f808c858SrafOf course, other targets (such as `cstyle') are fine as well, as long as 1167c478bd9Sstevel@tonic-gatethey are ISA-independent. 1177c478bd9Sstevel@tonic-gate 1187c478bd9Sstevel@tonic-gateThe ROOTHDRS and CHECKHDRS targets are provided in lib/Makefile.lib to make 1197c478bd9Sstevel@tonic-gateit easy for you to install and check your library's header files. To use 1207c478bd9Sstevel@tonic-gatethese targets, your Makefile must set the HDRS to the list of your library's 1217c478bd9Sstevel@tonic-gateheader files to install and HDRDIR to the their location in the source tree. 1227c478bd9Sstevel@tonic-gateIn addition, if your header files need to be installed in a location other 1237c478bd9Sstevel@tonic-gatethan $(ROOT)/usr/include, your Makefile must also set ROOTHDRDIR to the 1247c478bd9Sstevel@tonic-gateappropriate location in the proto area. Once HDRS, HDRDIR and (optionally) 1257c478bd9Sstevel@tonic-gateROOTHDRDIR have been set, your Makefile need only contain 1267c478bd9Sstevel@tonic-gate 1277c478bd9Sstevel@tonic-gate install_h: $(ROOTHDRS) 1287c478bd9Sstevel@tonic-gate 1297c478bd9Sstevel@tonic-gate check: $(CHECKHDRS) 1307c478bd9Sstevel@tonic-gate 1317c478bd9Sstevel@tonic-gateto bind the provided targets to the standard `install_h' and `check' rules. 1327c478bd9Sstevel@tonic-gate 1337c478bd9Sstevel@tonic-gateSimilar rules are provided (in $(SRC)/Makefile.msg.targ) to make it easy for 1347c478bd9Sstevel@tonic-gateyou to build and install message catalogs from your library's source files. 1357c478bd9Sstevel@tonic-gate 1367c478bd9Sstevel@tonic-gateTo install a catalog into the catalog directory in the proto area, define the 1377c478bd9Sstevel@tonic-gatePOFILE macro to be the name of your catalog, and specify that the _msg target 1387c478bd9Sstevel@tonic-gatedepends on $(MSGDOMAINPOFILE). The examples below should clarify this. 1397c478bd9Sstevel@tonic-gate 1407c478bd9Sstevel@tonic-gateTo build a message catalog from arbitrarily many message source files, use 1417c478bd9Sstevel@tonic-gatethe BUILDPO.msgfiles macro. 1427c478bd9Sstevel@tonic-gate 1437c478bd9Sstevel@tonic-gate include ../Makefile.lib 1447c478bd9Sstevel@tonic-gate 1457c478bd9Sstevel@tonic-gate POFILE = libfoo.po 1467c478bd9Sstevel@tonic-gate MSGFILES = $(OBJECTS:%.o=%.i) 1477c478bd9Sstevel@tonic-gate 1487c478bd9Sstevel@tonic-gate # ... 1497c478bd9Sstevel@tonic-gate 1507c478bd9Sstevel@tonic-gate $(POFILE): $(MSGFILES) 1517c478bd9Sstevel@tonic-gate $(BUILDPO.msgfiles) 1527c478bd9Sstevel@tonic-gate 1537c478bd9Sstevel@tonic-gate _msg: $(MSGDOMAINPOFILE) 1547c478bd9Sstevel@tonic-gate 1557c478bd9Sstevel@tonic-gate include $(SRC)/Makefile.msg.targ 1567c478bd9Sstevel@tonic-gate 1577c478bd9Sstevel@tonic-gateNote that this example doesn't use grep to find message files, since that can 1587c478bd9Sstevel@tonic-gatemask unreferenced files, and potentially lead to the inclusion of unwanted 1597c478bd9Sstevel@tonic-gatemessages or omission of intended messages in the catalogs. As such, MSGFILES 1607c478bd9Sstevel@tonic-gateshould be derived from a known list of objects or sources. 1617c478bd9Sstevel@tonic-gate 1627c478bd9Sstevel@tonic-gateIt is usually preferable to run the source through the C preprocessor prior 1637c478bd9Sstevel@tonic-gateto extracting messages. To do this, use the ".i" suffix, as shown in the 1647c478bd9Sstevel@tonic-gateabove example. If you need to skip the C preprocessor, just use the native 1657c478bd9Sstevel@tonic-gate(.[ch]) suffix. 1667c478bd9Sstevel@tonic-gate 1677c478bd9Sstevel@tonic-gateThe only time you shouldn't use BUILDPO.msgfiles as the preferred means of 168*f808c858Srafextracting messages is when you're extracting them from shell scripts; in 1697c478bd9Sstevel@tonic-gatethat case, you can use the BUILDPO.pofiles macro as explained below. 1707c478bd9Sstevel@tonic-gate 1717c478bd9Sstevel@tonic-gateTo build a message catalog from other message catalogs, or from source files 1727c478bd9Sstevel@tonic-gatethat include shell scripts, use the BUILDPO.pofiles macro: 1737c478bd9Sstevel@tonic-gate 1747c478bd9Sstevel@tonic-gate include ../Makefile.lib 1757c478bd9Sstevel@tonic-gate 1767c478bd9Sstevel@tonic-gate SUBDIRS = $(MACH) 1777c478bd9Sstevel@tonic-gate 1787c478bd9Sstevel@tonic-gate POFILE = libfoo.po 1797c478bd9Sstevel@tonic-gate POFILES = $(SUBDIRS:%=%/_%.po) 1807c478bd9Sstevel@tonic-gate 1817c478bd9Sstevel@tonic-gate _msg := TARGET = _msg 1827c478bd9Sstevel@tonic-gate 1837c478bd9Sstevel@tonic-gate # ... 1847c478bd9Sstevel@tonic-gate 1857c478bd9Sstevel@tonic-gate $(POFILE): $(POFILES) 1867c478bd9Sstevel@tonic-gate $(BUILDPO.pofiles) 1877c478bd9Sstevel@tonic-gate 1887c478bd9Sstevel@tonic-gate _msg: $(MSGDOMAINPOFILE) 1897c478bd9Sstevel@tonic-gate 1907c478bd9Sstevel@tonic-gate include $(SRC)/Makefile.msg.targ 1917c478bd9Sstevel@tonic-gate 1927c478bd9Sstevel@tonic-gateThe Makefile above would work in conjunction with the following in its 1937c478bd9Sstevel@tonic-gatesubdirectories' Makefiles: 1947c478bd9Sstevel@tonic-gate 1957c478bd9Sstevel@tonic-gate POFILE = _thissubdir.po 1967c478bd9Sstevel@tonic-gate MSGFILES = $(OBJECTS:%.o=%.i) 1977c478bd9Sstevel@tonic-gate 1987c478bd9Sstevel@tonic-gate $(POFILE): $(MSGFILES) 1997c478bd9Sstevel@tonic-gate $(BUILDPO.msgfiles) 2007c478bd9Sstevel@tonic-gate 2017c478bd9Sstevel@tonic-gate _msg: $(POFILE) 2027c478bd9Sstevel@tonic-gate 2037c478bd9Sstevel@tonic-gate include $(SRC)/Makefile.msg.targ 2047c478bd9Sstevel@tonic-gate 2057c478bd9Sstevel@tonic-gateSince this POFILE will be combined with those in other subdirectories by the 2067c478bd9Sstevel@tonic-gateparent Makefile and that merged file will be installed into the proto area 2077c478bd9Sstevel@tonic-gatevia MSGDOMAINPOFILE, there is no need to use MSGDOMAINPOFILE in this Makefile 2087c478bd9Sstevel@tonic-gate(in fact, using it would lead to duplicate messages in the catalog). 2097c478bd9Sstevel@tonic-gate 2107c478bd9Sstevel@tonic-gateWhen using any of these targets, keep in mind that other macros, like 2117c478bd9Sstevel@tonic-gateXGETFLAGS and TEXT_DOMAIN may also be set in your Makefile to override or 2127c478bd9Sstevel@tonic-gateaugment the defaults provided in higher-level Makefiles. 2137c478bd9Sstevel@tonic-gate 2147c478bd9Sstevel@tonic-gateAs previously mentioned, you should defer all ISA-specific targets to your 2157c478bd9Sstevel@tonic-gateISA-specific Makefiles. You can do this by: 2167c478bd9Sstevel@tonic-gate 2177c478bd9Sstevel@tonic-gate 1. Setting SUBDIRS to the list of directories to descend into: 2187c478bd9Sstevel@tonic-gate 2197c478bd9Sstevel@tonic-gate SUBDIRS = $(MACH) 2207c478bd9Sstevel@tonic-gate 2217c478bd9Sstevel@tonic-gate Note that if your library is also built 64-bit, then you should 2227c478bd9Sstevel@tonic-gate also specify 2237c478bd9Sstevel@tonic-gate 2247c478bd9Sstevel@tonic-gate $(BUILD64)SUBDIRS += $(MACH64) 2257c478bd9Sstevel@tonic-gate 2267c478bd9Sstevel@tonic-gate so that SUBDIRS contains $(MACH64) if and only if you're compiling 2277c478bd9Sstevel@tonic-gate on a 64-bit ISA. 2287c478bd9Sstevel@tonic-gate 2297c478bd9Sstevel@tonic-gate 2. Providing a common "descend into SUBDIRS" rule: 2307c478bd9Sstevel@tonic-gate 231*f808c858Sraf $(SUBDIRS): FRC 2327c478bd9Sstevel@tonic-gate @cd $@; pwd; $(MAKE) $(TARGET) 2337c478bd9Sstevel@tonic-gate 2347c478bd9Sstevel@tonic-gate FRC: 2357c478bd9Sstevel@tonic-gate 2367c478bd9Sstevel@tonic-gate 3. Providing a collection of conditional assignments that set TARGET 2377c478bd9Sstevel@tonic-gate appropriately: 2387c478bd9Sstevel@tonic-gate 2397c478bd9Sstevel@tonic-gate all := TARGET= all 2407c478bd9Sstevel@tonic-gate clean := TARGET= clean 2417c478bd9Sstevel@tonic-gate clobber := TARGET= clobber 2427c478bd9Sstevel@tonic-gate install := TARGET= install 2437c478bd9Sstevel@tonic-gate lint := TARGET= lint 2447c478bd9Sstevel@tonic-gate 2457c478bd9Sstevel@tonic-gate The order doesn't matter, but alphabetical is preferable. 2467c478bd9Sstevel@tonic-gate 2477c478bd9Sstevel@tonic-gate 4. Having the aforementioned targets depend on SUBDIRS: 2487c478bd9Sstevel@tonic-gate 249*f808c858Sraf all clean clobber install lint: $(SUBDIRS) 2507c478bd9Sstevel@tonic-gate 251*f808c858Sraf The `all' target must be listed first so that make uses it as the 252*f808c858Sraf default target; the others might as well be listed alphabetically. 2537c478bd9Sstevel@tonic-gate 2547c478bd9Sstevel@tonic-gateAs an example of how all of this goes together, here's libinetutil's 255*f808c858Sraftop-level library Makefile (license notice and copyright omitted): 2567c478bd9Sstevel@tonic-gate 2577c478bd9Sstevel@tonic-gate include ../Makefile.lib 2587c478bd9Sstevel@tonic-gate 2597c478bd9Sstevel@tonic-gate HDRS = libinetutil.h 2607c478bd9Sstevel@tonic-gate HDRDIR = common 2617c478bd9Sstevel@tonic-gate SUBDIRS = $(MACH) 2627c478bd9Sstevel@tonic-gate $(BUILD64)SUBDIRS += $(MACH64) 2637c478bd9Sstevel@tonic-gate 2647c478bd9Sstevel@tonic-gate all := TARGET = all 2657c478bd9Sstevel@tonic-gate clean := TARGET = clean 2667c478bd9Sstevel@tonic-gate clobber := TARGET = clobber 2677c478bd9Sstevel@tonic-gate install := TARGET = install 2687c478bd9Sstevel@tonic-gate lint := TARGET = lint 2697c478bd9Sstevel@tonic-gate 2707c478bd9Sstevel@tonic-gate .KEEP_STATE: 2717c478bd9Sstevel@tonic-gate 272*f808c858Sraf all clean clobber install lint: $(SUBDIRS) 2737c478bd9Sstevel@tonic-gate 2747c478bd9Sstevel@tonic-gate install_h: $(ROOTHDRS) 2757c478bd9Sstevel@tonic-gate 2767c478bd9Sstevel@tonic-gate check: $(CHECKHDRS) 2777c478bd9Sstevel@tonic-gate 278*f808c858Sraf $(SUBDIRS): FRC 2797c478bd9Sstevel@tonic-gate @cd $@; pwd; $(MAKE) $(TARGET) 2807c478bd9Sstevel@tonic-gate 2817c478bd9Sstevel@tonic-gate FRC: 2827c478bd9Sstevel@tonic-gate 2837c478bd9Sstevel@tonic-gate include ../Makefile.targ 2847c478bd9Sstevel@tonic-gate 2857c478bd9Sstevel@tonic-gateThe Common Makefile 2867c478bd9Sstevel@tonic-gate------------------- 2877c478bd9Sstevel@tonic-gate 2887c478bd9Sstevel@tonic-gateIn concept, your common Makefile should contain all of the rules and 2897c478bd9Sstevel@tonic-gatedefinitions that are the same on all ISAs. However, for reasons of 2907c478bd9Sstevel@tonic-gatemaintainability and cleanliness, you're encouraged to place even 2917c478bd9Sstevel@tonic-gateISA-dependent rules and definitions, as long you express them in an 292*f808c858SrafISA-independent way (e.g., by using $(MACH), $(TARGETMACH), and their kin). 293*f808c858Sraf(TARGETMACH is the same as MACH for 32-bit targets, and the same as MACH64 294*f808c858Sraffor 64-bit targets). 2957c478bd9Sstevel@tonic-gate 2967c478bd9Sstevel@tonic-gateThe common Makefile can be conceptually split up into four sections: 2977c478bd9Sstevel@tonic-gate 2987c478bd9Sstevel@tonic-gate 1. A copyright and comments section. Please see the prototype 2997c478bd9Sstevel@tonic-gate files in usr/src/prototypes for examples of how to format the 3007c478bd9Sstevel@tonic-gate copyright message properly. For brevity and clarity, this 3017c478bd9Sstevel@tonic-gate section has been omitted from the examples shown here. 3027c478bd9Sstevel@tonic-gate 3037c478bd9Sstevel@tonic-gate 2. A list of macros that must be defined prior to the inclusion of 3047c478bd9Sstevel@tonic-gate Makefile.lib. This section is conceptually terminated by the 3057c478bd9Sstevel@tonic-gate inclusion of Makefile.lib, followed, if necessary, by the 3067c478bd9Sstevel@tonic-gate inclusion of Makefile.rootfs (only if the library is to be 3077c478bd9Sstevel@tonic-gate installed in /lib rather than the default /usr/lib). 3087c478bd9Sstevel@tonic-gate 3097c478bd9Sstevel@tonic-gate 3. A list of macros that need not be defined prior to the inclusion 3107c478bd9Sstevel@tonic-gate of Makefile.lib (or which must be defined following the inclusion 3117c478bd9Sstevel@tonic-gate of Makefile.lib, to override or augment its definitions). This 3127c478bd9Sstevel@tonic-gate section is conceptually terminated by the .KEEP_STATE directive. 3137c478bd9Sstevel@tonic-gate 3147c478bd9Sstevel@tonic-gate 4. A list of targets. 3157c478bd9Sstevel@tonic-gate 3167c478bd9Sstevel@tonic-gateThe first section is self-explanatory. The second typically consists of the 3177c478bd9Sstevel@tonic-gatefollowing macros: 3187c478bd9Sstevel@tonic-gate 3197c478bd9Sstevel@tonic-gate LIBRARY 3207c478bd9Sstevel@tonic-gate 3217c478bd9Sstevel@tonic-gate Set to the name of the static version of your library, such 3227c478bd9Sstevel@tonic-gate as `libinetutil.a'. You should always specify the `.a' suffix, 3237c478bd9Sstevel@tonic-gate since pattern-matching rules in higher-level Makefiles rely on it, 3247c478bd9Sstevel@tonic-gate even though static libraries are not normally built in ON, and 3257c478bd9Sstevel@tonic-gate are never installed in the proto area. Note that the LIBS macro 3267c478bd9Sstevel@tonic-gate (described below) controls the types of libraries that are built 3277c478bd9Sstevel@tonic-gate when building your library. 3287c478bd9Sstevel@tonic-gate 3297c478bd9Sstevel@tonic-gate If you are building a loadable module (i.e., a shared object that 3307c478bd9Sstevel@tonic-gate is only linked at runtime with dlopen(3dl)), specify the name of 3317c478bd9Sstevel@tonic-gate the loadable module with a `.a' suffix, such as `devfsadm_mod.a'. 3327c478bd9Sstevel@tonic-gate 3337c478bd9Sstevel@tonic-gate VERS 3347c478bd9Sstevel@tonic-gate 3357c478bd9Sstevel@tonic-gate Set to the version of your shared library, such as `.1'. You 3367c478bd9Sstevel@tonic-gate actually do not need to set this prior to the inclusion of 3377c478bd9Sstevel@tonic-gate Makefile.lib, but it is good practice to do so since VERS and 3387c478bd9Sstevel@tonic-gate LIBRARY are so closely related. 3397c478bd9Sstevel@tonic-gate 3407c478bd9Sstevel@tonic-gate OBJECTS 3417c478bd9Sstevel@tonic-gate 3427c478bd9Sstevel@tonic-gate Set to the list of object files contained in your library, such as 3437c478bd9Sstevel@tonic-gate `a.o b.o'. Usually, this will be the same as your library's source 3447c478bd9Sstevel@tonic-gate files (except with .o extensions), but if your library compiles 3457c478bd9Sstevel@tonic-gate source files outside of the library directory itself, it will 3467c478bd9Sstevel@tonic-gate differ. We'll see an example of this with libinetutil. 3477c478bd9Sstevel@tonic-gate 3487c478bd9Sstevel@tonic-gateThe third section typically consists of the following macros: 3497c478bd9Sstevel@tonic-gate 3507c478bd9Sstevel@tonic-gate LIBS 3517c478bd9Sstevel@tonic-gate 3527c478bd9Sstevel@tonic-gate Set to the list of the types of libraries to build when building 3537c478bd9Sstevel@tonic-gate your library. For dynamic libraries, you should set this to 3547c478bd9Sstevel@tonic-gate `$(DYNLIB) $(LINTLIB)' so that a dynamic library and lint library 3557c478bd9Sstevel@tonic-gate are built. For loadable modules, you should just list DYNLIB, 3567c478bd9Sstevel@tonic-gate since there's no point in building a lint library for libraries 3577c478bd9Sstevel@tonic-gate that are never linked at compile-time. 3587c478bd9Sstevel@tonic-gate 3597c478bd9Sstevel@tonic-gate If your library needs to be built as a static library (typically 3607c478bd9Sstevel@tonic-gate to be used in other parts of the build), you should set LIBS to 3617c478bd9Sstevel@tonic-gate `$(LIBRARY)'. However, you should do this only when absolutely 3627c478bd9Sstevel@tonic-gate necessary, and you must *never* ship static libraries to customers. 3637c478bd9Sstevel@tonic-gate 3647c478bd9Sstevel@tonic-gate ROOTLIBDIR (if your library installs to a nonstandard directory) 3657c478bd9Sstevel@tonic-gate 3667c478bd9Sstevel@tonic-gate Set to the directory your 32-bit shared objects will install into 3677c478bd9Sstevel@tonic-gate with the standard $(ROOTxxx) macros. Since this defaults to 3687c478bd9Sstevel@tonic-gate $(ROOT)/usr/lib ($(ROOT)/lib if you included Makefile.rootfs), 3697c478bd9Sstevel@tonic-gate you usually do not need to set this. 3707c478bd9Sstevel@tonic-gate 3717c478bd9Sstevel@tonic-gate ROOTLIBDIR64 (if your library installs to a nonstandard directory) 3727c478bd9Sstevel@tonic-gate 3737c478bd9Sstevel@tonic-gate Set to the directory your 64-bit shared objects will install into 3747c478bd9Sstevel@tonic-gate with the standard $(ROOTxxx64) macros. Since this defaults to 3757c478bd9Sstevel@tonic-gate $(ROOT)/usr/lib/$(MACH64) ($(ROOT)/lib/$(MACH64) if you included 3767c478bd9Sstevel@tonic-gate Makefile.rootfs), you usually do not need to set this. 3777c478bd9Sstevel@tonic-gate 3787c478bd9Sstevel@tonic-gate SRCDIR 3797c478bd9Sstevel@tonic-gate 3807c478bd9Sstevel@tonic-gate Set to the directory containing your library's source files, such 3817c478bd9Sstevel@tonic-gate as `../common'. Because this Makefile is actually included from 3827c478bd9Sstevel@tonic-gate your ISA-specific Makefiles, make sure you specify the directory 3837c478bd9Sstevel@tonic-gate relative to your library's <isa> directory. 3847c478bd9Sstevel@tonic-gate 3857c478bd9Sstevel@tonic-gate SRCS (if necessary) 3867c478bd9Sstevel@tonic-gate 3877c478bd9Sstevel@tonic-gate Set to the list of source files required to build your library. 3887c478bd9Sstevel@tonic-gate This defaults to $(OBJECTS:%.o=$(SRCDIR)/%.c) in Makefile.lib, so 3897c478bd9Sstevel@tonic-gate you only need to set this when source files from directories other 3907c478bd9Sstevel@tonic-gate than SRCDIR are needed. Keep in mind that SRCS should be set to a 3917c478bd9Sstevel@tonic-gate list of source file *pathnames*, not just a list of filenames. 3927c478bd9Sstevel@tonic-gate 3937c478bd9Sstevel@tonic-gate LINTLIB-specific SRCS (required if building a lint library) 3947c478bd9Sstevel@tonic-gate 3957c478bd9Sstevel@tonic-gate Set to a special "lint stubs" file to use when constructing your 3967c478bd9Sstevel@tonic-gate library's lint library. The lint stubs file must be used to 3977c478bd9Sstevel@tonic-gate guarantee that programs that link against your library will be able 3987c478bd9Sstevel@tonic-gate to lint clean. To do this, you must conditionally set SRCS to use 3997c478bd9Sstevel@tonic-gate your stubs file by specifying `LINTLIB := SRCS= $(SRCDIR)/$(LINTSRC)' 4007c478bd9Sstevel@tonic-gate in your Makefile. Of course, you do not need to set this if your 4017c478bd9Sstevel@tonic-gate library does not build a lint library. 4027c478bd9Sstevel@tonic-gate 4037c478bd9Sstevel@tonic-gate LDLIBS 4047c478bd9Sstevel@tonic-gate 4057c478bd9Sstevel@tonic-gate Appended with the list of libraries and library directories needed 4067c478bd9Sstevel@tonic-gate to build your library; minimally "-lc". Note that this should 4077c478bd9Sstevel@tonic-gate *never* be set, since that will inadvertently clear the library 4087c478bd9Sstevel@tonic-gate search path, causing the linker to look in the wrong place for 4097c478bd9Sstevel@tonic-gate the libraries. 4107c478bd9Sstevel@tonic-gate 4117c478bd9Sstevel@tonic-gate Since lint targets also make use of LDLIBS, LDLIBS *must* only 4127c478bd9Sstevel@tonic-gate contain -l and -L directives; all other link-related directives 4137c478bd9Sstevel@tonic-gate should be put in DYNFLAGS (if they apply only to shared object 4147c478bd9Sstevel@tonic-gate construction) or LDFLAGS (if they apply in general). 4157c478bd9Sstevel@tonic-gate 416*f808c858Sraf MAPFILES (if necessary) 4177c478bd9Sstevel@tonic-gate 418*f808c858Sraf Set to the list of mapfiles used to link each ISA-specific version 419*f808c858Sraf of your library. This defaults to `$(SRCDIR)/mapfile-vers' in 420*f808c858Sraf Makefile.lib, so you only need to change this if you have additional 421*f808c858Sraf mapfiles or your mapfile doesn't follow the standard naming 422*f808c858Sraf convention. If you have supplemental ISA-dependent mapfiles that 423*f808c858Sraf reside in the respective <isa> directories, you can augment 424*f808c858Sraf MAPFILES like this: 4257c478bd9Sstevel@tonic-gate 426*f808c858Sraf MAPFILES += mapfile-vers 4277c478bd9Sstevel@tonic-gate 4287c478bd9Sstevel@tonic-gate CPPFLAGS (if necessary) 4297c478bd9Sstevel@tonic-gate 4307c478bd9Sstevel@tonic-gate Appended with any flags that need to be passed to the C 4317c478bd9Sstevel@tonic-gate preprocessor (typically -D and -I flags). Since lint macros use 4327c478bd9Sstevel@tonic-gate CPPFLAGS, CPPFLAGS *must* only contain directives known to the C 4337c478bd9Sstevel@tonic-gate preprocessor. When compiling MT-safe code, CPPFLAGS *must* 4347c478bd9Sstevel@tonic-gate include -D_REENTRANT. When compiling large file aware code, 4357c478bd9Sstevel@tonic-gate CPPFLAGS *must* include -D_FILE_OFFSET_BITS=64. 4367c478bd9Sstevel@tonic-gate 4377c478bd9Sstevel@tonic-gate CFLAGS 4387c478bd9Sstevel@tonic-gate 4397c478bd9Sstevel@tonic-gate Appended with any flags that need to be passed to the C compiler. 4407c478bd9Sstevel@tonic-gate Minimally, append `$(CCVERBOSE)'. Keep in mind that you should 4417c478bd9Sstevel@tonic-gate add any C preprocessor flags to CPPFLAGS, not CFLAGS. 4427c478bd9Sstevel@tonic-gate 4437c478bd9Sstevel@tonic-gate CFLAGS64 (if necessary) 4447c478bd9Sstevel@tonic-gate 4457c478bd9Sstevel@tonic-gate Appended with any flags that need to be passed to the C compiler 4467c478bd9Sstevel@tonic-gate when compiling 64-bit code. Since all 64-bit code is compiled 4477c478bd9Sstevel@tonic-gate $(CCVERBOSE), you usually do not need to modify CFLAGS64. 4487c478bd9Sstevel@tonic-gate 4497c478bd9Sstevel@tonic-gate COPTFLAG (if necessary) 4507c478bd9Sstevel@tonic-gate 4517c478bd9Sstevel@tonic-gate Set to control the optimization level used by the C compiler when 4527c478bd9Sstevel@tonic-gate compiling 32-bit code. You should only set this if absolutely 4537c478bd9Sstevel@tonic-gate necessary, and it should only contain optimization-related 4547c478bd9Sstevel@tonic-gate settings (or -g). 4557c478bd9Sstevel@tonic-gate 4567c478bd9Sstevel@tonic-gate COPTFLAG64 (if necessary) 4577c478bd9Sstevel@tonic-gate 4587c478bd9Sstevel@tonic-gate Set to control the optimization level used by the C compiler when 4597c478bd9Sstevel@tonic-gate compiling 64-bit code. You should only set this if absolutely 4607c478bd9Sstevel@tonic-gate necessary, and it should only contain optimization-related 4617c478bd9Sstevel@tonic-gate settings (or -g). 4627c478bd9Sstevel@tonic-gate 4637c478bd9Sstevel@tonic-gate LINTFLAGS (if necessary) 4647c478bd9Sstevel@tonic-gate 4657c478bd9Sstevel@tonic-gate Appended with any flags that need to be passed to lint when 4667c478bd9Sstevel@tonic-gate linting 32-bit code. You should only modify LINTFLAGS in 4677c478bd9Sstevel@tonic-gate rare instances where your code cannot (or should not) be fixed. 4687c478bd9Sstevel@tonic-gate 4697c478bd9Sstevel@tonic-gate LINTFLAGS64 (if necessary) 4707c478bd9Sstevel@tonic-gate 4717c478bd9Sstevel@tonic-gate Appended with any flags that need to be passed to lint when 4727c478bd9Sstevel@tonic-gate linting 64-bit code. You should only modify LINTFLAGS64 in 4737c478bd9Sstevel@tonic-gate rare instances where your code cannot (or should not) be fixed. 4747c478bd9Sstevel@tonic-gate 4757c478bd9Sstevel@tonic-gateOf course, you may use other macros as necessary. 4767c478bd9Sstevel@tonic-gate 4777c478bd9Sstevel@tonic-gateThe fourth section typically consists of the following targets: 4787c478bd9Sstevel@tonic-gate 4797c478bd9Sstevel@tonic-gate all 4807c478bd9Sstevel@tonic-gate 4817c478bd9Sstevel@tonic-gate Build all of the types of the libraries named by LIBS. Must always 4827c478bd9Sstevel@tonic-gate be the first real target in common Makefile. Since the 4837c478bd9Sstevel@tonic-gate higher-level Makefiles already contain rules to build all of the 4847c478bd9Sstevel@tonic-gate different types of libraries, you can usually just specify 4857c478bd9Sstevel@tonic-gate 4867c478bd9Sstevel@tonic-gate all: $(LIBS) 4877c478bd9Sstevel@tonic-gate 4887c478bd9Sstevel@tonic-gate though it should be listed as an empty target if LIBS is set by your 4897c478bd9Sstevel@tonic-gate ISA-specific Makefiles (see above). 4907c478bd9Sstevel@tonic-gate 4917c478bd9Sstevel@tonic-gate lint 4927c478bd9Sstevel@tonic-gate 4937c478bd9Sstevel@tonic-gate Use the `lintcheck' rule provided by lib/Makefile.targ to lint the 4947c478bd9Sstevel@tonic-gate actual library sources. Historically, this target has also been 4957c478bd9Sstevel@tonic-gate used to build the lint library (using LINTLIB), but that usage is 4967c478bd9Sstevel@tonic-gate now discouraged. Thus, this rule should be specified as 4977c478bd9Sstevel@tonic-gate 4987c478bd9Sstevel@tonic-gate lint: lintcheck 4997c478bd9Sstevel@tonic-gate 5007c478bd9Sstevel@tonic-gateConspicuously absent from this section are the `clean' and `clobber' targets. 5017c478bd9Sstevel@tonic-gateThese targets are already provided by lib/Makefile.targ and thus should not 5027c478bd9Sstevel@tonic-gatebe provided by your common Makefile. Instead, your common Makefile should 5037c478bd9Sstevel@tonic-gatelist any additional files to remove during a `clean' and `clobber' by 5047c478bd9Sstevel@tonic-gateappending to the CLEANFILES and CLOBBERFILES macros. 5057c478bd9Sstevel@tonic-gate 5067c478bd9Sstevel@tonic-gateOnce again, here's libinetutil's common Makefile, which shows how many of 5077c478bd9Sstevel@tonic-gatethese directives go together. Note that Makefile.rootfs is included to 5087c478bd9Sstevel@tonic-gatecause libinetutil.so.1 to be installed in /lib rather than /usr/lib: 5097c478bd9Sstevel@tonic-gate 5107c478bd9Sstevel@tonic-gate LIBRARY = libinetutil.a 5117c478bd9Sstevel@tonic-gate VERS = .1 512*f808c858Sraf OBJECTS = octet.o inetutil4.o ifspec.o ifaddrlist.o eh.o tq.o 5137c478bd9Sstevel@tonic-gate 5147c478bd9Sstevel@tonic-gate include ../../Makefile.lib 5157c478bd9Sstevel@tonic-gate include ../../Makefile.rootfs 5167c478bd9Sstevel@tonic-gate 5177c478bd9Sstevel@tonic-gate LIBS = $(DYNLIB) $(LINTLIB) 5187c478bd9Sstevel@tonic-gate 5197c478bd9Sstevel@tonic-gate SRCDIR = ../common 5207c478bd9Sstevel@tonic-gate COMDIR = $(SRC)/common/net/dhcp 521*f808c858Sraf SRCS = $(COMDIR)/octet.c $(SRCDIR)/inetutil4.c \ 522*f808c858Sraf $(SRCDIR)/ifspec.c $(SRCDIR)/eh.c $(SRCDIR)/tq.c \ 523*f808c858Sraf $(SRCDIR)/ifaddrlist.c 524*f808c858Sraf 525*f808c858Sraf $(LINTLIB):= SRCS = $(SRCDIR)/$(LINTSRC) 526*f808c858Sraf LDLIBS += -lsocket -lc 5277c478bd9Sstevel@tonic-gate 5287c478bd9Sstevel@tonic-gate CFLAGS += $(CCVERBOSE) 5297c478bd9Sstevel@tonic-gate CPPFLAGS += -I$(SRCDIR) 5307c478bd9Sstevel@tonic-gate 5317c478bd9Sstevel@tonic-gate .KEEP_STATE: 5327c478bd9Sstevel@tonic-gate 5337c478bd9Sstevel@tonic-gate all: $(LIBS) 5347c478bd9Sstevel@tonic-gate 5357c478bd9Sstevel@tonic-gate lint: lintcheck 5367c478bd9Sstevel@tonic-gate 5377c478bd9Sstevel@tonic-gate pics/%.o: $(COMDIR)/%.c 5387c478bd9Sstevel@tonic-gate $(COMPILE.c) -o $@ $< 5397c478bd9Sstevel@tonic-gate $(POST_PROCESS_O) 5407c478bd9Sstevel@tonic-gate 5417c478bd9Sstevel@tonic-gate include ../../Makefile.targ 5427c478bd9Sstevel@tonic-gate 543*f808c858SrafThe mapfile for libinetutil is named `mapfile-vers' and resides in $(SRCDIR), 544*f808c858Srafso the MAPFILES definition is omitted, defaulting to $(SRCDIR)/mapfile-vers. 545*f808c858Sraf 5467c478bd9Sstevel@tonic-gateNote that for libinetutil, not all of the object files come from SRCDIR. To 5477c478bd9Sstevel@tonic-gatesupport this, an alternate source file directory named COMDIR is defined, and 5487c478bd9Sstevel@tonic-gatethe source files listed in SRCS are specified using both COMDIR and SRCDIR. 5497c478bd9Sstevel@tonic-gateAdditionally, a special build rule is provided to build object files from the 5507c478bd9Sstevel@tonic-gatesources in COMDIR; the rule uses COMPILE.c and POST_PROCESS_O so that any 5517c478bd9Sstevel@tonic-gatechanges to the compilation and object-post-processing phases will be 5527c478bd9Sstevel@tonic-gateautomatically picked up. 5537c478bd9Sstevel@tonic-gate 5547c478bd9Sstevel@tonic-gateThe ISA-Specific Makefiles 5557c478bd9Sstevel@tonic-gate-------------------------- 5567c478bd9Sstevel@tonic-gate 5577c478bd9Sstevel@tonic-gateAs the name implies, your ISA-specific Makefiles should contain macros and 5587c478bd9Sstevel@tonic-gaterules that cannot be expressed in an ISA-independent way. Usually, the only 5597c478bd9Sstevel@tonic-gaterule you will need to put here is `install', which has different dependencies 5607c478bd9Sstevel@tonic-gatefor 32-bit and 64-bit libraries. For instance, here are the ISA-specific 5617c478bd9Sstevel@tonic-gateMakefiles for libinetutil: 5627c478bd9Sstevel@tonic-gate 5637c478bd9Sstevel@tonic-gate sparc/Makefile: 5647c478bd9Sstevel@tonic-gate 5657c478bd9Sstevel@tonic-gate include ../Makefile.com 5667c478bd9Sstevel@tonic-gate 5677c478bd9Sstevel@tonic-gate install: all $(ROOTLIBS) $(ROOTLINKS) $(ROOTLINT) 5687c478bd9Sstevel@tonic-gate 5697c478bd9Sstevel@tonic-gate sparcv9/Makefile: 5707c478bd9Sstevel@tonic-gate 5717c478bd9Sstevel@tonic-gate include ../Makefile.com 5727c478bd9Sstevel@tonic-gate include ../../Makefile.lib.64 5737c478bd9Sstevel@tonic-gate 5747c478bd9Sstevel@tonic-gate install: all $(ROOTLIBS64) $(ROOTLINKS64) 5757c478bd9Sstevel@tonic-gate 5767c478bd9Sstevel@tonic-gate i386/Makefile: 5777c478bd9Sstevel@tonic-gate 5787c478bd9Sstevel@tonic-gate include ../Makefile.com 5797c478bd9Sstevel@tonic-gate 5807c478bd9Sstevel@tonic-gate install: all $(ROOTLIBS) $(ROOTLINKS) $(ROOTLINT) 5817c478bd9Sstevel@tonic-gate 582*f808c858Sraf amd64/Makefile: 583*f808c858Sraf 584*f808c858Sraf include ../Makefile.com 585*f808c858Sraf include ../../Makefile.lib.64 586*f808c858Sraf 587*f808c858Sraf install: all $(ROOTLIBS64) $(ROOTLINKS64) 588*f808c858Sraf 5897c478bd9Sstevel@tonic-gateObserve that there is no .KEEP_STATE directive in these Makefiles, since all 5907c478bd9Sstevel@tonic-gateof these Makefiles include libinetutil/Makefile.com, and it already has a 591*f808c858Sraf.KEEP_STATE directive. Also, note that the 64-bit Makefiles also include 5927c478bd9Sstevel@tonic-gateMakefile.lib.64, which overrides some of the definitions contained in the 5937c478bd9Sstevel@tonic-gatehigher level Makefiles included by the common Makefile so that 64-bit 5947c478bd9Sstevel@tonic-gatecompiles work correctly. 5957c478bd9Sstevel@tonic-gate 5967c478bd9Sstevel@tonic-gateCTF Data in Libraries 5977c478bd9Sstevel@tonic-gate--------------------- 5987c478bd9Sstevel@tonic-gate 599*f808c858SrafBy default, all position-independent objects are built with CTF data using 6007c478bd9Sstevel@tonic-gatectfconvert, which is then merged together using ctfmerge when the shared 6017c478bd9Sstevel@tonic-gateobject is built. All C-source objects processed via ctfmerge need to be 6027c478bd9Sstevel@tonic-gateprocessed via ctfconvert or the build will fail. Objects built from non-C 6037c478bd9Sstevel@tonic-gatesources (such as assembly or C++) are silently ignored for CTF processing. 6047c478bd9Sstevel@tonic-gate 6057c478bd9Sstevel@tonic-gateFilter libraries that have no source files will need to explicitly disable 6067c478bd9Sstevel@tonic-gateCTF by setting CTFMERGE_LIB to ":"; see libw/Makefile.com for an example. 6077c478bd9Sstevel@tonic-gate 6087c478bd9Sstevel@tonic-gateMore Information 6097c478bd9Sstevel@tonic-gate---------------- 6107c478bd9Sstevel@tonic-gate 6117c478bd9Sstevel@tonic-gateOther issues and questions will undoubtedly arise while you work on your 6127c478bd9Sstevel@tonic-gatelibrary's Makefiles. To help in this regard, a number of libraries of 6137c478bd9Sstevel@tonic-gatevarying complexity have been updated to follow the guidelines and practices 6147c478bd9Sstevel@tonic-gateoutlined in this document: 6157c478bd9Sstevel@tonic-gate 6167c478bd9Sstevel@tonic-gate lib/libdhcputil 6177c478bd9Sstevel@tonic-gate 6187c478bd9Sstevel@tonic-gate Example of a simple 32-bit only library. 6197c478bd9Sstevel@tonic-gate 6207c478bd9Sstevel@tonic-gate lib/libdhcpagent 6217c478bd9Sstevel@tonic-gate 6227c478bd9Sstevel@tonic-gate Example of a simple 32-bit only library that obtains its sources 6237c478bd9Sstevel@tonic-gate from multiple directories. 6247c478bd9Sstevel@tonic-gate 6257c478bd9Sstevel@tonic-gate lib/ncad_addr 6267c478bd9Sstevel@tonic-gate 6277c478bd9Sstevel@tonic-gate Example of a simple loadable module. 6287c478bd9Sstevel@tonic-gate 6297c478bd9Sstevel@tonic-gate lib/libipmp 6307c478bd9Sstevel@tonic-gate 6317c478bd9Sstevel@tonic-gate Example of a simple library that builds a message catalog. 6327c478bd9Sstevel@tonic-gate 6337c478bd9Sstevel@tonic-gate lib/libdhcpsvc 6347c478bd9Sstevel@tonic-gate 6357c478bd9Sstevel@tonic-gate Example of a Makefile hierarchy for a library and a collection 6367c478bd9Sstevel@tonic-gate of related pluggable modules. 6377c478bd9Sstevel@tonic-gate 6387c478bd9Sstevel@tonic-gate lib/lvm 6397c478bd9Sstevel@tonic-gate 6407c478bd9Sstevel@tonic-gate Example of a Makefile hierarchy for a collection of related 6417c478bd9Sstevel@tonic-gate libraries and pluggable modules. 6427c478bd9Sstevel@tonic-gate 6437c478bd9Sstevel@tonic-gate Also an example of a Makefile hierarchy that supports the 6447c478bd9Sstevel@tonic-gate _dc target for domain and category specific messages. 6457c478bd9Sstevel@tonic-gate 6467c478bd9Sstevel@tonic-gateOf course, if you still have questions, please do not hesitate to send email 6477c478bd9Sstevel@tonic-gateto the ON gatekeepers. 648