Newbie Portfile writer question: what does "subport" do?

[Jim DeLaHunt]

On 2021-07-10 01:07, Joshua Root wrote:

> On 2021-7-10 17:42 , Jim DeLaHunt wrote:
>> Hi folks:
>>
>> I'm trying to write my first Portfile, and I have a terribly naive 
>> question: what does the "subport" directive in the Portfile do?
>
> Please see <https://trac.macports.org/ticket/36957#comment:3>.

Ah! Thank you. I guess I'm not the first person to notice this lack.


>> And: How do the "subport" directives interact with what is defined at 
>> the top level of the Portfile? How do both the top level of the 
>> Portfile and the subport blocks relate to a) fetching the source code 
>> and b) configuring the source code and c) building the software and 
>> d) installing the software?
>>
>> Should I think of the top-level Portfile definitions and each subport 
>> as being separate ports, each with their own fetch, configure, build, 
>> and install activity? Or do the subports somehow modify the top-level 
>> Portfile definitions for a single fetch, configure, build, and 
>> install activity?
>
> Both really. Each subport is added to the PortIndex as a distinct 
> port. Any code not inside a subport block executes for all subports 
> defined in the Portfile. They are separate ports that share part of 
> their definition.
>> … this means six fetches, configures, and builds, or one.
>
> …All the subports will share a dist_subdir by default though, so you 
> won't have to actually download 6 copies of the distfile.

I think I found the code which implements the subport directive: 
macports-base/src/port1.0/portutil.tcl:844-857 [1].
[1] 
https://github.com/macports/macports-base/blob/2c6fc24ddd1d6961afa83c5b35be12224b6850f6/src/port1.0/portutil.tcl#L844-L857

Assuming I understand this correctly, could I please get a review of 
this draft documentation for the subport declaration?

----------

[Insert 2nd-level section between current 5.5. Variants and 5.6. 5.6. 
Tcl Extensions & Useful Tcl Commands]

*5.6. Subports*

MacPorts subports are a way of declaring multiple related ports in a 
single Portfile. It is especially helpful to use subports when the 
related ports share variables or keywords, because they can be declared 
in the shared part of the Portfile and used by each subport.

*5.6.1 Subport Declarations*

subport /name/ /body/

The subport declaration causes MacPorts to define an additional port, 
with the /name/ given by the declaration. The keywords for the subport 
are those in the global section of the Portfile, and those in the 
brace-enclosed /body/.

*5.6.2 Subport Examples*

For example, if a Portfile contains:

-----
Portfile 1.0
Name /example/
depends_lib /aaa/
configure.args --/bbb/

subport /cd_sub/ {
     depends_lib-append /ccc/
     configure.args --/ddd///
}

subport /ef//_sub/ {
     depends_lib-append  eee
     configure.args-append --/fff///
}
-----

MacPorts will produce the same results as if there were three Portfiles:

-----
Portfile 1.0
Name /example/
depends_lib /aaa/
configure.args --/bbb/

-----
Portfile 1.0
Name /cd_sub/
depends_lib /aaa/
configure.args --/bbb/
     depends_lib-append /ccc/
     configure.args /--ddd/

-----
Portfile 1.0
Name /ef//_sub/
depends_lib /aaa/
configure.args --/bbb/
     depends_lib-append /eee/
     configure.args-append /--fff/
-----

5.6.3. Tips

Because MacPorts treats each subport as a separate port declaration, 
each subport will have its own, independent phases: fetch, configure, 
build, destroot, install, activate, etc. However, because the subports 
share the global declaration part, all the subports will by default 
share the same dist_subdir. This means that MacPorts only needs to fetch 
the distfiles once, and the remaining subports can reuse the distfiles.

----------

[Another minor change: change the intro text for Chapter 5. Portfile 
Reference as follows.]

Previous text:

    …port phases, dependencies, StartupItems, variables, keywords, and
    Tcl extensions.

New text:

    …keywords, variables, port phases, dependencies, variants, subports,
    Tcl extensions, StartupItems, Livecheck, and PortGroups.

----------

[Also for man page portfile(7), insert section SUBPORTS between existing 
VARIANTS and PLATFORM OPTIONS sections. Content is similar to the Guide 
content above, though maybe omit the example and the subsection headings.

----------

If the review comments show that I am close enough, I will turn this 
into a documentation pull request.


> P.S. Please use the list address @lists.macports.org, not the old 
> macosforge address.

Thank you, I appreciate the correction.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macports.org/pipermail/macports-dev/attachments/20210711/56df02aa/attachment.htm>