aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorFernando Apesteguía <fernape@FreeBSD.org>2023-08-28 10:24:53 +0000
committerFernando Apesteguía <fernape@FreeBSD.org>2023-09-01 07:55:45 +0000
commitd8f0cdf17224ec08a5dff4431d41070755a5ce4f (patch)
tree5593c68691259ccb288ac668ac9896e4184e2e18
parentc70e7661b582a58aeeee05d3f9cd346f4427e435 (diff)
downloaddoc-d8f0cdf172.tar.gz
doc-d8f0cdf172.zip
[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
-rw-r--r--documentation/content/en/books/porters-handbook/special/_index.adoc24
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