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.).
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 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.
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.
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 }
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.
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
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.
yes
Example:
universal_variant no
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.
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.
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
can be used to handle different tasks depending on the version of Darwin, the core operating system underlying macOS. +version+
+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 }
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.