![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to 3.t CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / smm / 02.config|
Return to 3.t CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / smm / 02.config |
1.1 root 1: .\" Copyright (c) 1983 Regents of the University of California.
2: .\" All rights reserved. The Berkeley software License Agreement
3: .\" specifies the terms and conditions for redistribution.
4: .\"
5: .\" @(#)3.t 6.2 (Berkeley) 6/3/86
6: .\"
7: .\".ds RH "System Building Process
8: .ne 2i
9: .NH
10: SYSTEM BUILDING PROCESS
11: .PP
12: In this section we consider the steps necessary to build a bootable system
13: image. We assume the system source is located in the ``/sys'' directory
14: and that, initially, the system is being configured from source code.
15: .PP
16: Under normal circumstances there are 5 steps in building a system.
17: .IP 1) 3
18: Create a configuration file for the system.
19: .IP 2) 3
20: Make a directory for the system to be constructed in.
21: .IP 3) 3
22: Run
23: .I config
24: on the configuration file to generate the files required
25: to compile and load the system image.
26: .IP 4)
27: Construct the source code interdependency rules for the
28: configured system with
29: .I make depend
30: using
31: .IR make (1).
32: .IP 5)
33: Compile and load the system with
34: .IR make .
35: .PP
36: Steps 1 and 2 are usually done only once. When a system configuration
37: changes it usually suffices to just run
38: .I config
39: on the modified configuration file, rebuild the source code dependencies,
40: and remake the system. Sometimes,
41: however, configuration dependencies may not be noticed in which case
42: it is necessary to clean out the relocatable object files saved
43: in the system's directory; this will be discussed later.
44: .NH 2
45: Creating a configuration file
46: .PP
47: Configuration files normally reside in the directory ``/sys/conf''.
48: A configuration file is most easily constructed by copying an
49: existing configuration file and modifying it. The 4.3BSD distribution
50: contains a number of configuration files for machines at Berkeley;
51: one may be suitable or, in worst case, a copy
52: of the generic configuration file may be edited.
53: .PP
54: The configuration file must have the same name as the directory in
55: which the configured system is to be built.
56: Further,
57: .I config
58: assumes this directory is located in the parent directory of
59: the directory in which it
60: is run. For example, the generic
61: system has a configuration file ``/sys/conf/GENERIC'' and an accompanying
62: directory named ``/sys/GENERIC''.
63: Although it is not required that the system sources and configuration
64: files reside in ``/sys,'' the configuration and compilation procedure
65: depends on the relative locations of directories within that hierarchy,
66: as most of the system code and the files created by
67: .I config
68: use pathnames of the form ``../''.
69: If the system files are not located in ``/sys,''
70: it is desirable to make a symbolic link there for use in installation
71: of other parts of the system that share files with the kernel.
72: .PP
73: When building the configuration file, be sure to include the items
74: described in section 2. In particular, the machine type,
75: cpu type, timezone, system identifier, maximum users, and root device
76: must be specified. The specification of the hardware present may take
77: a bit of work; particularly if your hardware is configured at non-standard
78: places (e.g. device registers located at funny places or devices not
79: supported by the system). Section 4 of this document
80: gives a detailed description of the configuration file syntax,
81: section 5 explains some sample configuration files, and
82: section 6 discusses how to add new devices to
83: the system. If the devices to be configured are not already
84: described in one of the existing configuration files you should check
85: the manual pages in section 4 of the UNIX Programmers Manual. For each
86: supported device, the manual page synopsis entry gives a
87: sample configuration line.
88: .PP
89: Once the configuration file is complete, run it through
90: .I config
91: and look for any errors. Never try and use a system which
92: .I config
93: has complained about; the results are unpredictable.
94: For the most part,
95: .IR config 's
96: error diagnostics are self explanatory. It may be the case that
97: the line numbers given with the error messages are off by one.
98: .PP
99: A successful run of
100: .I config
101: on your configuration file will generate a number of files in
102: the configuration directory. These files are:
103: .IP \(bu 3
104: A file to be used by \fImake\fP\|(1)
105: in compiling and loading the system,
106: .IR Makefile .
107: .IP \(bu 3
108: One file for each possible system image for this machine,
109: .IR swapxxx.c ,
110: where
111: .I xxx
112: is the name of the system image,
113: which describes where swapping, the root file system, and other
114: miscellaneous system devices are located.
115: .IP \(bu 3
116: A collection of header files, one per possible device the
117: system supports, which define the hardware configured.
118: .IP \(bu 3
119: A file containing the I/O configuration tables used by the system
120: during its
121: .I autoconfiguration
122: phase,
123: .IR ioconf.c .
124: .IP \(bu 3
125: An assembly language file of interrupt vectors which
126: connect interrupts from the machine's external buses to the main
127: system path for handling interrupts,
128: and a file that contains counters and names for the interrupt vectors.
129: .PP
130: Unless you have reason to doubt
131: .IR config ,
132: or are curious how the system's autoconfiguration scheme
133: works, you should never have to look at any of these files.
134: .NH 2
135: Constructing source code dependencies
136: .PP
137: When
138: .I config
139: is done generating the files needed to compile and link your system it
140: will terminate with a message of the form ``Don't forget to run make depend''.
141: This is a reminder that you should change over to the configuration
142: directory for the system just configured and type ``make depend''
143: to build the rules used by
144: .I make
145: to recognize interdependencies in the system source code.
146: This will insure that any changes to a piece of the system
147: source code will result in the proper modules being recompiled
148: the next time
149: .I make
150: is run.
151: .PP
152: This step is particularly important if your site makes changes
153: to the system include files. The rules generated specify which source code
154: files are dependent on which include files. Without these rules,
155: .I make
156: will not recognize when it must rebuild modules
157: due to the modification of a system header file.
158: The dependency rules are generated by a pass of the C preprocessor
159: and reflect the global system options.
160: This step must be repeated when the configuration file is changed
161: and
162: .I config
163: is used to regenerate the system makefile.
164: .NH 2
165: Building the system
166: .PP
167: The makefile constructed by
168: .I config
169: should allow a new system to be rebuilt by simply typing ``make image-name''.
170: For example, if you have named your bootable system image ``vmunix'',
171: then ``make vmunix''
172: will generate a bootable image named ``vmunix''. Alternate system image names
173: are used when the root file system location and/or swapping configuration
174: is done in more than one way. The makefile which
175: .I config
176: creates has entry points for each system image defined in
177: the configuration file.
178: Thus, if you have configured ``vmunix'' to be a system with the root file
179: system on an ``hp'' device and ``hkvmunix'' to be a system with the root
180: file system on an ``hk'' device, then ``make vmunix hkvmunix'' will generate
181: binary images for each.
182: As the system will generally use the disk from which it is loaded
183: as the root filesystem, separate system images are only required
184: to support different swap configurations.
185: .PP
186: Note that the name of a bootable image is different from the system
187: identifier. All bootable images are configured for the same system;
188: only the information about the root file system and paging devices differ.
189: (This is described in more detail in section 4.)
190: .PP
191: The last step in the system building process is to rearrange certain commonly
192: used symbols in the symbol table of the system image; the makefile
193: generated by
194: .I config
195: does this automatically for you.
196: This is advantageous for programs such as
197: \fInetstat\fP\|(1) and \fIvmstat\fP\|(1),
198: which run much faster when the symbols they need are located at
199: the front of the symbol table.
200: Remember also that many programs expect
201: the currently executing system to be named ``/vmunix''. If you install
202: a new system and name it something other than ``/vmunix'', many programs
203: are likely to give strange results.
204: .NH 2
205: Sharing object modules
206: .PP
207: If you have many systems which are all built on a single machine
208: there are at least two approaches to saving time in building system
209: images. The best way is to have a single system image which is run on
210: all machines. This is attractive since it minimizes disk space used
211: and time required to rebuild systems after making changes. However,
212: it is often the case that one or more systems will require a separately
213: configured system image. This may be due to limited memory (building
214: a system with many unused device drivers can be expensive), or to
215: configuration requirements (one machine may be a development machine
216: where disk quotas are not needed, while another is a production machine
217: where they are), etc. In these cases it is possible
218: for common systems to share relocatable object modules which are not
219: configuration dependent; most of the modules in the directory ``/sys/sys''
220: are of this sort.
221: .PP
222: To share object modules, a generic system should be built. Then, for
223: each system configure the system as before, but before recompiling and
224: linking the system, type ``make links'' in the system compilation directory.
225: This will cause the system
226: to be searched for source modules which are safe to share between systems
227: and generate symbolic links in the current directory to the appropriate
228: object modules in the directory ``../GENERIC''. A shell script,
229: ``makelinks'' is generated with this request and may be checked for
230: correctness. The file ``/sys/conf/defines'' contains a list of symbols
231: which we believe are safe to ignore when checking the source code
232: for modules which may be shared. Note that this list includes the definitions
233: used to conditionally compile in the virtual memory tracing facilities, and
234: the trace point support used only rarely (even at Berkeley).
235: It may be necessary
236: to modify this file to reflect local needs. Note further that
237: interdependencies which are not directly visible
238: in the source code are not caught. This means that if you place
239: per-system dependencies in an include file, they will not be recognized
240: and the shared code may be selected in an unexpected fashion.
241: .NH 2
242: Building profiled systems
243: .PP
244: It is simple to configure a system which will automatically
245: collect profiling information as it operates. The profiling data
246: may be collected with \fIkgmon\fP\|(8) and processed with
247: \fIgprof\fP\|(1)
248: to obtain information regarding the system's operation. Profiled
249: systems maintain histograms of the program counter as well as the
250: number of invocations of each routine. The \fIgprof\fP
251: command will also generate a dynamic call graph of the executing
252: system and propagate time spent in each routine along the arcs
253: of the call graph (consult the \fIgprof\fP documentation for elaboration).
254: The program counter sampling can be driven by the system clock, or
255: if you have an alternate real time clock, this can be used. The
256: latter is highly recommended, as use of the system clock will result
257: in statistical anomalies, and time spent in the clock routine will
258: not be accurately attributed.
259: .PP
260: To configure a profiled system, the
261: .B \-p
262: option should be supplied to \fIconfig\fP.
263: A profiled system is about 5-10% larger in its text space due to
264: the calls to count the subroutine invocations. When the system
265: executes, the profiling data is stored in a buffer which is 1.2
266: times the size of the text space. The overhead for running a
267: profiled system varies; under normal load we see anywhere from 5-25%
268: of the system time spent in the profiling code.
269: .PP
270: Note that systems configured for profiling should not be shared as
271: described above unless all the other shared systems are also to be
272: profiled.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.