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 5f808c858Sraf# Common Development and Distribution License (the "License"). 6f808c858Sraf# 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# 21f808c858Sraf# 22f808c858Sraf# Copyright 2006 Sun Microsystems, Inc. All rights reserved. 23f808c858Sraf# Use is subject to license terms. 24f808c858Sraf 257c478bd9Sstevel@tonic-gateWriting Library Makefiles in ON 267c478bd9Sstevel@tonic-gate=============================== 277c478bd9Sstevel@tonic-gate 287c478bd9Sstevel@tonic-gateIntroduction 297c478bd9Sstevel@tonic-gate------------ 307c478bd9Sstevel@tonic-gate 317c478bd9Sstevel@tonic-gateThis document guides you through the gnarly process of writing library 327c478bd9Sstevel@tonic-gateMakefiles for the ON consolidation. It assumes that you're comfortable with 337c478bd9Sstevel@tonic-gatemake(1) and are somewhat familiar with the ON Makefile standards outlined in 347c478bd9Sstevel@tonic-gate/shared/ON/general_docs/make_std.txt. 357c478bd9Sstevel@tonic-gate 367c478bd9Sstevel@tonic-gateMakefile Overview 377c478bd9Sstevel@tonic-gate----------------- 387c478bd9Sstevel@tonic-gate 397c478bd9Sstevel@tonic-gateYour library should consist of a hierarchical collection of Makefiles: 407c478bd9Sstevel@tonic-gate 417c478bd9Sstevel@tonic-gate lib/<library>/Makefile: 427c478bd9Sstevel@tonic-gate 437c478bd9Sstevel@tonic-gate This is your library's top-level Makefile. It should contain rules 447c478bd9Sstevel@tonic-gate for building any ISA-independent targets, such as installing header 457c478bd9Sstevel@tonic-gate files and building message catalogs, but should defer all other 467c478bd9Sstevel@tonic-gate targets to ISA-specific Makefiles. 477c478bd9Sstevel@tonic-gate 487c478bd9Sstevel@tonic-gate lib/<library>/Makefile.com 497c478bd9Sstevel@tonic-gate 507c478bd9Sstevel@tonic-gate This is your library's common Makefile. It should contain rules 517c478bd9Sstevel@tonic-gate and macros which are common to all ISAs. This Makefile should never 527c478bd9Sstevel@tonic-gate be built explicitly, but instead should be included (using the make 537c478bd9Sstevel@tonic-gate include mechanism) by all of your ISA-specific Makefiles. 547c478bd9Sstevel@tonic-gate 557c478bd9Sstevel@tonic-gate lib/<library>/<isa>/Makefile 567c478bd9Sstevel@tonic-gate 577c478bd9Sstevel@tonic-gate These are your library's ISA-specific Makefiles, one per ISA 58f808c858Sraf (usually sparc and i386, and often sparcv9 and amd64). These 597c478bd9Sstevel@tonic-gate Makefiles should include your common Makefile and then provide any 607c478bd9Sstevel@tonic-gate needed ISA-specific rules and definitions, perhaps overriding those 617c478bd9Sstevel@tonic-gate provided in your common Makefile. 627c478bd9Sstevel@tonic-gate 637c478bd9Sstevel@tonic-gateTo simplify their maintenance and construction, $(SRC)/lib has a handful of 647c478bd9Sstevel@tonic-gateprovided Makefiles that yours must include; the examples provided throughout 657c478bd9Sstevel@tonic-gatethe document will show how to use them. Please be sure to consult these 667c478bd9Sstevel@tonic-gateMakefiles before introducing your own custom build macros or rules. 677c478bd9Sstevel@tonic-gate 687c478bd9Sstevel@tonic-gate lib/Makefile.lib: 697c478bd9Sstevel@tonic-gate 707c478bd9Sstevel@tonic-gate This contains the bulk of the macros for building shared objects. 717c478bd9Sstevel@tonic-gate 727c478bd9Sstevel@tonic-gate lib/Makefile.lib.64 737c478bd9Sstevel@tonic-gate 747c478bd9Sstevel@tonic-gate This contains macros for building 64-bit objects, and should be 75f808c858Sraf included in Makefiles for 64-bit native ISAs. 767c478bd9Sstevel@tonic-gate 777c478bd9Sstevel@tonic-gate lib/Makefile.rootfs 787c478bd9Sstevel@tonic-gate 797c478bd9Sstevel@tonic-gate This contains macro overrides for libraries that install into /lib 807c478bd9Sstevel@tonic-gate (rather than /usr/lib). 817c478bd9Sstevel@tonic-gate 827c478bd9Sstevel@tonic-gate lib/Makefile.targ 837c478bd9Sstevel@tonic-gate 847c478bd9Sstevel@tonic-gate This contains rules for building shared objects. 857c478bd9Sstevel@tonic-gate 867c478bd9Sstevel@tonic-gateThe remainder of this document discusses how to write each of your Makefiles 877c478bd9Sstevel@tonic-gatein detail, and provides examples from the libinetutil library. 887c478bd9Sstevel@tonic-gate 897c478bd9Sstevel@tonic-gateThe Library Top-level Makefile 907c478bd9Sstevel@tonic-gate------------------------------ 917c478bd9Sstevel@tonic-gate 927c478bd9Sstevel@tonic-gateAs described above, your top-level library Makefile should contain 937c478bd9Sstevel@tonic-gaterules for building ISA-independent targets, but should defer the 947c478bd9Sstevel@tonic-gatebuilding of all other targets to ISA-specific Makefiles. The 957c478bd9Sstevel@tonic-gateISA-independent targets usually consist of: 967c478bd9Sstevel@tonic-gate 977c478bd9Sstevel@tonic-gate install_h 987c478bd9Sstevel@tonic-gate 99f808c858Sraf Install all library header files into the proto area. 100f808c858Sraf Can be omitted if your library has no header files. 1017c478bd9Sstevel@tonic-gate 1027c478bd9Sstevel@tonic-gate check 1037c478bd9Sstevel@tonic-gate 104f808c858Sraf Check all library header files for hdrchk compliance. 105f808c858Sraf Can be omitted if your library has no header files. 1067c478bd9Sstevel@tonic-gate 1077c478bd9Sstevel@tonic-gate _msg 1087c478bd9Sstevel@tonic-gate 109f808c858Sraf Build and install a message catalog. 110f808c858Sraf Can be omitted if your library has no message catalog. 1117c478bd9Sstevel@tonic-gate 112f808c858SrafOf course, other targets (such as `cstyle') are fine as well, as long as 1137c478bd9Sstevel@tonic-gatethey are ISA-independent. 1147c478bd9Sstevel@tonic-gate 1157c478bd9Sstevel@tonic-gateThe ROOTHDRS and CHECKHDRS targets are provided in lib/Makefile.lib to make 1167c478bd9Sstevel@tonic-gateit easy for you to install and check your library's header files. To use 1177c478bd9Sstevel@tonic-gatethese targets, your Makefile must set the HDRS to the list of your library's 1187c478bd9Sstevel@tonic-gateheader files to install and HDRDIR to the their location in the source tree. 1197c478bd9Sstevel@tonic-gateIn addition, if your header files need to be installed in a location other 1207c478bd9Sstevel@tonic-gatethan $(ROOT)/usr/include, your Makefile must also set ROOTHDRDIR to the 1217c478bd9Sstevel@tonic-gateappropriate location in the proto area. Once HDRS, HDRDIR and (optionally) 1227c478bd9Sstevel@tonic-gateROOTHDRDIR have been set, your Makefile need only contain 1237c478bd9Sstevel@tonic-gate 1247c478bd9Sstevel@tonic-gate install_h: $(ROOTHDRS) 1257c478bd9Sstevel@tonic-gate 1267c478bd9Sstevel@tonic-gate check: $(CHECKHDRS) 1277c478bd9Sstevel@tonic-gate 1287c478bd9Sstevel@tonic-gateto bind the provided targets to the standard `install_h' and `check' rules. 1297c478bd9Sstevel@tonic-gate 1307c478bd9Sstevel@tonic-gateSimilar rules are provided (in $(SRC)/Makefile.msg.targ) to make it easy for 1317c478bd9Sstevel@tonic-gateyou to build and install message catalogs from your library's source files. 1327c478bd9Sstevel@tonic-gate 1337c478bd9Sstevel@tonic-gateTo install a catalog into the catalog directory in the proto area, define the 1347c478bd9Sstevel@tonic-gatePOFILE macro to be the name of your catalog, and specify that the _msg target 1357c478bd9Sstevel@tonic-gatedepends on $(MSGDOMAINPOFILE). The examples below should clarify this. 1367c478bd9Sstevel@tonic-gate 1377c478bd9Sstevel@tonic-gateTo build a message catalog from arbitrarily many message source files, use 1387c478bd9Sstevel@tonic-gatethe BUILDPO.msgfiles macro. 1397c478bd9Sstevel@tonic-gate 1407c478bd9Sstevel@tonic-gate include ../Makefile.lib 1417c478bd9Sstevel@tonic-gate 1427c478bd9Sstevel@tonic-gate POFILE = libfoo.po 1437c478bd9Sstevel@tonic-gate MSGFILES = $(OBJECTS:%.o=%.i) 1447c478bd9Sstevel@tonic-gate 1457c478bd9Sstevel@tonic-gate # ... 1467c478bd9Sstevel@tonic-gate 1477c478bd9Sstevel@tonic-gate $(POFILE): $(MSGFILES) 1487c478bd9Sstevel@tonic-gate $(BUILDPO.msgfiles) 1497c478bd9Sstevel@tonic-gate 1507c478bd9Sstevel@tonic-gate _msg: $(MSGDOMAINPOFILE) 1517c478bd9Sstevel@tonic-gate 1527c478bd9Sstevel@tonic-gate include $(SRC)/Makefile.msg.targ 1537c478bd9Sstevel@tonic-gate 1547c478bd9Sstevel@tonic-gateNote that this example doesn't use grep to find message files, since that can 1557c478bd9Sstevel@tonic-gatemask unreferenced files, and potentially lead to the inclusion of unwanted 1567c478bd9Sstevel@tonic-gatemessages or omission of intended messages in the catalogs. As such, MSGFILES 1577c478bd9Sstevel@tonic-gateshould be derived from a known list of objects or sources. 1587c478bd9Sstevel@tonic-gate 1597c478bd9Sstevel@tonic-gateIt is usually preferable to run the source through the C preprocessor prior 1607c478bd9Sstevel@tonic-gateto extracting messages. To do this, use the ".i" suffix, as shown in the 1617c478bd9Sstevel@tonic-gateabove example. If you need to skip the C preprocessor, just use the native 1627c478bd9Sstevel@tonic-gate(.[ch]) suffix. 1637c478bd9Sstevel@tonic-gate 1647c478bd9Sstevel@tonic-gateThe only time you shouldn't use BUILDPO.msgfiles as the preferred means of 165f808c858Srafextracting messages is when you're extracting them from shell scripts; in 1667c478bd9Sstevel@tonic-gatethat case, you can use the BUILDPO.pofiles macro as explained below. 1677c478bd9Sstevel@tonic-gate 1687c478bd9Sstevel@tonic-gateTo build a message catalog from other message catalogs, or from source files 1697c478bd9Sstevel@tonic-gatethat include shell scripts, use the BUILDPO.pofiles macro: 1707c478bd9Sstevel@tonic-gate 1717c478bd9Sstevel@tonic-gate include ../Makefile.lib 1727c478bd9Sstevel@tonic-gate 1737c478bd9Sstevel@tonic-gate SUBDIRS = $(MACH) 1747c478bd9Sstevel@tonic-gate 1757c478bd9Sstevel@tonic-gate POFILE = libfoo.po 1767c478bd9Sstevel@tonic-gate POFILES = $(SUBDIRS:%=%/_%.po) 1777c478bd9Sstevel@tonic-gate 1787c478bd9Sstevel@tonic-gate _msg := TARGET = _msg 1797c478bd9Sstevel@tonic-gate 1807c478bd9Sstevel@tonic-gate # ... 1817c478bd9Sstevel@tonic-gate 1827c478bd9Sstevel@tonic-gate $(POFILE): $(POFILES) 1837c478bd9Sstevel@tonic-gate $(BUILDPO.pofiles) 1847c478bd9Sstevel@tonic-gate 1857c478bd9Sstevel@tonic-gate _msg: $(MSGDOMAINPOFILE) 1867c478bd9Sstevel@tonic-gate 1877c478bd9Sstevel@tonic-gate include $(SRC)/Makefile.msg.targ 1887c478bd9Sstevel@tonic-gate 1897c478bd9Sstevel@tonic-gateThe Makefile above would work in conjunction with the following in its 1907c478bd9Sstevel@tonic-gatesubdirectories' Makefiles: 1917c478bd9Sstevel@tonic-gate 1927c478bd9Sstevel@tonic-gate POFILE = _thissubdir.po 1937c478bd9Sstevel@tonic-gate MSGFILES = $(OBJECTS:%.o=%.i) 1947c478bd9Sstevel@tonic-gate 1957c478bd9Sstevel@tonic-gate $(POFILE): $(MSGFILES) 1967c478bd9Sstevel@tonic-gate $(BUILDPO.msgfiles) 1977c478bd9Sstevel@tonic-gate 1987c478bd9Sstevel@tonic-gate _msg: $(POFILE) 1997c478bd9Sstevel@tonic-gate 2007c478bd9Sstevel@tonic-gate include $(SRC)/Makefile.msg.targ 2017c478bd9Sstevel@tonic-gate 2027c478bd9Sstevel@tonic-gateSince this POFILE will be combined with those in other subdirectories by the 2037c478bd9Sstevel@tonic-gateparent Makefile and that merged file will be installed into the proto area 2047c478bd9Sstevel@tonic-gatevia MSGDOMAINPOFILE, there is no need to use MSGDOMAINPOFILE in this Makefile 2057c478bd9Sstevel@tonic-gate(in fact, using it would lead to duplicate messages in the catalog). 2067c478bd9Sstevel@tonic-gate 2077c478bd9Sstevel@tonic-gateWhen using any of these targets, keep in mind that other macros, like 2087c478bd9Sstevel@tonic-gateXGETFLAGS and TEXT_DOMAIN may also be set in your Makefile to override or 2097c478bd9Sstevel@tonic-gateaugment the defaults provided in higher-level Makefiles. 2107c478bd9Sstevel@tonic-gate 2117c478bd9Sstevel@tonic-gateAs previously mentioned, you should defer all ISA-specific targets to your 2127c478bd9Sstevel@tonic-gateISA-specific Makefiles. You can do this by: 2137c478bd9Sstevel@tonic-gate 2147c478bd9Sstevel@tonic-gate 1. Setting SUBDIRS to the list of directories to descend into: 2157c478bd9Sstevel@tonic-gate 2167c478bd9Sstevel@tonic-gate SUBDIRS = $(MACH) 2177c478bd9Sstevel@tonic-gate 2187c478bd9Sstevel@tonic-gate Note that if your library is also built 64-bit, then you should 2197c478bd9Sstevel@tonic-gate also specify 2207c478bd9Sstevel@tonic-gate 2217c478bd9Sstevel@tonic-gate $(BUILD64)SUBDIRS += $(MACH64) 2227c478bd9Sstevel@tonic-gate 2237c478bd9Sstevel@tonic-gate so that SUBDIRS contains $(MACH64) if and only if you're compiling 2247c478bd9Sstevel@tonic-gate on a 64-bit ISA. 2257c478bd9Sstevel@tonic-gate 2267c478bd9Sstevel@tonic-gate 2. Providing a common "descend into SUBDIRS" rule: 2277c478bd9Sstevel@tonic-gate 228f808c858Sraf $(SUBDIRS): FRC 2297c478bd9Sstevel@tonic-gate @cd $@; pwd; $(MAKE) $(TARGET) 2307c478bd9Sstevel@tonic-gate 2317c478bd9Sstevel@tonic-gate FRC: 2327c478bd9Sstevel@tonic-gate 2337c478bd9Sstevel@tonic-gate 3. Providing a collection of conditional assignments that set TARGET 2347c478bd9Sstevel@tonic-gate appropriately: 2357c478bd9Sstevel@tonic-gate 2367c478bd9Sstevel@tonic-gate all := TARGET= all 2377c478bd9Sstevel@tonic-gate clean := TARGET= clean 2387c478bd9Sstevel@tonic-gate clobber := TARGET= clobber 2397c478bd9Sstevel@tonic-gate install := TARGET= install 2407c478bd9Sstevel@tonic-gate 2417c478bd9Sstevel@tonic-gate The order doesn't matter, but alphabetical is preferable. 2427c478bd9Sstevel@tonic-gate 2437c478bd9Sstevel@tonic-gate 4. Having the aforementioned targets depend on SUBDIRS: 2447c478bd9Sstevel@tonic-gate 245241c90a0SRichard Lowe all clean clobber install: $(SUBDIRS) 2467c478bd9Sstevel@tonic-gate 247f808c858Sraf The `all' target must be listed first so that make uses it as the 248f808c858Sraf default target; the others might as well be listed alphabetically. 2497c478bd9Sstevel@tonic-gate 2507c478bd9Sstevel@tonic-gateAs an example of how all of this goes together, here's libinetutil's 251f808c858Sraftop-level library Makefile (license notice and copyright omitted): 2527c478bd9Sstevel@tonic-gate 253f808c858Sraf include ../Makefile.lib 2547c478bd9Sstevel@tonic-gate 255f808c858Sraf HDRS = libinetutil.h 256f808c858Sraf HDRDIR = common 257f808c858Sraf SUBDIRS = $(MACH) 258f808c858Sraf $(BUILD64)SUBDIRS += $(MACH64) 2597c478bd9Sstevel@tonic-gate 260f808c858Sraf all := TARGET = all 261f808c858Sraf clean := TARGET = clean 262f808c858Sraf clobber := TARGET = clobber 263f808c858Sraf install := TARGET = install 2647c478bd9Sstevel@tonic-gate 265f808c858Sraf .KEEP_STATE: 2667c478bd9Sstevel@tonic-gate 267241c90a0SRichard Lowe all clean clobber install: $(SUBDIRS) 2687c478bd9Sstevel@tonic-gate 269f808c858Sraf install_h: $(ROOTHDRS) 2707c478bd9Sstevel@tonic-gate 271f808c858Sraf check: $(CHECKHDRS) 2727c478bd9Sstevel@tonic-gate 273f808c858Sraf $(SUBDIRS): FRC 274f808c858Sraf @cd $@; pwd; $(MAKE) $(TARGET) 2757c478bd9Sstevel@tonic-gate 276f808c858Sraf FRC: 2777c478bd9Sstevel@tonic-gate 278f808c858Sraf include ../Makefile.targ 2797c478bd9Sstevel@tonic-gate 2807c478bd9Sstevel@tonic-gateThe Common Makefile 2817c478bd9Sstevel@tonic-gate------------------- 2827c478bd9Sstevel@tonic-gate 2837c478bd9Sstevel@tonic-gateIn concept, your common Makefile should contain all of the rules and 2847c478bd9Sstevel@tonic-gatedefinitions that are the same on all ISAs. However, for reasons of 2857c478bd9Sstevel@tonic-gatemaintainability and cleanliness, you're encouraged to place even 2867c478bd9Sstevel@tonic-gateISA-dependent rules and definitions, as long you express them in an 287f808c858SrafISA-independent way (e.g., by using $(MACH), $(TARGETMACH), and their kin). 288f808c858Sraf(TARGETMACH is the same as MACH for 32-bit targets, and the same as MACH64 289f808c858Sraffor 64-bit targets). 2907c478bd9Sstevel@tonic-gate 2917c478bd9Sstevel@tonic-gateThe common Makefile can be conceptually split up into four sections: 2927c478bd9Sstevel@tonic-gate 2937c478bd9Sstevel@tonic-gate 1. A copyright and comments section. Please see the prototype 2947c478bd9Sstevel@tonic-gate files in usr/src/prototypes for examples of how to format the 2957c478bd9Sstevel@tonic-gate copyright message properly. For brevity and clarity, this 2967c478bd9Sstevel@tonic-gate section has been omitted from the examples shown here. 2977c478bd9Sstevel@tonic-gate 2987c478bd9Sstevel@tonic-gate 2. A list of macros that must be defined prior to the inclusion of 2997c478bd9Sstevel@tonic-gate Makefile.lib. This section is conceptually terminated by the 3007c478bd9Sstevel@tonic-gate inclusion of Makefile.lib, followed, if necessary, by the 3017c478bd9Sstevel@tonic-gate inclusion of Makefile.rootfs (only if the library is to be 3027c478bd9Sstevel@tonic-gate installed in /lib rather than the default /usr/lib). 3037c478bd9Sstevel@tonic-gate 3047c478bd9Sstevel@tonic-gate 3. A list of macros that need not be defined prior to the inclusion 3057c478bd9Sstevel@tonic-gate of Makefile.lib (or which must be defined following the inclusion 3067c478bd9Sstevel@tonic-gate of Makefile.lib, to override or augment its definitions). This 3077c478bd9Sstevel@tonic-gate section is conceptually terminated by the .KEEP_STATE directive. 3087c478bd9Sstevel@tonic-gate 3097c478bd9Sstevel@tonic-gate 4. A list of targets. 3107c478bd9Sstevel@tonic-gate 3117c478bd9Sstevel@tonic-gateThe first section is self-explanatory. The second typically consists of the 3127c478bd9Sstevel@tonic-gatefollowing macros: 3137c478bd9Sstevel@tonic-gate 3147c478bd9Sstevel@tonic-gate LIBRARY 3157c478bd9Sstevel@tonic-gate 3167c478bd9Sstevel@tonic-gate Set to the name of the static version of your library, such 3177c478bd9Sstevel@tonic-gate as `libinetutil.a'. You should always specify the `.a' suffix, 3187c478bd9Sstevel@tonic-gate since pattern-matching rules in higher-level Makefiles rely on it, 3197c478bd9Sstevel@tonic-gate even though static libraries are not normally built in ON, and 3207c478bd9Sstevel@tonic-gate are never installed in the proto area. Note that the LIBS macro 3217c478bd9Sstevel@tonic-gate (described below) controls the types of libraries that are built 3227c478bd9Sstevel@tonic-gate when building your library. 3237c478bd9Sstevel@tonic-gate 3247c478bd9Sstevel@tonic-gate If you are building a loadable module (i.e., a shared object that 3257c478bd9Sstevel@tonic-gate is only linked at runtime with dlopen(3dl)), specify the name of 3267c478bd9Sstevel@tonic-gate the loadable module with a `.a' suffix, such as `devfsadm_mod.a'. 3277c478bd9Sstevel@tonic-gate 3287c478bd9Sstevel@tonic-gate VERS 3297c478bd9Sstevel@tonic-gate 3307c478bd9Sstevel@tonic-gate Set to the version of your shared library, such as `.1'. You 3317c478bd9Sstevel@tonic-gate actually do not need to set this prior to the inclusion of 3327c478bd9Sstevel@tonic-gate Makefile.lib, but it is good practice to do so since VERS and 3337c478bd9Sstevel@tonic-gate LIBRARY are so closely related. 3347c478bd9Sstevel@tonic-gate 3357c478bd9Sstevel@tonic-gate OBJECTS 3367c478bd9Sstevel@tonic-gate 3377c478bd9Sstevel@tonic-gate Set to the list of object files contained in your library, such as 3387c478bd9Sstevel@tonic-gate `a.o b.o'. Usually, this will be the same as your library's source 3397c478bd9Sstevel@tonic-gate files (except with .o extensions), but if your library compiles 3407c478bd9Sstevel@tonic-gate source files outside of the library directory itself, it will 3417c478bd9Sstevel@tonic-gate differ. We'll see an example of this with libinetutil. 3427c478bd9Sstevel@tonic-gate 3437c478bd9Sstevel@tonic-gateThe third section typically consists of the following macros: 3447c478bd9Sstevel@tonic-gate 3457c478bd9Sstevel@tonic-gate LIBS 3467c478bd9Sstevel@tonic-gate 3477c478bd9Sstevel@tonic-gate Set to the list of the types of libraries to build when building 3487c478bd9Sstevel@tonic-gate your library. For dynamic libraries, you should set this to 349241c90a0SRichard Lowe `$(DYNLIB)' so that a dynamic library is built. 3507c478bd9Sstevel@tonic-gate 3517c478bd9Sstevel@tonic-gate If your library needs to be built as a static library (typically 3527c478bd9Sstevel@tonic-gate to be used in other parts of the build), you should set LIBS to 3537c478bd9Sstevel@tonic-gate `$(LIBRARY)'. However, you should do this only when absolutely 3547c478bd9Sstevel@tonic-gate necessary, and you must *never* ship static libraries to customers. 3557c478bd9Sstevel@tonic-gate 3567c478bd9Sstevel@tonic-gate ROOTLIBDIR (if your library installs to a nonstandard directory) 3577c478bd9Sstevel@tonic-gate 3587c478bd9Sstevel@tonic-gate Set to the directory your 32-bit shared objects will install into 3597c478bd9Sstevel@tonic-gate with the standard $(ROOTxxx) macros. Since this defaults to 3607c478bd9Sstevel@tonic-gate $(ROOT)/usr/lib ($(ROOT)/lib if you included Makefile.rootfs), 3617c478bd9Sstevel@tonic-gate you usually do not need to set this. 3627c478bd9Sstevel@tonic-gate 3637c478bd9Sstevel@tonic-gate ROOTLIBDIR64 (if your library installs to a nonstandard directory) 3647c478bd9Sstevel@tonic-gate 3657c478bd9Sstevel@tonic-gate Set to the directory your 64-bit shared objects will install into 3667c478bd9Sstevel@tonic-gate with the standard $(ROOTxxx64) macros. Since this defaults to 3677c478bd9Sstevel@tonic-gate $(ROOT)/usr/lib/$(MACH64) ($(ROOT)/lib/$(MACH64) if you included 3687c478bd9Sstevel@tonic-gate Makefile.rootfs), you usually do not need to set this. 3697c478bd9Sstevel@tonic-gate 3707c478bd9Sstevel@tonic-gate SRCDIR 3717c478bd9Sstevel@tonic-gate 3727c478bd9Sstevel@tonic-gate Set to the directory containing your library's source files, such 3737c478bd9Sstevel@tonic-gate as `../common'. Because this Makefile is actually included from 3747c478bd9Sstevel@tonic-gate your ISA-specific Makefiles, make sure you specify the directory 3757c478bd9Sstevel@tonic-gate relative to your library's <isa> directory. 3767c478bd9Sstevel@tonic-gate 3777c478bd9Sstevel@tonic-gate SRCS (if necessary) 3787c478bd9Sstevel@tonic-gate 3797c478bd9Sstevel@tonic-gate Set to the list of source files required to build your library. 3807c478bd9Sstevel@tonic-gate This defaults to $(OBJECTS:%.o=$(SRCDIR)/%.c) in Makefile.lib, so 3817c478bd9Sstevel@tonic-gate you only need to set this when source files from directories other 3827c478bd9Sstevel@tonic-gate than SRCDIR are needed. Keep in mind that SRCS should be set to a 3837c478bd9Sstevel@tonic-gate list of source file *pathnames*, not just a list of filenames. 3847c478bd9Sstevel@tonic-gate 3857c478bd9Sstevel@tonic-gate 3867c478bd9Sstevel@tonic-gate LDLIBS 3877c478bd9Sstevel@tonic-gate 3887c478bd9Sstevel@tonic-gate Appended with the list of libraries and library directories needed 3897c478bd9Sstevel@tonic-gate to build your library; minimally "-lc". Note that this should 3907c478bd9Sstevel@tonic-gate *never* be set, since that will inadvertently clear the library 3917c478bd9Sstevel@tonic-gate search path, causing the linker to look in the wrong place for 3927c478bd9Sstevel@tonic-gate the libraries. 3937c478bd9Sstevel@tonic-gate 394f808c858Sraf MAPFILES (if necessary) 3957c478bd9Sstevel@tonic-gate 396f808c858Sraf Set to the list of mapfiles used to link each ISA-specific version 397f808c858Sraf of your library. This defaults to `$(SRCDIR)/mapfile-vers' in 398f808c858Sraf Makefile.lib, so you only need to change this if you have additional 399f808c858Sraf mapfiles or your mapfile doesn't follow the standard naming 400f808c858Sraf convention. If you have supplemental ISA-dependent mapfiles that 401f808c858Sraf reside in the respective <isa> directories, you can augment 402f808c858Sraf MAPFILES like this: 4037c478bd9Sstevel@tonic-gate 404f808c858Sraf MAPFILES += mapfile-vers 4057c478bd9Sstevel@tonic-gate 4067c478bd9Sstevel@tonic-gate CPPFLAGS (if necessary) 4077c478bd9Sstevel@tonic-gate 4087c478bd9Sstevel@tonic-gate Appended with any flags that need to be passed to the C 409241c90a0SRichard Lowe preprocessor (typically -D and -I flags). When compiling MT-safe 410241c90a0SRichard Lowe code, CPPFLAGS *must* include -D_REENTRANT. When compiling large 411241c90a0SRichard Lowe file aware code, CPPFLAGS *must* include -D_FILE_OFFSET_BITS=64. 4127c478bd9Sstevel@tonic-gate 4137c478bd9Sstevel@tonic-gate CFLAGS 4147c478bd9Sstevel@tonic-gate 4157c478bd9Sstevel@tonic-gate Appended with any flags that need to be passed to the C compiler. 4167c478bd9Sstevel@tonic-gate Minimally, append `$(CCVERBOSE)'. Keep in mind that you should 4177c478bd9Sstevel@tonic-gate add any C preprocessor flags to CPPFLAGS, not CFLAGS. 4187c478bd9Sstevel@tonic-gate 4197c478bd9Sstevel@tonic-gate CFLAGS64 (if necessary) 4207c478bd9Sstevel@tonic-gate 4217c478bd9Sstevel@tonic-gate Appended with any flags that need to be passed to the C compiler 4227c478bd9Sstevel@tonic-gate when compiling 64-bit code. Since all 64-bit code is compiled 4237c478bd9Sstevel@tonic-gate $(CCVERBOSE), you usually do not need to modify CFLAGS64. 4247c478bd9Sstevel@tonic-gate 42578a2e113SAndy Fiddaman COPTFLAG (if necessary) 4267c478bd9Sstevel@tonic-gate 4277c478bd9Sstevel@tonic-gate Set to control the optimization level used by the C compiler when 4287c478bd9Sstevel@tonic-gate compiling 32-bit code. You should only set this if absolutely 4297c478bd9Sstevel@tonic-gate necessary, and it should only contain optimization-related 4307c478bd9Sstevel@tonic-gate settings (or -g). 4317c478bd9Sstevel@tonic-gate 43278a2e113SAndy Fiddaman COPTFLAG64 (if necessary) 4337c478bd9Sstevel@tonic-gate 4347c478bd9Sstevel@tonic-gate Set to control the optimization level used by the C compiler when 4357c478bd9Sstevel@tonic-gate compiling 64-bit code. You should only set this if absolutely 4367c478bd9Sstevel@tonic-gate necessary, and it should only contain optimization-related 4377c478bd9Sstevel@tonic-gate settings (or -g). 4387c478bd9Sstevel@tonic-gate 439cd61ae21SRichard Lowe COMPATLINKS (if necessary) 440cd61ae21SRichard Lowe 441cd61ae21SRichard Lowe Set to a list of symbolic links that should also be provided for 442cd61ae21SRichard Lowe this library. Each should also have a target-specific assignment to 443cd61ae21SRichard Lowe COMPATLINKTARGET stating what the target of each link should be 444cd61ae21SRichard Lowe 445cd61ae21SRichard Lowe COMPATLINKS= usr/lib/libfoo.so 446cd61ae21SRichard Lowe $(ROOT)/usr/lib/libfoo.so := COMPATLINKTARGET= libbar.so 447cd61ae21SRichard Lowe 448cd61ae21SRichard Lowe COMPATLINKS64 (if necessary) 449cd61ae21SRichard Lowe 450cd61ae21SRichard Lowe As COMPATLINKS, above, for 64bit objects. 451cd61ae21SRichard Lowe 4527c478bd9Sstevel@tonic-gateOf course, you may use other macros as necessary. 4537c478bd9Sstevel@tonic-gate 4547c478bd9Sstevel@tonic-gateThe fourth section typically consists of the following targets: 4557c478bd9Sstevel@tonic-gate 4567c478bd9Sstevel@tonic-gate all 4577c478bd9Sstevel@tonic-gate 4587c478bd9Sstevel@tonic-gate Build all of the types of the libraries named by LIBS. Must always 4597c478bd9Sstevel@tonic-gate be the first real target in common Makefile. Since the 4607c478bd9Sstevel@tonic-gate higher-level Makefiles already contain rules to build all of the 4617c478bd9Sstevel@tonic-gate different types of libraries, you can usually just specify 4627c478bd9Sstevel@tonic-gate 4637c478bd9Sstevel@tonic-gate all: $(LIBS) 4647c478bd9Sstevel@tonic-gate 4657c478bd9Sstevel@tonic-gate though it should be listed as an empty target if LIBS is set by your 4667c478bd9Sstevel@tonic-gate ISA-specific Makefiles (see above). 4677c478bd9Sstevel@tonic-gate 4687c478bd9Sstevel@tonic-gate 4697c478bd9Sstevel@tonic-gateConspicuously absent from this section are the `clean' and `clobber' targets. 4707c478bd9Sstevel@tonic-gateThese targets are already provided by lib/Makefile.targ and thus should not 4717c478bd9Sstevel@tonic-gatebe provided by your common Makefile. Instead, your common Makefile should 4727c478bd9Sstevel@tonic-gatelist any additional files to remove during a `clean' and `clobber' by 4737c478bd9Sstevel@tonic-gateappending to the CLEANFILES and CLOBBERFILES macros. 4747c478bd9Sstevel@tonic-gate 4757c478bd9Sstevel@tonic-gateOnce again, here's libinetutil's common Makefile, which shows how many of 4767c478bd9Sstevel@tonic-gatethese directives go together. Note that Makefile.rootfs is included to 4777c478bd9Sstevel@tonic-gatecause libinetutil.so.1 to be installed in /lib rather than /usr/lib: 4787c478bd9Sstevel@tonic-gate 479f808c858Sraf LIBRARY = libinetutil.a 480f808c858Sraf VERS = .1 481f808c858Sraf OBJECTS = octet.o inetutil4.o ifspec.o ifaddrlist.o eh.o tq.o 4827c478bd9Sstevel@tonic-gate 483f808c858Sraf include ../../Makefile.lib 484f808c858Sraf include ../../Makefile.rootfs 4857c478bd9Sstevel@tonic-gate 486241c90a0SRichard Lowe LIBS = $(DYNLIB) 4877c478bd9Sstevel@tonic-gate 488f808c858Sraf SRCDIR = ../common 489f808c858Sraf COMDIR = $(SRC)/common/net/dhcp 490f808c858Sraf SRCS = $(COMDIR)/octet.c $(SRCDIR)/inetutil4.c \ 491f808c858Sraf $(SRCDIR)/ifspec.c $(SRCDIR)/eh.c $(SRCDIR)/tq.c \ 492f808c858Sraf $(SRCDIR)/ifaddrlist.c 4937c478bd9Sstevel@tonic-gate 494f808c858Sraf LDLIBS += -lsocket -lc 4957c478bd9Sstevel@tonic-gate 496f808c858Sraf CFLAGS += $(CCVERBOSE) 497f808c858Sraf CPPFLAGS += -I$(SRCDIR) 4987c478bd9Sstevel@tonic-gate 499f808c858Sraf .KEEP_STATE: 5007c478bd9Sstevel@tonic-gate 501f808c858Sraf all: $(LIBS) 502f808c858Sraf 503f808c858Sraf pics/%.o: $(COMDIR)/%.c 504f808c858Sraf $(COMPILE.c) -o $@ $< 505f808c858Sraf $(POST_PROCESS_O) 5067c478bd9Sstevel@tonic-gate 507f808c858Sraf include ../../Makefile.targ 508f808c858Sraf 509f808c858SrafThe mapfile for libinetutil is named `mapfile-vers' and resides in $(SRCDIR), 510f808c858Srafso the MAPFILES definition is omitted, defaulting to $(SRCDIR)/mapfile-vers. 5117c478bd9Sstevel@tonic-gate 5127c478bd9Sstevel@tonic-gateNote that for libinetutil, not all of the object files come from SRCDIR. To 5137c478bd9Sstevel@tonic-gatesupport this, an alternate source file directory named COMDIR is defined, and 5147c478bd9Sstevel@tonic-gatethe source files listed in SRCS are specified using both COMDIR and SRCDIR. 5157c478bd9Sstevel@tonic-gateAdditionally, a special build rule is provided to build object files from the 5167c478bd9Sstevel@tonic-gatesources in COMDIR; the rule uses COMPILE.c and POST_PROCESS_O so that any 5177c478bd9Sstevel@tonic-gatechanges to the compilation and object-post-processing phases will be 5187c478bd9Sstevel@tonic-gateautomatically picked up. 5197c478bd9Sstevel@tonic-gate 5207c478bd9Sstevel@tonic-gateThe ISA-Specific Makefiles 5217c478bd9Sstevel@tonic-gate-------------------------- 5227c478bd9Sstevel@tonic-gate 5237c478bd9Sstevel@tonic-gateAs the name implies, your ISA-specific Makefiles should contain macros and 5247c478bd9Sstevel@tonic-gaterules that cannot be expressed in an ISA-independent way. Usually, the only 5257c478bd9Sstevel@tonic-gaterule you will need to put here is `install', which has different dependencies 5267c478bd9Sstevel@tonic-gatefor 32-bit and 64-bit libraries. For instance, here are the ISA-specific 5277c478bd9Sstevel@tonic-gateMakefiles for libinetutil: 5287c478bd9Sstevel@tonic-gate 5297c478bd9Sstevel@tonic-gate sparc/Makefile: 5307c478bd9Sstevel@tonic-gate 5317c478bd9Sstevel@tonic-gate include ../Makefile.com 5327c478bd9Sstevel@tonic-gate 533241c90a0SRichard Lowe install: all $(ROOTLIBS) $(ROOTLINKS) 5347c478bd9Sstevel@tonic-gate 5357c478bd9Sstevel@tonic-gate sparcv9/Makefile: 5367c478bd9Sstevel@tonic-gate 5377c478bd9Sstevel@tonic-gate include ../Makefile.com 5387c478bd9Sstevel@tonic-gate include ../../Makefile.lib.64 5397c478bd9Sstevel@tonic-gate 5407c478bd9Sstevel@tonic-gate install: all $(ROOTLIBS64) $(ROOTLINKS64) 5417c478bd9Sstevel@tonic-gate 5427c478bd9Sstevel@tonic-gate i386/Makefile: 5437c478bd9Sstevel@tonic-gate 5447c478bd9Sstevel@tonic-gate include ../Makefile.com 5457c478bd9Sstevel@tonic-gate 546241c90a0SRichard Lowe install: all $(ROOTLIBS) $(ROOTLINKS) 5477c478bd9Sstevel@tonic-gate 548f808c858Sraf amd64/Makefile: 549f808c858Sraf 550f808c858Sraf include ../Makefile.com 551f808c858Sraf include ../../Makefile.lib.64 552f808c858Sraf 553f808c858Sraf install: all $(ROOTLIBS64) $(ROOTLINKS64) 554f808c858Sraf 555cd61ae21SRichard LoweIf you included Makefile.rootfs to install your library into /lib, you should 556cd61ae21SRichard Lowealso add $(ROOTCOMPATLINKS) and $(ROOTCOMPATLINKS64) to your install: target 557cd61ae21SRichard Loweto install compatibility symlinks into /usr/lib. 558cd61ae21SRichard Lowe 5597c478bd9Sstevel@tonic-gateObserve that there is no .KEEP_STATE directive in these Makefiles, since all 5607c478bd9Sstevel@tonic-gateof these Makefiles include libinetutil/Makefile.com, and it already has a 561f808c858Sraf.KEEP_STATE directive. Also, note that the 64-bit Makefiles also include 5627c478bd9Sstevel@tonic-gateMakefile.lib.64, which overrides some of the definitions contained in the 5637c478bd9Sstevel@tonic-gatehigher level Makefiles included by the common Makefile so that 64-bit 5647c478bd9Sstevel@tonic-gatecompiles work correctly. 5657c478bd9Sstevel@tonic-gate 5667c478bd9Sstevel@tonic-gateCTF Data in Libraries 5677c478bd9Sstevel@tonic-gate--------------------- 5687c478bd9Sstevel@tonic-gate 569f808c858SrafBy default, all position-independent objects are built with CTF data using 5707c478bd9Sstevel@tonic-gatectfconvert, which is then merged together using ctfmerge when the shared 5717c478bd9Sstevel@tonic-gateobject is built. All C-source objects processed via ctfmerge need to be 5727c478bd9Sstevel@tonic-gateprocessed via ctfconvert or the build will fail. Objects built from non-C 5737c478bd9Sstevel@tonic-gatesources (such as assembly or C++) are silently ignored for CTF processing. 5747c478bd9Sstevel@tonic-gate 5757c478bd9Sstevel@tonic-gateFilter libraries that have no source files will need to explicitly disable 5767c478bd9Sstevel@tonic-gateCTF by setting CTFMERGE_LIB to ":"; see libw/Makefile.com for an example. 5777c478bd9Sstevel@tonic-gate 5787c478bd9Sstevel@tonic-gateMore Information 5797c478bd9Sstevel@tonic-gate---------------- 5807c478bd9Sstevel@tonic-gate 5817c478bd9Sstevel@tonic-gateOther issues and questions will undoubtedly arise while you work on your 5827c478bd9Sstevel@tonic-gatelibrary's Makefiles. To help in this regard, a number of libraries of 5837c478bd9Sstevel@tonic-gatevarying complexity have been updated to follow the guidelines and practices 5847c478bd9Sstevel@tonic-gateoutlined in this document: 5857c478bd9Sstevel@tonic-gate 5867c478bd9Sstevel@tonic-gate lib/libdhcputil 5877c478bd9Sstevel@tonic-gate 5887c478bd9Sstevel@tonic-gate Example of a simple 32-bit only library. 5897c478bd9Sstevel@tonic-gate 5907c478bd9Sstevel@tonic-gate lib/libdhcpagent 5917c478bd9Sstevel@tonic-gate 59278a2e113SAndy Fiddaman Example of a simple 32/64-bit library that obtains its sources 5937c478bd9Sstevel@tonic-gate from multiple directories. 5947c478bd9Sstevel@tonic-gate 595*15f90b02SGarrett D'Amore lib/nametoaddr/straddr 5967c478bd9Sstevel@tonic-gate 5977c478bd9Sstevel@tonic-gate Example of a simple loadable module. 5987c478bd9Sstevel@tonic-gate 5997c478bd9Sstevel@tonic-gate lib/libipmp 6007c478bd9Sstevel@tonic-gate 6017c478bd9Sstevel@tonic-gate Example of a simple library that builds a message catalog. 6027c478bd9Sstevel@tonic-gate 6037c478bd9Sstevel@tonic-gate lib/libdhcpsvc 6047c478bd9Sstevel@tonic-gate 6057c478bd9Sstevel@tonic-gate Example of a Makefile hierarchy for a library and a collection 6067c478bd9Sstevel@tonic-gate of related pluggable modules. 6077c478bd9Sstevel@tonic-gate 6087c478bd9Sstevel@tonic-gate lib/lvm 6097c478bd9Sstevel@tonic-gate 6107c478bd9Sstevel@tonic-gate Example of a Makefile hierarchy for a collection of related 6117c478bd9Sstevel@tonic-gate libraries and pluggable modules. 6127c478bd9Sstevel@tonic-gate 6137c478bd9Sstevel@tonic-gate Also an example of a Makefile hierarchy that supports the 6147c478bd9Sstevel@tonic-gate _dc target for domain and category specific messages. 6157c478bd9Sstevel@tonic-gate 6167c478bd9Sstevel@tonic-gateOf course, if you still have questions, please do not hesitate to send email 6177c478bd9Sstevel@tonic-gateto the ON gatekeepers. 618