[pacman-dev] [PATCH] Revise PKGBUILD(5), document pkgver() in PKGBUILD(5), and update example PKGBUILD
Jason St. John
jstjohn at purdue.edu
Mon Apr 8 19:46:33 EDT 2013
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>
---
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
}
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).
@@ -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`
+ 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()`
+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:
*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.
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.
+
+There are several recommended ways to use the `pkgver()` function. Examples for
+various numbering schemes are below for each VCS supported by makepkg.
+
+*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
--
1.8.2.1
More information about the pacman-dev
mailing list