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

FreeBSD Manual Pages

  
 
  

home | help
CACHE-UPDATE(1)	      User Contributed Perl Documentation      CACHE-UPDATE(1)

NAME
       cache-update -- Incrementally update the	portindex cache

SYNOPSIS
       cache-update [-hvqs] [-c	dir] [-C file] [-T file] [-p dir] [-d dir] [-f
       format] [-P num]	[-i file] [-M file]... [-m file]...

DESCRIPTION
       cache-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.

       o       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.

       o       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.

       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
       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:

       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 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 ALSO
       cache-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.32.1			  2015-10-18		       CACHE-UPDATE(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-update&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help