Page MenuHomeFreeBSD

Subpackages. (deal with it.)
Needs RevisionPublic

Authored by mat on Jul 26 2018, 2:38 PM.


Group Reviewers

Introduce subpackages to the ports framework - this allows ports to be built once, but have multiple packages created. For example, have a subpackage for docs and examples.

To add subpackages to a port, define:


and in the plist, prefix files to put in a subpackage with @@foo@@.

For each subpackage, some variables can be set, if needed.

  • DESCR.<subpkg> defaults to the pkg-descr if pkg-descr.<subpkg> does not exist.
  • COMMENT.<subpkg> defaults to ${COMMENT} (subpkg: <subpkg>)
  • All the PKGMESSAGE/PKGINSTALL/... variable have .<subpkg> version, pointing to pkg-message.<subpkg>/pkg-install.<subpkg> files.
  • A few options helpers <opt>_SUBPACKAGES and <opt>_*_DEPENDS.<subpkg> can be used. See lang/perl5-devel example.
  • PLIST_FILES.<subpkg> and PLIST_DIRS.subpkg were added too.

Subpackages can depend on each other, a new variable has been introduced, SELF_DEPENDS, and a special subpackage name has been introduced to refer to the main package. For example:

If the foo subpackage depends on the main subpackage:

SUBPACKAGES=  foo main

If the main package depends on the tools subpackage:

Test Plan


You will probably need a patched poudriere, patches from either the branch or the pull request

Diff Detail

No Linters Available
No Unit Test Coverage
Build Status
Buildable 31581
Build 29177: arc lint + arc unit

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

I'm curious why we need both %%GDBM%% and @@gdbm@@.

mat marked an inline comment as done.Dec 6 2018, 3:45 PM
In D16457#391200, @bapt wrote:

I do think that is good enough as a start and that we should go further in an incremental way.
I do like the SELF_DEPENDS thing.
Can we proceed right now?

Well, I would like to finish with the php72 port, convert all options to subpackages to make sure I do not need more stuff to handle the few cases I have not done yet.


%%GDBM%% is there because GDBM support is an option, and @@gdbm@@ because the file gets in a subpackage.

It is still a review because stuff still need to be discussed ;-)

For example, if OPT_SUBPACKAGES is defined, does it mean that files guarded by %%OPT%% automatically get in the subpackage set in there? What if opt_SUBPACKAGES defines more than one subpackage? What if some files from option opt should go in a different subpackage, say the "doc" one?

This revision now requires review to proceed.Dec 9 2018, 10:14 AM

Just some thoughts, feel free to ignore:

  • when defining OPT_SUBPACKAGE (e.g. OPT_gdbm) it would be a nice idea to automatically move the %%GDBM%% files into the gdbm subpackage, so e.g. %%gdbm%%%%ARCH_LIB%%/ (so using lowercase option names to combine the subpackage and the regular option names). This way we can reduce some red tape.
  • When should go into multiple/different subpackages: %%GDBM%%@@doc@@%%ARCH_LIB%%/ %%GDBM%%@@gdbm@@%%ARCH_LIB%%/ %%gdbm%%%%ARCH_LIB%%/

This combining option and subpackage names is not foolproof, there are a few ports with lowercase option names (one qt4/kde4-using port IIRC).

mat marked an inline comment as done.Dec 9 2018, 10:54 AM
mat added inline comments.

I feel the semantics would get overly complicated and confuse people.

Options MUST be uppercase, I think there is a QA check for this. I do not remember finding ports with lowercase options, but in any case, they should be fixed.


Yes, probably better to leave the option and subpackage name split.

It was the QA check that notified me of that port ;)

I suggest to wait for 2019Q1, then:

  • update proudriere(-devel) with @mat 's patch
  • update user/developer documentation
  • rebase the patch
  • commit the patch
  • send out some emails to announce subpackages
In D16457#396393, @rene wrote:

I suggest to wait for 2019Q1, then:

  • update proudriere(-devel) with @mat 's patch
  • update user/developer documentation
  • rebase the patch
  • commit the patch
  • send out some emails to announce subpackages

