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.

I understand that subpackages can be used to split off development specific files (e.g. header files), examples, documentation, etc. from a package.

But I think there are significant issues for non-trivial ports that are converted to use subpackages to control the installed functionality.

I do not see that the case of build options depending on subpackages been considered? (i.e. the opposite case of subpackages being selected by port options)

AFAIU the patch, the selection of subpackages to be built can be controlled by either of two mechanisms:

1. The initial method is that OPTIONS add values to ${SUBPACKAGES}. In that case, other build parameters controlled by the options may be defined.
2. The subpackage in a *_DEPENDS variable is identified with a ~subpkg modifier added to its origin. But port options that lead to this subpackage being build by the first method are not known in that case (unless a mechanism is introduced that sets those options depending on the subpackage built as a dependency).

This leads to more complications in non-trivial cases. E.g. if a subpackage exists for NLS locale dependent data files, then the main program will need to be linked against optional libraries. For thos example, either the NLS option is always defined when building the main package (adding complexity for the non-NLS use case) or a ~nls subpackage cannot be combined with the non-NLS main program.
To work around this issue, ports will always need to be build with a complete set of options (e.g. if those control the integration of hooks), but if a port is built with plain make (or a port management tool) this will lead to all those subpackages and their dependencies being installed.

If a dependency for a non-default subpackage leads to main being rebuild with a non-default option, this may lead to creation of a main package with non-default options that replace the main subpackage initially built without that option. A later upgrade could then cause the main package to again be built without that additional option, breaking the subpackage that needs main with non-default options.

This is an issue not only for port building with make or port management tools, but also for poudriere if not all subpackages are always built (and thus all options defined that are required to support any of those subpackages). It is possible that some subpackages conflict with each other and thus that not all subpackages can be built at the same time. This includes cases that need different and incompatible hooks in the main package, too.

Other issues are (IMHO):

• No automatic creation of pkg-plist files for subpackages ("make makeplist" could be used to create a list of all files, but the assignment to subpackages cannot be automated)
• Why are there no CATEGORIES.${p} and *CONFLICTS.${p}?
• WIll the subpackage selector be included in the MANIFEST and in the package db?
• What will "make deinstall" do if non-default subpackages have been installed that depend on the main package?