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-INIT (1)

.ds Aq ’


cache-init -- Generate the portsindex cache by scanning the entire ports tree



<B>cache-initB> [<B>-hvqsB>] [<B>-cB> dir] [<B>-CB> file] [<B>-TB> file] [<B>-pB> dir] [<B>-MB> file]... [<B>-mB> file]...


<B>cache-initB> scans over the entire ports tree to initialise the <B>portindexB> 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.
<B>cache-initB> is used to bootstrap the <B>portindexB> data cache on a new system. It only needs to be run once, after which <B>cache-updateB> may be used to apply incremental updates to the data cache. As <B>cache-initB> 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.

<B>cache-initB> 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 <B>cache-updateB> 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 <B>cache-initB> 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/ <B>cache-updateB> 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 <B>makeB> 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.

<B>cache-initB> accepts the same UbiquitousMakefiles and EndemicMakefiles configuration options as <B>cache-updateB> (or the equivalent command line options). However, for <B>cache-initB> 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 <B>cache-updateB>. <B>makeB> 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 <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 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

<B>cache-initB> shares configuration files with <B>cache-updateB>, <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 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 (<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>-MB> file
<B>--ubiquitous-makefileB> file
<B>-mB> file
<B>--endemic-makefileB> file These options both have exactly the same effect for <B>cache-initB>, and are only provided separately for compatability with <B>cache-updateB>. 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/ (EndemicMakefiles) ${PORTSDIR}/Mk/, ${PORTSDIR}/Mk/, ${PORTSDIR}/Mk/


/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


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


<B>cache-initB> is quite a lot slower than make index. Possible improvements include running several make describe processes concurrently.

<B>cache-initB> should optionally parse the contents of <B>/usr/local/etc/pkgtools.confB> and apply settings from the MAKE_ENV array.

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

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

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