DragonFly On-Line Manual Pages
CACHE-INIT(1) User Contributed Perl Documentation CACHE-INIT(1)
NAME
cache-init -- Generate the portsindex cache by scanning the entire
ports tree
SYNOPSIS
cache-init [-hvqs] [-c dir] [-C file] [-T file] [-p dir] [-M file]...
[-m file]...
DESCRIPTION
cache-init scans over the entire ports tree to initialise the portindex
cache. The cache consists of a Berkeley DB Btree file, plus a
timestamp file showing when the cache contents were last modified. The
Btree file consistat of records indexed by the port origin directory
containing:
o The one-line port descriptions generated by "make describe".
o A list of all of the other Makefiles included by that port
Makefile from within /usr/ports (or $PORTSDIR if it is set in
the environment). Any Makefiles included in the
"UbiquitousMakefiles" or "EndemicMakefiles" lists will be
ommitted from the record.
o A record of the sub-directories at the top level (ie
categories) and the ports within each category, based on the
value of the "SUBDIR" variable.
cache-init is used to bootstrap the portindex data cache on a new
system. It only needs to be run once, after which cache-update may be
used to apply incremental updates to the data cache. As cache-init is
fairly slow to execute, dealing as it does with some 17,500 separate
ports, running it repeatedly is a handy way to waste a great deal of
time.
cache-init will preserve a backup copy of any pre-existing cache files
by renaming them with a .old suffix.
When to run cache-init and when to run cache-update
Over time, successively updating the INDEX file via cache-update can
inevitably produce minor inconsistencies and an INDEX file that
diverges slowly from equivalence to what "make index" would produce.
For best results it will be necessary to occasionally re-run cache-init
and rebuild the cache from scratch. Certain changes to your system
should act as warning flags that this needs to be considered.
o Modifications to ubiquitously included makefiles such as
/etc/make.conf or /usr/ports/Mk/bsd.port.mk. cache-update will
compare timestamps on these files with the cache timestamp and
attempt to warn you when a re-initialisation might be a good
idea.
Technically there are several other makefiles which will always
be included any time make is invoked within the ports system,
but no warnings will be generated for those files. They rarely
change, and when they do, the changes are unlikely to have any
material effect on the ports INDEX.
cache-init accepts the same "UbiquitousMakefiles" and
"EndemicMakefiles" configuration options as cache-update (or
the equivalent command line options). However, for cache-init
the effect is different. All that happens is that none of the
Makefile names mentioned in those lists will be included in the
cached data.
o Modifying the environment between successive runs of cache-
update. make variables can be set from the environment,
although in most cases using /etc/make.conf would generally be
a better idea. There are two things that can be done to
prevent this causing problems. Firstly, the configuration file
can contain live Perl code: you can modify the environment of
the process by manipulating the global %ENV hash from within
the configuration file. Secondly both cache-init and cache-
update obey a "--scrub-environment" command line flag, and the
equivalent "ScrubEnvironment" configuration file setting, which
deletes everything from the environment except for certain
standard variables. As command line options generally override
configuration files, "--scrub-environment" will trump modifying
%ENV.
o Installing or updating certain software packages. For
instance, the simple presence of the Gnome libraries on the
system will cause many packages to add a "-gnome" suffix to
their names. The editors/vim port is a good example of this
behaviour. Ports containing Linux software run under emulation
will automatically detect which version of the linux-base ports
you have installed: changing to a different linux-base port
will affect the dependency lists for all Linux software ports.
Unfortunately it is practically impossible to detect such
changes and automatically update affected ports. These are not
the only two examples of such behaviour.
Configuration Files
cache-init shares configuration files with cache-update, find-updated
and portindex. Any configuration settings are taken from the following
locations, where the later items on this list override the earlier:
o Built-in settings from the FreeBSD::Portindex::Config perl
module.
o The system wide configuration file /usr/local/etc/portindex.cfg
o The per-user configuration file ${HOME}/.portindexrc. This file
is ignored if the process is run as root.
o The local configuration file, found in the current working
directory of the cache-init process ./.portindexrc. This file
is ignored if the process is run as root.
o The program command line.
All of the configuration files are optional. A summary of the
resultant configuration options including the effect of any command
line settings is printed as part of the help text when cache-init is
invoked with the "-h" option.
OPTIONS
-h
--help Print a brief usage message and a summary of the configuration
settings after command line processing and then exit.
-v
--verbose
Turn on verbose output printed to "STDERR". This is the
default.
-q
--quiet
--noverbose
Turn off verbose output to "STDERR". Using both the -v amd -q
options together does not make any sense, but neither does it
generate an error. The last mentioned of the two options will
prevail.
-s
--scrub-environment
Delete all environment variables except for $USER, $HOME,
$PATH, $SHELL, $TERM and $TERMCAP. This provides a
standardized environment for "make describe" and other sub-
processes.
--noscrub-environment
Turn off environment scrubbing. All environment variables will
be passed through intact to "make describe" and other sub-
processes. This is the default.
-c dir
--cache-dir=dir
The location of the portindex data cache, by default
/var/db/portindex.
-C file
--cache-file=file
Berkeley DB Btree file containing the cached output of the
equivalent of running "make describe" plus "make -V
.MAKEFILE_LIST" for all of the ports in the tree and and "make
-V SUBDIR" for all of the categories -- instead of actually
running "make describe", this program extracts the values of a
series of "make" variables and generates the "make describe"
output itself, internally. This file name will be relative to
the cache directory (-c option above) unless an absolute path
is given. Defaults to portindex-cache.db.
-T file
--timestamp-file=file
A file within the cache directory whose modification time marks
the last time that data was modified in or added to the cache.
Defaults to portsindex-timestamp.
-p dir
--ports-dir=dir
The location of the ports tree. Almost always defaults to
/usr/ports unless $PORTSDIR is set in the environment.
-M file
--ubiquitous-makefile file
-m file
--endemic-makefile file
These options both have exactly the same effect for cache-init,
and are only provided separately for compatability with cache-
update. Do not include the named makefile in the data cache as
a trigger for re-checking the "make describe" output for any
ports. Non absolute paths will be taken as relative to
"PortsDir". Repeat the option to add more makefiles to the
list. Default values are: (UbiquitousMakefiles)
/etc/make.conf, ${PORTSDIR}/Mk/bsd.port.mk (EndemicMakefiles)
${PORTSDIR}/Mk/bsd.sites.mk, ${PORTSDIR}/Mk/bsd.commands.mk,
${PORTSDIR}/Mk/bsd.destdir.mk.
FILES
/usr/ports The default ports directory.
/var/db/portindex
The location of the data cache.
portindex-cache.db
Btree file containing cached "make describe" and other
output.
__db.001, __db.002, __db.003, __db.004
Files used as part of the internal workings of
BerkeleyDB, for memory pool management and DB locking.
Will be recreated automatically if deleted.
portindex-timestamp
This file contains the last time and date that the
cache was updated or modified.
/usr/local/etc/portindex.cfg
System-wide configuration file.
${HOME}/.portindexrc
Per-user configuration file
./.portindexrc Local configuration file
SEE ALSO
portindex(1), cache-update(1), find-updated(1), cvsup(1), ports(7)
BUGS
cache-init is quite a lot slower than "make index". Possible
improvements include running several "make describe" processes
concurrently.
cache-init should optionally parse the contents of
/usr/local/etc/pkgtools.conf and apply settings from the "MAKE_ENV"
array.
perl v5.20.2 2012-02-08 CACHE-INIT(1)