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