Difference between revisions of "VCS package guidelines"

From ArchWiki
Jump to: navigation, search
m (Removed protection from "VCS PKGBUILD Guidelines")
(fix branch name)
(19 intermediate revisions by 4 users not shown)
Line 8: Line 8:
  
 
== Prototypes ==
 
== Prototypes ==
 +
{{Warning|The prototype files provided in the {{Pkg|abs}} package and in [https://projects.archlinux.org/abs.git/tree/prototypes the ABS Git repository] are ''significantly'' out-of-date. Do ''not'' consider the prototypes to be authoritative in any way. See {{Bug|34485}}.}}
  
The [[ABS]] package provides prototypes for [[cvs]], [[svn]], [[git]], [[mercurial]], and [[Wikipedia:darcs|darcs]] [[PKGBUILD]]s. When {{Pkg|abs}} is installed, you can find them in {{ic|/usr/share/pacman}}. Latest versions can be found in the [https://projects.archlinux.org/abs.git/tree/prototypes prototypes directory in the ABS Git repository].
+
The {{Pkg|abs}} package for the [[Arch Build System]] provides prototypes for [[CVS]], [[SVN]], [[Git]], [[Mercurial]], and [[Wikipedia:Darcs|Darcs]] [[PKGBUILD]]s. When {{Pkg|abs}} is installed, you can find them in {{ic|/usr/share/pacman}}. Latest versions can be found in the [https://projects.archlinux.org/abs.git/tree/prototypes prototypes directory in the ABS Git repository].
  
 
== Guidelines ==
 
== Guidelines ==
Line 15: Line 16:
 
* Suffix {{Ic|pkgname}} with {{Ic|-cvs}}, {{Ic|-svn}}, {{Ic|-hg}}, {{Ic|-darcs}}, {{Ic|-bzr}}, {{Ic|-git}} etc. unless the package fetches a specific release.
 
* Suffix {{Ic|pkgname}} with {{Ic|-cvs}}, {{Ic|-svn}}, {{Ic|-hg}}, {{Ic|-darcs}}, {{Ic|-bzr}}, {{Ic|-git}} etc. unless the package fetches a specific release.
  
* If the resulting package is different after changing the dependencies, URL, sources, etc. increasing the {{Ic|pkgrel}} is mandatory. Touching the {{ic|pkgver}} isn't.
+
* If the resulting package is different after changing the dependencies, URL, sources, etc. increasing the {{Ic|pkgrel}} is mandatory. Touching the {{ic|pkgver}} is not.
  
 
* {{Ic|--holdver}} can be used to prevent [[makepkg]] from updating the {{ic|pkgver}} (see: [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8)])
 
* {{Ic|--holdver}} can be used to prevent [[makepkg]] from updating the {{ic|pkgver}} (see: [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8)])
Line 51: Line 52:
  
 
{{hc|<nowiki>pkgver() {
 
{{hc|<nowiki>pkgver() {
  cd local_repo
+
cd local_repo
  git describe --always | sed 's|-|.|g'
+
local ver="$(git describe --long)"
 +
printf "%s" "${ver//-/.}"
 
}</nowiki>|
 
}</nowiki>|
 
2.0.6.a17a017
 
2.0.6.a17a017
Line 60: Line 62:
  
 
{{hc|<nowiki>pkgver() {
 
{{hc|<nowiki>pkgver() {
  cd local_repo
+
cd local_repo
  echo $(git rev-list --count HEAD).$(git rev-parse --short HEAD)
+
printf "%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"
 
}</nowiki>|
 
}</nowiki>|
 
1142.a17a017
 
1142.a17a017
Line 68: Line 70:
 
==== Subversion ====
 
==== Subversion ====
 
{{hc|<nowiki>pkgver() {
 
{{hc|<nowiki>pkgver() {
  cd local_repo
+
cd local_repo
  svnversion | tr -d [A-z]
+
local ver="$(svnversion)"
 +
printf "%s" "${ver//[[:alpha:]]}"
 
}</nowiki>|
 
}</nowiki>|
 
8546
 
8546
Line 76: Line 79:
 
==== Mercurial ====
 
==== Mercurial ====
 
{{hc|<nowiki>pkgver() {
 
{{hc|<nowiki>pkgver() {
  cd local_repo
+
cd local_repo
  echo $(hg identify -n).$(hg identify -i)
+
printf "%s.%s" "$(hg identify -n)" "$(hg identify -i)"
 
}</nowiki>|
 
}</nowiki>|
 
2813.75881cc5391e
 
2813.75881cc5391e
Line 84: Line 87:
 
==== Bazaar ====
 
==== Bazaar ====
 
{{hc|<nowiki>pkgver() {
 
{{hc|<nowiki>pkgver() {
  cd local_repo
+
cd local_repo
  bzr revno
+
bzr revno
 
}</nowiki>|
 
}</nowiki>|
 
830
 
830
Line 91: Line 94:
  
 
==== Fallback ====
 
==== Fallback ====
The current date can be used, in case no satisfactory {{ic|pkgver}} can be extracted from the repo:
+
The current date can be used, in case no satisfactory {{ic|pkgver}} can be extracted from the repository:
  
 
{{hc|<nowiki>pkgver() {
 
{{hc|<nowiki>pkgver() {
  date +%Y%m%d
+
date +%Y%m%d
 
}</nowiki>|
 
}</nowiki>|
 
20130408
 
20130408
Line 106: Line 109:
 
   
 
   
 
  pkgname=expac-git
 
  pkgname=expac-git
_gitname=expac
 
 
  pkgver=0.0.0
 
  pkgver=0.0.0
 
  pkgrel=1
 
  pkgrel=1
Line 114: Line 116:
 
  license=('MIT')
 
  license=('MIT')
 
  depends=('pacman')
 
  depends=('pacman')
  makedepends=('git' 'perl')
+
  makedepends=('git')
 
  conflicts=('expac')
 
  conflicts=('expac')
 
  provides=('expac')
 
  provides=('expac')
 
  # The git repo is detected by the 'git:' or 'git+' beginning. The branch
 
  # The git repo is detected by the 'git:' or 'git+' beginning. The branch
  # 'pacman41' is then checked out upon cloning, expediating versioning:
+
  # '$pkgname' is then checked out upon cloning, expediating versioning:
 
  #source=('git+https://github.com/falconindy/expac.git'
 
  #source=('git+https://github.com/falconindy/expac.git'
  source=('git://github.com/falconindy/expac.git'
+
  source=("$pkgname"::'git://github.com/falconindy/expac.git'
 
         'expac_icon.png')
 
         'expac_icon.png')
 
  # Because the sources are not static, skip Git checksum:
 
  # Because the sources are not static, skip Git checksum:
Line 127: Line 129:
 
   
 
   
 
  pkgver() {
 
  pkgver() {
  cd $_gitname
+
cd "$pkgname"
  # Use the tag of the last commit
+
# Use the tag of the last commit
  git describe --always | sed 's|-|.|g'
+
local ver="$(git describe --long)"
 +
printf "%s" "${ver//-/.}"
 
  }
 
  }
 
   
 
   
 
  build() {
 
  build() {
  cd $_gitname
+
cd "$pkgname"
  make
+
make
 
  }
 
  }
 
   
 
   
 
  package() {
 
  package() {
  cd $_gitname
+
cd "$pkgname"
  make PREFIX=/usr DESTDIR="$pkgdir" install
+
make PREFIX=/usr DESTDIR="$pkgdir" install
  install -Dm644 "$srcdir/expac_icon.png" "$pkgdir/usr/share/pixmaps/expac.png"
+
install -Dm644 "$srcdir/expac_icon.png" "$pkgdir/usr/share/pixmaps/expac.png"
 
  }
 
  }

Revision as of 04:43, 12 October 2013

Template:Package Guidelines

Version control systems can be used for retrieval of source code for both usual statically versioned packages and latest (trunk) version of a development branch. This article covers both cases.

Prototypes

Warning: The prototype files provided in the abs package and in the ABS Git repository are significantly out-of-date. Do not consider the prototypes to be authoritative in any way. See FS#34485.

The abs package for the Arch Build System provides prototypes for CVS, SVN, Git, Mercurial, and Darcs PKGBUILDs. When abs is installed, you can find them in /usr/share/pacman. Latest versions can be found in the prototypes directory in the ABS Git repository.

Guidelines

  • Suffix pkgname with -cvs, -svn, -hg, -darcs, -bzr, -git etc. unless the package fetches a specific release.
  • If the resulting package is different after changing the dependencies, URL, sources, etc. increasing the pkgrel is mandatory. Touching the pkgver is not.
  • Include what the package conflicts with and provides (e.g. for fluxbox-gitAUR: conflicts=('fluxbox') and provides=('fluxbox')).
  • replaces=() generally causes unnecessary problems and should be avoided.
  • When using the cvsroot, use anonymous:@ rather than anonymous@ to avoid having to enter a blank password or anonymous:password@, if one is required.
  • Include the appropriate VCS tool in makedepends=() (cvs, subversion, git, ...).

VCS sources

Note: Pacman 4.1 supports the following VCS sources: bzr, git, hg and svn. See the fragment section of man PKGBUILD or PKGBUILD(5) for a list of supported VCS.

Starting with pacman 4.1, the VCS sources should be specified in the source=() array and will be treated like any other source. makepkg will clone/checkout/branch the repo into $SRCDEST (same as $startdir if not set in makepkg.conf(5)) and copy it to $srcdir (in a specific way to each VCS). The local repo is left untouched, thus invalidating the need for a -build directory.

The general format of a VCS source=() array is:

source=('[folder::][vcs+]url[#fragment]')
  • folder (optional) is used to change the default repo name to something more relevant (e.g. than trunk) or to preserve the previous sources
  • vcs+ is needed for URLs that do not reflect the VCS type, e.g. git+http://some_repo.
  • url is the URL to the distant or local repo
  • #fragment (optional) is needed to pull a specific branch or commit

An example Git source array:

source=('project_name::git+http://project_url#branch=project_branch')

The pkgver() function

The pkgver autobump is now achieved via a dedicated pkgver() function. This allows for better control over the pkgver, and maintainers should favor a pkgver that makes sense. Following are some examples showing the intended output:

Git

Using the tag of the last commit:

pkgver() {
	cd local_repo
	local ver="$(git describe --long)"
	printf "%s" "${ver//-/.}"
}
2.0.6.a17a017

If there are no annotated tags:

pkgver() {
	cd local_repo
	printf "%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"
}
1142.a17a017

Subversion

pkgver() {
	cd local_repo
	local ver="$(svnversion)"
	printf "%s" "${ver//[[:alpha:]]}"
}
8546

Mercurial

pkgver() {
	cd local_repo
	printf "%s.%s" "$(hg identify -n)" "$(hg identify -i)"
}
2813.75881cc5391e

Bazaar

pkgver() {
	cd local_repo
	bzr revno
}
830

Fallback

The current date can be used, in case no satisfactory pkgver can be extracted from the repository:

pkgver() {
	date +%Y%m%d
}
20130408

Tips

A sample Git PKGBUILD

# Maintainer: Dave Reisner <d@falconindy.com> 
# Contributor: William Giokas (KaiSforza) <1007380@gmail.com>

pkgname=expac-git
pkgver=0.0.0
pkgrel=1
pkgdesc="Pacman database extraction utility"
arch=('i686' 'x86_64')
url="https://github.com/falconindy/expac"
license=('MIT')
depends=('pacman')
makedepends=('git')
conflicts=('expac')
provides=('expac')
# The git repo is detected by the 'git:' or 'git+' beginning. The branch
# '$pkgname' is then checked out upon cloning, expediating versioning:
#source=('git+https://github.com/falconindy/expac.git'
source=("$pkgname"::'git://github.com/falconindy/expac.git'
        'expac_icon.png')
# Because the sources are not static, skip Git checksum:
md5sums=('SKIP'
         '020c36e38466b68cbc7b3f93e2044b49')

pkgver() {
	cd "$pkgname"
	# Use the tag of the last commit
	local ver="$(git describe --long)"
	printf "%s" "${ver//-/.}"
}

build() {
	cd "$pkgname"
	make
}

package() {
	cd "$pkgname"
	make PREFIX=/usr DESTDIR="$pkgdir" install
	install -Dm644 "$srcdir/expac_icon.png" "$pkgdir/usr/share/pixmaps/expac.png"
}