Guide has wrong advice about variants

[ryandesign (Ryan Carsten Schmidt)]

The Guide ​says this of variants:

If a variant requires options in addition to those provided by keywords using -append and/or -delete, in other words, any actions that would normally take place within a port installation phase, do not try to do this within the variant declaration. Rather, modify the behavior of any affected phases when the variant is invoked using the variant_isset keyword.

post-destroot {
    xinstall -m 755 -d ${destroot}${prefix}/etc/
    xinstall ${worksrcpath}/examples/foo.conf \
        ${destroot}${prefix}/etc/

    if {[variant_isset carbon]} {
        delete ${destroot}${prefix}/bin/emacs
        delete ${destroot}${prefix}/bin/emacs-${version}
    }
}

I do not know why the Guide says this because it is the opposite of what I recommend. It should say something more like:

If a variant requires options in addition to those provided by keywords using -append and/or -delete, in other words, any actions that would normally take place within a port installation phase, include these within the variant declaration if possible, so that it is easier to see at a glance what a variant does. If you want to take an action if a variant is *not* set, use the variant_isset keyword.

post-destroot {
    xinstall -d ${destroot}${prefix}/share/emacs/${version}/leim
    delete ${destroot}${prefix}/bin/ctags
    delete ${destroot}${prefix}/share/man/man1/ctags.1
}

variant carbon conflicts x11 description {Adds a Mac (Carbon) version of Emacs} {
    configure.args-delete   --without-carbon
    configure.args-append   --with-carbon \
                            --enable-carbon-app=${applications_dir}
    post-destroot {
        delete ${destroot}${prefix}/bin/emacs ${destroot}${prefix}/bin/emacs-${version}
    }
}

post-activate {
    if {![variant_isset carbon]} {
        ui_msg "Note: You have not selected the +carbon variant"
    }
}

[blb@…]

Replying to ryandesign@…:

I do not know why the Guide says this because it is the opposite of what I recommend. It should say something more like:

I believe the reason is that at one point, doing a post-<phase> in a variant would actually override the top-level version of post-<phase>. Once MacPorts was updated so that it chained these instead of overriding, then your suggestion became the better method.

[markd@…]

I think I did it that way because that is the way I was told to do it way back. But it also seems to me that somewhere in the past I borked the hourly portindex function on macports because of a variant I used in the global section of a portfile. I think it was explained to me that variants in the global section of portfiles are evaluated by the macports box that does the portindex. So I thought that only certain keywords could be used within a variant declaration. That is what I recall, by way of explanation. If that is wrong or no longer true, then let's hash that out and I'd be happy to modify the guide accordingly. I do agree that it is clearer to put everything a variant does in the variant declarations much of the time.

Also, realize that I recently started distinguishing in the guide between "platform variants" and "user-selected variants" (see reference section). If there is any truth to my recalled understanding above, perhaps it was the platform variants that caused the problem. If so, then that would change the user advice too; at the vary least it would mean only warning about being careful with platform variants instead of variants in general.

So let me know if there is any truth at all to this and I'll be happy to correct the guide accordingly.

[ryandesign (Ryan Carsten Schmidt)]

True, platform variants are auto-selected by MacPorts regardless of what port command is being run, and that includes running the portindex. And users may have variants set in their variants.conf so that they are auto-selected. So the kinds of things you should not do directly in a variant or directly in a portfile are:

• output a message
• return an error code
• run a program that is in the port's dependencies

If you need to do these things, do them in a phase (be it inside a variant or not). Otherwise they run even at times when you don't want them to, such as portindex or port info.

[(none)]

Milestone Website & Documentation deleted

[jbusser@…]

Can the GUide in relation to variants incorporate not only the above, but also two suggested changes below:

Original guide 3.2. Port Variants

Variants are a way for port authors to provide options for a port that may be chosen during the port install. To display the available variants, if any, use this command: <snip> Note: Variant descriptions are optional, so you may not see descriptions for all variants.

suggest alter & add to the Note:

As variant descriptions are optional, you may not see descriptions in all cases. Two more variant kinds may be listed. A variant may be "universal" if the port's methods may allow the same install to run under more than one architecture. A "platform" variant denotes steps that will run under a particular platform, say "darwin_10" as meaning OS 10.6 Snow Leopard, automatically.

3.2.1. Invoking Variants

A variant can only be invoked when a port is installed. After you have determined what variants a given port has, if any, you may install a port using the variant as shown.

%% port install fetchmail +ssl

Port variant execution may be verified using the port command with the verbose switch.

%% port -v install fetchmail +ssl

When a port is installed using a valid variant and specified correctly, the verbose output will contain:

DEBUG: Executing variant ssl provides ssl

suggest add:

NOTE: Whereas "universal" variants can also be chosen (when not configured in MacPort settings to be auto-applied, when possible), the "platform" variant needs no selection, being automatic.

[cooljeanius (Eric Gallager)]

Cc Me!

[mf2k (Frank Schima)]

markd has retired. See #44782.