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
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

5.5. Variants

MacPorts variants are conditional modifications of port installation behavior during port installation. There are two types of variants: user-selected variants and platform variants. User-selected variants are options selected by a user when a port is installed; platform variants are selected automatically by MacPorts base according to the OS or hardware platform (darwin, freebsd, linux, i386, powerpc, etc.).

5.5.1. User-Selected Variants

User-selected variants are those that are defined so a user can invoke them to enable port options at install time. They also allow a port author a level of modularity and control using the keyword default_variants (see below).

Note

Variant names may contain only letters, numbers and underscore characters. In particular, the hyphen is not a valid character in variant names because it would conflict with the notation for deselecting a variant.

variant name [requires variant1 variant2 ...] [conflicts variant1 variant2 ...] [description description]

The variant declaration may contain any keywords that can be placed in a Portfile's global section. If you wish to execute system (shell) calls or Tcl extensions during the execution of a port phase, you should place those statements within a variant_isset conditional within a phase declaration and not within the variant declaration itself. Dependencies and conflicts with other variants in the same port can be expressed with requires and conflicts options as shown below.

  • Default: none

  • Examples:

    variant gnome requires glib {
        configure.args-append   --with-gnome
        depends_lib-append      port:gnome-session
    }
    variant apache2 conflicts apache {
        configure.args-append \
            --with-apxs2=${prefix}/apache2/bin/apxs
    }
default_variants

The optional default_variants keyword is used to specify variants that a port author wishes to have enabled by default. This allows for Portfile modularity and also allows users to suppress default variants if they wish.

  • Default: none

  • Example:

    default_variants    +ssl +tcpd
    
    

Default variants may be suppressed by preceding a variant name with a - as shown in this example.

%% port install foo -ssl
universal_variant

When using MacPorts on macOS, a universal variant is defined by default to configure ports with universal flags. The variant can be overridden if the default code does not work (see the Configure Universal section above), or suppressed if a universal variant does not function properly for a given port.

  • Default: yes

  • Example:

    universal_variant   no

5.5.2. User-Selected Variant Descriptions

User-selected variants ought to provide a description, which will be displayed when using command port variants foo. The syntax used for the description keyword is shown below.

variant bar description {Add IMAP support} {}

Descriptions should be short but clear, and not merely repeat the name of the variant. To allow for compatibility for possible MacPorts GUI support, a good rule of thumb is to use sentence fragments for brevity, with a capitalized first letter and no trailing punctuation. Think of them as short labels such as ones you'd find next to a GUI checkbox or radio button. Thus, it would be better to write Build with support for foo instead of Builds with support for foo; Add support for foo would be better than Adds support for foo.

Variant descriptions are strings, so one should take care not to put whitespace between the brackets and the beginning and end of the variant description, and also not to use unnecessary whitespace, unlike with port descriptions and long_descriptions.

5.5.3. Platform Variants

Platform variants are either defined by default in MacPorts base, or defined by a port author to customize a port's installation according to OS (operating system) or hardware platform.

platform os [version] [arch]

MacPorts allows platform-specific port options to be specified in a Portfile for handling differences between platforms and versions of the same platform.

platform darwin version can be used to handle different tasks depending on the version of Darwin, the core operating system underlying macOS. version is the major version of Darwin, and can be 18 for macOS Mojave 10.14, 17 for macOS High Sierra 10.13, 16 for macOS Sierra 10.12, and so on.

  • Examples:

    platform darwin 10 {
        configure.env-append LIBS=-lresolv
    }
    platform darwin i386 {
        configure.args-append --disable-mmx
    }
    platform darwin 8 powerpc {
        configure.compiler gcc-3.3
    }

Note

Though a combination of OS version and hardware platform may be specified in a single platform statement (e.g., darwin 8 i386), it is not possible to specify a range of platforms with a single statement. For example, to select Darwin versions 9 and 10 while excluding all others, you would need two statements: platform darwin 9 and platform darwin 10. Alternately, you could make that behavior the port's default, and add a platform darwin 8 block to remove it again.