[pacman-dev] [PATCH 1/3] doc: describe when and why the prepare function should be used

[Eli Schwartz]

We don't want people to run architecture/OS/makepkg.conf specific
processes during prepare() and in fact it's been observed that makepkg
by design doesn't even run prepare_buildenv() for it, so the prohibition
against this is now baked into makepkg.

Reflect this differentiation in the documentation on just what, exactly,
a prepare() function is.

Signed-off-by: Eli Schwartz <eschwartz at archlinux.org>
---

This patch coincides with quequotion's clarification of the options=()
array, so thanks for inspiring me to write this!

I believe that both patches have merit independent of each other.

 doc/PKGBUILD.5.asciidoc | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/PKGBUILD.5.asciidoc b/doc/PKGBUILD.5.asciidoc
index e8ce691f..285627ab 100644
--- a/doc/PKGBUILD.5.asciidoc
+++ b/doc/PKGBUILD.5.asciidoc
@@ -342,9 +342,12 @@ files into the packaging directory, with optional `prepare()`, `build()`, and
 *prepare() Function*::
 	An optional `prepare()` function can be specified in which operations to
 	prepare the sources for building, such as patching, are performed. This
-	function is run after the source extraction and before the `build()`
-	function. The `prepare()` function is skipped when source extraction
-	is skipped.
+	function is run exactly once, after the source extraction and before the
+	`build()` function. The `prepare()` function is skipped when source
+	extraction is skipped. No system-specific or build-specific commands should
+	be run during `prepare()` under any circumstances, as they are meant to run
+	exclusively during `build()`, and features like `buildflags` or `makeflags`
+	are expressly not available.
 
 *build() Function*::
 	The optional `build()` function is use to compile and/or adjust the source
-- 
2.21.0