On 09/04/13 09:46, Jason St. John wrote:

From: "Jason St. John"

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 ---

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

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