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

.ds Aq ’


portindex -- generate an INDEX file from cached data



<B>portindexB> [<B>-hvqwWLB>] [<B>-cB> dir] [<B>-CB> file] [<B>-TB> file] [<B>-oB> file]


<B>portindexB> 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 <B>portindexB>.

The processing done by <B>portindexB> 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

<B>portindexB> shares configuration files with <B>cache-initB>, <B>cache-updateB> and <B>find-updatedB>. 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 (ignored if the program is being run by the superuser)
o The local configuration file, found in the current working directory of the <B>cache-initB> process ./.portindexrc (ignored if the program is being run by the superuser)
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>portindexB> 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>--warningsB> Turn on warning messages about duplicate ports and ports unreferenced from their catergory Makefile. Default: off.
<B>-nowarningsB> Turn off warning messages. 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>-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 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 (<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 portindex-timestamp
<B>-oB> file
<B>--outputB>=file Filename to write the generated ports INDEX file to. Setting this to - means output to STDOUT, which is the default.
<B>--crunch-whitespaceB> 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.
<B>--shlibsB> 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


/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


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


The INDEX file produced by <B>portindexB> 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 <B>portindexB>, x11-clocks, x11-fm, x11-themes, x11-toolkits and x11-wm will all sort before x11, whereas usually they would sort after.

<B>portindexB> 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 <B>portindexB>.

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

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

perl v5.20.3 PORTINDEX (1) 2015-10-18

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