python portgroup should not auto-create ${destroot}${prefix}/share/doc/${subport}/examples

[ryandesign (Ryan Carsten Schmidt)]

Following discussion in October 2013 about the correct location for examples to be installed, we decided it is ${destroot}${prefix}/share/doc/${subport}/examples, but that ​the python portgroup should not automatically create it, because it is just as likely that a portfile author wants to copy an existing directory there, in which case the portfile author has to first delete the automatically created directory. See also #23280.

All ports using the python portgroup and using ${prefix}/share/doc/${subport} need to be audited and possibly updated for compatibility with this change.

[petrrr]

Cc Me!

[petrrr]

This change is (obviously) fine for me. Anyway, once we touch this, I would propose to also consider the following changes:

• We should introduce a preset variable/option with the correct location of the doc and example directory. This should also help to enforce the "correct location". I myself usually use something like this in my Portfiles set dest_doc ${destroot}${prefix}/share/doc/${subport}.
• We should audit ports for the correct location. I observed some inconsistencies.
• We could use something like a create_docdir option to influence the behavior. If this defaults to yes, we should have a quite smooth migration path and can make the changes in the portgroup and the port audit independently.

[ryandesign (Ryan Carsten Schmidt)]

Just wanted to Cc you since it had been your mailing list post.

Having MacPorts base provide an option pre-set to the correct docdir is interesting. If we do provide this option in base, it should not begin with ${destroot} because sometimes you want to pass it as an argument to a configure script, display it in notes, or reinplace it into installed files.

Many ports already use the variable docdir for this, as recommended in my recipe. I think having MacPorts base define an option of the same name wouldn't cause a problem but I'm not sure.

I was going to audit and update the python ports now, which would mean potentially having to update ports again later—if this MacPorts base option gets added—if only to remove setting docdir.

Providing another option to automatically create the directory is superfluous. If a portfile author is going to install documentation files manually, it's just as easy to write:

post-destroot {
    xinstall -d ${destroot}${docdir}
    xinstall -m 644 ${worksrcpath}/README ${destroot}${docdir}
}

as it would be to write:

destroot.create_docdir yes

post-destroot {
    xinstall -m 644 ${worksrcpath}/README ${destroot}${docdir}
}

In any case in this ticket I only want to handle removing the default creation of the examples directory from the python portgroup, and the fallout from that. I think discussions of adding an option to MacPorts base, using it in other ports, and auditing other ports for correct docdir usage is outside the scope of this ticket.

[ryandesign (Ryan Carsten Schmidt)]

Replying to ryandesign@…:

Having MacPorts base provide an option pre-set to the correct docdir is interesting.

But is there any precedent for it? We have the variable prefix, but we don't have any variables representing ${prefix}/bin, ${prefix}/lib, ${prefix}/share/man, etc. so why would we single out the value ${prefix}/share/doc/${subport} as needing a dedicated variable to represent it?

[ryandesign (Ryan Carsten Schmidt)]

Ugh, MacPorts base doesn't auto-create ${destroot}${prefix}/share/doc, despite the fact that it's in porthier(7). #47688.

[petrrr]

To keep the scope of this ticket limited as Ryan proposes, I created ticket #47690 to track removal of ${prefix}/share/examples.

[dliessi (Davide Liessi)]

Cc Me!

[mascguy (Christopher Nielsen)]

Add keyword portgroup, to pg-related tickets