<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<p>On 2021-07-10 01:07, Joshua Root wrote:<br>
</p>
<blockquote type="cite"
cite="mid:b6fd1c33-2c6e-b218-4925-aeed4776637a@macports.org">On
2021-7-10 17:42 , Jim DeLaHunt wrote:
<br>
<blockquote type="cite">Hi folks:
<br>
<br>
I'm trying to write my first Portfile, and I have a terribly
naive question: what does the "subport" directive in the
Portfile do?
<br>
</blockquote>
<br>
Please see
<a class="moz-txt-link-rfc2396E" href="https://trac.macports.org/ticket/36957#comment:3"><https://trac.macports.org/ticket/36957#comment:3></a>.
<br>
</blockquote>
<p>Ah! Thank you. I guess I'm not the first person to notice this
lack.<br>
</p>
<p><br>
</p>
<blockquote type="cite"
cite="mid:b6fd1c33-2c6e-b218-4925-aeed4776637a@macports.org">
<blockquote type="cite">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?
<br>
<br>
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?
<br>
</blockquote>
<br>
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.
<br>
<blockquote type="cite">… this means six fetches, configures, and
builds, or one.
<br>
</blockquote>
<br>
…All the subports will share a dist_subdir by default though, so
you won't have to actually download 6 copies of the distfile.
<br>
</blockquote>
<p>I think I found the code which implements the subport directive:
macports-base/src/port1.0/portutil.tcl:844-857 [1]. <br>
[1]
<a class="moz-txt-link-freetext" href="https://github.com/macports/macports-base/blob/2c6fc24ddd1d6961afa83c5b35be12224b6850f6/src/port1.0/portutil.tcl#L844-L857">https://github.com/macports/macports-base/blob/2c6fc24ddd1d6961afa83c5b35be12224b6850f6/src/port1.0/portutil.tcl#L844-L857</a><br>
</p>
<p>Assuming I understand this correctly, could I please get a review
of this draft documentation for the subport declaration?</p>
<p>----------<br>
</p>
<p>[Insert 2nd-level section between current 5.5. Variants and 5.6.
5.6. Tcl Extensions & Useful Tcl Commands]</p>
<p><b>5.6. Subports</b></p>
<p>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. <br>
</p>
<p><b>5.6.1 Subport Declarations</b><br>
</p>
<p>subport <i>name</i> <i>body</i><br>
</p>
<p>The subport declaration causes MacPorts to define an additional
port, with the <i>name</i> given by the declaration. The keywords
for the subport are those in the global section of the Portfile,
and those in the brace-enclosed <i>body</i>. <br>
</p>
<p><b>5.6.2 Subport Examples</b><br>
</p>
<p>For example, if a Portfile contains: <br>
</p>
<p>-----<br>
Portfile 1.0<br>
Name <i>example</i><br>
depends_lib <i>aaa</i><br>
configure.args --<i>bbb</i><br>
<br>
subport <i>cd_sub</i> {<br>
depends_lib-append <i>ccc</i><br>
configure.args --<i>ddd</i><i></i><br>
}<br>
<br>
subport <i>ef</i><i>_sub</i> {<br>
depends_lib-append eee<br>
configure.args-append --<i>fff</i><i></i><br>
}<br>
-----<br>
</p>
<p>MacPorts will produce the same results as if there were three
Portfiles:</p>
<p>-----<br>
Portfile 1.0<br>
Name <i>example</i><br>
depends_lib <i>aaa</i><br>
configure.args --<i>bbb</i><br>
</p>
<p>-----<br>
Portfile 1.0<br>
Name <i>cd_sub</i><br>
depends_lib <i>aaa</i><br>
configure.args --<i>bbb</i><br>
depends_lib-append <i>ccc</i><br>
configure.args <i>--ddd</i><br>
</p>
<p>-----<br>
Portfile 1.0<br>
Name <i>ef</i><i>_sub</i><br>
depends_lib <i>aaa</i><br>
configure.args --<i>bbb</i><br>
depends_lib-append <i>eee</i><br>
configure.args-append <i>--fff</i><br>
-----<br>
</p>
<p>5.6.3. Tips</p>
<p>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.</p>
<p>----------<br>
</p>
<p>[Another minor change: change the intro text for Chapter 5.
Portfile Reference as follows.]</p>
<p>Previous text: <br>
</p>
<blockquote>
<p>…port phases, dependencies, StartupItems, variables, keywords,
and Tcl extensions.</p>
</blockquote>
<p>New text: <br>
</p>
<blockquote>
<p>…keywords, variables, port phases, dependencies, variants,
subports, Tcl extensions, StartupItems, Livecheck, and
PortGroups.</p>
</blockquote>
<p>----------<br>
</p>
<p>[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.<br>
</p>
<p>----------<br>
</p>
<p>If the review comments show that I am close enough, I will turn
this into a documentation pull request.</p>
<p><br>
</p>
<blockquote type="cite"
cite="mid:b6fd1c33-2c6e-b218-4925-aeed4776637a@macports.org">P.S.
Please use the list address @lists.macports.org, not the old
macosforge address.
<br>
</blockquote>
<p>Thank you, I appreciate the correction.</p>
<br>
</body>
</html>