CACHE-UPDATE(1) User Contributed Perl Documentation CACHE-UPDATE(1)NAMEcache-update-- Incrementally update the portindex cache
SYNOPSIScache-update [-hvqs] [-c dir] [-C file] [-T file] [-p dir] [-d dir] [-f
format] [-P num] [-i file] [-M file]... [-m file]...
DESCRIPTIONcache-update processes a list of port origins, regenerating the index
("make describe") and Makefile dependency data ("make -V
.MAKEFILE_LIST") or sub-directory list ("make -V SUBDIR") for
categories from each of them, and updating the record of thst data held
in the portindex cache. If cache-update is passed a port origin that
no longer exists, it will delete any corresponding record from the
cache. To handle a port that has been moved, it is necessary to pass
cache-update both the old and the new locations of the port for
processing.
The list of ports to be processed by cache-update may be supplied in
three formats, together with two modifiers that add scanning of certain
other files:
cache Uses the cached timestamps for all Makefiles and pkg-descr
files within the ports tree, and various other Makefiles
elsewhere in the filesystem: any file that could affect the
resultant INDEX. While this option is processed as if it were
an input format, that is misleading. When using -f cache, no
input file is read.
cache cannot be combined with any of the other input format
options.
cache is the default input format.
plain A list of port origin directories, one per line. The output of
portsnap update can be passed directly to cache-update or find-
updated may be used to generate a list in this format. The
generated list of ports to check for updates includes all
listed in the input, plus all ports that are slave ports of
those listed in the input, or ports that include any Makefile
listed in the input.
svn-up The output from running svn update to update a checked-out copy
of the ports tree.
options cache-update will search the directory tree where port options
settings are stored. It will compare the timestamps on the
options files it finds with the timestamps recorded in the
cache of the last time the data for that port was updated. If
the port options have been updated more recently than the cache
data, the cache entry is refreshed.
other cache-update will check the last modification time on a number
of makefiles outside "PORTSDIR" and "PORT_DBDIR", and if they
differ from the values stored in the cache, will cause a check
for updates of any port that includes the makefile.
The options format processing may also be combined with any of the
first three formats. The following combinations are recognised in
addition to the single options above:
plain,options
plain,options,other
plain,other
svn-up,options
svn-up,options,other
svn-up,other
options,other
Where an update to a Makefile or pkg-descr is detected, all ports where
that file is included will be added to the list of ports to reprocess.
In certain circumstances it may be more advantageous to run cache-init
rather than cache-update.
When to run cache-init and when to run cache-update
Over time, successively updating the INDEX file via cache-update can
produce minor inconsistencies and an INDEX file that diverges slowly
from equivalence to what starting afresh 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 warnings that this needs to be done.
· Modifications to ubiquitously included makefiles such as
/etc/make.conf or /usr/ports/Mk/bsd.port.mk are handled
specially. cache-update will compare timestamps on these files
with the cache timestamp and attempt to warn you when they
change. If so, cache re-initialisation might be a good idea.
It won't automatically reinitialise, as that's an expensive
operation and frequently not necessary despite any changes to
an unbiquitous makefile.
The list of ubiquitous makefiles to test in this manner can be
set for cache-init using the "--ubiquitous-makefile" command
line option or "UbiquitousMakefiles" configuration file. These
values are built into the cached data. If you want to change
them, it will be necessary to rerun cache-init.
The "--endemic-makefile" option or "EndemicMakefiles"
configuration file setting is used by cache-init in the same
manner. It lists makefiles where changes should have no effect
on the outcome of generating the INDEX at all. Being marked as
endemic will cause changes to that makefile to be ignored,
suppressing the warning on changes if the makefile is also
marked ubiquitous, or preventing cache-update rechecking and
updating the cached data otherwise.
There are a number of additional makefiles located outside
/usr/ports ($PORTSDIR) or /var/db/ports ($PORT_DBDIR) which can
be included when make is invoked by the ports system. These are
recorded by cache-init and by default any such makefiles will
be checked for modification by cache-update. New instances of
such files may not be picked up immediately on update, unless
at least one of the ports that includes it is also modified.
· Modifying the environment between successive runs of cache-
update. make variables can often be set from the environment,
although 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 processes 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.
· 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 an 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-update shares configuration files with cache-init, find-updated
and portindex. Any configuration settings are taken from the following
locations, where the later items on this list override the earlier:
· Built-in settings from the FreeBSD::Portindex::Config perl
module.
· The system wide configuration file /usr/local/etc/portindex.cfg
· The per-user configuration file ${HOME}/.portindexrc. This file
is ignored if the process is run as root.
· 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.
· 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 and processed
values of a number of "make" variables for all of the ports in
the tree. 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.
-d dir
--port-dbdir=dir
Where the "OPTIONS" settings for ports are stored. Almost
always defaults to /var/db/ports unless $PORT_DBDIR is set in
the environment.
-i file
--input=file
Filename to read in order to generate the list of ports for
which the "make describe" data needs to be reprocessed. -
means read from STDIN, which is the default.
-f { cache | plain | svn-up | options | plain,options | svn-up,options
| plain,other | svn-up,other | plain,options,other |
svn-up,options,other }
--format={ plain | ... }
Which input formats cache-update should parse to determine the
list of ports to reprocess. Default: cache
FILES
/usr/ports The default ports directory.
/var/db/portindex
The location of the data caches.
portindex-cache.db
Btree file containing cached "make describe" and other
output.
portindex-timestamp
This file contains the last time and date that the
cache was updated or modified.
__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.
/usr/local/etc/portindex.cfg
System-wide configuration file.
${HOME}/.portindexrc
Per-user configuration file
./.portindexrc Local configuration file
SEE ALSOcache-init(1), portindex(1), find-updated(1), cvsup(1), ports(7)BUGS
cvsup-checkouts format mode is not completely accurate. Choosing the
correct propagation delay is a matter of guesswork.
cache-update should optionally parse the contents of
/usr/local/etc/pkgtools.conf and apply settings from the "MAKE_ENV"
array.
Changes to some makefiles outside the ports tree can have significant
effects, which aren't detected. For instance /usr/local/etc/php.conf.
perl v5.20.2 2013-03-29 CACHE-UPDATE(1)
