idbuild(1M)
idbuild --
build new UNIX system base kernel or configure loadable modules
Synopsis
/etc/conf/bin/idbuild [-B] [-#] [-K] [-Q] [[-I include-path] . . .]
[-O output-file] [-S] [[-M module-name] . . .] [-x]
[[-D symbol] . . .] [[-U symbol] . . .]
[-C] [-F] [-x] [-c] [-n]
Description
One of the ID/TP (Installable Driver/Tunable Parameters)
kernel configuration tools,
idbuild builds a UNIX system base kernel
and/or configures loadable kernel modules
using the current system configuration in
$ROOT/$MACH/etc/conf.
idbuild uses the environment variables
$ROOT and $MACH
from the user's environment to compose its starting path
as $ROOT/$MACH.
Except for the special case of kernel development in a non-root
source tree, the shell variable $ROOT
should always be set to null or to ``/'';
if $ROOT is null or ``/'', $MACH is
ignored (treated as null).
Before idbuild uses the system configuration,
it calls
idconfupdate(1M)
to synchronize the resource manager database
and the sdevice files.
Options
idbuild takes the following options:
-B-
Rebuild the kernel immediately.
If any other options are used, it is not necessary to
specify this one.
-C-
Always clean temporary files
if the -K option is not set,
regardless of available space.
Without -C or -K,
temporary files are cleaned only if space is low.
-#-
Print debugging information.
-F-
Force a full rebuild, ignoring modification times.
Without this option,
only out-of-date components are rebuilt.
This option is not normally required
and will be removed in a later release.
-K-
Keep the temporary configuration files and
object modules created by idbuild.
This can allow you to perform a
quick rebuild using the -Q option.
-Q-
Perform a quick build, where some of the
normal processing and compilation of configuration-dependent
files is skipped.
To use the quick build option, you must have the temporary
configuration files and object modules from the last rebuild
of the kernel, which are kept when you use the -K
option for a normal build.
Use the quick build option with caution.
The use of this option precludes the use of the other
configuration options, except for -#, -K,
-O, -l.
This option should not normally be required
and will be removed in a later release.
-I include-path-
Search the specified directory for #include files
before searching the default directory,
$ROOT/usr/include.
This option can be repeated on the command line
as many times as needed to list all the directories to be
searched.
-O output-file-
Place the kernel in output-file rather than placing it
in the default file $ROOT/$MACH/etc/conf/cf.d/unix.
-S-
Statically link all the configured kernel modules
into the base kernel.
-M module-name-
Configure the specified loadable kernel module and put it
into the
$ROOT/$MACH/etc/conf/mod.d directory,
using a file named the same as the module.
The -M option can be repeated on the command line
as many times as needed to include all the required modules.
More details about using this option are listed below.
-c-
Supress checks of the
System(4dsp)
files in the sdevice directory.
Sdevice file information is ignored.
All modules are assumed to be configured
into the system.
Modules capable of being loadable
are configured loadable.
No resource conflict checking is done.
-n-
No build.
Check for configuration and symbol errors,
but do not actually build any modules.
No changes are made to any files.
Like -c,
all modules are assumed to be configured
into the system.
Implies the -S option.
-x-
Limit the symbol table information attached to
the newly generated kernel
to the global symbols.
-D symbol-
In addition to the standard symbols, #define
the specified symbol
when configuration-dependent files are compiled.
This option can be repeated on the command line
as many times as needed to specify all the required symbols.
-U symbol-
#undef for the specified symbol when the
configuration-dependent files are compiled, even if the
symbol normally would be defined.
The -U option overrides any -D option specified
for the same symbol, and
can be repeated on the command line
as many times as needed to specify all the undefined symbols.
Usage
Building a UNIX system kernel consists of three steps.
First, configuration tables and symbols,
and module lists are generated
from the configuration data files.
Second, configuration-dependent files are compiled,
and then these are linked together with all of the configured
kernel and device driver object modules.
Third, if the loadable kernel module feature or a kernel debugger is
enabled, kernel symbol table information is attached to the kernel.
The kernel is, by default, placed in
$ROOT/$MACH/etc/conf/cf.d/unix.
If the kernel build is successful and $ROOT is
null or ``/'', idbuild
sets a flag to instruct the system shutdown/reboot sequence
to replace the standard kernel in /stand/unix
with the new kernel.
Then, another flag will be set
to cause the environment (device special files, /etc/inittab,
and so on)
to be reconfigured accordingly.
If one or more loadable kernel modules are specified
with the -M
option, idbuild will configure only the specified loadable
kernel modules and put them into the
$ROOT/$MACH/etc/conf/mod.d
directory.
Otherwise, a UNIX system base
kernel is rebuilt with all the loadable modules reconfigured into
the
$ROOT/$MACH/etc/conf/modnew.d directory, which will be
changed to /etc/conf/mod.d at
the next system reboot if $ROOT
is null or ``/''
(see
modadmin(1M)).
If a loadable module has already been loaded, but to another
major device range, you can either unload the module and then
use idbuild with the -M option, or use idbuild
without the -M option and reboot the system.
If you attempt to use the -M option for a module
already loaded at another major device range, idbuild
will fail with error ENXIO.
When loadable kernel modules are configured with the -M
option,
idbuild also creates the necessary nodes
in the /dev directory,
adding and activating /etc/inittab entries
if any Init file is
associated with the modules, and registering the modules to the running
kernel.
This makes them available for dynamic
loading without requiring a system reboot.
Base kernel rebuilds are usually needed after a statically linked
kernel module is installed, when any static module is removed,
or when system tunable parameters are modified.
If you execute idbuild without any options and if the environment
variable $ROOT
is null or ``/'', a flag is set and the
kernel rebuild is deferred to next system reboot.
Files
The configuration data files needed
as input for each module are described in:
Autotune(4dsp)
Init(4dsp)
Master(4dsp)
Mtune(4dsp)
Node(4dsp)
Rc(4)
Sd(4)
System(4dsp)
Space.c(4dsp)
Stubs.c(4dsp)
These files must be installed in
$ROOT/$MACH/etc/conf using
idinstall(1M)
prior to invoking idbuild.
In addition,
idbuild expects the following files
to be in $ROOT/$MACH/etc/conf/cf.d:
deflist-
This file contains a list of extra
cc(1)
arguments to use when
compiling configuration-dependent files
(including Space.c files);
these should be of the
-Dxxxxxxx
or
-Uxxxxxxx,
where xxxxxxx is used to define or
undefine platform-specific pre-processor symbols (for
example, -Dat386 or -Dhector).
This file is provided as part
of the base system and should not be modified.
kernmap-
This platform-specific mapfile is passed to
ld(1)
to control
the kernel linking.
This file is provided as part of the base system
and should not be modified.
stune-
This file contains site-specific tunable parameter values.
You should access the stune file using
idtune(1M).
Exit codes
Since idbuild
calls other system commands to perform the system reconfiguration,
link editing, and symbol table set up, it will report all errors
encountered by those commands.
In general, the exit value 1 indicates an error was encountered by
idbuild and the exit value 0 indicates success.
The errors encountered fall into the following categories:
-
configuration data file error messages from
idbuild(1M)
-
compiler and link-editor error messages from
cc(1)
and
ld(1)
If, when loading a module using the -M option, a
driver module is already loaded at a different major device
range, the idbuild command will fail with the error
ENXIO.
In this instance, idbuild reports
that module configuration is completed, meaning that the
configuration completed with a failure condition.
In this instance, the module load has still failed.
A description of what to do if this happens follows in the
next section of this manual page.
If the idinstall of a particular module fails during
reconfiguration, a message is displayed indicating the
failure, then the reconfiguration continues.
References
Dtune(4dsp),
Ftab(4dsp),
idconfupdate(1M),
idinstall(1M),
idmkinit(1M),
idtune(1M),
Init(4dsp),
Interface(4dsp),
Master(4dsp),
Mtune(4dsp),
Node(4dsp),
Rc(4),
Sd(4),
Space.c(4dsp),
Stubs.c(4dsp),
stune(4dsp),
System(4dsp)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004