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.
