Return to 3.t CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / smm / 02.config

Annotation of 43BSDReno/share/doc/smm/02.config/3.t, revision 1.1

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.