[pacman-dev] [PATCH] Revise PKGBUILD(5), document pkgver() in PKGBUILD(5), and update example PKGBUILD
Allan McRae
allan at archlinux.org
Mon Apr 8 21:05:14 EDT 2013
On 09/04/13 09:46, Jason St. John wrote:
> From: "Jason St. John" <jstjohn at purdue.edu>
>
> Several grammatical errors and minor formatting consistency issues have been resolved in
> PKGBUILD(5).
>
> The pkgver() function is now fully documented in PKGBUILD(5), including
> several usage examples taken from ArchWiki. The "Using VCS Sources"
> section now states that CVS and Darcs are not natively supported in
> makepkg.
>
> The example PKGBUILD for 'patch' was rather basic and lacked the
> prepare() and check() functions. The PKGBUILD was also rather dated
> compared to the current, official PKGBUILD. The new example PKGBUILD is
> a lot more complete and displays more features of makepkg.
>
> Signed-off-by: Jason St. John <jstjohn at purdue.edu>
> ---
I'm of the opinion we do not need most of this.... Details below.
> doc/PKGBUILD-example.txt | 45 +++++++++----
> doc/PKGBUILD.5.txt | 163 ++++++++++++++++++++++++++++++++++-------------
> 2 files changed, 152 insertions(+), 56 deletions(-)
>
> diff --git a/doc/PKGBUILD-example.txt b/doc/PKGBUILD-example.txt
> index 9ab5dff..8508b10 100644
> --- a/doc/PKGBUILD-example.txt
> +++ b/doc/PKGBUILD-example.txt
> @@ -1,24 +1,45 @@
> # Maintainer: Joe User <joe.user at example.com>
>
> pkgname=patch
> -pkgver=2.5.4
> -pkgrel=3
> -pkgdesc="A utility to apply patch files to original sources"
> +pkgver=2.7.1
> +pkgrel=2
> +pkgdesc='A utility to apply patch files to original sources'
> arch=('i686' 'x86_64')
> -url="https://www.gnu.org/software/patch/patch.html"
> +url='https://www.gnu.org/software/patch/patch.html'
> license=('GPL')
> groups=('base-devel')
> -depends=('glibc' 'ed')
> -source=(ftp://ftp.gnu.org/gnu/$pkgname/$pkgname-$pkgver.tar.gz)
> -md5sums=('ee5ae84d115f051d87fcaaef3b4ae782')
> +depends=('glibc')
> +makedepends=('ed')
> +optdepends=('ed: for patch -e functionality')
> +source=("ftp://ftp.gnu.org/gnu/${pkgname}/${pkgname}-${pkgver}.tar.xz{,.sig}"
> + 'patch-2.7.1-initialize-data-structures-early-enough.patch')
> +md5sums=('e9ae5393426d3ad783a300a338c09b72'
> + 'b12189e0de3cb2af25268441647ec517'
> + 'dc6367a7cd49933d4006c246789e98da')
> +
> +prepare() {
> + cd "${srcdir}/${pkgname}-${pkgver}"
> +
> + # Fix segfault on non-numeric strip-count
> + # (also segfaults on nonexistent directory passed to -d)
> + # http://savannah.gnu.org/bugs/?37500
> + patch -Np1 -i \
> + "$srcdir/patch-2.7.1-initialize-data-structures-early-enough.patch"
> +}
>
> build() {
> - cd "$srcdir"/$pkgname-$pkgver
> - ./configure --prefix=/usr
> - make
> + cd "${srcdir}/${pkgname}-${pkgver}"
> +
> + ./configure --prefix=/usr
> + make
> +}
> +
> +check() {
> + cd "${srcdir}/${pkgname}-${pkgver}"
> + make check
> }
>
> package() {
> - cd "$srcdir"/$pkgname-$pkgver
> - make prefix="$pkgdir"/usr install
> + cd "${srcdir}/${pkgname}-${pkgver}"
> + make DESTDIR="$pkgdir" install
> }
This has gone from being a nice minimal example to something that is
very overboard... We already refer the user to their distributions
PKGBUILDs or ABS to get more examples, so I think it should sta as
simple as possible.
> diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
> index ea280a0..f1d2998 100644
> --- a/doc/PKGBUILD.5.txt
> +++ b/doc/PKGBUILD.5.txt
> @@ -49,7 +49,7 @@ similar to `$_basekernver`.
> The variable is not allowed to contain colons or hyphens.
> +
> The `pkgver` variable can be automatically updated by providing a `pkgver()` function
> -in the PKGBUILD that outputs the new package version. This is run after downloading
> +in the PKGBUILD that outputs the new package version. This is run after downloading
> and extracting the sources so can use those files in determining the new `pkgver`.
> This is most useful when used with sources from version control systems (see below).
>
Sure - not shown in man page anyway...
> @@ -91,13 +91,13 @@ This is most useful when used with sources from version control systems (see bel
>
> *install*::
> Specifies a special install script that is to be included in the package.
> - This file should reside in the same directory as the PKGBUILD, and will
> + This file should reside in the same directory as the PKGBUILD and will
> be copied into the package by makepkg. It does not need to be included
> in the source array (e.g., `install=$pkgname.install`).
>
> *changelog*::
> Specifies a changelog file that is to be included in the package.
> - This file should reside in the same directory as the PKGBUILD, and will
> + This file should reside in the same directory as the PKGBUILD and will
> be copied into the package by makepkg. It does not need to be included
> in the source array (e.g., `changelog=$pkgname.changelog`).
>
> @@ -105,10 +105,9 @@ This is most useful when used with sources from version control systems (see bel
> An array of source files required to build the package. Source files
> must either reside in the same directory as the PKGBUILD, or be a
> fully-qualified URL that makepkg can use to download the file.
> - To make the PKGBUILD as useful as possible, use the `$pkgname` and `$pkgver`
> - variables if possible when specifying the download location. Compressed files
> - will be extracted automatically unless found in
> - the noextract array described below.
> + To make maintaining the PKGBUILD easy, use the `$pkgname` and `$pkgver`
To simplify the maintenance of PKGBUILDs, use...
> + variables when specifying the download location, if possible. Compressed files
> + will be extracted automatically unless found in the noextract array described below.
> +
> It is also possible to change the name of the downloaded file, which is helpful
> with weird URLs and for handling multiple source files with the same
> @@ -123,7 +122,7 @@ makepkg as PGP signatures and will be automatically used to verify the integrity
> of the corresponding source file.
>
> *noextract (array)*::
> - An array of filenames corresponding to those from the source array. Files
> + An array of file names corresponding to those from the source array. Files
> listed here will not be extracted with the rest of the source files. This
> is useful for packages that use compressed data directly.
>
> @@ -152,9 +151,9 @@ of the corresponding source file.
> files should use `arch=('any')`.
>
> *backup (array)*::
> - An array of filenames, without preceding slashes, that
> + An array of file names, without preceding slashes, that
> should be backed up if the package is removed or upgraded. This is
> - commonly used for packages placing configuration files in /etc. See
> + commonly used for packages placing configuration files in '/etc'. See
> Handling Config Files in linkman:pacman[8] for more information.
>
> *depends (array)*::
> @@ -289,13 +288,13 @@ 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.
> +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()`
functions
> +being used to create those files from source.
>
> *package() Function*::
> - The package() function is used to install files into the directory that
> + 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
> @@ -303,41 +302,41 @@ create those files from source.
> be run as the user calling makepkg.
>
> *prepare() Function*::
> - An optional prepare() function can be specified in which operations that
> + 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
> + 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
> + 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`.
> + 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.
> +recommended to use the Bash `local` keyword to scope the variable to inside
> +the `build()` function.
>
> *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`.
> + 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 the
> + `checkdepends` array.
>
> -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:
> +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 during the build and install process:
for during -> for use during?
>
> *srcdir*::
> - This contains the directory where makepkg extracts, or copies, all source
> - files.
> + This contains the directory where makepkg extracts, or copies, all source
> + files.
>
> *pkgdir*::
> - 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.
> + 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.
>
> *startdir*::
> This contains the absolute path to the directory where the PKGBUILD is
> @@ -362,8 +361,8 @@ An optional global directive is available when building a split package:
>
> *pkgbase*::
> The name used to refer to the group of packages in the output of makepkg
> - and in the naming of source-only tarballs. If not specified, the first
> - element in the `pkgname` array is used. The variable is not allowed to
> + and in the naming of source-only tarballs. If not specified, the first
> + element in the `pkgname` array is used. The variable is not allowed to
> begin with a hyphen.
>
> Install/Upgrade/Remove Scripting
> @@ -415,10 +414,12 @@ reference with all of the available functions defined.
>
> Using VCS Sources[[VCS]]
> ------------------------
> -Building a developmental version of a package using sources from a version control
> -system (VCS) is enabled by specifying the source in the form
> -`source=('folder::url#fragment')`. Currently makepkg supports the `bzr`, `git`, `hg` and
> -`svn` protocols.
> +Building a developmental version of a package using sources from a version
> +control system (VCS) is enabled by specifying the source in the form
> +`source=('folder::url#fragment')`. Currently makepkg supports the `bzr`, `git`,
> +`hg` and `svn` protocols. For `cvs` and `darcs`, the source array should be left
> +empty and manual cloning of upstream repositories must be done in the
> +`prepare()` function.
For other version control system, manual cloning...
(arrays should not be left enpty)
Or people could submit patches...
>
> The source URL is divided into three components:
>
> @@ -427,10 +428,11 @@ The source URL is divided into three components:
> source into.
>
> *url*::
> - The url to the VCS repo. This must include the the vcs in the URL protocol for
> - makepkg to recognize this as a VCS source. If the protocol does not include
> - the VCS name, it can be added by prefixing the URL with `vcs+`. For example,
> - using a git repository over `http` would have a source URL in the form
> + The URL to the VCS repository. This must include the VCS in the URL protocol
> + for makepkg to recognize this as a VCS source. If the protocol does not
> + include the VCS name, it can be added by prefixing the URL with `vcs+`. For
> + example, using a git repository over `http` would have a source URL in the
> + form:
> `git+http://...`.
>
> *fragment*::
> @@ -451,6 +453,79 @@ The source URL is divided into three components:
> *svn*;;
> revision
>
> +The `pkgver()` function is used to automatically update the `pkgver` variable in
> +VCS PKGBUILDs.
Already documented in the pkgver() section.
> +There are several recommended ways to use the `pkgver()` function. Examples for
> +various numbering schemes are below for each VCS supported by makepkg.
I really do not think these are warranted in the man page.
> +*Git*::
> + *Using the tag of the last commit*;;
> + Example result: 4.1.0
> +
> + pkgver() {
> + cd local_repo
> + git describe --always | sed 's|-|.|g'
> + }
> +
> + *Using the total count of commits and the tag of the last commit*;;
> + Example result: 0.1142.2.0.6
> +
> + pkgver() {
> + cd local_repo
> + echo "0.$(git rev-list --count HEAD).$(git describe --always)"
> + }
> +
> + *Using the last commit date*;;
> + Example result: 20130108
> +
> + pkgver() {
> + cd local_repo
> + git log -1 --format="%cd" --date=short | tr -d '-'
> + }
> +
> + *Using the amount of seconds between the last commit and the Unix epoch*;;
> + Example result: 1358182650
> +
> + pkgver() {
> + cd local_repo
> + git log -1 --format=%cd --date=raw | cut -d " " -f1
> + }
> +
> +*Subversion*::
> + Example result: 8546
> +
> + pkgver() {
> + cd "$SRCDEST"/local_repo
> + svnversion | tr -d [A-z]
> + }
> +
> +*Mercurial*::
> + Example result: 2813.75881cc5391e
> +
> + pkgver() {
> + cd local_repo
> + hg identify -ni | awk 'BEGIN{OFS=".";} {print $2,$1}'
> + }
> +
> +*Bazaar*::
> + Example result: 830
> +
> + pkgver() {
> + cd local_repo
> + bzr revno
> + }
> +
> +*Fallback*::
> + If no acceptable version information can be extracted from the
> + repository, use the current date.
> + Example result: 20130408
> +
> + pkgver() {
> + date +%Y%m%d
> + }
> +
> +
> Example
> -------
> The following is an example PKGBUILD for the 'patch' package. For more
>
More information about the pacman-dev
mailing list