Commit | Line | Data |
---|---|---|
b8b2a7ff KM |
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 | .\" | |
57349e41 | 5 | .\" @(#)3.t 6.2 (Berkeley) %G% |
b8b2a7ff | 6 | .\" |
57349e41 MK |
7 | .\".ds RH "System Building Process |
8 | .ne 2i | |
9 | .NH | |
10 | SYSTEM BUILDING PROCESS | |
b8b2a7ff KM |
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 | |
57349e41 MK |
28 | configured system with |
29 | .I make depend | |
30 | using | |
31 | .IR make (1). | |
b8b2a7ff KM |
32 | .IP 5) |
33 | Compile and load the system with | |
57349e41 | 34 | .IR make . |
b8b2a7ff KM |
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 | |
57349e41 MK |
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. | |
b8b2a7ff KM |
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 | |
57349e41 MK |
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 | |
b8b2a7ff | 67 | .I config |
57349e41 MK |
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. | |
b8b2a7ff | 72 | .PP |
57349e41 | 73 | When building the configuration file, be sure to include the items |
b8b2a7ff KM |
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) | |
57349e41 MK |
105 | in compiling and loading the system, |
106 | .IR Makefile . | |
b8b2a7ff | 107 | .IP \(bu 3 |
57349e41 MK |
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, | |
b8b2a7ff KM |
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 | |
57349e41 | 119 | A file containing the I/O configuration tables used by the system |
b8b2a7ff KM |
120 | during its |
121 | .I autoconfiguration | |
57349e41 MK |
122 | phase, |
123 | .IR ioconf.c . | |
b8b2a7ff KM |
124 | .IP \(bu 3 |
125 | An assembly language file of interrupt vectors which | |
57349e41 MK |
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. | |
b8b2a7ff KM |
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 | |
57349e41 MK |
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. | |
b8b2a7ff KM |
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. | |
57349e41 MK |
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. | |
b8b2a7ff KM |
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 | |
57349e41 | 197 | \fInetstat\fP\|(1) and \fIvmstat\fP\|(1), |
b8b2a7ff KM |
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 | |
57349e41 | 219 | configuration dependent; most of the modules in the directory ``/sys/sys'' |
b8b2a7ff KM |
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 | |
57349e41 MK |
224 | linking the system, type ``make links'' in the system compilation directory. |
225 | This will cause the system | |
b8b2a7ff KM |
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 | |
57349e41 MK |
236 | to modify this file to reflect local needs. Note further that |
237 | interdependencies which are not directly visible | |
b8b2a7ff KM |
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 | |
57349e41 | 250 | number of invocations of each routine. The \fIgprof\fP |
b8b2a7ff KM |
251 | command will also generate a dynamic call graph of the executing |
252 | system and propagate time spent in each routine along the arcs | |
57349e41 | 253 | of the call graph (consult the \fIgprof\fP documentation for elaboration). |
b8b2a7ff | 254 | The program counter sampling can be driven by the system clock, or |
57349e41 MK |
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. | |
b8b2a7ff KM |
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. |