1. Introduction
2. Installing MacPorts
2.1. Install Xcode
2.2. Install MacPorts
2.3. MacPorts Upgrade
2.4. Uninstall
2.5. MacPorts and the Shell
3. Using MacPorts
3.1. The port Command
3.2. Port Variants
3.3. Common Tasks
3.4. Port Binaries
4. Portfile Development
4.1. Portfile Introduction
4.2. Creating a Portfile
4.3. Example Portfiles
4.4. Port Variants
4.5. Patch Files
4.6. Local Portfile Repositories
4.7. Portfile Best Practices
4.8. MacPorts' buildbot
5. Portfile Reference
5.1. Global Keywords
5.2. Global Variables
5.3. Port Phases
5.4. Dependencies
5.5. Variants
5.6. Tcl Extensions & Useful Tcl Commands
5.7. StartupItems
5.8. Livecheck / Distcheck
5.9. PortGroups
6. MacPorts Internals
6.1. File Hierarchy
6.2. Configuration Files
6.3. Port Images
6.4. APIs and Libs
6.5. The MacPorts Registry
7. MacPorts Project
7.1. Using Trac for Tickets
7.2. Contributing to MacPorts
7.3. Port Update Policies
7.4. Updating Documentation
7.5. MacPorts Membership
7.6. The PortMgr Team
8. MacPorts Guide Terms
Glossary

This chapter provides an overview of the MacPorts registry and its API. The registry is queried by MacPorts utilities for information about installed ports related to dependencies, port images, and simple user information about what is installed. It provides abstraction over a modular receipt storage layer; where the default format is a SQLite database.

The registry allows MacPorts utilities to:

  • Modify receipts to reflect changes made to installed ports being maintained by MacPorts.

  • Query the global file and dependency databases for file conflicts between a port being installed and a port already installed.

  • Maintain dependency trees of installed ports.

The SQLite registry used by default is located at ${portdbpath}/registry, which by default would be ${prefix}/var/macports/registry. All data is stored in a single file named registry.db, although the additional directory portfiles is used temporarily for extracting stored Portfiles from the registry. Furthermore, access to the registry may be locked using .registry.lock with the registry::exclusive_lock and registry::exclusive_unlock APIs.

The legacy flat file registry files are contained in ${portdbpath}/receipts, which by default is location ${prefix}/var/macports/receipts. File mappings and dependency mappings are tracked in the flat file registry by file_map.db and dep_map.bz2. If found, these will be automatically converted to the new SQLite registry.

The MacPorts registry provides a public API in the registry1.0 Tcl package. Using this API listed below you can access the MacPorts Registry using the default receipt storage mechanism chosen in macports.conf.

registry::new_entry {name version {revision 0} {variants ""}}

Begin the creation of a new registry entry for the given port. Returns a reference ID to the registry entry created.

registry::open_entry {name {version 0} {revision 0} {variants ""}}

Opens an existing registry entry. Returns a reference ID to the registry entry that was opened.

registry::entry_exists {name version {revision 0} {variants ""}}

Checks to see if a port exists in the registry. Returns 1 if the entry exists, 0 if not.

registry::write_entry {ref}

Writes the receipt associated with the given reference.

registry::delete_entry {ref}

Deletes the receipt associated with the given reference.

registry::property_store {ref property value}

Store the given value with the property name in the receipt associated with the given reference.

registry::property_retrieve {ref property}

Retrieve the property name from the receipt associated with the given reference. Returns the value of the property, if the property exists.

registry::installed {{name ""} {version ""}}

Get all installed ports, optionally all installed ports matching the given name, or the given name and version. Returns a list of the installed ports.

registry::location {portname portversion}

Returns the physical location the port is installed in on the disk. This is primarily useful for finding out where a port image is installed.

registry::open_file_map {args}

Opens the file map that contains file-port relationships.

registry::file_registered {file}

Returns the name of the port that owns the given file, if the file is registered as installed, and 0 otherwise.

registry::port_registered {name}

Returns a list of all files associated with the given port if that port is installed, and 0 otherwise.

registry::register_file {file port}

Registers the given file in the file map as belonging to the given port.

registry::unregister_file {file}

Removes the file from the file map.

registry::write_file_map {args}

Write the changes to the file map.

registry::open_dep_map {args}

Opens the dependency map that contains port dependency relationships.

registry::fileinfo_for_file {fname}

Returns a list for the given file name representing all data currently known about the file. This is a 6-tuple in the form of:

  1. file path

  2. uid

  3. gid

  4. mode

  5. size

  6. md5 checksum

registry::fileinfo_for_index {flist}

Returns a list of information concerning each file in the given file list, if that file exists in the registry. The information if obtained through registry::fileinfo_for_file

registry::list_depends {name}

Returns a list of all the ports that given port name depends on.

registry::list_dependents {name}

Returns a list of all the ports that depend on the given port name.

registry::register_dep {dep type port}

Registers the given dependency as the given type of dependency with the given port.

registry::unregister_dep {dep type port}

Unregister the given dependency of the given type as a dependency of the given port.

registry::write_dep_map {args}

Write changes to the dependency map.