.Dd March 6, 2009
.Os Darwin
.Dt KEXTCACHE 8
.Sh NAME
.Nm kextcache
.Nd create kext cache files
.Sh SYNOPSIS
.Nm
.Ar mkext_option Op Ar filename
.Op Ar options
.Op Fl -
.Ar kext_or_directory Li \&.\|.\|.
.Nm
.Fl prelinked-kernel Ar filename
.Op Ar options
.Op Fl -
.Op Ar kext_or_directory Li \&.\|.\|.
.Nm
.Fl system-prelinked-kernel
.Op Ar options
.Op Fl -
.Op Ar kext_or_directory Li \&.\|.\|.
.Nm
.Fl system-caches
.Op Ar options
.Nm
.Fl update-volume Ar os_volume
.Op Ar options
.Sh DESCRIPTION
The
.Nm
program creates kext caches, which speed up kext loading operations.
It is invoked automatically as needed to rebuild system caches.
.Pp
.Em Caution:
Incorrect use of
.Nm
can render a volume incapable of startup.
Installers and administrators should not use this program
to update system kext caches.
Instead they should run
.Xr touch 1
on the
.Pa /System/Library/Extensions/
directory of the installation target volume after they have finished,
which causes the system to update all necessary kext caches.
See
.Dq "Apple Developer Technical Q&A QA1319: Installing an I/O Kit Kext Without Rebooting"
for information on updating kext caches on prior releases of Mac OS X.
.Pp
.Nm
creates several kinds of kext caches.
The first is the prelinked kernel (also known as a \*(Lqkernelcache\*(Rq),
which contains the kernel code
and the essential files (info dictionary and executable)
for an arbitrary set of kexts,
with kext executables linked for their run-time locations.
A prelinked kernel speeds early system startup
by collecting these many files in one place for the booter to locate,
and by having each kext linked in place and ready to start as needed.
To create or update a prelinked kernel, use the
.Fl prelinked-kernel
or
.Fl system-prelinked-kernel
option.
.Pp
Other kext caches collect specific data
from the info dictionaries of kexts.
There are many individual caches for specific subsets of data;
they care collectively called system info caches.
These caches are used to optimize disk I/O when working with kexts
during late system startup and beyond.
To update the system kext info caches for the root volume,
use the
.Fl system-caches
option.
.Pp
The last type of kext cache is the mkext cache,
which contains the essential files (info dictionary and executable)
for an arbitrary set of kexts;
executables are unrelocated.
Mkext is a legacy format that was used on prior releases of Mac OS X.
To create an mkext cache, use one of the
.Fl mkext ,
.Fl mkext1 ,
or
.Fl mkext2
options,
with appropriate filtering options, described below.
.Sh PRIMARY OPTIONS
You must specify one of these options to have
.Nm
do anything:
.Bl -tag -width -indent
.It Fl c [ Ar filename ] , Fl prelinked-kernel Ar [ filename ]
Create a prelinked kernel.
.Ar filename
is required unless this option is the last argument.
If this option is the last argument and no
.Ar filename
is given,
the startup prelinked kernel for the system is created.
See
.Fl all-loaded .
.It Fl system-prelinked-kernel
This option is a convenience to update the prelinked kernel
used for startup on the root volume,
with all kexts in the system extensions folder
that have been loaded to date.
This option implies
.Fl all-loaded .
.It Fl system-caches
Rebuild the info caches for system kexts on the root volume.
.It Fl u Ar os_volume , Fl update-volume Ar os_volume
Rebuild out-of-date caches and update any helper partitions associated
with
.Ar os_volume .
.Ar os_volume Ns Pa /System/Library/Caches/com.apple.bootstamps/
is used to track whether any helper partitions are up to date.
See
.Fl caches-only
and
.Fl force .
.Pp
Which caches are rebuilt depends on the Mac OS X release installed on
.Ar os_volume .
If
.Nm
cannot find or make sense of
.Ar os_volume Ns Pa /usr/standalone/bootcaches.plist
the volume is treated as if no caches need updating: success is returned.
.It Fl U Ar os_volume
Used by the system to update volumes during startup.
Not for use otherwise.
.It Fl m Ar filename , Fl mkext Ar filename
Create an mkext of the latest supported format.
.It Fl mkext1 Ar filename
Create an mkext of format 1, used on Mac OS X versions 10.5 (Leopard)
and earlier.
.It Fl mkext2 Ar filename
Create an mkext of format 2, used on Mac OS X version 10.6 (Snow Leopard).
.It Fl e , Fl system-mkext
This option is provided for legacy compatibility, and is simply an alias to
.Fl system-prelinked-kernel .
.El
.Sh PRELINKED KERNEL AND MKEXT FILTERING OPTIONS
These options restrict which kexts are included in a prelinked kernel or mkext.
The options
.Fl arch
and
.Fl bundle-id
select kexts by supported architecture and bundle identifier;
the remaining filtering options select kexts based on the value
of their OSBundleRequired property.
If these options are specified,
the cache will contain only kexts
whose OSBundleRequired property matches any of these options,
or whose OSBundleRequired property is
.Dq Root
or
.Dq Console .
.Pp
A prelinked kernel or mkext cache intended for a startup from a local disk
should be created with the
.Fl local-root
option, while a cache intended for startup from the network
should be created with the
.Fl network-root
option.
When creating a prelinked kernel,
if the
.Fl all-loaded
option is specified,
kexts requested by the kernel are always included
regardless of these filtering options.
.Bl -tag -width -indent
.It Fl a Ar arch , Fl arch Ar arch
Include in an mkext or prelinked kernel only kexts
loadable on
.Ar arch ,
thinning executables to that architecture before inclusion.
Multiple architectures are allowed;
in this case a multi-architecture file is created
containing an embedded cache
for each of the specified architectures.
If no architectures are specified,
a default set of architectures supported
by the current Mac OS X version is used (Mac OS X 10.6 and later).
.It Fl b Ar identifier , Fl bundle-id Ar identifier
Find the kext whose CFBundleIdentifier is
.Ar identifier
amongst known kexts and repository directories
and include it in the mkext or prelinked kernel.
The kext of the highest CFBundleVersion with the given identifier is used;
in the case of version ties,
the last such kext specified on the command line is used.
This option may be specified multiple times;
if so, the specified bundle identifiers select
a subset from all named repositories and kexts,
to which the remaining filters
described in this section are then applied.
.It Fl caches-only
With
.Fl update-volume ,
skips updating any helper partitions even if they appear out of to date.
.It Fl force
With
.Fl update-volume ,
rebuilds any helper partitions even if they appear up to date.
.It Fl Installer
Currently used with
.Fl update-volume
to trigger "best effort" behaviors for Apple's Installer.
.It Fl l , Fl local-root
Specifies that for directory arguments,
only extensions required for local disk boot
be included in a cache.
Kexts explicitly indicated by name or identifier
are included unconditionally;
to apply this filter to all kexts, use the
.Fl local-root-all
option.
.It Fl L , Fl local-root-all
Specifies that only extensions required for local disk boot
be included in a cache,
regardless of whether they are from a repository directory
or are explicitly indicated by name or identifier.
To apply this restriction only to kexts from repository directories, use the
.Fl local-root
option.
.It Fl n , Fl network-root
Specifies that for directory arguments,
only extensions required for network disk boot
be included in a cache.
Kexts explicitly indicated by name or identifier
are included unconditionally;
to apply this filter to all kexts, use the
.Fl network-root-all
option.
.It Fl N , Fl network-root-all
Specifies that only extensions required for network disk boot
be included in a cache,
regardless of whether they are from a repository directory
or are explicitly indicated by name or identifier.
To apply this restriction only to kexts from repository directories, use the
.Fl network-root
option.
.It Fl s , Fl safe-boot
Specifies that for directory arguments,
only extensions required for safe boot
be included in a cache.
Kexts explicitly indicated by name or identifier
are included unconditionally;
to apply this filter to all kexts, use the
.Fl safe-boot-all
option.
.It Fl S , Fl safe-boot-all
Specifies that only extensions required for safe boot
be included in a cache,
regardless of whether they are from a repository directory
or are explicitly indicated by name or identifier.
To apply this restriction only to kexts from repository directories, use the
.Fl safe-boot
option.
.El
.Sh OTHER OPTIONS AND ARGUMENTS
.Bl -tag -width -indent
.It Ar kext_or_directory
A kext bundle or a repository directory containing kexts
to consider for inclusion in an mkext or prelinked kernel.
The filtering options described under
.Dq PRELINKED KERNEL AND MKEXT FILTERING OPTIONS
select the individual kexts to be included in the archive.
If no filtering options are specified, then all kexts
named as arguments are included (this is probably not what you want).
.It Fl F
Run in low-priority mode, as when forked and executed by
.Xr kextd 8 .
(This used to actually fork, but no longer does, as
.Xr kextd 8
handles the forking.)
.It Fl f , Fl force
Used with
.Fl update-volume
to specify that all caches on a helper partition should be updated
regardless of cached timestamp information.
.It Fl h , Fl help
Print a help message describing each option flag and exit with a success result,
regardless of any other options on the command line.
.It Fl K Ar kernel_filename , Fl kernel Ar kernel_filename
The name of the kernel file to use as the base
of a prelinked kernel file (the default is
.Pa /mach_kernel Ns No ).
.It Fl q , Fl quiet
Quiet mode; print no informational or error messages.
.It Fl r , Fl all-loaded
When creating a prelinked kernel,
include all kexts in the system extensions folder
that have been loaded by the machine running
this command during this startup session.
This include kexts loaded and later unloaded.
.It Fl compressed
Compress the mkext or prelinked kernel (enabled by default).
.It Fl uncompressed
Do not compress the mkext or prelinked kernel.
If specified as the only other argument with
.Fl c ,
uncompresses an existing prelinked kernel file in place.
.It Fl symbols Ar symbol_directory
Generate symbols for every kext in the prelinked kernel and save them in
.Ar symbol_directory .
The directory must already exist.
Symbol files are named after the CFBundleIdentifier
of each kext with a
.Pa .sym
suffix attached.
.It Fl t , Fl print-diagnostics
If a kext has validation, authentication, or dependency resolution problems,
print them.
Note that tests are performed in three stages:
validation, authentication, and dependency resolution;
a failure at any stage can make tests in further stages impossible.
Thus, a kext with validation failures may have unreported
authentication problems or missing dependencies.
.It Fl v Li [ 0-6 | 0x#### Ns Li ] , Fl verbose Li [ 0-6 | 0x#### Ns Li ]
Verbose mode; print information about program operation.
Higher levels of verbosity include all lower levels.
By default
.Nm
prints only warnings and errors.
You can specify a level from 0-6,
or a hexadecimal log specification
(as described in
.Xr kext_logging 8 Ns No ).
The levels of verbose output are:
.Bl -tag -width "1 (or none)"
.It 0
Print only errors (that is, suppress warnings); see also
.Fl quiet .
.It 1 (or none)
Print basic information about program operation.
.It 2
Print basic information about program progress and files created.
.It 3
Print information about individual kexts;
for example, when a kext is added to or omitted from an archive.
.It 4
Print information about compression and architectures processed.
.It 5
Print debug-level information about internal operations.
.It 6
Identical to level 5 for
.Nm .
.El
.Pp
Unlike in other kext tools,
the
.Fl verbose
flag in
.Nm
applies to all kexts
(that is, it turns on hexadecimal bit 0x8 by default).
See
.Xr kext_logging 8
for more information on verbose logging.
.It Fl volume-root Ar path
When creating caches for a volume other than the root volume,
remove
.Ar path
from the beginning of absolute kext paths stored in the cache file.
This ensures that the kext paths stored in the kernel are accurate
when the caches are used for startup with that volume.
.It Fl z , Fl no-authenticate
Don't authenticate kexts.
This option is for convenience in building cache files.
Caches used for startup must have
proper ownership (root:wheel) and permissions (0644)
in order to be used by the system.
.It Fl -
End of all options. Only kext or directory names follow.
.El
.Sh FILES
.Bl -tag -width
.It Pa /System/Library/Extensions/
The standard system repository of kernel extensions.
.It Pa /System/Library/Caches/com.apple.kext.caches/
Contains all kext caches for a Mac OS X 10.6 system: prelinked kernel,
mkext, and system kext info caches.
.It Pa /mach_kernel
The default kernel file.
.It Pa /usr/standalone/bootcaches.plist
Describes specific kext cache files for a Mac OS X volume.
.It Pa /System/Library/Caches/com.apple.bootstamps/
Contains timestamp information about kext caches.
.El
.Sh DIAGNOSTICS
.Nm
exits with a zero status upon success.
Upon failure, it prints an error message
and exits with a nonzero status.
.Sh BUGS
Many single-letter options are inconsistent in meaning
with (or directly contradictory to) the same letter options
in other kext tools.
.Sh SEE ALSO
.Xr mkextunpack 8 ,
.Xr kext_logging 8 ,
.Xr kextd 8 ,
.Xr kextload 8 ,
.Xr kextutil 8 ,
.Xr kextstat 8 ,
.Xr kextunload 8