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
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. MacPorts Membership
7.5. The PortMgr Team
8. MacPorts Guide Terms

The MacPorts Project uses a system called Trac to file tickets to report bugs and enhancement requests. Trac also provides an interface to browse the MacPorts Subversion repository. Though anyone may search Trac for tickets, you must register for a Trac account to create tickets.

  • Clean and try again

    If a build fails or is otherwise interrupted, and you try again, MacPorts tries to pick up where it left off. Sometimes this causes new problems, and even if it doesn't, it means that log messages from earlier steps, which can be essential for figuring out why a build failed, are not included in the new log; MacPorts prints Skipping completed in the log for each previously-completed phase that was skipped. Before filing a ticket, sudo port clean the port that failed, then try again.

  • Check the problem hotlist

    The Problem Hotlist contains possible solutions to problems that affect many MacPorts users. If a solution to your problem listed there works, don't file a ticket.

  • Search to see if a Trac ticket has already been filed

    Avoid filing duplicate bugs. Search for duplicates by:

  • Is the problem an application error and not related to compiling and installing?

    In general, application bugs should be reported to the developers of the app (upstream), not MacPorts. An application bug that affects a large number of MacPorts users might merit a MacPorts bug for informational purposes only, but this should be done sparingly.

  • Is the problem with a 'port upgrade' operation?

    If so, try a 'port uninstall foo' and then reinstall. You might also want to run 'port -nR upgrade --force foo' to rebuild ports depending upon port foo. Note that it is safest and recommended that most users always upgrade with 'port upgrade outdated' to update all ports at once. Upgrading a single port can lead to software errors in other ports that have not yet been upgraded.

Once you are logged into Trac, you may click New Ticket and you will be presented with a new ticket window shown in the graphic below. Follow the Trac ticket guidelines below to fill out the form. If you are reporting a failed port install and a log was mentioned in the error, please use the I have files to attach to this ticket checkbox to add that log file to the ticket.

screenshot of a new ticket on the Trac system

There are certain conventions used to ensure that Trac tickets convey as much accurate information as possible so problems and contributions may be acted upon efficiently.

  • Summary: [port] [version] [concise description]

    • Example: "rrdtool @1.2.23 +python Configure error - build failure"

  • Description: All details that might be relevant to someone reading the ticket. Be sure to mention the versions of your operating system and Xcode install. Wiki formatting should be used to ensure that text is formatted correctly. Use the Preview button before submitting. If you want to post preformatted text such as a log or terminal output, make sure you use {{{...}}} around the text or it could break the page layout. Example:

    your error message here

    Submitters are advised to trim inline pastes and logs to what's really relevant to the report, as otherwise overly large ticket pages can become unmanageable. Long output, such as the full log from a port build, should be added as an attachment, not pasted inline. See I have files to attach to this ticket below.

  • Type: There are five types of tickets.

    • defect - The default; any port/MacPorts build/runtime failures and/or documentation corrections.

    • enhancement - Tickets, with or without patches, created to enhance something that isn't failing its intended purpose.

    • update - Tickets, with or without patches, involving updating a port to a newer upstream version.

    • submission - Tickets created to submit Portfiles for software not currently available in MacPorts.

    • request - Tickets created to request the creation of a new port.

  • Priority: Assign a priority level to the ticket.

    • High - Reserved for the use of MacPorts team members, as they are the best fit to determine which reports warrant a higher priority over others.

    • Normal - The default. For normal port failures, non-critical enhancement requests, non-critical port failures.

    • Low - For mostly cosmetic improvements, documentation corrections/improvements, etc.

    • Not set - Anything that doesn't fit the categories high, normal, or low.

  • Milestone: This is a ticket label that indicates that the ticket is intended to be fixed in a particular MacPorts release. Leave it blank; it will be set by a project member if appropriate.

  • Component: Set what part of the MacPorts Project the ticket is to be filed against.

    • base - Tickets related to MacPorts base code.

    • guide - Documentation enhancements and error corrections, or patches to the MacPorts Guide.

    • ports - Tickets related to ports.

    • server/hosting - For MacPorts hosting & server-side issues, reserved for MacPorts PortMgr team members.

    • website - MacPorts website enhancements and error corrections.

    • wiki - MacPorts Wiki enhancements and error corrections.

  • Version: Select the MacPorts version you are using when it is applicable.

  • Keywords: Type any keywords that might help when searching for tickets. It is not useful to list words here that already appear elsewhere in the ticket. Keywords also serve as tags; for example, use tiger if reporting a bug that only affects OS X 10.4, haspatch if a fix is attached to the ticket, maintainer if you are the port's maintainer, or LP64 if reporting an issue that only affects 64-bit platforms.

  • Cc: Anyone else besides the ticket reporter and assignee who would like to be kept involved in the development of the ticket. Multiple email addresses should be separated with a comma and a space (e.g., you@example.org, maintainer@macports.org).

    When reporting port-related tickets, make sure you add the port maintainers email address to the Cc: field so they are notified of the ticket (unless you have commit access, then see Assign To: below). You can obtain the email address of the port maintainer from the Portfile, or by running port info --maintainers [port]

  • Assign To: Only users with commit access can edit this field. If this is not you, see the section on the Cc field above.

    For tickets on ports, enter the email address of the port's maintainer (use port info <portname> to find this). If multiple maintainers are listed, enter the first maintainer's email address here and enter the remaining maintainers' email addresses in the Cc field. Exclude the email address if it appears. If the maintainer's email address is , leave the field blank.

  • Port: For tickets on ports, enter the name of the port (or ports, space-separated, when multiple are affected).

  • I have files to attach to this ticket: Use this checkbox to attach files to the ticket immediately after you create it. Or you can attach files later using the Attach File button.

    If the file you are attaching is larger than 256 KiB, please compress it with bzip2 or gzip first to save space on the server and bandwidth for those downloading it, as Trac will not preview files above that size anyway.