Kevin Van Vechten | kevin@opendarwin.org 9-Oct-2002
Many software titles have optional functionatily which needs to be dealt with at compile time. These titles are either compiled with or without support for a certain feature. One of the most common examples is whether to compile software with or without X11 support.
Variants were created as a means to address this optional functionality. Often, compiling with or without X11 support is a matter of specifying --with-x11 or --without-x11 in the configure.args variable. In its most basic form, a variant is equivalent to a Tcl if statement. If the variant was specified by the user, then the block of code is executed. Here's an example of an X11 variant:
configure.args --without-x11
variant x11 {
configure.args-delete --without-x11
configure.args-append --with-x11
}
As normal, the code outside of any variant block is executed unconditionally before any variants are evaluated. However, if +x11 was specified, the configure.args-delete and configure.args-append statements will also be evaluated.
If two variants are defined, for example x11 and kde, either or both of them may be chosen by the user. Specifying +x11 will cause the x11 variant to be evaluated, and specifying +kde will cause the kde variant to be evaluated. If +x11 +kde is specified, then both variants will be evaluated. It's also possible to define variants containing several terms. For example:
variant x11 kde {
# do something here, when both x11 and kde are selected
}
In this example, the x11-kde variant will execute only if both +x11 and +kde were specified. This allows conflicts between two variant "primitives" to be resolved without much overhead. Also, because these combined variants are most often used to resolve conflicts, they're evaluated after each of the constituent parts has been evaluated.
Sometimes it's beneficial to guarantee a variant runs after another variant. This can make variable manipulation and and other operartions more straightforward. Ordering can be achieve by the follows keyword. (Important: the follows keyword has not yet been implemented.) In the following example, the kde variant declares that whenever both +kde and +x11 are specified, the kde variant will always be evaluated after the x11 variant. The kde variant will still be evaluated even if only +kde is specified.
variant kde follows x11 {
# do something here, after x11
}
On the other hand, it's possible to allow kde as a variant if and only if x11 has also been selected. This can be done using the requires keyword in the following manner:
variant kde requires x11 {
# do something here, only after x11
}
A Portfile may specify a default set of variants, which will be selected while evaluating the Portfile, unless the user has specifically negated them. This can be done by using the default_variants command in the Portfile as follows:
default_variants +x11 +kde
This specifies that the x11 and kde variants will be evaluated, unless the user were to specify -kde -x11 on the command line.
Some variants are specified by the system implicitly. Like default variants, these can be negated on the command line. Currently the platform and architecture are the only two implicit variants. Variants of the same name as the values of os.platform and os.arch are selected. os.platform contains the value of uname -s such as darwin or freebsd. os.arch contains the value of uname -p such as ppc or i386.