On 09/04/13 09:46, Jason St. John wrote: > From: "Jason St. John" <[email protected]> > > 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 <[email protected]> > ---
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 <[email protected]> > > 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 >
