# 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, ppc, etc.).

## 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).

Variant names may contain only the characters A-Z, a-z, and the underscore character _. Therefore, take care to never use hyphens in variant names.

variant name [requires variant] [conflicts variant] [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 Mac OS X, 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

## 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 unnceccessary whitespace, unlike with port descriptions and long_descriptions.

## 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 Mac OS X. version can be `6` for 10.2 Jaguar, `7` for 10.3 Panther, `8` for 10.4 Tiger or `9` for 10.5 Leopard.

  - Default: ???

  - Examples:

        platform darwin 7 {
            # Only used on Mac OS X 10.3.
            configure.args-append \
                --enable-tcl \
                --with-tcl=/System/Library/Tcl/8.3
        }

        platform darwin powerpc {
            # Only used if Mac OS X is running on a PowerPC processor.
            configure.args-append \
                --host=${os.arch}-apple-rhapsody${os.version}
        }
        platform darwin i386 {
            # Only used if Mac OS X is running on an Intel processor.
            configure.args-append \
                --host=i386-gnu-rhapsody${os.version}
        }

Though a combination of OS and hardware platform may be specified in a single platform statement (i. e. darwin i386), it is not possible to select a range of platforms with a single statement. For example, to select darwin versions 7 and 8 while excluding all others, you would need two statements: `platform darwin 7` and `platform darwin 8`.