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