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