[pacman-dev] [PATCH 2/2] doc: update PKGBUILD man page

[Allan McRae]

On 02/02/13 12:51, Allan McRae wrote:
> 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 at 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.

...

also re-added $startdir here.   There still seem some almost valid uses
for it (see any Arch kernel module package).

Allan