git: d8f0cdf172 - main - [phb]: Document inclusion of Makefile.* files

The branch main has been updated by fernape:

URL: https://cgit.FreeBSD.org/doc/commit/?id=d8f0cdf17224ec08a5dff4431d41070755a5ce4f

commit d8f0cdf17224ec08a5dff4431d41070755a5ce4f
Author:     Fernando Apesteguía <[email protected]>
AuthorDate: 2023-08-28 10:24:53 +0000
Commit:     Fernando Apesteguía <[email protected]>
CommitDate: 2023-09-01 07:55:45 +0000

    [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
---
 .../en/books/porters-handbook/special/_index.adoc  | 24 ++++++++++++++++++++++
 1 file changed, 24 insertions(+)

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