Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  CACHE-UPDATE (1)

.ds Aq ’


cache-update -- Incrementally update the portindex cache



<B>cache-updateB> [<B>-hvqsB>] [<B>-cB> dir] [<B>-CB> file] [<B>-TB> file] [<B>-pB> dir] [<B>-dB> dir] [<B>-fB> format] [<B>-PB> num] [<B>-iB> file] [<B>-MB> file]... [<B>-mB> file]...


<B>cache-updateB> 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 <B>portindexB> cache. If <B>cache-updateB> 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 <B>cache-updateB> both the old and the new locations of the port for processing.

The list of ports to be processed by <B>cache-updateB> may be supplied in three formats, together with two modifiers that add scanning of certain other files:
<B>cacheB> 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 <B>-f cacheB>, no input file is read.

<B>cacheB> cannot be combined with any of the other input format options.

<B>cacheB> is the default input format.

<B>plainB> A list of port origin directories, one per line. The output of <B>portsnap updateB> can be passed directly to <B>cache-updateB> or <B>find-updatedB> 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.
<B>svn-upB> The output from running <B>svn updateB> to update a checked-out copy of the ports tree.
<B>optionsB> <B>cache-updateB> 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.
<B>otherB> <B>cache-updateB> 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 <B>optionsB> 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:
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 <B>cache-initB> rather than <B>cache-updateB>.

When to run cache-init and when to run cache-update

Over time, successively updating the INDEX file via <B>cache-updateB> 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 <B>cache-initB> and rebuild the cache from scratch. Certain changes to your system should act as warnings that this needs to be done.
o Modifications to ubiquitously included makefiles such as /etc/make.conf or /usr/ports/Mk/ are handled specially. <B>cache-updateB> 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 <B>cache-initB> 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 <B>cache-initB>.

The --endemic-makefile option or EndemicMakefiles configuration file setting is used by <B>cache-initB> 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 <B>cache-updateB> 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 <B>makeB> is invoked by the ports system. These are recorded by <B>cache-initB> and by default any such makefiles will be checked for modification by <B>cache-updateB>. 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.

o Modifying the environment between successive runs of <B>cache-updateB>. <B>makeB> 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 <B>cache-initB> and <B>cache-updateB> 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 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

<B>cache-updateB> shares configuration files with <B>cache-initB>, <B>find-updatedB> and <B>portindexB>. 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 <B>FreeBSD::Portindex::ConfigB> 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 <B>cache-initB> 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 <B>cache-initB> is invoked with the -h option.


<B>--helpB> Print a brief usage message and a summary of the configuration settings after command line processing and then exit.
<B>--verboseB> Turn on verbose output printed to STDERR. This is the default.
<B>--noverboseB> Turn off verbose output to STDERR. Using both the <B>-vB> amd <B>-qB> options together does not make any sense, but neither does it generate an error. The last mentioned of the two options will prevail.
<B>--scrub-environmentB> 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.
<B>--noscrub-environmentB> Turn off environment scrubbing. All environment variables will be passed through intact to make describe and other sub-processes. This is the default.
<B>-cB> dir
<B>--cache-dirB>=dir The location of the <B>portindexB> data cache, by default /var/db/portindex.
<B>-CB> file
<B>--cache-fileB>=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 (<B>-cB> option above) unless an absolute path is given. Defaults to portindex-cache.db.
<B>-TB> file
<B>--timestamp-fileB>=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
<B>-pB> dir
<B>--ports-dirB>=dir The location of the ports tree. Almost always defaults to /usr/ports unless $PORTSDIR is set in the environment.
<B>-dB> dir
<B>--port-dbdirB>=dir Where the OPTIONS settings for ports are stored. Almost always defaults to /var/db/ports unless $PORT_DBDIR is set in the environment.
<B>-iB> file
<B>--inputB>=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.
<B>-fB> { cache | plain | svn-up | options | plain,options | svn-up,options | plain,other | svn-up,other | plain,options,other | svn-up,options,other }
<B>--formatB>={ plain | ... } Which input formats <B>cache-updateB> should parse to determine the list of ports to reprocess. Default: cache


/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


cache-init(1), portindex(1), find-updated(1), cvsup(1), ports(7)


cvsup-checkouts format mode is not completely accurate. Choosing the correct propagation delay is a matter of guesswork.

<B>cache-updateB> should optionally parse the contents of <B>/usr/local/etc/pkgtools.confB> 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.

Search for    or go to Top of page |  Section 1 |  Main Index

perl v5.20.3 CACHE-UPDATE (1) 2015-10-18

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.