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