Add documentation for $startdir, $srcdir, and $pkgdir variables, as well as
general information about the build() function and about custom variables
in PKGBUILDs. This addresses FS#10634.
Signed-off-by: Dan McGee
---
doc/PKGBUILD.5.txt | 44 +++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 43 insertions(+), 1 deletions(-)
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
index ac39472..f4ddc83 100644
--- a/doc/PKGBUILD.5.txt
+++ b/doc/PKGBUILD.5.txt
@@ -30,12 +30,22 @@ distribution of this package.
Options and Directives
----------------------
+The following is a list of standard options and directives available for use
+in a PKGBUILD. These are all understood and interpreted by makepkg, and most
+will be directly transferred to the built package.
+
+If you need to create any custom variables for use in your build process, it is
+recommended to name your custom variables with an '_' (underscore) prefix.
+This will prevent any possible name clashes with internal makepkg variables.
+For example, to store the base kernel version in a variable, use something
+similar to `$_basekernver`.
+
*pkgname*::
The name of the package. This has be a unix-friendly name as it will be
used in the package filename.
*pkgver*::
- The version of the software as released from the author (e.g. \'2.7.1').
+ The version of the software as released from the author (e.g. '2.7.1').
*pkgrel*::
This is the release number specific to the Arch Linux release. This
@@ -205,6 +215,38 @@ Options and Directives
of a package changes (or is alphanumeric).
+build() Function
+----------------
+In addition to the above directives, the build() bash function 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. 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 three variables for your
+use during the build and install process. These three variables are as follows:
+
+*startdir*::
+ This contains the absolute path to the directory where the PKGBUILD was
+ located, which is usually the output of `$(pwd)` when makepkg is started.
+ $$startdir$$ was most often used in combination with `/src` or `/pkg`
+ postfixes, but use of the `srcdir` and `pkgdir` variables is preferred.
+
+*srcdir*::
+ This points to the directory where makepkg extracts or copies all source
+ files. Although it currently is an alias for `$startdir/src`, this
+ assumption should not be assumed true for all future revisions of makepkg.
+
+*pkgdir*::
+ This points to the directory where makepkg bundles the installed package
+ (this directory will become the root directory of your built package).
+ Although it currently is an alias for `$startdir/pkg`, this assumption
+ should not be assumed true for all future revisions of makepkg.
+
+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.
+
Install/Upgrade/Remove Scripting
--------------------------------
Pacman has the ability to store and execute a package-specific script when it
--
1.5.5.3