Mmmm, you assume the patch has not changed in the past few months because it is ready, it is most probably not. It has not changed because I do not have had the time to work on it any more.

Ah, I was too optimistic :(


^ flavors sounds wrong here.


^ I would keep it afterwards and add a DEV_WARNING


How about adding a ala

COMMENTSUFFIX.debug?=           Debug Parts
COMMENTSUFFIX.doc?=             Documentation
COMMENTSUFFIX.l10n?=            Localization Files

And then do something like:

.    if defined(COMMENTSUFFIX.${p})
.    else
_COMMENTSUFFIX?=       ${p} subpackage
.    endif
. endfor
mat marked an inline comment as done.Feb 4 2019, 2:08 PM
mat added inline comments.

Ah, yes, too much copy&paste ^^


Mmmm. You mean a DEV_WARNING when the subpackage does not have a specific description file?


First, I think should die, preferably in a large bonfire. Because it's all filled in with:

<foo>_DESC= <foo> support

Which is mostly useless to end users, because it does not tell them anything. Of course option foo as something to do with foo being added. But it does not tell the users what foo is, or what adding foo support actually does.

For example, if a port has the ICU option, the user will be shown "Unicode support via ICU", but what does it mean for the port? Does it mean that without it, the port will only accept 7 bit ASCII text input?

So, while your three examples are ok, I feel having this would end up as the options, and not saying much of what's in it. Or it would need to require some sort of approval to add to, unlike options.desc right now.

Also, I feel adding too many helpers defeats the purpose of having everything customizable.

(Side note, your example can be written as two lines:

COMMENTSUFFIX.${p}?=       ${p} subpackage


mat marked an inline comment as done.

rebase & add git subpackages

Small fix in:

  • Strip subpackage markers from the plist. (May not be correct.)


  • Use sed instead of grep here, grep exists if it does not output

Fixup in

  • Start getting php72 to use subpackages.

@mat is this stable enough to start play around with? Because for example Qt has many split ports that could be used as testing ground too (basically all the ports that have the same qt-dist value).

@mat is this stable enough to start play around with? Because for example Qt has many split ports that could be used as testing ground too (basically all the ports that have the same qt-dist value).

Yes, this is definitively a good idea to play around with it. There are still a few things that need fixing/doing, but I doubt the way it works will change.

Note that you need a patch for poudriere to play with subpackages :-)

  • Add automatic metapkg support for Python flavors.
mat marked 7 inline comments as done.Jan 28 2020, 1:42 PM
  • fixup! Add automatic metapkg support for Python flavors.
  • fixup! Add automatic metapkg support for Python flavors.
  • Sanitize environment here, sometime, stuff leaks from and breaks
  • fixup! Add automatic metapkg support for Python flavors.
  • Ajouter une variable PKGNAME.<subpkg>.
  • Ajouter une variable PKGNAME.<subpkg>.
  • Add PKGNAMES that has the main package name, and subpackage names.

Can we add this (from

Sub Packages
Build the port once and create multiple packages. For example, have a sub package for docs and examples.

or some similar description to summary for people who aren't familiar with subpackages.

Are there any blockers preventing us from committing this feature?

mandree requested changes to this revision.EditedOct 23 2020, 7:31 PM
mandree added a subscriber: mandree.

I might find breaking out one build into multiple packages very useful,
but for a successful launch I propose this would require a proper specification added to the documentation. Documentation by example is no good for developers who are new to this feature.
I wonder if there should be an option for split-out pkg-plist files, which would be much easier to understand.

Please add:

  • an section for the porter's handbook, consisting of (1) introduction (the summary is mostly okay), (2) specification, (3) examples,
  • proposals for portlint, portclippy/portfmt and, if needed, stage-qa and check-plist
  • a proposed ports/CHANGES entry
  • for new volunteers, some thoughts on the intended relation between options and subpackages, and possibly subpackages and dependencies
  • an option to have pkg-plist.<subpkg> - it does not look very useful if I need to search @@subpkg@@ lines that are few and far between in a longish file of a nontrivial port.
This revision now requires changes to proceed.Oct 23 2020, 7:31 PM

Just a note to other developers interested in this feature: the current blocker is Poudriere support, additional help with the development is appreciated: