1. Introduction
2. Installing MacPorts
2.1. Install Xcode
2.2. Install MacPorts
2.3. Upgrade MacPorts
2.4. Uninstall MacPorts
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
5.10. PortGroup Introduction
5.11. PortGroup github
5.12. PortGroup gnustep
5.13. PortGroup golang
5.14. PortGroup haskell
5.15. PortGroup java
5.16. PortGroup perl5
5.17. PortGroup python
5.18. PortGroup ruby
5.19. PortGroup xcode
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
6.6. Tests
7. MacPorts Project
7.1. Using Trac for Tickets
7.2. Using Git and GitHub
7.3. Contributing to MacPorts
7.4. Port Update Policies
7.5. Updating Documentation
7.6. MacPorts Membership
7.7. The PortMgr Team
8. MacPorts Guide Glossary
Glossary

6.4. APIs and Libs

The MacPorts system is composed of three Tcl libraries:

  • MacPorts API - MacPorts public API for handling Portfiles, dependencies, and registry
  • Ports API - API for Portfile parsing and execution
  • pextlib - C extensions to Tcl

6.4.1. Ports API

The code for the Port API is located in base/src/port1.0. The Port API provides all the primitives required for a Portfile to be parsed, queried, and executed. It also provides a single procedure call that the MacPorts API uses to kick off execution: +eval_targets+. The port Tcl library supplies these procedures, all of which are generated at run-time using the options procedure in portutil.tcl.

The macports Tcl library loads the Portfile into a sub-interpreter, within which all port-specific code is run. This process ensures that there will never be pollution of the Tcl space of other ports, nor the MacPorts libraries, nor the calling application.

Note

Portfiles are executed in a Tcl interpreter as Tcl code (and not truly parsed strictly speaking), so every Portfile option must be a Tcl procedure.

The Ports API performs the following functions:

  • Manages target registrations. All targets register themselves with the Port API. Accordingly, the Port API creates pre-/post-/main overrides for each of the targets.
  • Option/Default handling. All Portfile options (name, version, revision …​) are registered by targets. The Port API creates procedures for these options, and sets up the complex variable traces necessary to support option defaults.
  • Executes target procedures, including the pre/post/main routines.
  • Manages a state file containing information about what variants were specified and what targets have run successfully.
  • Provides essential Portfile Tcl extensions (reinplace, xinstall, etc).
  • Provides simple access to the ui_event mechanism by providing the various ui_ procedures (i.e., ui_msg, ui_error).

6.4.2. MacPorts API

The code for the MacPorts API is located in base/src/macports1.0. The MacPorts API provides a public API into the MacPorts system by providing simple primitives for handling Portfiles, dependencies, and registry operations, and exports the MacPorts API for the +port+ command line utility, or any other. The API has very little information about the contents Portfiles; instead, it relies entirely upon the +port+ Tcl library. By keeping the high level API simple and generic, revisions to the underlying ports system will not necessarily require a revision of the high level MacPorts API.

The MacPorts API is also responsible for loading user specified options into a sub-interpreter to be evaluated by the ports API. In that case it sets the variable name in the sub-interpreter and adds the option to the sub-interpreter’s global array user_options(). User options are passed as part of the call to +mportopen+.

The MacPorts API performs the following functions:

  • Dependency support.

    This is implemented in a highly generic fashion, and is used throughout the system. The dependency functions are exported to the Port API, and the Port API uses them to execute targets in the correct order.

  • Dependency processing.

    Software dependencies are handled at this layer using the dependency support layer.

  • UI abstractions.

    UI Abstractions are handled at this layer. Each port action is provided a context, and a mechanism for posting user interface events is exported to the Port API (ui_event).

  • Registry management routines.

    Manages the SQLite port registry in ${prefix}/var/macports/registry/. See also Section 6.5, “The MacPorts Registry”.

  • Exports the MacPorts API for use by client applications.

    The following routines are defined. mportinit: Initializes the MacPorts system. Should be called before trying to use any other procedure. mportsearch: Given a regexp, searches the PortIndex for ports with matching names. mportopen: Given a URI to a port, opens a Portfile and returns an opaque handle to it. mportclose: Given a port handle, closes a Portfile. mportexec: Given a port handle, executes a target (e.g., install). mportinfo: Given a port handle, this returns the PortInfo array (as a flat list of array elements). This is a little tricky and unstable and only used by +portindex+. ** mportdepends: Given a port handle, returns a list of ports upon which the specified port depends.

For an example of the MacPorts API, when one executes +port search cm3+, the port utility:

  • Calls the mportsearch function to find all ports containing cm3.
  • Returns Tcl array(s) containing data from the PortIndex: port name, version, revision, variants, etc.
  • Formats the list of arrays in the standard viewing format.

For another MacPorts API example, when one executes +port install cm3+, the port utility:

  • Calls the mportsearch function to find the first port that matches the name cm3.
  • Calls the mportopen function to open the port.
  • Calls the mportexec function to execute the install target in the port.
  • Calls the mportclose function to close the port.

6.4.3. pextlib

The pextlib Tcl library provides a variety of C extensions to add capabilities to Tcl procedures; for example, an interface to flock(2) and mkstemp(3).