Wiki code for The Source Tree, part 2

Hide Line numbers
1: {{toc start=2 depth=6 numbered="false" scope="page"/}}
2: 
3: == 3.3 Using Your Workspace
4: 
5:  This section describes how to perform common operations on your [[workspace>>Community Group on.#workspace]], such as editing files and modifying the build system.
6: 
7: === 3.3.1 Getting Ready to Work
8: 
9:  Once you have brought over a [[workspace>>Community Group on.#workspace]], you must set up both the workspace itself and your environment before you can safely use it.
10: 
11:  First, you must set your environment variables appropriately so that the build tools will work properly. This must be done once in any shell which will run commands that affect the workspace. Although there are numerous variables which must be set, nearly all of them are set by bldenv(1), which accepts a nightly-style environment file. For example, if your workspace’s environment file is in /aux0/testws/opensolaris.sh, you would need to run the following command in each shell from which you will run commands that affect the workspace:
12: 
13: {{{
14: 
15: $ bldenv /aux0/testws/opensolaris.sh
16: 
17: }}}
18: 
19:  It may be tempting to run this command from your shell initialization scripts; however, if you have more than one workspace, it can be inconvenient and even dangerous, as you may inadvertently perform an operation on the wrong workspace.
20: 
21: === 3.3.2 Editing Files
22: 
23:  You can use any text editor you like to edit source files. Although choice of editor is a personal matter, not all editors are equal. In particular, there are two types of editor behavior which are certain to cause problems. First, some editors such as pico and nano wrap lines longer than 72 characters or so. While this is fine for documents, it causes havoc in source files. If you must use such an editor, be sure to turn off line wrapping; otherwise your diffs will include large quantities of noise and the resulting file may not compile. Second, some editors, especially on non-Unix systems which may have different conventions, will change newline characters from ’\n’ to something else. If you must edit sources on a foreign system, be absolutely certain your editor outputs Unix-style newlines. Source files containing foreign newline characters cannot be integrated into any OpenSolaris consolidation and may not compile.
24: 
25:  When you edit source files, be sure that you are familiar with the style guide; see section 7.2 for more details. Once again, not all editors are equal: some may offer the ability to set parameters that will help you to write conformant code, while others may enforce fixed settings which conflict with our style. Regardless of your choice of editor, you will need to be sure that your code conforms to the style guidelines.
26: 
27: === 3.3.3 Modifying the ON Build System
28: 
29:  This section provides detailed, step-by-step instructions for common build-related tasks, such as adding or moving kernel modules and adding new libraries. You should also read the sections regarding makefile layout and operation to gain a better understanding of the overall build system.
30: 
31: ==== 3.3.3.1 Adding a New Kernel Module
32: 
33:  The most common build-related operation developers need to perform is adding a new kernel module to the [[gate>>Community Group on.#gate]]. In this section, we describe the process of adding build instructions for foofs, whose sources are located under usr/src/uts/common/fs/foofs. Adding related commands and libraries (in usr/src/cmd and usr/src/lib) is not covered here.
34: 
35:  0) Create the usr/src/uts/common/fs/foofs directory and populate it with your sources.
36: 
37:  1) Edit uts/*/Makefiles.files to define the set of objects. By convention the symbolic name of this set is of the form MODULE_OBJS, where MODULE is the module name (foofs). The files in each subtree should be defined in the Makefile.files in the root directory of that subtree. Note that they are defined using the += operator, so that the set can be accumulated across multiple makefiles. As example:
38: 
39: {{{
40: 
41: FOOFS_OBJS +=	foovfs.o foovno.o
42: 
43: }}}
44: 
45:  Each source file needs a build rule in the corresponding Makefile.rules file (compilation and linting). A typical pair of entries would be:
46: 
47: {{{
48: 
49: $(OBJS_DIR)/%.o:		$(UTSBASE)/common/fs/foofs/%.c
50: 	$(COMPILE.c) -o $@ $<
51: 	$(CTFCONVERT_O)
52: 
53: }}}
54: 
55: {{{
56: 
57: $(LINTS_DIR)/%.ln:		$(UTSBASE)/common/fs/foofs/%.c
58: 	@($(LHEAD) $(LINT.c) $< $(LTAIL))
59: 
60: }}}
61: 
62:  In this case, these are added to usr/src/uts/common/Makefile.rules. If the module being added is architecture-specific, they must instead be added to the appropriate architecture-specific Makefile.rules file. See section 3.2.3 for more information about specific makefiles.
63: 
64:  2) Create build directories in the appropriate places. If the module can be built in a platform-independent way, this would be in the "instruction set architecture" directory (i.e.: sparc, intel). If not, these directories would be created for all appropriate "implementation architecture"-dependent directories (i.e.: sun4u). In this case, foofs is common code, so two build directories are needed: usr/src/uts/sparc/foofs and usr/src/uts/intel/foofs.
65: 
66:  3) In each build directory, create a makefile. This can usually be accomplished by copying a Makefile from a parallel directory and editing the following lines (in addition to comments).
67: 
68: {{{
69: 
70: MODULE		= foofs
71: OBJECTS		= $(FOOFS_OBJS:%=$(OBJS_DIR)/%)
72: LINTS		= $(FOOFS_OBJS:%.o=$(LINTS_DIR)/%.ln)
73: ROOTMODULE	= $(ROOT_FS_DIR)/$(MODULE)
74: 
75: }}}
76: 
77:  - replace directory part with the appropriate installation directory name (see Makefile.uts)
78: 
79:  If a custom version of modstubs.o is needed to check the undefineds for this routine, the following lines need to appear in the makefile (after the inclusion of Makefile.plat (i.e.: Makefile.sun4u)).
80: 
81: {{{
82: 
83: MODSTUBS_DIR	 = $(OBJS_DIR)
84: $(MODSTUBS_O)	:= AS_CPPFLAGS += -DFOOFS_MODULE
85: 
86: }}}
87: 
88:  - replace "-DFOOFS_MODULE" with the appropriate flag for the modstubs.o assembly.
89: 
90: {{{
91: 
92: CLEANFILES	+= $(MODSTUBS_O)
93: 
94: }}}
95: 
96:  4) Edit the parent Makefile.mach (i.e.: Makefile.sparc, Makefile.intel) to know about the new module:
97: 
98: {{{
99: 
100: FS_KMODS	+= foofs
101: 
102: }}}
103: 
104:  Note that if your module only applies to a subset of the supported architectures, you will only need to perform this step for the makefiles that are used for those architectures.
105: 
106:  Any additional questions can be easily answered by looking at the many existing examples or by using the mailing lists and fora at [[http://opensolaris.org/>>http://opensolaris.org/]].
107: 
108: ==== 3.3.3.2 Making a Kernel Module Architecture-Independent
109: 
110:  In some cases, a module which was specific to a particular implementation architecture is adapted to be more general, often because the hardware it supports has become available on more platforms. Once the module itself is able to be used across multiple platforms, its build parameters should be updated to reflect this. Its location in the source tree will also need to change.
111: 
112:  0) Create the build directory under the appropriate "instruction set architecture" build directory (i.e.: sparc/MODULE).
113: 
114:  1) Move the makefile from the "implementation architecture" build directory (i.e.: sun4u/MODULE) to the directory created above. Edit this makefile to reflect the change of parent (trivial: comments, paths and includes).
115: 
116:  2) Edit the "implementation architecture" directory makefile (i.e.: Makefile.sun4u) to *not* know about this module and edit the "instruction set architecture" directory makefile (i.e.: Makefile.sparc) to know about it.
117: 
118:  3) Since the install locations may have changed (as well as the set of systems on which these files are installed) you may also need to adjust the package prototypes in usr/src/pkgdefs to reflect that such changes.
119: 
120: ==== 3.3.3.3 Adding New Libraries
121: 
122:  This section describes the overall layout and operation of the library makefiles and provides detailed step-by-step instructions for adding new libraries and enhancing existing library makefiles. This is based very closely on the file usr/src/lib/README.Makefiles and will be updated from time to time to match its contents.
123: 
124:  Your library should consist of a hierarchical collection of Makefiles:
125: 
126: * lib/<library>/Makefile:
127:  This is your library’s top-level Makefile. It should contain rules for building any ISA-independent targets, such as installing header files and building message catalogs, but should defer all other targets to ISA-specific Makefiles.
128: * lib/<library>/Makefile.com
129:  This is your library’s common Makefile. It should contain rules and macros which are common to all ISAs. This Makefile should never be built explicitly, but instead should be included (using the make include mechanism) by all of your ISA-specific Makefiles.
130: * lib/<library>/<isa>/Makefile
131:  These are your library’s ISA-specific Makefiles, one per ISA (usually sparc and i386, and sometimes sparcv9 and ia64). These Makefiles should include your common Makefile and then provide any needed ISA-specific rules and definitions, perhaps overriding those provided in your common Makefile.
132:  To simplify their maintenance and construction, $(SRC)/lib has a handful of provided Makefiles that yours must include; the examples provided throughout the document will show how to use them. Please be sure to consult these Makefiles before introducing your own custom build macros or rules.
133: * lib/Makefile.lib:
134:  This contains the bulk of the macros for building shared objects.
135: * lib/Makefile.lib.64
136:  This contains macros for building 64-bit objects, and should be included in Makefiles for 64-bit native ISAs.
137: * lib/Makefile.rootfs
138:  This contains macro overrides for libraries that install into /lib (rather than /usr/lib).
139: * lib/Makefile.targ
140:  This contains rules for building shared objects.
141: 
142:  The remainder of this document discusses how to write each of your Makefiles in detail, and provides examples from the libinetutil library.
143: 
144: **The Library Top-level Makefile**
145: 
146:  As described above, your top-level library Makefile should contain rules for building ISA-independent targets, but should defer the building of all other targets to ISA-specific Makefiles. The ISA-independent targets usually consist of:
147: 
148: * install_h
149:  Install all library header files into the proto area. Can be omitted if your library has no header files.
150: * check
151:  Check all library header files for hdrchk compliance. Can be omitted if your library has no header files.
152: * _msg
153:  Build and install a message catalog. Can be omitted if your library has no message catalog.
154: 
155:  Of course, other targets are (such as `cstyle’) are fine as well, as long as they are ISA-independent.
156: 
157:  The ROOTHDRS and CHECKHDRS targets are provided in lib/Makefile.lib to make it easy for you to install and check your library’s header files. To use these targets, your Makefile must set the HDRS to the list of your library’s header files to install and HDRDIR to the their location in the source tree. In addition, if your header files need to be installed in a location other than $(ROOT)/usr/include, your Makefile must also set ROOTHDRDIR to the appropriate location in the proto area. Once HDRS, HDRDIR and (optionally) ROOTHDRDIR have been set, your Makefile need only contain
158: 
159: {{{
160: 
161: install_h: $(ROOTHDRS)
162: 
163: }}}
164: 
165: {{{
166: 
167: check: $(CHECKHDRS)
168: 
169: }}}
170: 
171:  to bind the provided targets to the standard `install_h’ and `check’ rules.
172: 
173:  Similar rules are provided (in $(SRC)/Makefile.msg.targ) to make it easy for you to build and install message catalogs from your library’s source files.
174: 
175:  To install a catalog into the catalog directory in the proto area, define the POFILE macro to be the name of your catalog, and specify that the _msg target depends on $(MSGDOMAINPOFILE). The examples below should clarify this.
176: 
177:  To build a message catalog from arbitrarily many message source files, use the BUILDPO.msgfiles macro.
178: 
179: {{{
180: 
181: include ../Makefile.lib
182: 
183: }}}
184: 
185: {{{
186: 
187: POFILE =	  libfoo.po
188: MSGFILES =	  $(OBJECTS:%.o=%.i)
189: 
190: }}}
191: 
192: {{{
193: 
194: # ...
195: 
196: }}}
197: 
198: {{{
199: 
200: $(POFILE): $(MSGFILES)
201: 		$(BUILDPO.msgfiles)
202: 
203: }}}
204: 
205: {{{
206: 
207: _msg: $(MSGDOMAINPOFILE)
208: 
209: }}}
210: 
211: {{{
212: 
213: include $(SRC)/Makefile.msg.targ
214: 
215: }}}
216: 
217:  Note that this example doesn’t use grep to find message files, since that can mask unreferenced files, and potentially lead to the inclusion of unwanted messages or omission of intended messages in the catalogs. As such, MSGFILES should be derived from a known list of objects or sources.
218: 
219:  It is usually preferable to run the source through the C preprocessor prior to extracting messages. To do this, use the ".i" suffix, as shown in the above example. If you need to skip the C preprocessor, just use the native (.[ch]) suffix.
220: 
221:  The only time you shouldn’t use BUILDPO.msgfiles as the preferred means of extracting messages in when you’re extracting them from shell scripts; in that case, you can use the BUILDPO.pofiles macro as explained below.
222: 
223:  To build a message catalog from other message catalogs, or from source files that include shell scripts, use the BUILDPO.pofiles macro:
224: 
225: {{{
226: 
227: include ../Makefile.lib
228: 
229: }}}
230: 
231: {{{
232: 
233: SUBDIRS =	  $(MACH)
234: 
235: }}}
236: 
237: {{{
238: 
239: POFILE =	  libfoo.po
240: POFILES =	  $(SUBDIRS:%=%/_%.po)
241: 
242: }}}
243: 
244: {{{
245: 
246: _msg :=	  TARGET = _msg
247: 
248: }}}
249: 
250: {{{
251: 
252: # ...
253: 
254: }}}
255: 
256: {{{
257: 
258: $(POFILE): $(POFILES)
259: 		$(BUILDPO.pofiles)
260: 
261: }}}
262: 
263: {{{
264: 
265: _msg: $(MSGDOMAINPOFILE)
266: 
267: }}}
268: 
269: {{{
270: 
271: include $(SRC)/Makefile.msg.targ
272: 
273: }}}
274: 
275:  The Makefile above would work in conjunction with the following in its subdirectories’ Makefiles:
276: 
277: {{{
278: 
279: POFILE =	  _thissubdir.po
280: MSGFILES =	  $(OBJECTS:%.o=%.i)
281: 
282: }}}
283: 
284: {{{
285: 
286: $(POFILE):	  $(MSGFILES)
287: 		  $(BUILDPO.msgfiles)
288: 
289: }}}
290: 
291: {{{
292: 
293: _msg:		  $(POFILE)
294: 
295: }}}
296: 
297: {{{
298: 
299: include $(SRC)/Makefile.msg.targ
300: 
301: }}}
302: 
303:  Since this POFILE will be combined with those in other subdirectories by the parent Makefile and that merged file will be installed into the proto area via MSGDOMAINPOFILE, there is no need to use MSGDOMAINPOFILE in this Makefile (in fact, using it would lead to duplicate messages in the catalog).
304: 
305:  When using any of these targets, keep in mind that other macros, like XGETFLAGS and TEXT_DOMAIN may also be set in your Makefile to override or augment the defaults provided in higher-level Makefiles.
306: 
307:  As previously mentioned, you should defer all ISA-specific targets to your ISA-specific Makefiles. You can do this by:
308: 
309: 1. Setting SUBDIRS to the list of directories to descend into:
310: 
311: {{{
312: SUBDIRS = $(MACH)
313: }}}
314: 
315:  Note that if your library is also built 64-bit, then you should also specify
316: 
317: {{{
318: $(BUILD64)SUBDIRS += $(MACH64)
319: }}}
320: 
321:  so that SUBDIRS contains $(MACH64) if and only if you’re compiling on a 64-bit ISA.
322: 1. Providing a common "descend into SUBDIRS" rule:
323: 
324: {{{
325: spec $(SUBDIRS): FRC
326: 	@cd $@; pwd; $(MAKE) $(TARGET)
327: }}}
328: 
329: {{{
330: FRC:
331: }}}
332: 
333: 1. Providing a collection of conditional assignments that set TARGET appropriately:
334: 
335: {{{
336: all	:= TARGET= all
337: clean	:= TARGET= clean
338: clobber := TARGET= clobber
339: install := TARGET= install
340: lint	:= TARGET= lint
341: }}}
342: 
343:  The order doesn’t matter, but alphabetical is preferable.
344: 1. Having the aforementioned targets depend on SUBDIRS:
345: 
346: {{{
347: all clean clobber install: spec .WAIT $(SUBDIRS)
348: }}}
349: 
350: {{{
351: lint: $(SUBDIRS)
352: }}}
353: 
354:  A few notes are in order here:
355: 
356:  * The `all’ target must be listed first; the others might as well be listed alphabetically.
357: 
358:  * The `lint’ target is listed separately because there is nothing to lint in the spec subdirectory.
359: 
360:  * The .WAIT between spec and $(SUBDIRS) is suboptimal but currently required to make sure that two different make invocations don’t simultaneously build the mapfiles. It will likely be replaced with a more sophisticated mechanism in the future.
361: 
362:  As an example of how all of this goes together, here’s libinetutil’s top-level library Makefile (copyright omitted):
363: 
364: {{{
365: 
366: include ../Makefile.lib
367: 
368: }}}
369: 
370: {{{
371: 
372: HDRS =		libinetutil.h
373: HDRDIR =	common
374: SUBDIRS =	$(MACH)
375: $(BUILD64)SUBDIRS += $(MACH64)
376: 
377: }}}
378: 
379: {{{
380: 
381: all :=		TARGET = all
382: clean :=	TARGET = clean
383: clobber :=	TARGET = clobber
384: install :=	TARGET = install
385: lint :=		TARGET = lint
386: 
387: }}}
388: 
389: {{{
390: 
391: .KEEP_STATE:
392: 
393: }}}
394: 
395: {{{
396: 
397: all clean clobber install: spec .WAIT $(SUBDIRS)
398: 
399: }}}
400: 
401: {{{
402: 
403: lint:		$(SUBDIRS)
404: 
405: }}}
406: 
407: {{{
408: 
409: install_h:	$(ROOTHDRS)
410: 
411: }}}
412: 
413: {{{
414: 
415: check:		$(CHECKHDRS)
416: 
417: }}}
418: 
419: {{{
420: 
421: $(SUBDIRS) spec: FRC
422: 	@cd $@; pwd; $(MAKE) $(TARGET)
423: 
424: }}}
425: 
426: {{{
427: 
428: FRC:
429: 
430: }}}
431: 
432: {{{
433: 
434: include ../Makefile.targ
435: 
436: }}}
437: 
438: **The Common Makefile**
439: 
440:  In concept, your common Makefile should contain all of the rules and definitions that are the same on all ISAs. However, for reasons of maintainability and cleanliness, you’re encouraged to place even ISA-dependent rules and definitions, as long you express them in an ISA-independent way (e.g., by using $(MACH), $(TRANSMACH), and their kin).
441: 
442:  The common Makefile can be conceptually split up into four sections:
443: 
444: 1. A copyright and comments section.
445:  Please see the prototype files in usr/src/prototypes for examples of how to format the copyright message properly. For brevity and clarity, this section has been omitted from the examples shown here.
446: 1. A list of macros that must be defined prior to the inclusion of Makefile.lib.
447:  This section is conceptually terminated by the inclusion of Makefile.lib, followed, if necessary, by the inclusion of Makefile.rootfs (only if the library is to be installed in /lib rather than the default /usr/lib).
448: 1. A list of macros that need not be defined prior to the inclusion of Makefile.lib
449:  (or which must be defined following the inclusion of Makefile.lib, to override or augment its definitions). This section is conceptually terminated by the .KEEP_STATE directive.
450: 1. A list of targets.
451: 
452:  The first section is self-explanatory. The second typically consists of the following macros:
453: 
454: {{code}}LIBRARY{{/code}}
455: 
456:  Set to the name of the static version of your library, such as `libinetutil.a’. You should always specify the `.a’ suffix, since pattern-matching rules in higher-level Makefiles rely on it, even though static libraries are not normally built in [[ON>>Community Group on.#on]], and are never installed in the proto area. Note that the LIBS macro (described below) controls the types of libraries that are built when building your library.
457: 
458:  If you are building a loadable module (i.e., a shared object that is only linked at runtime with dlopen(3dl)), specify the name of the loadable module with a `.a’ suffix, such as `devfsadm_mod.a’.
459: 
460: {{code}}VERS{{/code}}
461: 
462:  Set to the version of your shared library, such as `.1’. You actually do not need to set this prior to the inclusion of Makefile.lib, but it is good practice to do so since VERS and LIBRARY are so closely related.
463: 
464: {{code}}OBJECTS{{/code}}
465: 
466:  Set to the list of object files contained in your library, such as `a.o b.o’. Usually, this will be the same as your library’s source files (except with .o extensions), but if your library compiles source files outside of the library directory itself, it will differ. We’ll see an example of this with libinetutil.
467: 
468:  The third section typically consists of the following macros:
469: 
470: {{code}}LIBS{{/code}}
471: 
472:  Set to the list of the types of libraries to build when building your library. For dynamic libraries, you should set this to `$(DYNLIB) $(LINTLIB)’ so that a dynamic library and lint library are built. For loadable modules, you should just list DYNLIB, since there’s no point in building a lint library for libraries that are never linked at compile-time.
473: 
474:  If your library needs to be built as a static library (typically to be used in other parts of the build), you should set LIBS to `$(LIBRARY)’. However, you should do this only when absolutely necessary, and you must *never* ship static libraries to customers.
475: 
476: {{code}}ROOTLIBDIR{{/code}} (if your library installs to a nonstandard directory)
477: 
478:  Set to the directory your 32-bit shared objects will install into with the standard $(ROOTxxx) macros. Since this defaults to $(ROOT)/usr/lib ($(ROOT)/lib if you included Makefile.rootfs), you usually do not need to set this.
479: 
480: {{code}}ROOTLIBDIR64{{/code}} (if your library installs to a nonstandard directory)
481: 
482:  Set to the directory your 64-bit shared objects will install into with the standard $(ROOTxxx64) macros. Since this defaults to $(ROOT)/usr/lib/$(MACH64) ($(ROOT)/lib/$(MACH64) if you included Makefile.rootfs), you usually do not need to set this.
483: 
484: {{code}}SRCDIR{{/code}}
485: 
486:  Set to the directory containing your library’s source files, such as `../common’. Because this Makefile is actually included from your ISA-specific Makefiles, make sure you specify the directory relative to your library’s <isa> directory.
487: 
488: {{code}}SRCS{{/code}} (if necessary)
489: 
490:  Set to the list of source files required to build your library. This defaults to $(OBJECTS:%.o=$(SRCDIR)/%.c) in Makefile.lib, so you only need to set this when source files from directories other than SRCDIR are needed. Keep in mind that SRCS should be set to a list of source file *pathnames*, not just a list of filenames.
491: 
492:  LINTLIB-specific SRCS (required if building a [[lint>>Community Group on.#lint]] library)
493: 
494:  Set to a special "lint stubs" file to use when constructing your library’s lint library. The lint stubs file must be used to guarantee that programs that link against your library will be able to lint clean. To do this, you must conditionally set SRCS to use your stubs file by specifying `LINTLIB := SRCS= $(SRCDIR)/$(LINTSRC)’ in your Makefile. Of course, you do not need to set this if your library does not build a lint library.
495: 
496: {{code}}LDLIBS{{/code}}
497: 
498:  Appended with the list of libraries and library directories needed to build your library; minimally "-lc". Note that this should *never* be set, since that will inadvertently clear the library search path, causing the linker to look in the wrong place for the libraries.
499: 
500:  Since lint targets also make use of LDLIBS, LDLIBS *must* only contain -l and -L directives; all other link-related directives should be put in DYNFLAGS (if they apply only to shared object construction) or LDFLAGS (if they apply in general).
501: 
502: {{code}}MAPDIR{{/code}}
503: 
504:  Set to the directory in which your library mapfile is built. If your library builds its mapfile from specfiles, set this to `../spec/$(TRANSMACH)’ (TRANSMACH is the same as MACH for 32-bit targets, and the same as MACH64 for 64-bit targets).
505: 
506: {{code}}MAPFILE{{/code}} (required if your mapfile is under source control)
507: 
508:  Set to the path to your library mapfile. If your library builds its mapfile from specfiles, this need not be set. If you set this, you must also set DYNFLAGS to include `-M $(MAPFILE)’ and set DYNLIB to depend on MAPFILE.
509: 
510: {{code}}SPECMAPFILE{{/code}} (required if your mapfile is generated from specfiles)
511: 
512:  Set to the path to your generated mapfile (usually `$(MAPDIR)/mapfile’). If your library mapfile is under source control, you need not set this. Setting this triggers a number of features in higher-level Makefiles:
513: 
514:  * Your shared library will automatically be linked with `-M $(SPECMAPFILE)’.
515: 
516:  * A `make clobber’ will remove $(SPECMAPFILE).
517: 
518:  * Changes to $(SPECMAPFILE) will cause your shared library to be rebuilt.
519: 
520:  * An attempt to build $(SPECMAPFILE) will automatically cause a `make mapfile’ to be done in MAPDIR.
521: 
522: {{code}}CPPFLAGS{{/code}} (if necessary)
523: 
524:  Appended with any flags that need to be passed to the C preprocessor (typically -D and -I flags). Since lint macros use CPPFLAGS, CPPFLAGS *must* only contain directives known to the C preprocessor. When compiling MT-safe code, CPPFLAGS *must* include -D_REENTRANT. When compiling large file aware code, CPPFLAGS *must* include -D_FILE_OFFSET_BITS=64.
525: 
526: {{code}}CFLAGS{{/code}}
527: 
528:  Appended with any flags that need to be passed to the C compiler. Minimally, append `$(CCVERBOSE)’. Keep in mind that you should add any C preprocessor flags to CPPFLAGS, not CFLAGS.
529: 
530: {{code}}CFLAGS64{{/code}} (if necessary)
531: 
532:  Appended with any flags that need to be passed to the C compiler when compiling 64-bit code. Since all 64-bit code is compiled $(CCVERBOSE), you usually do not need to modify CFLAGS64.
533: 
534: {{code}}COPTFLAG{{/code}} (if necessary)
535: 
536:  Set to control the optimization level used by the C compiler when compiling 32-bit code. You should only set this if absolutely necessary, and it should only contain optimization-related settings (or -g).
537: 
538: {{code}}COPTFLAG64{{/code}} (if necessary)
539: 
540:  Set to control the optimization level used by the C compiler when compiling 64-bit code. You should only set this if absolutely necessary, and it should only contain optimization-related settings (or -g).
541: 
542: {{code}}LINTFLAGS{{/code}} (if necessary)
543: 
544:  Appended with any flags that need to be passed to lint(1) when linting 32-bit code. You should only modify LINTFLAGS in rare instances where your code cannot (or should not) be fixed.
545: 
546: {{code}}LINTFLAGS64{{/code}} (if necessary)
547: 
548:  Appended with any flags that need to be passed to lint(1) when linting 64-bit code. You should only modify LINTFLAGS64 in rare instances where your code cannot (or should not) be fixed.
549: 
550:  Of course, you may use other macros as necessary.
551: 
552:  The fourth section typically consists of the following targets:
553: 
554: * all
555:  Build all of the types of the libraries named by LIBS. Must always be the first real target in common Makefile. Since the higher-level Makefiles already contain rules to build all of the different types of libraries, you can usually just specify
556: 
557: {{{
558: all: $(LIBS)
559: }}}
560: 
561:  though it should be listed as an empty target if LIBS is set by your ISA-specific Makefiles (see above).
562: * lint
563:  Use the `lintcheck’ rule provided by lib/Makefile.targ to lint the actual library sources. Historically, this target has also been used to build the lint library (using LINTLIB), but that usage is now discouraged. Thus, this rule should be specified as
564: 
565: {{{
566: lint: lintcheck
567: }}}
568: 
569:  Conspicuously absent from this section are the `clean’ and `clobber’ targets. These targets are already provided by lib/Makefile.targ and thus should not be provided by your common Makefile. Instead, your common Makefile should list any additional files to remove during a `clean’ and `clobber’ by appending to the CLEANFILES and CLOBBERFILES macros.
570: 
571:  Once again, here’s libinetutil’s common Makefile, which shows how many of these directives go together. Note that Makefile.rootfs is included to cause libinetutil.so.1 to be installed in /lib rather than /usr/lib:
572: 
573: {{{
574: 
575: LIBRARY =	libinetutil.a
576: VERS =		.1
577: OBJECTS =	octet.o inetutil4.o ifspec.o
578: 
579: }}}
580: 
581: {{{
582: 
583: include ../../Makefile.lib
584: include ../../Makefile.rootfs
585: 
586: }}}
587: 
588: {{{
589: 
590: LIBS =		$(DYNLIB) $(LINTLIB)
591: SRCS =		$(COMDIR)/octet.c $(SRCDIR)/inetutil4.c \
592: 		$(SRCDIR)/ifspec.c
593: $(LINTLIB):=	SRCS = $(SRCDIR)/$(LINTSRC)
594: LDLIBS +=	-lsocket -lc
595: 
596: }}}
597: 
598: {{{
599: 
600: SRCDIR =	../common
601: COMDIR =	$(SRC)/common/net/dhcp
602: MAPDIR =	../spec/$(TRANSMACH)
603: SPECMAPFILE =	$(MAPDIR)/mapfile
604: 
605: }}}
606: 
607: {{{
608: 
609: CFLAGS +=	$(CCVERBOSE)
610: CPPFLAGS +=	-I$(SRCDIR)
611: 
612: }}}
613: 
614: {{{
615: 
616: .KEEP_STATE:
617: 
618: }}}
619: 
620: {{{
621: 
622: all: $(LIBS)
623: 
624: }}}
625: 
626: {{{
627: 
628: lint: lintcheck
629: 
630: }}}
631: 
632: {{{
633: 
634: pics/%.o: $(COMDIR)/%.c
635: 	$(COMPILE.c) -o $@ $<
636: 	$(POST_PROCESS_O)
637: 
638: }}}
639: 
640: {{{
641: 
642: include ../../Makefile.targ
643: 
644: }}}
645: 
646:  Note that for libinetutil, not all of the object files come from SRCDIR. To support this, an alternate source file directory named COMDIR is defined, and the source files listed in SRCS are specified using both COMDIR and SRCDIR. Additionally, a special build rule is provided to build object files from the sources in COMDIR; the rule uses COMPILE.c and POST_PROCESS_O so that any changes to the compilation and object-post-processing phases will be automatically picked up.
647: 
648: **The ISA-Specific Makefiles**
649: 
650:  As the name implies, your ISA-specific Makefiles should contain macros and rules that cannot be expressed in an ISA-independent way. Usually, the only rule you will need to put here is `install’, which has different dependencies for 32-bit and 64-bit libraries. For instance, here are the ISA-specific Makefiles for libinetutil:
651: 
652: {{{
653: 
654: sparc/Makefile:
655: 
656: }}}
657: 
658: {{{
659: 
660: include ../Makefile.com
661: 
662: }}}
663: 
664: {{{
665: 
666: install: all $(ROOTLIBS) $(ROOTLINKS) $(ROOTLINT)
667: 
668: }}}
669: 
670: {{{
671: 
672: sparcv9/Makefile:
673: 
674: }}}
675: 
676: {{{
677: 
678: include ../Makefile.com
679: include ../../Makefile.lib.64
680: 
681: }}}
682: 
683: {{{
684: 
685: install: all $(ROOTLIBS64) $(ROOTLINKS64)
686: 
687: }}}
688: 
689: {{{
690: 
691: i386/Makefile:
692: 
693: }}}
694: 
695: {{{
696: 
697: include ../Makefile.com
698: 
699: }}}
700: 
701: {{{
702: 
703: install: all $(ROOTLIBS) $(ROOTLINKS) $(ROOTLINT)
704: 
705: }}}
706: 
707:  Observe that there is no .KEEP_STATE directive in these Makefiles, since all of these Makefiles include libinetutil/Makefile.com, and it already has a .KEEP_STATE directive. Also, note that the 64-bit Makefile also includes Makefile.lib.64, which overrides some of the definitions contained in the higher level Makefiles included by the common Makefile so that 64-bit compiles work correctly.
708: 
709: **CTF Data in Libraries**
710: 
711:  By default, all position-independent objects are built with [[CTF>>Community Group on.#ctf]] data using ctfconvert, which is then merged together using ctfmerge when the shared object is built. All C-source objects processed via ctfmerge need to be processed via ctfconvert or the build will fail. Objects built from non-C sources (such as assembly or C++) are silently ignored for CTF processing.
712: 
713:  Filter libraries that have no source files will need to explicitly disable CTF by setting CTFMERGE_LIB to ":"; see libw/Makefile.com for an example.
714: 
715: **More Information**
716: 
717:  Other issues and questions will undoubtedly arise while you work on your library’s Makefiles. To help in this regard, a number of libraries of varying complexity have been updated to follow the guidelines and practices outlined in this document:
718: 
719: * lib/libdhcputil
720:  Example of a simple 32-bit only library.
721: * lib/libdhcpagent
722:  Example of a simple 32-bit only library that obtains its sources from multiple directories.
723: * lib/ncad_addr
724:  Example of a simple loadable module.
725: * lib/libipmp
726:  Example of a simple library that builds a message catalog.
727: * lib/libdhcpsvc
728:  Example of a Makefile hierarchy for a library and a collection of related pluggable modules.
729: * lib/lvm
730:  Example of a Makefile hierarchy for a collection of related libraries and pluggable modules.
731:  Also an example of a Makefile hierarchy that supports the _dc target for domain and category specific messages.
732: 
733: == 3.4 Keeping Your Workspace in Sync
734: 
735:  Over time, other developers will put back their work into the main [[gate>>Community Group on.#gate]], and your [[workspace>>Community Group on.#workspace]] will become out of date with respect to these changes. By keeping your workspace in sync as much as possible, you will save time in two ways.
736: 
737:  First, you will have less merging to do when you are ready to put back, which will reduce or eliminate conflict resolution and simplify testing.
738: 
739:  Second, the risk of missing semantic changes in other parts of the code will be reduced. If an interface you use is changed, you want to know about it as soon as possible so you will not continue to implement your features on the basis of a deprecated or nonexistent interface. This will save much work and grief; you do not want to be preparing to put back and only then discover that your code no longer compiles because a crucial interface has been removed.
740: 
741:  Keeping your workspace in sync is not difficult, and should be done as often as practical. However, there is one drawback, which may limit the frequency at which you choose to sync your workspace. Pulling in changes unrelated to your work exposes you to the risk of breakage caused by those changes. If an unrelated change breaks your workspace, you could waste time trying to identify the cause of breakage by assuming it is in your changes rather than someone else’s. Also, it is possible that an unrelated change will render your workspace unable to boot or perform any useful work at all, which would make it impossible for you to test your changes until the original bugs are fixed. For these reasons, you will want to carefully consider your synchronization process to minimize risk while keeping as up to date as possible. Merging with recent, tested build snapshots on a biweekly basis rather than merging daily with the gate is often a good compromise.
742: 
743:  Until the main gate is accessible to all developers, the Sun engineer who is carrying the fix will have to do any final merges with the internal gate. If you have submitted a change that causes this merge to get too hairy, you should be ready to answer questions about the change and provide assistance during the merge. In extreme cases, the Sun engineer may ask that you do the merge externally (i.e., after the next snapshot has been released) and resubmit your source patch. This reduces the chance that your change will break other changes being made to the same area of code.
744: 
745: === 3.4.1 Workspace Updates with Mercurial
746: 
747:  You can use the command "hg pull -u" to synchronize your workspace with the [[gate>>Community Group on.#gate]]. If you haven’t made any changes in your workspace, this will pull down any new [[changesets>>http://www.selenic.com/mercurial/wiki/ChangeSet]] and update your [[working directory>>http://www.selenic.com/mercurial/wiki/WorkingDirectory]] to the last one.
748: 
749:  External developers may wish to specify a revision with "hg pull", to match up a source changeset with closed binaries, as described in [[3.1.2 Obtaining Sources via Mercurial>>Community Group on.#3_1_2_obtaining_sources_via_hg]].
750: 
751:  Internal developers should remember to update both their open and closed repositories.
752: 
753:  If you have made changes in your workspace, bringing down changes from the gate will create a branch in your workspace. The last changeset in each branch is called a "head", so you will see a message from Mercurial about the creation of a new head. You should merge these branches before proceeding, using "hg merge". See the Mercurial wiki for an [[overview of the merge process>>http://www.selenic.com/mercurial/wiki/Merge]].
754: 
755:  If you have nightly(1) configured to do a pull (the default for internal developers), nightly(1) will attempt an automated merge if one is needed. The build will error out if the merge fails. Even if the automated merge succeeds, be sure to review the changes before committing them.
OpenSolaris

Top Menu

Wiki code for The Source Tree, part 2

Search

Collectives

Community Group

Project

User Group

Subsites

Community Group on Pages
