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 241 The order doesn't matter, but alphabetical is preferable. 242 243 4. Having the aforementioned targets depend on SUBDIRS: 244 245 all clean clobber install: $(SUBDIRS) 246 247 The `all' target must be listed first so that make uses it as the 248 default target; the others might as well be listed alphabetically. 249 250As an example of how all of this goes together, here's libinetutil's 251top-level library Makefile (license notice and copyright omitted): 252 253 include ../Makefile.lib 254 255 HDRS = libinetutil.h 256 HDRDIR = common 257 SUBDIRS = $(MACH) 258 $(BUILD64)SUBDIRS += $(MACH64) 259 260 all := TARGET = all 261 clean := TARGET = clean 262 clobber := TARGET = clobber 263 install := TARGET = install 264 265 .KEEP_STATE: 266 267 all clean clobber install: $(SUBDIRS) 268 269 install_h: $(ROOTHDRS) 270 271 check: $(CHECKHDRS) 272 273 $(SUBDIRS): FRC 274 @cd $@; pwd; $(MAKE) $(TARGET) 275 276 FRC: 277 278 include ../Makefile.targ 279 280The Common Makefile 281------------------- 282 283In concept, your common Makefile should contain all of the rules and 284definitions that are the same on all ISAs. However, for reasons of 285maintainability and cleanliness, you're encouraged to place even 286ISA-dependent rules and definitions, as long you express them in an 287ISA-independent way (e.g., by using $(MACH), $(TARGETMACH), and their kin). 288(TARGETMACH is the same as MACH for 32-bit targets, and the same as MACH64 289for 64-bit targets). 290 291The common Makefile can be conceptually split up into four sections: 292 293 1. A copyright and comments section. Please see the prototype 294 files in usr/src/prototypes for examples of how to format the 295 copyright message properly. For brevity and clarity, this 296 section has been omitted from the examples shown here. 297 298 2. A list of macros that must be defined prior to the inclusion of 299 Makefile.lib. This section is conceptually terminated by the 300 inclusion of Makefile.lib, followed, if necessary, by the 301 inclusion of Makefile.rootfs (only if the library is to be 302 installed in /lib rather than the default /usr/lib). 303 304 3. A list of macros that need not be defined prior to the inclusion 305 of Makefile.lib (or which must be defined following the inclusion 306 of Makefile.lib, to override or augment its definitions). This 307 section is conceptually terminated by the .KEEP_STATE directive. 308 309 4. A list of targets. 310 311The first section is self-explanatory. The second typically consists of the 312following macros: 313 314 LIBRARY 315 316 Set to the name of the static version of your library, such 317 as `libinetutil.a'. You should always specify the `.a' suffix, 318 since pattern-matching rules in higher-level Makefiles rely on it, 319 even though static libraries are not normally built in ON, and 320 are never installed in the proto area. Note that the LIBS macro 321 (described below) controls the types of libraries that are built 322 when building your library. 323 324 If you are building a loadable module (i.e., a shared object that 325 is only linked at runtime with dlopen(3dl)), specify the name of 326 the loadable module with a `.a' suffix, such as `devfsadm_mod.a'. 327 328 VERS 329 330 Set to the version of your shared library, such as `.1'. You 331 actually do not need to set this prior to the inclusion of 332 Makefile.lib, but it is good practice to do so since VERS and 333 LIBRARY are so closely related. 334 335 OBJECTS 336 337 Set to the list of object files contained in your library, such as 338 `a.o b.o'. Usually, this will be the same as your library's source 339 files (except with .o extensions), but if your library compiles 340 source files outside of the library directory itself, it will 341 differ. We'll see an example of this with libinetutil. 342 343The third section typically consists of the following macros: 344 345 LIBS 346 347 Set to the list of the types of libraries to build when building 348 your library. For dynamic libraries, you should set this to 349 `$(DYNLIB)' so that a dynamic library is built. 350 351 If your library needs to be built as a static library (typically 352 to be used in other parts of the build), you should set LIBS to 353 `$(LIBRARY)'. However, you should do this only when absolutely 354 necessary, and you must *never* ship static libraries to customers. 355 356 ROOTLIBDIR (if your library installs to a nonstandard directory) 357 358 Set to the directory your 32-bit shared objects will install into 359 with the standard $(ROOTxxx) macros. Since this defaults to 360 $(ROOT)/usr/lib ($(ROOT)/lib if you included Makefile.rootfs), 361 you usually do not need to set this. 362 363 ROOTLIBDIR64 (if your library installs to a nonstandard directory) 364 365 Set to the directory your 64-bit shared objects will install into 366 with the standard $(ROOTxxx64) macros. Since this defaults to 367 $(ROOT)/usr/lib/$(MACH64) ($(ROOT)/lib/$(MACH64) if you included 368 Makefile.rootfs), you usually do not need to set this. 369 370 SRCDIR 371 372 Set to the directory containing your library's source files, such 373 as `../common'. Because this Makefile is actually included from 374 your ISA-specific Makefiles, make sure you specify the directory 375 relative to your library's <isa> directory. 376 377 SRCS (if necessary) 378 379 Set to the list of source files required to build your library. 380 This defaults to $(OBJECTS:%.o=$(SRCDIR)/%.c) in Makefile.lib, so 381 you only need to set this when source files from directories other 382 than SRCDIR are needed. Keep in mind that SRCS should be set to a 383 list of source file *pathnames*, not just a list of filenames. 384 385 386 LDLIBS 387 388 Appended with the list of libraries and library directories needed 389 to build your library; minimally "-lc". Note that this should 390 *never* be set, since that will inadvertently clear the library 391 search path, causing the linker to look in the wrong place for 392 the libraries. 393 394 MAPFILES (if necessary) 395 396 Set to the list of mapfiles used to link each ISA-specific version 397 of your library. This defaults to `$(SRCDIR)/mapfile-vers' in 398 Makefile.lib, so you only need to change this if you have additional 399 mapfiles or your mapfile doesn't follow the standard naming 400 convention. If you have supplemental ISA-dependent mapfiles that 401 reside in the respective <isa> directories, you can augment 402 MAPFILES like this: 403 404 MAPFILES += mapfile-vers 405 406 CPPFLAGS (if necessary) 407 408 Appended with any flags that need to be passed to the C 409 preprocessor (typically -D and -I flags). When compiling MT-safe 410 code, CPPFLAGS *must* include -D_REENTRANT. When compiling large 411 file aware code, CPPFLAGS *must* include -D_FILE_OFFSET_BITS=64. 412 413 CFLAGS 414 415 Appended with any flags that need to be passed to the C compiler. 416 Minimally, append `$(CCVERBOSE)'. Keep in mind that you should 417 add any C preprocessor flags to CPPFLAGS, not CFLAGS. 418 419 CFLAGS64 (if necessary) 420 421 Appended with any flags that need to be passed to the C compiler 422 when compiling 64-bit code. Since all 64-bit code is compiled 423 $(CCVERBOSE), you usually do not need to modify CFLAGS64. 424 425 COPTFLAG (if necessary) 426 427 Set to control the optimization level used by the C compiler when 428 compiling 32-bit code. You should only set this if absolutely 429 necessary, and it should only contain optimization-related 430 settings (or -g). 431 432 COPTFLAG64 (if necessary) 433 434 Set to control the optimization level used by the C compiler when 435 compiling 64-bit code. You should only set this if absolutely 436 necessary, and it should only contain optimization-related 437 settings (or -g). 438 439 COMPATLINKS (if necessary) 440 441 Set to a list of symbolic links that should also be provided for 442 this library. Each should also have a target-specific assignment to 443 COMPATLINKTARGET stating what the target of each link should be 444 445 COMPATLINKS= usr/lib/libfoo.so 446 $(ROOT)/usr/lib/libfoo.so := COMPATLINKTARGET= libbar.so 447 448 COMPATLINKS64 (if necessary) 449 450 As COMPATLINKS, above, for 64bit objects. 451 452Of course, you may use other macros as necessary. 453 454The fourth section typically consists of the following targets: 455 456 all 457 458 Build all of the types of the libraries named by LIBS. Must always 459 be the first real target in common Makefile. Since the 460 higher-level Makefiles already contain rules to build all of the 461 different types of libraries, you can usually just specify 462 463 all: $(LIBS) 464 465 though it should be listed as an empty target if LIBS is set by your 466 ISA-specific Makefiles (see above). 467 468 469Conspicuously absent from this section are the `clean' and `clobber' targets. 470These targets are already provided by lib/Makefile.targ and thus should not 471be provided by your common Makefile. Instead, your common Makefile should 472list any additional files to remove during a `clean' and `clobber' by 473appending to the CLEANFILES and CLOBBERFILES macros. 474 475Once again, here's libinetutil's common Makefile, which shows how many of 476these directives go together. Note that Makefile.rootfs is included to 477cause libinetutil.so.1 to be installed in /lib rather than /usr/lib: 478 479 LIBRARY = libinetutil.a 480 VERS = .1 481 OBJECTS = octet.o inetutil4.o ifspec.o ifaddrlist.o eh.o tq.o 482 483 include ../../Makefile.lib 484 include ../../Makefile.rootfs 485 486 LIBS = $(DYNLIB) 487 488 SRCDIR = ../common 489 COMDIR = $(SRC)/common/net/dhcp 490 SRCS = $(COMDIR)/octet.c $(SRCDIR)/inetutil4.c \ 491 $(SRCDIR)/ifspec.c $(SRCDIR)/eh.c $(SRCDIR)/tq.c \ 492 $(SRCDIR)/ifaddrlist.c 493 494 LDLIBS += -lsocket -lc 495 496 CFLAGS += $(CCVERBOSE) 497 CPPFLAGS += -I$(SRCDIR) 498 499 .KEEP_STATE: 500 501 all: $(LIBS) 502 503 pics/%.o: $(COMDIR)/%.c 504 $(COMPILE.c) -o $@ $< 505 $(POST_PROCESS_O) 506 507 include ../../Makefile.targ 508 509The mapfile for libinetutil is named `mapfile-vers' and resides in $(SRCDIR), 510so the MAPFILES definition is omitted, defaulting to $(SRCDIR)/mapfile-vers. 511 512Note that for libinetutil, not all of the object files come from SRCDIR. To 513support this, an alternate source file directory named COMDIR is defined, and 514the source files listed in SRCS are specified using both COMDIR and SRCDIR. 515Additionally, a special build rule is provided to build object files from the 516sources in COMDIR; the rule uses COMPILE.c and POST_PROCESS_O so that any 517changes to the compilation and object-post-processing phases will be 518automatically picked up. 519 520The ISA-Specific Makefiles 521-------------------------- 522 523As the name implies, your ISA-specific Makefiles should contain macros and 524rules that cannot be expressed in an ISA-independent way. Usually, the only 525rule you will need to put here is `install', which has different dependencies 526for 32-bit and 64-bit libraries. For instance, here are the ISA-specific 527Makefiles for libinetutil: 528 529 sparc/Makefile: 530 531 include ../Makefile.com 532 533 install: all $(ROOTLIBS) $(ROOTLINKS) 534 535 sparcv9/Makefile: 536 537 include ../Makefile.com 538 include ../../Makefile.lib.64 539 540 install: all $(ROOTLIBS64) $(ROOTLINKS64) 541 542 i386/Makefile: 543 544 include ../Makefile.com 545 546 install: all $(ROOTLIBS) $(ROOTLINKS) 547 548 amd64/Makefile: 549 550 include ../Makefile.com 551 include ../../Makefile.lib.64 552 553 install: all $(ROOTLIBS64) $(ROOTLINKS64) 554 555If you included Makefile.rootfs to install your library into /lib, you should 556also add $(ROOTCOMPATLINKS) and $(ROOTCOMPATLINKS64) to your install: target 557to install compatibility symlinks into /usr/lib. 558 559Observe that there is no .KEEP_STATE directive in these Makefiles, since all 560of these Makefiles include libinetutil/Makefile.com, and it already has a 561.KEEP_STATE directive. Also, note that the 64-bit Makefiles also include 562Makefile.lib.64, which overrides some of the definitions contained in the 563higher level Makefiles included by the common Makefile so that 64-bit 564compiles work correctly. 565 566CTF Data in Libraries 567--------------------- 568 569By default, all position-independent objects are built with CTF data using 570ctfconvert, which is then merged together using ctfmerge when the shared 571object is built. All C-source objects processed via ctfmerge need to be 572processed via ctfconvert or the build will fail. Objects built from non-C 573sources (such as assembly or C++) are silently ignored for CTF processing. 574 575Filter libraries that have no source files will need to explicitly disable 576CTF by setting CTFMERGE_LIB to ":"; see libw/Makefile.com for an example. 577 578More Information 579---------------- 580 581Other issues and questions will undoubtedly arise while you work on your 582library's Makefiles. To help in this regard, a number of libraries of 583varying complexity have been updated to follow the guidelines and practices 584outlined in this document: 585 586 lib/libdhcputil 587 588 Example of a simple 32-bit only library. 589 590 lib/libdhcpagent 591 592 Example of a simple 32/64-bit library that obtains its sources 593 from multiple directories. 594 595 lib/nametoaddr/straddr 596 597 Example of a simple loadable module. 598 599 lib/libipmp 600 601 Example of a simple library that builds a message catalog. 602 603 lib/libdhcpsvc 604 605 Example of a Makefile hierarchy for a library and a collection 606 of related pluggable modules. 607 608 lib/lvm 609 610 Example of a Makefile hierarchy for a collection of related 611 libraries and pluggable modules. 612 613 Also an example of a Makefile hierarchy that supports the 614 _dc target for domain and category specific messages. 615 616Of course, if you still have questions, please do not hesitate to send email 617to the ON gatekeepers. 618