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