Home > FreeBSD > FreeBSD’s Package Index

FreeBSD’s Package Index

Interpreting the package INDEX

On some FreeBSD media, there is a package INDEX file which contains definitions for various FreeBSD and/or Ports packages. The following document describes the package INDEX file and its numerous nuances. This document was emailed to me by the author.

Author: Devin Teske
Date: 1 Jan 2006
Last modified: 24 Feb 2006


This file documents the file format of the /packages/INDEX file located on FreeBSD installation CD-ROMs and conveys what it is used for (and its importance).

The layout of this document is as follows:

  • Foreword
  • The INDEX File
    • The FreeBSD INDEX File Format
      • FreeBSD-5.2 and FreeBSD-4.10 or Lower
      • FreeBSD-5.3 and FreeBSD-4.11 or Higher
      • FreeBSD-6.0 or Higher
  • Field Definitions
  • Field Population
  • References


This document describes the format of the `/packages/INDEX’ file located on the FreeBSD installation CD-ROM. Depending on which FreeBSD release version you are working with, the format may vary. Documented below you will find 3 versions commonly used.

Common between each version, is that each line (delimited by the new-line character) corresponds to a single package (found in packages/All). It is possible to have additional fields beyond the last field (for custom purposes) as they will be ignored by sysinstall.

The INDEX File

The INDEX file (located on the FreeBSD installation CD-ROMs) is a file that is read by sysinstall (see sysinstall(8)) for the installation of ancillary packages (located in `/packages’). When sysinstall displays an interactive menu for the selection of these packages, it uses the INDEX file (located at `/packages/INDEX’) to display information such as the package name, the package description, and what categories to place it in.

If sysinstall is scripted, then the interactive menu may or may not be invoked (if not, then the categories/description fields may be omitted).

When sysinstall is in the process of installing the packages, it first makes sure that all the run-dependencies (listed in the INDEX file for that package) are installed. If a package that is listed in the `run-deps’ field is not installed, sysinstall installs it before installing the requested package. After installing any dependent packages (recursively), sysinstall then unpacks the requested package and reads its packing-list (the `+CONTENTS’ file within the package tarball). All package dependencies listed inside the package’s packing-list MUST be installed before-hand or else sysinstall will generate an error. Therefore, all package dependencies that appear in the packing list MUST be present in the `run-deps’ field of the INDEX file. There reverse is not true, however. A dependency may appear in the INDEX file and not in the package’s packing-list.

INDEX File Format

FreeBSD-5.2 and FreeBSD-4.10 or Lower


FreeBSD-5.3 and FreeBSD-4.11 or Higher


I have never seen the 11th, 12th, or 13th field populated. So their purpose remains unknown.

FreeBSD-6.0 or Higher


Field Definitions

Field Comments
package This is the name of the package. This should be the name of the file as it appears in packages/All without the .tgz suffix. This value is used for finding the package tarball and is also displayed in the left-hand column of the interactive package selection menu of sysinstall.
port-origin The package origin (as a qualified pathname). Basically, this is the origin of the package with a /usr/ports/ prefix. Even if you do not install the Ports Collection (which installs Makefiles and other information), this should be populated respectively.
install-prefix The base directory where the package will install it’s files to. For example, if the package installs files into /usr/local/bin and /usr/local/sbin then the install-prefix would be /usr/local. This is an informational value (the package’s packing-list takes precedence).
comment This is the one-line comment for the package. This should be the same as the contents of the +COMMENT file located within the package tarball. This value is displayed in the right-hand column of the interactive package selection menu of sysinstall.
desc-file When you install the Ports Collection the /usr/ports directory is populated with Makefiles and other information. This value should be the path to the description file for the package. This is only used when you install the FreeBSD Ports Collection.
maintainer The e-mail address of the package maintainer.
categories Within the /packages directory of the CD-ROM, you will find (besides the INDEX file) several directories. The actual package should always reside in theAll directory (as this is where sysinstall looks for it). However, finding the package you want/need can become quite cumbersome if you have to sift through every package in one directory. To ease the process of finding a specific package, you can populate this field with several categories (sub-directories) that the package can be found in.

When sysinstall’s interactive package selection menu is invoked (either by a script or simply interactively) it allows a user to browse several categories to find a specific package. This field dictates to sysinstall which categories (delimited by a space) the package is available in.

When you specify a category (sub-directory), the simplest (and most efficient) thing to do is, create a symbolic link in the category directory (in /packages) pointing to the actual package (in /packages/All).

build-deps These are the dependencies (names of packages delimited by a space) that this package requires to bebuilt. This is used if you install the FreeBSD Ports Collection.
run-deps These are the dependencies (names of packages delimited by a space) that this package requires to run. Any package listed here will be installed by sysinstall before the package is even attempted to be installed. See section 2 paragraph 3 for more information.
www-site Either the website URL of where the package can be obtained, the package maintainer, or the website URL of the item that the package installs.
unknown If a field has been marked `unknown’ in section 3, it is because I have never seen it populated and thus never used. These fields can be left empty without any recourse.
disc The disc that the package can be found on (in a multi-disc distribution of the FreeBSD installation). This is a new feature of FreeBSD-6.0 Other distributions (such as FreeBSD-4.8 and FreeBSD-4.11 do not list packages in the INDEX file unless it appears on the same CD-ROM).

Field Population

Below you will find various ways that you can use to populate the formats listed in section 3 given nothing more than a package tarball. NOTE: these commands must be run on a FreeBSD distribution (as Linux and other UNIX distributions do not have the `pkg_info’ command).
  • package: file_name without `.tgz’ suffix
  • port-path: echo /usr/ports/`pkg_info -qo file`
  • install-prefix: pkg_info -qp file | head -n1 | sed -e ‘s/^@cwd //’
  • comment: pkg_info -qI file
  • desc-file: echo /usr/ports/`pkg_info -qo file`/pkg-descr
  • maintainer: echo ports@FreeBSD.org
  • categories: find . -type l -name FILE | sed -e ‘s/^\.\/\(.*\)\/[^\/]*$/\1/’ | tr ‘\n’ ‘ ‘
  • build-deps: pkg_info -qr file | sed -e ‘s/^@pkgdep //’ | tr ‘\n’ ‘ ‘
  • run-deps: pkg_info -qr file | sed -e ‘s/^@pkgdep //’ | tr ‘\n’ ‘ ‘
  • www-site: pkg_info -qd file | grep ‘^WWW: ‘ | sed -e ‘s/^WWW: //’
  • disc: the disc that the package resides on


The information in this document is the result of many hours of reverse-engineering and testing. Little or no sources on this topic have been found online. Even when the subject matter was found online, the amount of information on the topic was anemic.
Categories: FreeBSD
  1. Pavel
    February 23, 2017 at 9:29 AM

    In the description of the index file helps to consider the /usr/ports/Mk/bsd.port.mk with the line 4246.

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: