Wiki code for The Source Tree, part 1

Hide Line numbers
1: = Chapter 3. The Source Tree
2: 
3:  This chapter discusses obtaining, managing, and modifying ON source code.
4: 
5: {{toc start=2 depth=6 numbered="false" scope="page"/}}
6: 
7: == 3.1 Retrieving the Sources
8: 
9:  A snapshot tarball of ON is posted for each biweekly build. Sources are also available via a [[Mercurial>>devref_glossary#HMercurial]] repository, which is updated in real time. If you plan to build ON source, you will also need the ON closed binaries.
10: 
11:  There are two advantages to using source tarballs. First, the sources have gone through [[PIT>>devref_glossary#HPIT]] tests and are known to be reasonably sane. Second, the sources are delivered with closed binaries that match the sources. The disadvantage is that they are inconvenient to work with over time: updates require downloading the entire source tree, and there is no automation to help you merge any changes that you have made.
12: 
13:  The advantage of using a Mercurial repository is that it is easier to use over time. Updates only require pulling down the files that changed since last time, and there are facilities to help you merge your local changes with changes in the [[gate>>devref_glossary#Hgate]]. The disadvantage is that there is some risk of pulling down unstable changes. ON only publishes new closed binaries once a day, so there is a slight chance that the source changes you pull down are incompatible with your closed binaries. And while the gate has a [[tag>>http://www.selenic.com/mercurial/wiki/Tag]] for each biweekly build, the tag simply indicates the cutoff for that build. Critical fixes which were integrated after the cutoff are not covered by the tag, although they will be present in the corresponding source tarball.
14: 
15:  See also [[3.4 Keeping Your Workspace in Sync>>Community Group on.devref_3b]] for details of how to keep your workspace up-to-date once you have set it up.
16: 
17: === 3.1.1 Obtaining Sources via Tarball
18: 
19:  You can obtain the tarballs for ON (or any other released consolidation) at [[ http://opensolaris.org/os/downloads/>>Main.downloads]]. You can obtain the closed binaries from the same location. Be sure to obtain the appropriate binaries for your platform. Once you have done so, create your [[workspace>>devref_glossary#Hworkspace]] as follows:
20: 
21: {{{
22: 
23: $ mkdir /path/to/workspace
24: $ cd /path/to/workspace
25: $ bzip2 -dc /path/to/tarball/on-src-<ver>.tar.bz2 | tar xf -
26: $ bzip2 -dc /path/to/tarball/on-closed-bins-<ver>.{x86,sparc}.tar.bz2 | tar xf -
27: 
28: }}}
29: 
30: === 3.1.2 Obtaining Sources via Mercurial
31: 
32:  You can download the closed binaries from [[ http://dlc.sun.com/osol/on/downloads/nightly-bins/>>http://dlc.sun.com/osol/on/downloads/nightly-bins/]]. The hex numbers that you’ll see on that page indicate the Mercurial [[changeset ID>>http://www.selenic.com/mercurial/wiki/ChangeSetID]] (from the source tree) that the binaries should be compatible with.
33: 
34:  To get a copy of the Mercurial repository that matches your closed binaries, use:
35: 
36: {{{
37: 
38: $ hg clone -r changeset_ID ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate /path/to/workspace
39: 
40: }}}
41: 
42: == 3.2 Tour of Your ON Workspace
43: 
44:  After creating and populating your [[workspace>>devref_glossary#Hworkspace]], you can begin to investigate the contents of the source tree. This section describes the layout and contents of your [[ON>>devref_glossary#HON]] workspace.
45: 
46: === 3.2.1 Organization
47: 
48:  Initially, your [[workspace>>devref_glossary#Hworkspace]] will have only one directory: usr. Once you have completed a build, you may have several additional directories, including archives, log, packages, and proto. We include here a diagram showing all these directories and their subdirectories. We also include the build subdirectories, which contain object files and are described in greater detail in subsections 2-4 below.
49: 
50:  If you have done a nightly(1) build, you will also have a log directory at the top level. It will contain the complete output from the nightly(1) build process. See [[Section 4.2 Using nightly and bldenv>>devref_4]] for more information on nightly(1) and the log files it generates.
51: 
52:  All sources are found under usr/src. This includes both the sources used to build the [[ON>>devref_glossary#HON]] consolidation and sources for tools and other peripheral utilities needed to build but not shipped as part of Solaris. Because it includes only ON sources, it does not contain Java, the windowing system, or packaging and installation tools. Because of contractual obligations, it may not include all code from third-party hardware vendors. The usr/src directory has several subdirectories which are described here.
53: 
54: * cmd
55:  This directory contains sources for the executable programs and scripts that are part of ON. It includes all the basic commands, daemons, startup scripts, and related data. Most subdirectories are named for the command or commands they provide; however, there are some exceptions listed here.
56: * cmd/Adm
57:  Miscellaneous key system files, such as crontabs and data installed in /etc.
58: * cmd/cmd-crypto
59:  Basic cryptographic utilities, such as elfsign and kcfd.
60: * cmd/cmd-inet
61:  Network commands and daemons, including the Berkeley r-commands, PPP, telnet, the inetd super-server, and other network-related utilities.
62: * cmd/fs.d
63:  Utilities for checking, mounting, unmounting, and analyzing filesystems.
64: * cmd/netfiles
65:  IP port definitions and name service switch configuration files installed into /etc.
66: * cmd/ptools
67:  Utilities for manipulating and observing processes; these are based on proc(4) and libproc interfaces.
68: * cmd/sgs
69:  Software Generation System. This directory contains binary utilities, such as ld(1), ar(1), and mcs(1), and development tools such as lex(1), yacc(1), and m4(1). Note that this directory also includes several libraries and headers used by these tools.
70: * common
71:  Files which are common among cmd, lib, stand, and uts. These typically include headers and sources to basic libraries used by both the kernel and user programs.
72: * head
73:  Userland header files (kernel headers are in uts/). Note that only libc headers should be stored here; other libraries should have their headers in their own subdirectories under lib/.
74: * lib
75:  Libraries. Most subdirectories are named for the library whose sources they contain or are otherwise self-explanatory.
76: * pkgdefs
77:  Contains one subdirectory for each package generated from the ON sources. Each subdirectory contains packaging information files; see pkginfo(4), depend(4), prototype(4), pkgmap(1), and pkgproto(1) for more information about the contents of these files.
78: * prototypes
79:  Sample files showing format and copyright notices.
80: * psm
81:  Platform-specific modules. Currently this contains only OBP and most of the boot code.
82: * stand
83:  Standalone environment code. This is used for booting; for example, code for reading from UFS and the network is here.
84: * tools
85:  Development tools and sources. See README.tools for more information about each tool; the file should be updated as tools are added or removed.
86: * ucbcmd
87:  Commands and daemons installed into /usr/ucb (for SunOS 4.x compatibility).
88: * ucbhead
89:  Header files installed into /usr/ucb (for SunOS 4.x compatibility).
90: * ucblib
91:  Libraries installed into /usr/ucb (for SunOS 4.x compatibility).
92: * uts
93:  Kernel sources are here (UTS == UNIX Time Sharing). There are numerous subdirectories of uts which are of interest:
94: * uts/adb
95:  adb contained the obsolete kernel debugger macros; it is no longer supported, and this directory is now empty. Use mdb(1) instead, and write mdb dcmds instead of adb macros.
96: * uts/common
97:  All platform-independent kernel sources. Nearly all of the Solaris kernel is here; only a few small parts are architecture-dependent.
98: * uts/common/c2
99:  Auditing code to support the C2 U.S. government security standard.
100: * uts/common/conf
101:  System configuration parameters.
102: * uts/common/contract
103:  Code to support process contracts. See contract(4) and libcontract(3LIB) for more information on process contracts.
104: * uts/common/cpr
105:  CheckPoint-and-Resume support. This implements suspend and resume functionality.
106: * uts/common/crypto
107:  Kernel cryptographic framework. See kcfd(1M) and cryptoadm(1M) for more information.
108: * uts/common/ctf
109:  Code for handling Compact C Type Format data.
110: * uts/common/des
111:  Implements the old Data Encryption Standard. This is used by KCF.
112: * uts/common/disp
113:  Dispatcher, thread handling, and scheduling classes.
114: * uts/common/dtrace
115:  CPU-independent dtrace(7D) kernel support.
116: * uts/common/exec
117:  Code for handling userland binary executable types (a.out, ELF, etc).
118: * uts/common/fs
119:  Filesystems.
120: * uts/common/gssapi
121:  Generic Security Services API.
122: * uts/common/inet
123:  IP networking subsystem, including IPv6.
124: * uts/common/io
125:  I/O subsystem. Most of the code in this directory is device drivers (and pseudo-device drivers).
126: * uts/common/ipp
127:  IP policy framework; includes QoS and other traffic management.
128: * uts/common/kmdb
129:  Kernel modular debugger. See kmdb(1).
130: * uts/common/krtld
131:  Kernel runtime linker/loader. This is responsible for handling loadable modules and symbol resolution; it is analogous to ld.so.1, and shares code with it.
132: * uts/common/ktli
133:  Kernel TLI (Transport Layer Interface).
134: * uts/common/net
135:  Header files; most are shipped in /usr/include/net.
136: * uts/common/netinet
137:  Header files; most are shipped in /usr/include/netinet.
138: * uts/common/nfs
139:  Network File System headers shipped in /usr/include/nfs.
140: * uts/common/os
141:  Core operating system implementation. This includes such varied aspects as privileges, zones, timers, the DDI/DKI interfaces, and high-level locking mechanisms.
142: * uts/common/pcmcia
143:  PCMCIA I/O subsystem and drivers.
144: * uts/common/rpc
145:  Remote Procedure Call subsystem used by services such as NFS and NIS.
146: * uts/common/rpcsvc
147:  Generated RPC header files shipped in /usr/include/rpcsvc.
148: * uts/common/sys
149:  Header files shipped in /usr/include/sys. These same headers are used to build the kernel as well (if the _KERNEL preprocessor symbol is defined).
150: * uts/common/syscall
151:  System call implementations. Most syscalls are implemented in files matching their names. Note that some system calls are implemented in os/ or other subdirectories instead.
152: * uts/common/tnf
153:  Old tracing subsystem, not related to dtrace(7D).
154: * uts/common/vm
155:  Virtual memory subsystem.
156: * uts/common/zmod
157:  Compression/decompression library.
158: * uts/i86pc
159:  Architecture-dependent files for x86 machines. The architecture-dependent directories (i86pc, sun, sun4, sun4u) all have a set of subdirectories similar to common/ above.
160: * uts/intel
161:  ISA-dependent, architecture-independent files for x86 machines. Note that all architecture-independent source files are built into objects in this hierarchy.
162: * uts/sfmmu
163:  Code specific to the SpitFire memory management unit (UltraSPARC).
164: * uts/sparc
165:  ISA-dependent, architecture-independent files for SPARC machines. Note that all architecture-independent source files are built into objects in this hierarchy.
166: * uts/sun
167:  Sources common to all Sun implementations. Currently this contains a small number of device drivers and some headers shipped in /usr/include/sys.
168: * uts/sun4
169:  Sources common to all sun4* machine architectures.
170: * uts/sun4u
171:  Architecture-dependent sources for the sun4u architecture. Each system implementation has a subdirectory here:
172: 
173: {{{
174: * blade		Serverblade1
175: * chalupa		Sun-Fire-V440
176: * cherrystone		Sun-Fire-480R
177: * daktari		Sun-Fire-880
178: * darwin		Ultra-5_10
179: * enchilada		Sun-Blade-2500
180: * ents		Sun-Fire-V250
181: * excalibur		Sun-Blade-1000
182: * fjlite		UltraAX-i2
183: * grover		Sun-Blade-100
184: * javelin		Ultra-250
185: * littleneck		Sun-Fire-280R
186: * lw2plus		Netra-T4
187: * lw8			Netra-T12
188: * makaha		UltraSPARC IIe-NetraCT-40, UltraSPARC IIe-NetraCT-60
189: * montecarlo		UltraSPARC IIi-NetraCT
190: * mpxu		Sun-Fire-V240
191: * quasar		Ultra-80
192: * serengeti		Sun-Fire
193: * snowbird		Netra-CP2300
194: * starcat		Sun-Fire-15000
195: * starfire		Ultra-Enterprise-10000
196: * sunfire		Ultra-Enterprise
197: * taco		Sun-Blade-1500
198: * tazmo		Ultra-4
199: }}}
200: 
201: === 3.2.2 Object Directories
202: 
203:  There are two basic strategies that can be used in the creation of object files and finished binaries (executables and libraries):
204: 
205:  (a) place objects in a dedicated directory hierarchy parallel to the sources
206: 
207:  (b) place objects in the same directories as the sources they are built from
208: 
209:  ON actually uses each of these approaches in different parts of the tree. Strategy (a) must be used for all kernel code and many libraries, is preferred for new code, and will be described in detail here. There are several legacy variations on strategy (a) as well as instances in which strategy (b) is still used; the majority of these are in the cmd hierarchy. The entire uts hierarchy has been converted to strategy (a) as described below, and you will see this same approach used throughout much of the rest of the tree.
210: 
211: ==== 3.2.2.1 General Strategy for Kernel Objects
212: 
213:  First, each platform-independent module has zero or one build directory per architecture. An architecture in this case can be a machine (sun4u, i86pc) or a processor architecture (intel, sparc). The path to this location is always usr/src/uts/<platform>/<module>. The module name in this case is what’s found in /kernel/drv or a similar location, and in the case of device drivers or STREAMS modules should always match the name of the man page describing that driver or module.
214: 
215:  The only files normally present in this directory for a clean tree are makefiles. After a build, these directories contain one or more of obj32, obj64, debug32, and debug64 directories. These directories contain the object files and finally linked modules that are later installed into the kernel directory and other locations in the prototype.
216: 
217:  "Implementation architecture"-independent modules are produced in individual directories (one per module) under the "instruction-set architecture" directory (i.e.: sparc). Similarly, "implementation architecture"-dependent modules are produced in individual directories under the "implementation architecture" directory (i.e.: sun4, sun4u, i86pc).
218: 
219:  Platform-dependent modules (including "unix") may be built more than once in different locations. Platform-dependent modules are discussed in greater detail in <section>.
220: 
221:  The sources are not contained in these build directories.
222: 
223: ==== 3.2.2.2 General Strategy for Command/Library Objects
224: 
225:  Most libraries and some commands and daemons are built using makefiles very similar to those used to build the kernel. Accordingly, intermediate objects, shared objects, libraries, and executables are built by small makefile fragments and placed in dedicated ISA-specific subdirectories.
226: 
227:  Other commands’ build systems place objects in the same directories as the sources. See sections 3.2.2.3, 3.2.3.2, and 3.2.5 for more information on how commands are built.
228: 
229: ==== 3.2.2.3 Exceptions in cmd and lib
230: 
231:  Most of the cmd tree is directly based on the original System V Release 4 source, which uses strategy (b) described above. Since most commands and daemons do not need to provide both 32- and 64-bit versions, or do anything special when building for different architectures, this strategy is adequate and appropriate for most commands and has been applied even to new subdirectories. In situations in which architecture-dependent build options are needed or multiple ISA versions of a program must be delivered, this strategy is unworkable and the more general approach of multiple per-ISA object directories must be used instead. This latter approach is similar to the approach used for kernel modules.
232: 
233:  The lib hierarchy is somewhat simpler; nearly all subdirectories must use per-ISA object file locations and makefiles.
234: 
235:  A few directories do not appear to follow any rule or pattern, such as cmd/cmd-inet and cmd/agents. These are primarily historical artifacts of Sun’s internal project organization.
236: 
237: === 3.2.3 Makefile Layout
238: 
239:  This discussion is intended to provide a step-by-step explanation of what targets exist and how they are built by the makefiles. I ignore the platform-specific module architecture because it is unlikely to be of significant interest except to hardware support engineers. The three main subtrees of interest are the kernel (uts), commands and daemons (cmd), and libraries (lib). The next three subsections cover these three subtrees in turn. There are also a handful of makefiles which apply to all builds:
240: 
241: * usr/src/Makefile
242:  This is the top-level makefile. It drives builds for various targets in each subdirectory. It is aware of the specific targets that need to be built in each subdirectory in order to perform a complete build, and itself knows how to create a skeleton proto area for later use by install and install_h targets.
243: * usr/src/Makefile.lint
244:  All linting from the top level is driven by this makefile. It contains long lists of directories known to be [[lint>>devref_glossary#Hlint]]-clean and contains simple recursive rules for rebuilding each subdirectory’s lint target. The actual linting is driven by the lower-level makefiles.
245: * usr/src/Makefile.master
246: * usr/src/Makefile.master.64
247:  These two makefiles contain generic definitions, such as build and installation tools locations, template macros for compilers, linkers, and other tools to be used by other makefiles in defining rules, and global definitions such as the ISA and machine names that apply to this build. Makefile.master.64 contains definitions specific to 64-bit builds that override the generic definitions.
248: * usr/src/Makefile.msg.targ
249:  Common targets for building message catalogues are defined here. Message catalogues provide translations of messages for g11n purposes.
250: * usr/src/Makefile.psm
251:  This makefile defines the installation locations for platform-specific modules. These are analogous to the other kernel module install locations /kernel and /usr/kernel (see section 3.2.6 below for more information on kernel module installation).
252: * usr/src/Makefile.psm.targ
253:  Installation target definitions for platform-specific modules are defined here. This instructs the build system how to install files into the directories defined by Makefile.psm.
254: * usr/src/Targetdirs
255:  This is a set of definitions for the owner, group, and permissions of each directory that will be created by the installation process. It also contains information about special symbolic links to be installed for some 64-bit library versions.
256: 
257: ==== 3.2.3.1 Kernel Makefile Layout
258: 
259:  The driving makefile for any module is located in the leaf directory (build directory) where the module and its component objects are built. After a ’make clobber’ operation, the makefile should be the only file remaining in that directory. There are two other types of makefiles in the tree: suffixed and non-suffixed. Common definitions and rules needed by all leaf makefiles are contained in the suffixed makefiles; these are included by leaf makefiles. Non-suffixed makefiles generally invoke multiple lower-level makefiles with the same target so that many modules can be built with a single make invocation.
260: 
261: * uts/Makefile
262: * uts/sparc/Makefile
263: * uts/sun4u/Makefile
264: * uts/intel/Makefile
265: * uts/intel/ia32/Makefile
266: * uts/i86pc/Makefile
267:  These makefiles generally are cognizant of the components made in subdirectories and invoke makefiles in those sub- directories to perform the actual build. Some targets (or pseudo-targets) may be directly built at this level (such as the cscope databases).
268: * uts/Makefile.uts
269:  Contains common definitions for all possible architectures.
270: * uts/Makefile.targ
271:  Contains common targets for all possible architectures.
272: * uts/common/Makefile.files
273: * uts/sun/Makefile.files
274: * uts/sparc/Makefile.files
275: * uts/sun4/Makefile.files
276: * uts/sun4u/Makefile.files
277: * uts/intel/Makefile.files
278: * uts/intel/ia32/Makefile.files
279: * uts/i86pc/Makefile.files
280:  These makefiles are divided into two sections. The first section defines the object lists which comprise each module. The second section defines the appropriate header search paths and other machine-specific global build parameters.
281: * uts/common/Makefile.rules
282: * uts/sun/Makefile.rules
283: * uts/sparc/Makefile.rules
284: * uts/sun4/Makefile.rules
285: * uts/sun4u/Makefile.rules
286: * uts/intel/Makefile.rules
287: * uts/intel/ia32/Makefile.rules
288: * uts/intel/amd64/Makefile.rules
289: * uts/i86pc/Makefile.rules
290:  The files provide build rules (targets) which allow make to function in a multiple directory environment. Each source tree below the directory containing the makefile has a build rule in the file.
291: * uts/sun4/Makefile.sun4
292: * uts/sun4u/Makefile.sun4u
293: * uts/intel/Makefile.intel
294: * uts/intel/ia32/Makefile.ia32
295: * uts/i86pc/Makefile.i86pc
296:  These makefiles contain the definitions specific (defaults) to the obvious "implementation architecture". These rules can be overridden in specific leaf node makefiles if necessary.
297: * Makefile.*.shared
298:  These makefiles provide settings that are shared between the open-source makefiles and the closed-source makefiles that are internal to Sun. See Section 3.2.8 Source Files not Included for more details.
299: * uts/sun4u/unix/Makefile
300: * uts/i86pc/unix/Makefile
301:  Main driving makefile for building unix.
302: * uts/sun4u/MODULE/Makefile (for MODULE in cgsix, cpu, kb, ...)
303:  Main driving makefile for building MODULE.
304: * uts/sun4u/genunix/Makefile
305: * uts/i86pc/genunix/Makefile
306:  Main driving makefile for building genunix.
307: 
308:  Issuing the command ’make’ in the uts directory will cause all supported, modularized kernels and modules to be built.
309: 
310:  Issuing the command ’make’ in a uts/ARCHITECTURE directory (i.e.: uts/sparc) will cause all supported, "implementation architecture"-independent modules for ARCHITECTURE to be built.
311: 
312:  Issuing the command ’make’ in a uts/MACHINE directory (i.e.: uts/sun4u) will cause that kernel and all supported, "implementation architecture"- dependent modules for MACHINE to be built.
313: 
314:  The makefiles are verbosely commented. It is desired that they should stay this way.
315: 
316: ==== 3.2.3.2 Command Makefile Layout
317: 
318:  Most command and daemon subdirectories follow one of two general layout rules, depending on where object files will be located (see sections 3.2.2.2 and 3.2.2.3). For ISA-dependent programs, the layout is similar to that used by the kernel. Programs which do not need ISA-dependent build behavior use a simplified makefile layout. In the description here, we use the example of a generic command called "foocmd" whose sources are located in usr/src/cmd/foocmd. The makefiles relevant to building foocmd are:
319: 
320: * usr/src/cmd/Makefile
321:  Top-level driving makefile for all commands/daemons. This is a simple recursive makefile which is aware of which subdirectories should be built and will cause the given target to be rebuilt in each of them.
322: * usr/src/cmd/Makefile.cmd
323:  This makefile defines the installation directories and rules for installing executables into them.
324: * usr/src/cmd/Makefile.cmd.64
325:  Additional definitions specific to 64-bit builds are provided here.
326: * usr/src/cmd/Makefile.cmd.bsm
327:  This specialty makefile is used only by auditstat and dminfo. It provides some generic boilerplate rules.
328: * usr/src/cmd/Makefile.targ
329:  Basic target definitions for clobber, lint, and installation.
330: * usr/src/cmd/foocmd/Makefile
331:  Driving makefile for foocmd. Normally defines PROG but otherwise contains only boilerplate definitions and targets. This is almost always copied from another similar makefile. If foocmd does not require ISA-dependent build behavior, rules will normally be specified directly, including those for the install target. If foocmd does require ISA-dependent build behavior, this makefile will instead define SUBDIRS to include the ISA-specific versions that must be built, and define targets recursively. This will usually leave the install target definition for each ISA makefile and cause a link to $(ISAEXEC) to be created. See section 3.2.5 for more information on platform dependencies and $(ISAEXEC).
332: * usr/src/cmd/foocmd/Makefile.com
333:  Defines PROG, OBJS, SRCS, and includes Makefile.cmd. May also contain additional flags for compilation or linking. This makefile normally defines targets for all, $(PROG), clean, and lint; this portion is usually generic and would be copied from another similar makefile.
334: * usr/src/cmd/foocmd/*/Makefile
335:  ISA-specific makefiles, which may define additional ISA-specific flags or targets, and will generally include its own install target to install the ISA-specific program(s) it builds.
336: 
337: ==== 3.2.3.3 Library Makefile Layout
338: 
339:  Most library subdirectories follow the same general layout, which is similar to the command layout. Unlike commands, most libraries are built for both 32- and 64-bit architecture variants, so ISA-specific directories will almost always be present. Therefore, the overall build structure for each library is similar to that of the kernel. See [[Section 3.3.3.3 Adding New Libraries>>devref_3b]] for more detailed information on library makefiles.
340: 
341: === 3.2.4 Makefile Operation
342: 
343:  This section describes in detail how make dependencies and rules are built up, and how each individual makefile contributes to the build process. Once you understand how the makefiles work, modifying existing build rules and creating new ones are mainly an exercise in copying existing files and making minor modifications to them. We begin with the kernel makefiles, then address the very similar command and library makefiles.
344: 
345: ==== 3.2.4.1 Kernel Makefile Operation
346: 
347:  There are two parts to the make dependencies: a set of targets and a set of rules.
348: 
349:  The rules are contained in the Makefile.rules files in each directory under uts. They cover how to compile a source file in some other directory (common/io for example) into an object file in the build directory described above. They also describe which sources are needed to build a given object file. The order in which they are specified determines which source file is needed if there are multiple source files matching the same basename. The key to all this is understanding that all rules and targets are static and module-independent, but variables set in each module’s build directory (leaf) makefile define the module-specific build information.
350: 
351:  The targets are of two kinds: the first are "make targets," generic directives you can give make like "all" or "install" which are executed in each build directory. The build directory makefiles in turn include other makefiles that contain rules for building objects and modules. The second type of target is more interesting - they are the actual module names (directories, in fact) that must be built. These variables are called KMODS and XMODS.
352: 
353:  If KMODS contains, for example, "aac ata asy", then for each of the aac, ata, and asy build directories, the make system will cd to that directory and rerun make with whatever target (all, install, etc) is given. The rules for that module are derived from all the included makefiles; the crucial variables to look for are of the form XXX_OBJS, where XXX is the module name. More than one makefile may contain definitions adding to each of these object lists, because building a module may require different objects on each platform.
354: 
355:  XMODS is used only for building export versions of the commercial Solaris product; it is not used in building ON.
356: 
357:  So for example we see:
358: 
359: {{{
360: 
361: common/Makefile.files:ASY_OBJS +=      asy.o
362: 
363: }}}
364: 
365:  This indicates that the asy.o object is needed to build the ASY module. The makefile in the <platform>/asy directory will reference ASY_OBJS and thus know what to build. So in intel/asy/Makefile we see:
366: 
367: {{{
368: 
369: MODULE          = asy
370: OBJECTS         = $(ASY_OBJS:%=$(OBJS_DIR)/%)
371: 
372: }}}
373: 
374:  So, what good is this? Plenty. Because our ALL_TARGET is also defined:
375: 
376: {{{
377: 
378: ALL_TARGET      = $(BINARY) $(SRC_CONFILE)
379: 
380: }}}
381: 
382:  Makefile.uts defines BINARY as follows:
383: 
384: {{{
385: 
386: BINARY             = $(OBJS_DIR)/$(MODULE)
387: 
388: }}}
389: 
390:  And OBJS_DIR is the individual module build directory I described at the beginning. So, make knows we need to build usr/src/uts/intel/asy/obj32/asy. Makefile.targ defines the rules for doing so, too:
391: 
392: {{{
393: 
394: $(BINARY):              $(OBJECTS)
395: 	$(LD) -r $(LDFLAGS) -o $@ $(OBJECTS)
396: 	$(CTFMERGE_UNIQUIFY_AGAINST_GENUNIX)
397: 	$(POST_PROCESS)
398: 	$(ELFSIGN_MOD)
399: 
400: }}}
401: 
402:  We’re almost there - OBJECTS have to come from somewhere. We find this defined in intel/asy/Makefile:
403: 
404: {{{
405: 
406: OBJECTS         = $(ASY_OBJS:%=$(OBJS_DIR)/%)
407: 
408: }}}
409: 
410:  And that’s that. We have a module (asy) that has a BINARY (obj32/asy) which depends on OBJECTS made from ASY_OBJS. The rules for each entry in ASY_OBJS is in one of the Makefile.rules files; they look something like this:
411: 
412: {{{
413: 
414: $(OBJS_DIR)/%.o:                $(UTSBASE)/common/io/%.c
415: 	$(COMPILE.c) -o $@ $<
416: 	$(CTFCONVERT_O)
417: 
418: }}}
419: 
420:  Each object is built in accordance with these rules. The rule for $(BINARY) then links them into the module.
421: 
422:  We can now put it all together. The extensive use of macros and local per-module definitions provides much greater flexibility, but in the example given, the equivalent makefile fragment would look very familiar:
423: 
424: {{{
425: 
426: KMODS +=	asy
427: 
428: }}}
429: 
430: {{{
431: 
432: all:	$(KMODS)
433: 
434: }}}
435: 
436: {{{
437: 
438: asy:	obj32/asy.o
439: 	$(LD) -r $(LDFLAGS) -o $@ obj32/asy.o
440: 	...
441: 
442: }}}
443: 
444: {{{
445: 
446: obj32/asy.o:	../../common/io/asy.c
447: 	$(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $@
448: 	...
449: 
450: }}}
451: 
452: ==== 3.2.4.2 Command Makefile Operation
453: 
454:  Command makefiles vary widely, as described above. Therefore it is impossible to provide a "representative example" of a command makefile. However, understanding the material in sections 3.2.4.1 and 3.3.3.3 will provide you with the necessary knowledge to work with command makefiles. As always, if you are looking for information about a specific command, it is usually best to use the mailing lists and other community resources.
455: 
456: ==== 3.2.4.3 Library Makefile Operation
457: 
458:  Section 3.3.3.3 describes library makefile operation in detail.
459: 
460: === 3.2.5 ISA Dependencies
461: 
462:  Most code in OpenSolaris is generic and platform- and ISA-independent; that is, it is portable code that can be compiled and run on any system for which a suitable compiler is available. However, even portable code must sometimes deal with specific attributes of the system on which it runs, or must be provided compiled for multiple supported architectures so that users can run or link with the architecture-specific version of their choosing.
463: 
464:  There are two distinct situations in which multiple architecture-specific builds must be shipped: commands that, by their nature, must have visibility into the system’s hardware characteristics, and libraries, which must be built separately for each architecture a developer may wish to target. Each case is discussed in its own subsection below.
465: 
466: ==== 3.2.5.1 ISA-Dependent Commands
467: 
468:  Commands (normally executable programs or daemons) usually do not depend on the ISA on which they are executed; that is, they will be built and installed in the same way regardless of the ISA they are built for. Some commands, however, mainly those which operate on other processes or manipulate binary objects, must behave differently depending on the ISA(s) supported by the system and/or their targets. The /usr/lib/isaexec wrapper program provides this behavior in the following way:
469: 
470:  First, one or more ISA-specific programs are installed into ISA-specific directories in the system. These are subdirectories of those directories which ordinarily contain executable programs, such as /usr/bin. On SPARC systems, ISA subdirectories might include /usr/bin/sparcv7 and /usr/bin/sparcv9 to contain 32- and 64-bit binaries, respectively. Other ISAs may be supported by other systems; you can find out which your system supports by using isalist(1).
471: 
472:  Next, a hard link is installed into the ordinary binary directory (in the example above, /usr/bin) targeting /usr/lib/isaexec. This will cause isaexec to be invoked with the name of the ISA-dependent program the user has executed.
473: 
474:  When this happens, isaexec will select the most appropriate ISA-specific program installed in the first step and exec(2) it. This is transparent, so a user will not notice that a separate program has been invoked.
475: 
476:  A similar mechanism (/usr/lib/platexec) exists for platform-specific programs; these are much less common even than ISA-specific programs.
477: 
478:  Because it needs to interact both with user processes and kernel data structures, dtrace(1) is an example of a command that must provide multiple ISA-specific versions.
479: 
480:  cmd/dtrace contains two makefiles: Makefile and Makefile.com. It also contains a single source file, dtrace.c, and four ISA directories: amd64, i386, sparc, and sparcv9. Each contains a single makefile. The top-level makefiles should look very familiar after our tour of the uts makefiles; Makefile is mainly boilerplate, customized only to specify that the program produced is ISA- specific and therefore a link to the isaexec program needs to be installed into /usr/sbin in the proto area:
481: 
482: {{{
483: 
484: install:        $(SUBDIRS)
485: 	-$(RM) $(ROOTUSRSBINPROG)
486: 	-$(LN) $(ISAEXEC) $(ROOTUSRSBINPROG)
487: 
488: }}}
489: 
490:  Otherwise, it simply leaves all building and installation to the makefiles in the ISA subdirectories. Makefile.com is also boilerplate; it specifies the name of the program to build and the objects from which it must be built:
491: 
492: {{{
493: 
494: PROG = dtrace
495: OBJS = dtrace.o
496: 
497: }}}
498: 
499:  It then transforms the objects into sources:
500: 
501: {{{
502: 
503: SRCS = $(OBJS:%.o=../%.c)
504: 
505: }}}
506: 
507:  and includes the generic top-level Makefile.cmd fragment to pick up build rules.
508: 
509:  Compilation and linkage flags are specified:
510: 
511: {{{
512: 
513: CFLAGS += $(CCVERBOSE)
514: CFLAGS64 += $(CCVERBOSE)
515: LDLIBS += -ldtrace -lproc
516: 
517: }}}
518: 
519:  and the remainder consists of a handful of generic build rules. One feature is noteworthy: an extra ../ is prepended to all paths in this fragment. This is because it is always included by makefiles interpreted from the ISA-specific build directory, which is one level deeper than Makefile.com itself.
520: 
521:  The makefiles in the ISA-specific build directories are even simpler; they each consist of only two lines:
522: 
523: {{{
524: 
525: include ../Makefile.com
526: 
527: }}}
528: 
529: {{{
530: 
531: install: all $(ROOTUSRSBINPROG32)
532: 
533: }}}
534: 
535:  The first line picks up all common definitions in the makefile we just examined, and the second specifies (indirectly) the location in which the program is to be installed. To complete the picture, we need to briefly examine usr/src/cmd/Makefile.cmd, which defines the various locations in which programs can be installed. Since we have not defined ROOTUSRSBINPROG32, it must be defined there, and indeed it is:
536: 
537: {{{
538: 
539: ROOTUSRSBIN=    $(ROOT)/usr/sbin
540: ROOTUSRSBINPROG=$(PROG:%=$(ROOTUSRSBIN)/%)
541: ROOTUSRSBIN32=  $(ROOTUSRSBIN)/$(MACH32)
542: ROOTUSRSBINPROG32=      $(PROG:%=$(ROOTUSRSBIN32)/%)
543: 
544: }}}
545: 
546:  Note that the program is actually installed in /usr/sbin/$(MACH32), which is not normally in a user’s search path. But remember that we also created a link from $(ROOTUSRSBINPROG) to $(ISAEXEC); expanding these variables shows that we will actually install two separate files:
547: 
548: {{{
549: 
550: $(ROOT)/usr/sbin/dtrace		-> $(ROOT)/usr/lib/isaexec
551: $(ROOT)/usr/sbin/$(MACH32)/dtrace	(our executable program)
552: 
553: }}}
554: 
555:  Since the isaexec program is responsible for selecting an ISA-specific program from among several options depending on the system’s supported instruction sets, we can see that a typical system will have one or more dtrace(1) binaries installed and that when dtrace(1) is run by the user, isaexec will select the appropriate one from those installed in the ISA-specific subdirectories of /usr/sbin. As we might expect, other ISA-specific makefiles under cmd/dtrace install their binaries into ROOTUSRSBIN64, also defined in usr/src/cmd/Makefile.cmd.
556: 
557: ==== 3.2.5.2 ISA-Dependent Libraries
558: 
559:  Libraries, unlike commands, must almost always be built for all supported ISAs and have separate ISA-specific versions installed on, at minimum, every system that supports that ISA. In practice, libraries for each ISA in the system’s processor family are installed. This allows developers on that system to write programs using any supported ISA and link them with the appropriate system libraries (it is not possible, for example, to link 32-bit object files and 64-bit libraries, nor vice versa).
560: 
561:  Libraries use a build system very similar to that used by commands which must provide multiple ISA-specific executable programs. We examine here the makefiles used by dtrace(1)’s library counterpart libdtrace(3LIB) and how they support building and installing multiple ISA-specific versions of the dtrace library.
562: 
563:  lib/libdtrace contains two makefiles: Makefile and Makefile.com. It also contains a directory for common code and four ISA directories: amd64, i386, sparc, and sparcv9. Each ISA directory contains a single makefile and in some cases some ISA-specific sources. The top-level Makefile should once again look very familiar; is very similar to the uts and cmd makefiles and is mainly boilerplate. There are a few customizations to add a yydebug target and to tell top-level makefiles that lex and yacc generated files should not have cross-references built against them.
564: 
565: {{{
566: 
567: yydebug := TARGET = yydebug
568: ...
569: lint yydebug: $(SUBDIRS)
570: 
571: }}}
572: 
573:  and
574: 
575: {{{
576: 
577: XRDIRS = common i386 sparc sparcv9
578: XRDEL = dt_lex.c dt_grammar.c Makefile*
579: 
580: }}}
581: 
582:  Otherwise, it simply leaves all building and installation to the makefiles in the ISA subdirectories. Makefile.com is somewhat more interesting. It first specifies the name of the library to build (in static format; shared library names are translated as we shall see below), and the library version. These are common to all library makefiles. Next, we see long lists of source files used to build the library, and an OBJECTS specification. This particular library also has some unique characteristics, including the D runtime init code, built as a separate object file (drti.o), and a number of D "header" files which are installed into a separate directory /usr/lib/dtrace. You can see these unique features here:
583: 
584: {{{
585: 
586: DRTISRC = drti.c
587: DRTIOBJ = $(DRTISRC:%.c=%.o)
588: 
589: }}}
590: 
591: {{{
592: 
593: DLIBSRCS += \
594: 	errno.d \
595: 	io.d \
596: 	procfs.d \
597: 	regs.d \
598: 	sched.d \
599: 	signal.d \
600: 	unistd.d
601: ...
602: ROOTDLIBDIR = $(ROOT)/usr/lib/dtrace
603: ROOTDLIBDIR64 = $(ROOT)/usr/lib/dtrace/64
604: ...
605: $(ROOTDLIBDIR):
606: 	$(INS.dir)
607: 
608: }}}
609: 
610: {{{
611: 
612: $(ROOTDLIBDIR64): $(ROOTDLIBDIR)
613: 	$(INS.dir)
614: 
615: }}}
616: 
617: {{{
618: 
619: $(ROOTDLIBDIR)/%.d: ../common/%.d
620: 	$(INS.file)
621: 
622: }}}
623: 
624: {{{
625: 
626: $(ROOTDLIBDIR)/%.d: ../$(MACH)/%.d
627: 	$(INS.file)
628: 
629: }}}
630: 
631: {{{
632: 
633: $(ROOTDLIBDIR)/%.d: %.d
634: 	$(INS.file)
635: 
636: }}}
637: 
638:  Note that some of the D "headers" are in turn generated from other files; this makefile includes rules for performing these transformations.
639: 
640:  Once the LIBSRCS and OBJECTS have been defined, the generic library makefile fragment Makefile.lib is included to provide target and directory definitions.
641: 
642:  Binary objects are built in the pics/ subdirectory. pics stands for position- independent code(s), referring to the fact that dynamic shared libraries are built in such a way as to be loaded at any address. This is an historical artifact; static linking of system libraries is not supported by OpenSolaris-based distributions, so the non-PIC objects which would have been used to build an archive-style library are not built. The rules for building are given as:
643: 
644: {{{
645: 
646: pics/%.o: ../$(MACH)/%.c 
647: 	$(COMPILE.c) -o $@ $<
648: 	$(POST_PROCESS_O)
649: 
650: }}}
651: 
652: {{{
653: 
654: pics/%.o: ../$(MACH)/%.s
655: 	$(COMPILE.s) -o $@ $<
656: 	$(POST_PROCESS_O)
657: 
658: }}}
659: 
660: {{{
661: 
662: %.o: ../common/%.c
663: 	$(COMPILE.c) -o $@ $<
664: 	$(POST_PROCESS_O)
665: 
666: }}}
667: 
668:  Note that because this makefile fragment is included by each ISA’s makefile, the objects produced will be placed relative to that makefile, in each ISA directory. Once again, this also means that included makefile fragments include an additional ../ component.
669: 
670:  The libdtrace Makefile.com also contains a large number of custom rules to accommodate building a lexer and parser from lex(1) and yacc(1) definitions; these sources are then compiled specially using the custom rules and are removed when the clean or clobber target is executed.
671: 
672:  The makefiles in the ISA-specific build directories are once again very simple. The SPARC-specific makefile, for example, defines additional assembler flags, specifies the directory where the library interface map is located, and then includes the common makefile:
673: 
674: {{{
675: 
676: ASFLAGS += -D_ASM -K PIC -P
677: 
678: }}}
679: 
680: {{{
681: 
682: MAPDIR = ../spec/sparc
683: include ../Makefile.com
684: 
685: }}}
686: 
687:  The makefile may also add a few ISA-specific sources to the build list; for example, sparc/Makefile includes:
688: 
689: {{{
690: 
691: SRCS += dt_asmsubr.s
692: OBJECTS += dt_asmsubr.o
693: 
694: }}}
695: 
696:  And once again, a separate install target is provided to indicate the directories where these specific libraries and headers should be installed:
697: 
698: {{{
699: 
700: install yydebug: all $(ROOTLIBS) $(ROOTLINKS) $(ROOTLINT) \
701: 	$(ROOTDLIBS) $(ROOTDOBJS)
702: 
703: }}}
704: 
705:  To support building a separate set of 64-bit objects, sparcv9/Makefile includes slightly different definitions and a different install target:
706: 
707: {{{
708: 
709: MAPDIR = ../spec/sparcv9
710: include ../Makefile.com
711: include ../../Makefile.lib.64
712: 
713: }}}
714: 
715: {{{
716: 
717: CPPFLAGS += -D_ELF64
718: ...
719: install yydebug: all $(ROOTLIBS64) $(ROOTLINKS64) $(ROOTLINT64) \
720: 	$(ROOTDLIBS) $(ROOTDOBJS64)
721: 
722: }}}
723: 
724:  Note the additional inclusion of Makefile.lib.64 and the additional flag for 64-bit ELF targets. Also, the 64-bit-specific versions of the installation files are used, which as we can see in Makefile.lib cause them to be installed into /usr/lib/sparcv9:
725: 
726: {{{
727: 
728: ROOTLIBDIR=     $(ROOT)/usr/lib
729: ROOTLIBDIR64=   $(ROOT)/usr/lib/$(MACH64)
730: ...
731: ROOTLIBS=       $(LIBS:%=$(ROOTLIBDIR)/%)
732: ROOTLIBS64=     $(LIBS:%=$(ROOTLIBDIR64)/%)
733: 
734: }}}
735: 
736:  The linker (ld(1)) and runtime loader (ld.so.1(1)) know which of these directories to search for libraries depending on the bitness of the objects being linked or the program being run, respectively. For more information about 32- versus 64-bit linking, consult the Solaris Linkers and Libraries Guide, which can be found at [[http://docs.sun.com/db/doc/816-1386>>http://docs.sun.com/db/doc/816-1386]].
737: 
738: === 3.2.6 Understanding Kernel Module Installation
739: 
740:  The install target causes binaries and headers to be installed into a hierarchy called the prototype or proto area (see section 4.4.1 for more information on the prototype area’s contents and purpose). The root of the proto area is defined by the environment variable ROOT. This variable is used in defining ROOT_MOD_DIR and USR_MOD_DIR in usr/src/uts/Makefile.uts:
741: 
742: {{{
743: 
744: ROOT_MOD_DIR               = $(ROOT)/kernel
745: USR_MOD_DIR                = $(ROOT)/usr/kernel
746: 
747: }}}
748: 
749:  All modules are installed below one of these directories. The exact subdirectory used depends on the definition of ROOTMODULE in the module build directory, which is discussed below.
750: 
751:  Additional files to be installed may be given by the INSTALL_TARGET definition in this makefile. For example, the asy makefile (usr/src/uts/intel/asy/Makefile) specifies:
752: 
753: {{{
754: 
755: INSTALL_TARGET  = $(BINARY) $(ROOTMODULE) $(ROOT_CONFFILE)
756: 
757: }}}
758: 
759:  Since this is a common set of installation targets, let’s look at how each component is derived.
760: 
761:  $(BINARY) is simply the module itself; we’ve discussed its dependencies and rules in detail above. Including it here requires it to be fully built before any installation is attempted.
762: 
763:  $(ROOTMODULE) is a name transform on the name of the module, relocating it into the prototype area. For example, usr/src/uts/intel/asy/Makefile defines:
764: 
765: {{{
766: 
767: ROOTMODULE      = $(ROOT_DRV_DIR)/$(MODULE)
768: 
769: }}}
770: 
771:  ROOT_DRV_DIR requires a bit of additional explanation; it is one of many module installation subdirectories defined in Makefile.uts. Because the ending location of binary kernel modules depends on the machine type, specifically its 32 versus 64 bitness, there are really several definitions. First, the subdirectory definition for each 64-bit machine type:
772: 
773: {{{
774: 
775: SUBDIR64_sparc          = sparcv9
776: SUBDIR64_i386           = amd64
777: SUBDIR64                = $(SUBDIR64_$(MACH))
778: 
779: }}}
780: 
781:  Next, the 32- and 64-bit installation directories for each type of module:
782: 
783: {{{
784: 
785: ROOT_KERN_DIR_32        = $(ROOT_MOD_DIR)
786: ROOT_DRV_DIR_32         = $(ROOT_MOD_DIR)/drv
787: ROOT_DTRACE_DIR_32      = $(ROOT_MOD_DIR)/dtrace
788: ROOT_EXEC_DIR_32        = $(ROOT_MOD_DIR)/exec
789: ...
790: 
791: }}}
792: 
793: {{{
794: 
795: ROOT_KERN_DIR_64        = $(ROOT_MOD_DIR)/$(SUBDIR64)
796: ROOT_DRV_DIR_64         = $(ROOT_MOD_DIR)/drv/$(SUBDIR64)
797: ROOT_DTRACE_DIR_64      = $(ROOT_MOD_DIR)/dtrace/$(SUBDIR64)
798: ROOT_EXEC_DIR_64        = $(ROOT_MOD_DIR)/exec/$(SUBDIR64)
799: ...
800: 
801: }}}
802: 
803:  And finally the selection of either the 32- or 64-bit directory based on the actual bitness of this build:
804: 
805: {{{
806: 
807: ROOT_KERN_DIR           = $(ROOT_KERN_DIR_$(CLASS))
808: ROOT_DRV_DIR            = $(ROOT_DRV_DIR_$(CLASS))
809: ROOT_DTRACE_DIR         = $(ROOT_DTRACE_DIR_$(CLASS))
810: ROOT_EXEC_DIR           = $(ROOT_EXEC_DIR_$(CLASS))
811: ...
812: 
813: }}}
814: 
815:  There are similar definitions for USR_XXX_DIR based in $(ROOT)/usr/kernel. See usr/src/uts/Makefile.uts for the complete list of possible ROOT_ and USR_ installation directories.
816: 
817:  The rules for installing files into each of these directories are given in usr/src/uts/Makefile.targ:
818: 
819: {{{
820: 
821: $(ROOT_MOD_DIR)/%:      $(OBJS_DIR)/% $(ROOT_MOD_DIR) FRC
822: 	$(INS.file)
823: 
824: }}}
825: 
826: {{{
827: 
828: $(ROOT_DRV_DIR)/%:      $(OBJS_DIR)/% $(ROOT_DRV_DIR) FRC
829: 	$(INS.file)
830: ...
831: 
832: }}}
833: 
834:  These rules install the file currently located in $(OBJS_DIR), described in detail above, into the appropriate directory in the proto area.
835: 
836:  $(ROOT_CONFFILE) is the module’s configuration file (most commonly used for drivers), transformed into the proto area. The CONFFILE variables are defined in usr/src/uts/Makefile.uts:
837: 
838: {{{
839: 
840: CONFFILE                = $(MODULE).conf
841: SRC_CONFFILE            = $(CONF_SRCDIR)/$(CONFFILE)
842: ROOT_CONFFILE_32        = $(ROOTMODULE).conf
843: ROOT_CONFFILE_64        = $(ROOTMODULE:%/$(SUBDIR64)/$(MODULE)=%/$(MODULE)).conf
844: ROOT_CONFFILE           = $(ROOT_CONFFILE_$(CLASS))
845: 
846: }}}
847: 
848:  Each module’s Makefile defines CONF_SRCDIR to specify the location of the configuration file that should be installed on this platform. The asy makefile defines:
849: 
850: {{{
851: 
852: CONF_SRCDIR     = $(UTSBASE)/common/io
853: 
854: }}}
855: 
856:  which causes usr/src/uts/common/io/asy.conf to be installed in the proto area as /kernel/drv/asy.conf. Note that the configuration file installation directory does not depend on whether this is a 32- or 64-bit build.
857: 
858:  Note that although it is confusing, installation targets are always named ROOTMODULE, ROOT_CONFFILE, and so on, even if they are actually installed into one of the USR_ directories. This simplifies the higher-level makefiles.
859: 
860: === 3.2.7 Finding Sources for a Module
861: 
862:  As we’ve seen, the sources are derived from $(XXX_OBJS) and the included rules. Now, here’s the tricky part - finding where those sources are. The easiest way by far is to run make from the module’s object directory and observe the compilation commands that are run. The path to each source file will be included in the output. This is the simplest and recommended way to find which source files are needed to build a module. However, if this does not work (perhaps the makefile itself is buggy) or if you want to gain greater understanding, the rest of this section describes logical processes for finding source files.
863: 
864:  Since you know the basenames (they are simply the XXX_OBJS entries with .o replaced by .c) you can use a simple
865: 
866: {{{
867: 
868: $ find usr/src/uts -name asy.c
869: 
870: }}}
871: 
872:  Suppose you find two source files with the same name - which is actually used? There are two ways to figure this out. The lazy way is to use make -d to show you the exact dependencies being used. Alternatively, you could reason it out, starting with the fact that not all source files are used on your platform (i.e., usr/src/uts/sparc/* is not used by x86 builds), and then looking at the specific order of the rules in each Makefile.rules. The more specific rules are listed first and take precedence over later rules (in fact they all add a dependency to the specific object file in question, but since the rules all use $<, only the first dependency is actually used).
873: 
874:  Non-kernel source files are easier to locate, since the cmd and lib directories are generally organized with one subdirectory for each library or command, named accordingly. The major exceptions are cmd/sgs, which contains the entire binary tools subsystem, and cmd/cmd-inet, which contains most of the Berkeley networking commands and daemons as well as some additional network-related utilities, laid out in a BSD-style directory structure.
875: 
876: === 3.2.8 Source Files not Included
877: 
878:  Some sources used to build the branded Solaris product are not included in OpenSolaris. There are two main reasons for this:
879: 
880: * The source could be subject to third-party rights.
881:  Sun’s lawyers won’t let anyone talk about this. Not even a little bit. They do love explaining it themselves, though, so you should contact Sun’s legal department and ask there. We can’t help you. Sorry.
882: * The consolidation may not yet have been released.
883:  The OpenSolaris code base does not yet include all consolidations in Solaris, and some consolidations are still incomplete. See the program roadmap at [[http://opensolaris.org/os/about/roadmap/>>Main.roadmap]] and the downloads page at [[http://opensolaris.org/os/downloads/>>Main.downloads]] for information on the consolidations that interest you.
884: 
885:  To accommodate fully functional builds for ON, even though some sources are missing, a set of closed binaries are available, and the build system has been modified to make use of them. The makefile variable CLOSED_BUILD controls whether the build system will use the prebuilt closed binaries or look for the closed sources.
886: 
887:  CLOSED_BUILD is typically used in makefile lines that build up the list of modules or subdirectories that are to be built. Makefile lines that start with CLOSED_BUILD, e.g.,
888: 
889: {{{
890: 
891: $(CLOSED_BUILD)DCSUBDIRS += \
892: 	$(CLOSED)/cmd/pax
893: 
894: }}}
895: 
896:  are for use only when the closed sources are present.
897: 
898:  Sometimes a separate closed module list is built up, rather than adding to the open module list. This approach is used extensively in the kernel, as in
899: 
900: {{{
901: 
902: $(CLOSED_BUILD)CLOSED_DRV_KMODS	+= chxge
903: 
904: }}}
905: 
906:  Because this approach requires additional variables, the first approach is usually preferred. The second approach is used when the list needs to contain individual component names, rather than paths. For example, the kernel makefiles use the module names to construct a series of "-l" clauses for linting; that would be a lot messier if paths were used instead of module names.
907: 
908:  You shouldn’t normally need to set CLOSED_BUILD. Instead, bldenv(1) and nightly(1) set the environment variable CLOSED_IS_PRESENT, and the ON makefiles use this to set CLOSED_BUILD.
909: 
910:  The kernel provides an additional challenge, which is that many makefile rules and declarations are practically the same for both the open and closed source trees. To avoid duplication of code, the common text was put in shared makefiles (e.g., Makefile.sun4u.shared). When used for open code, the makefile variable $(UTSTREE) is set to $(UTSBASE). For closed code, it is set to $(UTSCLOSED).
OpenSolaris

Top Menu

Wiki code for The Source Tree, part 1

Search

Collectives

Community Group

Project

User Group

Subsites

Community Group on Pages
