From nobody Fri Sep 01 07:57:19 2023 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4RcVk76R32z4sCwC for ; Fri, 1 Sep 2023 07:57:19 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4RcVk74X1bz3Hx7; Fri, 1 Sep 2023 07:57:19 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1693555039; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=USd1zkdrbtPWIqVH6DmtHJmQAy4ar8mmhC6zvkGtEKU=; b=hOHB7J4WEKtyKB8eegRDfprpVoNJmCtYaulvjNIwMPwACNk1taNWom7C9haSgSVKfDzWM+ cJ8YRoLVFX5h0bWnoDEw8qAM0MxZSFkybIcqaY1u5RbdCu0qcOZ3UeRIrPdhpfCtVNq54x 5BJUMCk35fZGPGqQd/PkhqEH7x85DfdMRJw919DBzGIrLmqy/QboyzMPnG5galhzlfwM6X Ew9ot1yTjExp1N3fYaZiwcuXD0j9Pm6pg86TvjIbmvk8/hhjpVEl3+caAQR1TiQIppizAy cayFGby5YcFnEqxFcq4TwfQMcPxCSOTNKbVU5ON7isUB4qPDHjDPMtMls1q7Ng== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1693555039; a=rsa-sha256; cv=none; b=vPFlfEcP27sbylnmw1Hs+96gX9NTC7ns2GeAfwzikVS92e700rqYw1k5LD2MyfqUw/a8KD 5naZAG7wxVvpzQjf29hUeE37v4UttQvOu/l/MiUNj3RF/EZ0aoItG90pbGyPKi01m2yqJa eu4DjdJIZrzI0+EWwfsl8f519DBa4Qx2ZSuAIORYWALiHiZsvZpNmXFYM7hRegAQONbY+H NAOk4W6/GqCsTqLyEaKZljxBnX3QNSCXtn1f1MOpqthEvfjTkKoajzONw81N62ap+KD9ld QABLGWFzDelXA6WWYRJCa5rS0MsMa6onWOlpGdc3V5oQiCAC0+inBwY9dpOszQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1693555039; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=USd1zkdrbtPWIqVH6DmtHJmQAy4ar8mmhC6zvkGtEKU=; b=X/XuZ6xEfJ7W3Yw6LbYDPyWI3bCj4VxO0o27632dbsd9MV7V+vh0gvMJarmxpbOdL9jf8e dnKT1kgtDrdceoTkIexf+EdXsVJrc+rMYFcQ+aZyVaT5HC2l6TDynYR8HHTAIWt4leUn5z MOrmX798Disrl9+U0kRKc+/HZrgsUfGVtUGc8UR12Q1wVNXarnYYZFwg8IgFv153aTLQHi IEBkkTpOMBUNDEOE5J6/2oR/b7UcNtKNAmtwMhQ4PyVC9AyobkM1bS6gF2+/s3Vwz4fRat 55Glsqob9onXVqq9hu0QSkrocCmRq/z5QbBGRpaXlbN6w3vs47yeB1e3kUEzzQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4RcVk73FmTzslb; Fri, 1 Sep 2023 07:57:19 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 3817vJDt074910; Fri, 1 Sep 2023 07:57:19 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 3817vJFC074907; Fri, 1 Sep 2023 07:57:19 GMT (envelope-from git) Date: Fri, 1 Sep 2023 07:57:19 GMT Message-Id: <202309010757.3817vJFC074907@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Fernando =?utf-8?Q?Apestegu=C3=ADa?= Subject: git: d8f0cdf172 - main - [phb]: Document inclusion of Makefile.* files List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: fernape X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: d8f0cdf17224ec08a5dff4431d41070755a5ce4f Auto-Submitted: auto-generated The branch main has been updated by fernape: URL: https://cgit.FreeBSD.org/doc/commit/?id=d8f0cdf17224ec08a5dff4431d41070755a5ce4f commit d8f0cdf17224ec08a5dff4431d41070755a5ce4f Author: Fernando Apesteguía AuthorDate: 2023-08-28 10:24:53 +0000 Commit: Fernando Apesteguía 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