[phb]: Document inclusion of Makefile.* files

Document the automatic inclusion of several Makefile.* files.
Also mention idiomatic splitting of pkg-plist.* files.

PR:			244742
Reported by:		salvadore@
Reviewed by:		carlavilla@, ceri@, grahamperrin
Differential Revision: 	https://reviews.freebsd.org/D41625

1 files changed, 24 insertions, 0 deletions

diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc
index 564a9d3122..608f93123e 100644
--- a/documentation/content/en/books/porters-handbook/special/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/special/_index.adoc
@@ -49,6 +49,30 @@ endif::[]
 
 This section explains the most common things to consider when creating a port.
 
+[[splitting-long-files]]
+== Splitting long files
+
+Sometimes, port [.filename]#Makefiles# can be really long.
+For example, rust ports can have a very long `CARGO_CRATES` list.
+In other cases, the [.filename]#Makefile# might have code that varies depending on the architecture.
+In such cases, it can be convenient to split the original [.filename]#Makefile# into several files.
+[.filename]#bsd.port.mk# automatically includes some types of [.filename]#Makefiles# into the main port [.filename]#Makefile#.
+
+These are the files that the framework handles automatically if they are found:
+
+* [.filename]#Makefile.crates#. An example can be found in package:audio/ebur128[].
+* [.filename]#Makefile.inc#. An example can be found in package:net/ntp[].
+* [.filename]#Makefile.${ARCH}-${OPSYS}#
+* [.filename]#Makefile.${OPSYS}#. An example can be found in package:net/cvsup-static[].
+* [.filename]#Makefile.${ARCH}#
+* [.filename]#Makefile.local#
+
+It is also usual practice to split the packaging list of the port into several files if the list varies a lot from one architecture to another or depends on the selected flavor.
+In this case, the [.filename]#pkg-plist# file for each architecture is named following the pattern [.filename]#pkg-plist.${ARCH}# or [.filename]#pkg-plist.${FLAVOR}#.
+The framework does not create the packaging list automatically if multiple [.filename]#pkg-plist# files exist.
+It is the responsibility of the porter to select the proper [.filename]#pkg-plist# and assign it to the `PLIST` variable.
+Examples on how to deal with this can be found in package:audio/logitechmediaserver[] and package:deskutils/libportal[].
+
 [[staging]]
 == Staging