PortGroup muniversal not documented

[abarnert@…]

While trying to work around #32427 I ran into the problem that I have no idea what exactly PortGroup muniversal does, or how or why.

While searching this site for muniversal, I found a number of other bugs that were either caused or fixed by changing a port to muniversal, but there's no mention of it in ProblemHotlist.

The Guide describes a handful of portgroups (under 5.9): gnustep, haskell, perl5, python, python2, ruby, xcode), but not muniversal. It also has an explanation on how to set up universal builds, with no mention of muniversal.

The manpage portgroup(7) describes a different set: gnustep, perl5, python24, python25, python30, ruby, xcode. Looking in $prefix/var/macports/sources/rsync.macports.org/release/ports/_resources/port1.0/group/ there are 34 groups, many of which have brief comments explaining their purpose, but muniversal (which seems to be one of the more complex ones) doesn't.

The PortfileRecipes page has some information on controlling -arch and related things; I don't know if muniversal is relevant here.

A ticket search, a Google site search, a Google web search, etc. turned up lots and lots of discussion about applying muniversal to specific ports, but I couldn't find anything explaining muniversal.

From the name, it's pretty obvious that it has something to do with universal builds, and a quick scan of the source confirms that. From what I can tell, just including the portgroup without doing anything else causes +universal builds to be done by building each architecture separately and then merging, instead of attempting a single build with multiple architectures.

In summary, I think muniversal needs to be documented in:

• Guide section 5.3.7.1 (Configure Universal)
• Guide section 5.9 (PortGroups)
• Man page portgroup(7)
• PortfileRecipes
• ProblemHotlist
• Header comments in the group file itself

Ideally these should explain what it does, when and why you should (or shouldn't) use it, how to experiment with turning it on and off to resolve common problems with +universal builds, etc.

[ryandesign (Ryan Carsten Schmidt)]

I agree with most of what you've written (except that merge-universal builds are not a "hot" problem and so don't belong on the ProblemHotlist).

[cooljeanius (Eric Gallager)]

Cc Me!

[cooljeanius (Eric Gallager)]

I found a user who could've benefitted from more documentation for the muniversal portgroup in #38995

[cooljeanius (Eric Gallager)]

I added some examples of when to use this PortGroup to the UniversalDevelopment wiki page: version6

[mf2k (Frank Schima)]

markd has retired. See #44782.

[mascguy (Christopher Nielsen)]

Add keyword portgroup, to pg-related tickets

[ryandesign (Ryan Carsten Schmidt)]

What's even more confusing now is that a new muniversal 1.1 portgroup has been created with a substantially different interface and no documentation explaining the differences or advantages of the new approach.