# Variants

## What are variants?

MacPorts allows multiple versions of a port to be specified in a single Portfile. For example, vim can be built with and without x11 support. Rather than duplicate the whole port and have vim-x11 vim-nox ports MacPorts supports "variants".

## Guidelines

There are some guidelines for using variants:

- Never change the version of a port inside a variant.

- Heavy usage of variants is considered bad style - keep the number of variants low.

- Prefer function restricting variants over function enhancing ones. Make the default installation the one that serves most purposes.

## Syntax

The variants syntax is largely identical to the syntax in the main part of the Portfile.

variant

  The key variant is used to begin the foo variant as shown in the example.

      variant foo    {
      			      [variant code]
      			      [more variant code]
                       }

  Within the variant block essentially all of the keys available in the main section are available. Using a key used in the main section will overwrite it.

append

  For most of the keys you can append additional terms.

      variant foo    { configure.args-append --with-x}

delete

  For most of the keys you can delete terms. The item being deleted should match a string in the option being deleted exactly.

      variant gnome    { configure.args-delete --without-gnome}

## Advanced variants

For the most part, variants are quite straightforward to use. Several more advanced features of variants are also available.

default_variants

  In some cases you may want a variant or variants to be executed by default. For example w3m is distributed with a patch to add international text support. This is a vendor provided patch, but not a core part of the program. In this case it makes sense to make the internationalised version the default, but keep the vanilla w3m as the main port. The default_variants key is used in the main section of a Portfile, not in a variant.

  `default_variants +foo +bar`

platform_variants

  Platform specific variants are automatically executed on that platform, without needing any intervention from the user. Currently available platforms are:

  - darwin
  - freebsd
  - linux

  `variant foo darwin {[variant code]}`