Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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.32.0			  2015-10-18			 CACHE-INIT(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | FILES | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cache-init&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help