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
28 Writing Library Makefiles in ON
29 ===============================
30
31 Introduction
32 ------------
33
34 This document guides you through the gnarly process of writing library
35 Makefiles for the ON consolidation. It assumes that you're comfortable with
36 make(1) and are somewhat familiar with the ON Makefile standards outlined in
37 /shared/ON/general_docs/make_std.txt.
38
39 Makefile Overview
40 -----------------
41
42 Your 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
66 To simplify their maintenance and construction, $(SRC)/lib has a handful of
67 provided Makefiles that yours must include; the examples provided throughout
68 the document will show how to use them. Please be sure to consult these
69 Makefiles 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
89 The remainder of this document discusses how to write each of your Makefiles
90 in detail, and provides examples from the libinetutil library.
91
92 The Library Top-level Makefile
93 ------------------------------
94
95 As described above, your top-level library Makefile should contain
96 rules for building ISA-independent targets, but should defer the
97 building of all other targets to ISA-specific Makefiles. The
98 ISA-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
115 Of course, other targets (such as `cstyle') are fine as well, as long as
116 they are ISA-independent.
117
118 The ROOTHDRS and CHECKHDRS targets are provided in lib/Makefile.lib to make
119 it easy for you to install and check your library's header files. To use
120 these targets, your Makefile must set the HDRS to the list of your library's
121 header files to install and HDRDIR to the their location in the source tree.
122 In addition, if your header files need to be installed in a location other
123 than $(ROOT)/usr/include, your Makefile must also set ROOTHDRDIR to the
124 appropriate location in the proto area. Once HDRS, HDRDIR and (optionally)
125 ROOTHDRDIR have been set, your Makefile need only contain
126
127 install_h: $(ROOTHDRS)
128
129 check: $(CHECKHDRS)
130
131 to bind the provided targets to the standard `install_h' and `check' rules.
132
133 Similar rules are provided (in $(SRC)/Makefile.msg.targ) to make it easy for
134 you to build and install message catalogs from your library's source files.
135
136 To install a catalog into the catalog directory in the proto area, define the
137 POFILE macro to be the name of your catalog, and specify that the _msg target
138 depends on $(MSGDOMAINPOFILE). The examples below should clarify this.
139
140 To build a message catalog from arbitrarily many message source files, use
141 the 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
157 Note that this example doesn't use grep to find message files, since that can
158 mask unreferenced files, and potentially lead to the inclusion of unwanted
159 messages or omission of intended messages in the catalogs. As such, MSGFILES
160 should be derived from a known list of objects or sources.
161
162 It is usually preferable to run the source through the C preprocessor prior
163 to extracting messages. To do this, use the ".i" suffix, as shown in the
164 above example. If you need to skip the C preprocessor, just use the native
165 (.[ch]) suffix.
166
167 The only time you shouldn't use BUILDPO.msgfiles as the preferred means of
168 extracting messages is when you're extracting them from shell scripts; in
169 that case, you can use the BUILDPO.pofiles macro as explained below.
170
171 To build a message catalog from other message catalogs, or from source files
172 that 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
192 The Makefile above would work in conjunction with the following in its
193 subdirectories' 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
205 Since this POFILE will be combined with those in other subdirectories by the
206 parent Makefile and that merged file will be installed into the proto area
207 via 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
210 When using any of these targets, keep in mind that other macros, like
211 XGETFLAGS and TEXT_DOMAIN may also be set in your Makefile to override or
212 augment the defaults provided in higher-level Makefiles.
213
214 As previously mentioned, you should defer all ISA-specific targets to your
215 ISA-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
254 As an example of how all of this goes together, here's libinetutil's
255 top-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
285 The Common Makefile
286 -------------------
287
288 In concept, your common Makefile should contain all of the rules and
289 definitions that are the same on all ISAs. However, for reasons of
290 maintainability and cleanliness, you're encouraged to place even
291 ISA-dependent rules and definitions, as long you express them in an
292 ISA-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
294 for 64-bit targets).
295
296 The 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
316 The first section is self-explanatory. The second typically consists of the
317 following 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
348 The 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
475 Of course, you may use other macros as necessary.
476
477 The 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
500 Conspicuously absent from this section are the `clean' and `clobber' targets.
501 These targets are already provided by lib/Makefile.targ and thus should not
502 be provided by your common Makefile. Instead, your common Makefile should
503 list any additional files to remove during a `clean' and `clobber' by
504 appending to the CLEANFILES and CLOBBERFILES macros.
505
506 Once again, here's libinetutil's common Makefile, which shows how many of
507 these directives go together. Note that Makefile.rootfs is included to
508 cause 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
543 The mapfile for libinetutil is named `mapfile-vers' and resides in $(SRCDIR),
544 so the MAPFILES definition is omitted, defaulting to $(SRCDIR)/mapfile-vers.
545
546 Note that for libinetutil, not all of the object files come from SRCDIR. To
547 support this, an alternate source file directory named COMDIR is defined, and
548 the source files listed in SRCS are specified using both COMDIR and SRCDIR.
549 Additionally, a special build rule is provided to build object files from the
550 sources in COMDIR; the rule uses COMPILE.c and POST_PROCESS_O so that any
551 changes to the compilation and object-post-processing phases will be
552 automatically picked up.
553
554 The ISA-Specific Makefiles
555 --------------------------
556
557 As the name implies, your ISA-specific Makefiles should contain macros and
558 rules that cannot be expressed in an ISA-independent way. Usually, the only
559 rule you will need to put here is `install', which has different dependencies
560 for 32-bit and 64-bit libraries. For instance, here are the ISA-specific
561 Makefiles 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.