[pacman-dev] [PATCH 1/3] doc: describe when and why the prepare function should be used
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@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
Currently this is scoped to the build() function, which is simply wrong as it equally applies to any function. Simply moving the paragraphs up to the main manpage section makes this clear. Signed-off-by: Eli Schwartz <eschwartz@archlinux.org> --- doc/PKGBUILD.5.asciidoc | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/PKGBUILD.5.asciidoc b/doc/PKGBUILD.5.asciidoc index 285627ab..83a61458 100644 --- a/doc/PKGBUILD.5.asciidoc +++ b/doc/PKGBUILD.5.asciidoc @@ -332,6 +332,14 @@ PKGBUILD must contain a `package()` function which installs all the package's files into the packaging directory, with optional `prepare()`, `build()`, and `check()` functions being used to create those files from source. +This is directly sourced and executed by makepkg, so anything that Bash or the +system has available is available for use here. Be sure any exotic commands +used are covered by the `makedepends` array. + +If you create any variables of your own in any of these functions, it is +recommended to use the Bash `local` keyword to scope the variable to inside the +function. + *package() Function*:: The `package()` function is used to install files into the directory that will become the root directory of the built package and is run after all @@ -351,14 +359,7 @@ files into the packaging directory, with optional `prepare()`, `build()`, and *build() Function*:: The optional `build()` function is use to compile and/or adjust the source - files in preparation to be installed by the `package()` function. This is - directly sourced and executed by makepkg, so anything that Bash or the - system has available is available for use here. Be sure any exotic - commands used are covered by the `makedepends` array. -+ -If you create any variables of your own in the `build()` function, it is -recommended to use the Bash `local` keyword to scope the variable to inside -the `build()` function. + files in preparation to be installed by the `package()` function. *check() Function*:: An optional `check()` function can be specified in which a package's -- 2.21.0
It is often not obvious to people, that build() can be run multiple times when continuing a build with --noextract. Signed-off-by: Eli Schwartz <eschwartz@archlinux.org> --- doc/PKGBUILD.5.asciidoc | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/PKGBUILD.5.asciidoc b/doc/PKGBUILD.5.asciidoc index 83a61458..6336a5cd 100644 --- a/doc/PKGBUILD.5.asciidoc +++ b/doc/PKGBUILD.5.asciidoc @@ -359,7 +359,11 @@ function. *build() Function*:: The optional `build()` function is use to compile and/or adjust the source - files in preparation to be installed by the `package()` function. + files in preparation to be installed by the `package()` function. All + commands specific to the package creation (but not source code + preparation), before the final installation of files into the packaging + root, should be performed here. The `build()` function is permitted to run + multiple times if `makepkg --noextract` is used. *check() Function*:: An optional `check()` function can be specified in which a package's -- 2.21.0
On 13/3/19 3:01 am, Eli Schwartz wrote:
It is often not obvious to people, that build() can be run multiple times when continuing a build with --noextract.
Signed-off-by: Eli Schwartz <eschwartz@archlinux.org> --- doc/PKGBUILD.5.asciidoc | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/doc/PKGBUILD.5.asciidoc b/doc/PKGBUILD.5.asciidoc index 83a61458..6336a5cd 100644 --- a/doc/PKGBUILD.5.asciidoc +++ b/doc/PKGBUILD.5.asciidoc @@ -359,7 +359,11 @@ function.
*build() Function*:: The optional `build()` function is use to compile and/or adjust the source - files in preparation to be installed by the `package()` function. + files in preparation to be installed by the `package()` function. All + commands specific to the package creation (but not source code + preparation), before the final installation of files into the packaging + root, should be performed here. The `build()` function is permitted to run + multiple times if `makepkg --noextract` is used.
The last sentence is confusing. I know when the build() function runs, but still took too long to parse what you meant.
*check() Function*:: An optional `check()` function can be specified in which a package's
On 3/19/19 12:14 AM, Allan McRae wrote:
On 13/3/19 3:01 am, Eli Schwartz wrote:
It is often not obvious to people, that build() can be run multiple times when continuing a build with --noextract.
Signed-off-by: Eli Schwartz <eschwartz@archlinux.org> --- doc/PKGBUILD.5.asciidoc | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/doc/PKGBUILD.5.asciidoc b/doc/PKGBUILD.5.asciidoc index 83a61458..6336a5cd 100644 --- a/doc/PKGBUILD.5.asciidoc +++ b/doc/PKGBUILD.5.asciidoc @@ -359,7 +359,11 @@ function.
*build() Function*:: The optional `build()` function is use to compile and/or adjust the source - files in preparation to be installed by the `package()` function. + files in preparation to be installed by the `package()` function. All + commands specific to the package creation (but not source code + preparation), before the final installation of files into the packaging + root, should be performed here. The `build()` function is permitted to run + multiple times if `makepkg --noextract` is used.
The last sentence is confusing. I know when the build() function runs, but still took too long to parse what you meant.
Would it help to say: s/run/be executed/ -- Eli Schwartz Bug Wrangler and Trusted User
On 13/3/19 3:01 am, Eli Schwartz wrote:
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@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
Why add "exactly once" here? What is this clarifying?
+ `build()` function. The `prepare()` function is skipped when source + extraction is skipped. No system-specific or build-specific commands should
what is a system-specific or build-specific command here?
+ 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
How about this, which documents by example? An optional `prepare()` function can be specified in which operations to prepare the sources for building, such as patching, are performed. For example, generating configuration files using autoreconf should occur in prepare(), but running the configure script should happen in build(). This function is run after the source extraction and before the `build()` function. The `prepare()` function is skipped when source extraction is skipped.
On 3/19/19 12:30 AM, Allan McRae wrote:
On 13/3/19 3:01 am, Eli Schwartz wrote:
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@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
Why add "exactly once" here? What is this clarifying?
In contrast to the build function, which should be optimally designed to work when makepkg --noextract carries on a build. But in retrospect, saying "exactly once" does not clarify this and it should be inferred since build() is logically an exception.
+ `build()` function. The `prepare()` function is skipped when source + extraction is skipped. No system-specific or build-specific commands should
what is a system-specific or build-specific command here?
system-specific or build-specific is anything that depends on either the operating system or the current makepkg environment, so that would preclude running any sort of configure script, meson, cmake, etc.
+ 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
How about this, which documents by example?
An optional `prepare()` function can be specified in which operations to prepare the sources for building, such as patching, are performed. For example, generating configuration files using autoreconf should occur in prepare(), but running the configure script should happen in build(). This function is run after the source extraction and before the `build()` function. The `prepare()` function is skipped when source extraction is skipped.
I like the mentioning by example, but I would ideally like to mention the unavailability of buildflags somehow, as this illustrates why prepare() "must" not be used for configure, rather than "should" not. -- Eli Schwartz Bug Wrangler and Trusted User
participants (2)
-
Allan McRae
-
Eli Schwartz