NAME

portindex -- generate an INDEX file from cached data

SYNOPSIS

portindex [-hvqwWL] [-c dir] [-C file] [-T file] [-o file]

DESCRIPTION

portindex processes the cached port description data into the INDEX-7, INDEX-8 or INDEX-9 files used by the ports system. The cache contains a record of the one-line description of all ports generated by "make describe", indexed by the port origin directory. It also contains a record of the master-slave relationships between some ports and of which Makefiles are included by the port's Makefile, but that information is not used by portindex.

The processing done by portindex consists of two phases. When generating an INDEX, in the first phase the various direct dependencies listed in the raw "make describe" output (FETCH_DEPENDS, EXTRACT_DEPENDS, PATCH_DEPENDS, BUILD_DEPENDS, RUN_DEPENDS, LIB_DEPENDS) are accumulated with the (previously accumulated) RUN_DEPENDS list for each dependency target. Thus, for example, the final BUILD_DEPENDS dependency list will contain everything that the port depends on directly to build itself, plus all of the dependencies required for those build tools to run.

In the second phase the accumulated dependencies are converted from lists of port origins to lists of package names, including version numbers. The data is already sorted, by virtue of the way the Btree cache files operate, so all that remains is to format it tidily and print it out.

The processing done when generating a SHLIBS file is very similar, but in this case only the "LIB_DEPENDS" variable is considered, and library dependencies are accumulated and printed out as the list of ports providing the shared libraries depended on.

Configuration Files

portindex shares configuration files with cache-init, cache-update and find-updated. 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 (ignored if the program is being run by the superuser)
The local configuration file, found in the current working directory of the cache-init process ./.portindexrc (ignored if the program is being run by the superuser)
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 portindex 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.
-w
--warnings: Turn on warning messages about duplicate ports and ports unreferenced from their catergory Makefile. Default: off.
-nowarnings: Turn off warning messages. 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.
-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 post-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 portindex-timestamp
-o file
--output=file: Filename to write the generated ports INDEX file to. Setting this to - means output to STDOUT, which is the default.
-W
--crunch-whitespace: Make the generated INDEX closer to the output of "make index" by modifying the "COMMENT" field so that any sequence of whitespace characters is collapsed into a single space. Default: off.
-L
--shlibs: Instead of the normal INDEX file, generate an alternative SHLIBS index of the available ports. The SHLIBS file consists of three columns separated by '|' characters. The first two columns are the same as in the INDEX file: the package name and version, followed by the directory containing the port. The third column is a space separated list of the cumulative "LIB_DEPENDS" dependencies the port has on other ports that provide shared libraries. The use of this is to identify the ports that would need to be reinstalled given an ABI version bump in some dependency shared library. eg.
% grep databases/db46 SHLIBS | cut -d '|' -f 1

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" output.
__db.001, __db.002, __db.003: 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

BUGS

The INDEX file produced by portindex will not be identical to the result of running "make index" from the same ports tree. However, the differences are mostly cosmetic and seem to have no practical impact.

The sort order of the entries in the generated INDEX file is generated as a side effect of the way that BDB Btree files work. It is not eactly the same as produced by the sorting methods used in "make index". For example, in portindex, "x11-clocks", "x11-fm", "x11-themes", "x11-toolkits" and "x11-wm" will all sort before "x11", whereas usually they would sort after.

portindex uses the port origin as its unique key in the data cache. "make index" uses the package name. Since certain ports modify their package name depending on the local settings and conditions, this can lead to package name collisions. Such collisions are weeded out of the generated INDEX file by "make index", but not by portindex.

Unless the "--crunch-whitespace" option is given, portindex extracts the "COMMENT" lines from the "make describe" output exactly as shown. "make index" collapses multiple spaces to single.