Rearrange the functions section of the PKGBUILD man package. Clarify
that the package() function is a requirement and the rest are all
optional. Note that $pkgdir should only be used in the package()
function.
Signed-off-by: Allan McRae <allan(a)archlinux.org>
---
doc/PKGBUILD.5.txt | 97 +++++++++++++++++++++++++++---------------------------
1 file changed, 48 insertions(+), 49 deletions(-)
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
index b48f0a7..688ce8a 100644
--- a/doc/PKGBUILD.5.txt
+++ b/doc/PKGBUILD.5.txt
@@ -280,62 +280,61 @@ A normal sync or upgrade will not use its value.
When used in combination with the `strip' option, a separate package
containing the debug symbols is created.
-build() Function
-----------------
-In addition to the above directives, the optional build() function usually
-comprises the remainder of the PKGBUILD. This is directly sourced and executed
-by makepkg, so anything that bash or the system has available is available for
-use here. The function is run in `bash -e` mode, meaning any command that exits
-with a non-zero status will cause the function to exit. Be sure any exotic
-commands used are covered by `makedepends`.
-All of the above variables such as `$pkgname` and `$pkgver` are available for use
-in the build function. In addition, makepkg defines the following three
-variables for use during the build and install process:
+Packaging Functions
+-------------------
+
+In addition to the above directives, PKGBUILDs require a set of functions that
+provide instructions to build and install the package. As a minimum, the PKGBUILD
+must contain a package() function which installs all the package's files into the
+packaging directory, with optional prepare(), build() and check() being used to
+create those files from source.
+
+*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
+ the optional functions listed below. When specified in combination with
+ the fakeroot BUILDENV option in linkman:makepkg.conf[5], fakeroot usage
+ will be limited to running the packaging stage. All other functions will
+ be run as the user calling makepkg.
+
+*prepare() Function*::
+ An optional prepare() function can be specified in which operations that
+ are to be run in order to prepare the sources for building (such as
+ patching) are performed. This function is run after the source extraction
+ and before the build() function and is skipped when source extraction is
+ skipped.
+
+*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 `makedepends`.
++
+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.
-*startdir*::
- This contains the absolute path to the directory where the PKGBUILD is
- located, which is usually the output of `$(pwd)` when makepkg is started.
- Use of this variable is deprecated and strongly discouraged.
+*check() Function*::
+ An optional check() function can be specified in which a package's
+ test-suite may be run. This function is run between the build() and
+ package() functions. Be sure any exotic commands used are covered by
+ `checkdepends`.
+
+All of the above variables such as `$pkgname` and `$pkgver` are available for use
+in the build function. In addition, makepkg defines the following variables for use
+during the build and install process:
*srcdir*::
- This contains the directory where makepkg extracts, or copies, all source
- files.
+ This contains the directory where makepkg extracts, or copies, all sourc
+ files.
*pkgdir*::
- This contains the directory where makepkg bundles the installed package
- (this directory will become the root directory of your built package).
-
-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.
+ This contains the directory where makepkg bundles the installed package
+ (this directory will become the root directory of your built package).
+ This variable should only be used in the package() function.
-prepare() Function
-------------------
-An optional prepare() function can be specified in which operations that are
-to be run in order to prepare the sources for building (such as patching) are
-performed. This function is run after the source extraction and before the
-build() function and is skipped when source extraction is skipped. The
-function is run in `bash -e` mode, meaning any command that exits with a
-non-zero status will cause the function to exit.
-
-check() Function
-----------------
-An optional check() function can be specified in which a packages test-suite
-may be run. This function is run between the build() and package() functions.
-The function is run in `bash -e` mode, meaning any command that exits with a
-non-zero status will cause the function to exit. Be sure any exotic commands
-used are covered by `checkdepends`.
-
-package() Function
-------------------
-An optional package() function can be specified in addition to the build()
-function. This function is run after the build() and check() functions. The
-function is run in `bash -e` mode, meaning any command that exits with a
-non-zero status will cause the function to exit. When specified in combination
-with the fakeroot BUILDENV option in linkman:makepkg.conf[5], fakeroot usage
-will be limited to running the packaging stage. An existing build() function
-will be run as the user calling makepkg.
Package Splitting
-----------------
--
1.8.1.2