854
edits
Difference between revisions of "VCS PKGBUILD Guidelines"
Marked this version for translation
m (added languages and translate tags) |
(Marked this version for translation) |
||
| Line 2: | Line 2: | ||
__TOC__ | __TOC__ | ||
<translate> | <translate> | ||
<!--T:1--> | |||
[[Wikipedia:Revision_control|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. | [[Wikipedia:Revision_control|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. | ||
== Guidelines == | == Guidelines == <!--T:2--> | ||
<!--T:3--> | |||
* 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. | ||
<!--T:4--> | |||
* 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. | * 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. | ||
<!--T:5--> | |||
* {{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)]) | ||
<!--T:6--> | |||
* Include what the package conflicts with and provides (e.g. for {{AUR|fluxbox-git}}: {{Ic|1=conflicts=('fluxbox')}} and {{Ic|1=provides=('fluxbox')}}). | * Include what the package conflicts with and provides (e.g. for {{AUR|fluxbox-git}}: {{Ic|1=conflicts=('fluxbox')}} and {{Ic|1=provides=('fluxbox')}}). | ||
<!--T:7--> | |||
* {{Ic|1=replaces=()}} generally causes unnecessary problems and should be avoided. | * {{Ic|1=replaces=()}} generally causes unnecessary problems and should be avoided. | ||
<!--T:8--> | |||
* When using the cvsroot, use {{Ic|anonymous:@}} rather than {{Ic|anonymous@}} to avoid having to enter a blank password or {{Ic|anonymous:password@}}, if one is required. | * When using the cvsroot, use {{Ic|anonymous:@}} rather than {{Ic|anonymous@}} to avoid having to enter a blank password or {{Ic|anonymous:password@}}, if one is required. | ||
<!--T:9--> | |||
* Include the appropriate VCS tool in {{Ic|1=makedepends=()}} ({{ic|cvs}}, {{ic|subversion}}, {{ic|git}}, ...). | * Include the appropriate VCS tool in {{Ic|1=makedepends=()}} ({{ic|cvs}}, {{ic|subversion}}, {{ic|git}}, ...). | ||
=== VCS sources === | === VCS sources === <!--T:10--> | ||
{{Note|Pacman 4.1 supports the following VCS sources: {{ic|bzr}}, {{ic|git}}, {{ic|hg}} and {{ic|svn}}. See the {{ic|fragment}} section of {{ic|man PKGBUILD}} or [https://www.archlinux.org/pacman/PKGBUILD.5.html PKGBUILD(5)] for a list of supported VCS.}} | {{Note|Pacman 4.1 supports the following VCS sources: {{ic|bzr}}, {{ic|git}}, {{ic|hg}} and {{ic|svn}}. See the {{ic|fragment}} section of {{ic|man PKGBUILD}} or [https://www.archlinux.org/pacman/PKGBUILD.5.html PKGBUILD(5)] for a list of supported VCS.}} | ||
<!--T:11--> | |||
Starting with {{ic|pacman}} 4.1, the VCS sources should be specified in the {{ic|1=source=()}} array and will be treated like any other source. {{ic|makepkg}} will clone/checkout/branch the repo into {{ic|$SRCDEST}} (same as {{ic|$startdir}} if not set in [https://www.archlinux.org/pacman/makepkg.conf.5.html makepkg.conf(5)]) and copy it to {{ic|$srcdir}} (in a specific way to each VCS). The local repo is left untouched, thus invalidating the need for a {{ic|-build}} directory. | Starting with {{ic|pacman}} 4.1, the VCS sources should be specified in the {{ic|1=source=()}} array and will be treated like any other source. {{ic|makepkg}} will clone/checkout/branch the repo into {{ic|$SRCDEST}} (same as {{ic|$startdir}} if not set in [https://www.archlinux.org/pacman/makepkg.conf.5.html makepkg.conf(5)]) and copy it to {{ic|$srcdir}} (in a specific way to each VCS). The local repo is left untouched, thus invalidating the need for a {{ic|-build}} directory. | ||
<!--T:12--> | |||
The general format of a VCS {{ic|1=source=()}} array is: | The general format of a VCS {{ic|1=source=()}} array is: | ||
source=('[folder::][vcs+]url[#fragment]') | source=('[folder::][vcs+]url[#fragment]') | ||
<!--T:13--> | |||
* {{ic|folder}} (optional) is used to change the default repo name to something more relevant (e.g. than {{ic|trunk}}) or to preserve the previous sources | * {{ic|folder}} (optional) is used to change the default repo name to something more relevant (e.g. than {{ic|trunk}}) or to preserve the previous sources | ||
* {{ic|vcs+}} is needed for URLs that do not reflect the VCS type, e.g. {{ic|git+http://some_repo}}. | * {{ic|vcs+}} is needed for URLs that do not reflect the VCS type, e.g. {{ic|git+http://some_repo}}. | ||
| Line 33: | Line 44: | ||
* {{ic|#fragment}} (optional) is needed to pull a specific branch or commit. See {{ic|man PKGBUILD}} for more information on the fragments available for each VCS. | * {{ic|#fragment}} (optional) is needed to pull a specific branch or commit. See {{ic|man PKGBUILD}} for more information on the fragments available for each VCS. | ||
<!--T:14--> | |||
An example Git source array: | An example Git source array: | ||
source=('project_name::git+http://project_url#branch=project_branch') | source=('project_name::git+http://project_url#branch=project_branch') | ||
=== The pkgver() function === | === The pkgver() function === <!--T:15--> | ||
The {{ic|pkgver}} autobump is now achieved via a dedicated {{ic|pkgver()}} function. This allows for better control over the {{ic|pkgver}}, and maintainers should favor a {{ic|pkgver}} that makes sense. | The {{ic|pkgver}} autobump is now achieved via a dedicated {{ic|pkgver()}} function. This allows for better control over the {{ic|pkgver}}, and maintainers should favor a {{ic|pkgver}} that makes sense. | ||
<!--T:16--> | |||
It is recommended to have following version format: ''RELEASE.rREVISION'' where ''REVISION'' is a monotonically increasing number that uniquely identifies the source tree (VCS revisions do this). The last VCS tag can be used for ''RELEASE''. If there are no public releases and no repository tags then zero could be used as a release number or you can drop ''RELEASE'' completely and use version number that looks like ''rREVISION''. If there are public releases but repo has no tags then developer should get the release version somehow e.g. by parsing the project files. | It is recommended to have following version format: ''RELEASE.rREVISION'' where ''REVISION'' is a monotonically increasing number that uniquely identifies the source tree (VCS revisions do this). The last VCS tag can be used for ''RELEASE''. If there are no public releases and no repository tags then zero could be used as a release number or you can drop ''RELEASE'' completely and use version number that looks like ''rREVISION''. If there are public releases but repo has no tags then developer should get the release version somehow e.g. by parsing the project files. | ||
<!--T:17--> | |||
Following are some examples showing the ''intended'' output: | Following are some examples showing the ''intended'' output: | ||
==== Git ==== | ==== Git ==== <!--T:18--> | ||
<!--T:19--> | |||
Using the annotated tag of the last commit: | Using the annotated tag of the last commit: | ||
<!--T:20--> | |||
{{hc|<nowiki>pkgver() { | {{hc|<nowiki>pkgver() { | ||
cd "$srcdir/repo" | cd "$srcdir/repo" | ||
| Line 54: | Line 70: | ||
}} | }} | ||
<!--T:21--> | |||
Using the unannotated tag of the last commit: | Using the unannotated tag of the last commit: | ||
<!--T:22--> | |||
{{hc|<nowiki>pkgver() { | {{hc|<nowiki>pkgver() { | ||
cd "$srcdir/repo" | cd "$srcdir/repo" | ||
| Line 63: | Line 81: | ||
}} | }} | ||
<!--T:23--> | |||
If there are no tags then use number of revisions since beginning of the history: | If there are no tags then use number of revisions since beginning of the history: | ||
<!--T:24--> | |||
{{hc|<nowiki>pkgver() { | {{hc|<nowiki>pkgver() { | ||
cd "$srcdir/repo" | cd "$srcdir/repo" | ||
| Line 72: | Line 92: | ||
}} | }} | ||
<!--T:25--> | |||
{{Note|SHA1 (in this case {{ic|a17a017}}) is not used in the version comparison and can be omitted, although it allows quick identification of the exact revision used and might be useful during debugging.}} | {{Note|SHA1 (in this case {{ic|a17a017}}) is not used in the version comparison and can be omitted, although it allows quick identification of the exact revision used and might be useful during debugging.}} | ||
==== Subversion ==== | ==== Subversion ==== <!--T:26--> | ||
{{hc|<nowiki>pkgver() { | {{hc|<nowiki>pkgver() { | ||
cd "$srcdir/repo" | cd "$srcdir/repo" | ||
| Line 83: | Line 104: | ||
}} | }} | ||
<!--T:27--> | |||
{{Note|If the project has releases you should use them instead of the {{ic|0.}}.}} | {{Note|If the project has releases you should use them instead of the {{ic|0.}}.}} | ||
==== Mercurial ==== | ==== Mercurial ==== <!--T:28--> | ||
{{hc|<nowiki>pkgver() { | {{hc|<nowiki>pkgver() { | ||
cd "$srcdir/repo" | cd "$srcdir/repo" | ||
| Line 93: | Line 115: | ||
}} | }} | ||
==== Bazaar ==== | ==== Bazaar ==== <!--T:29--> | ||
{{hc|<nowiki>pkgver() { | {{hc|<nowiki>pkgver() { | ||
cd "$srcdir/repo" | cd "$srcdir/repo" | ||
| Line 101: | Line 123: | ||
}} | }} | ||
==== Fallback ==== | ==== Fallback ==== <!--T:30--> | ||
The current date can be used, in case no satisfactory {{ic|pkgver}} can be extracted from the repository: | The current date can be used, in case no satisfactory {{ic|pkgver}} can be extracted from the repository: | ||
<!--T:31--> | |||
{{hc|<nowiki>pkgver() { | {{hc|<nowiki>pkgver() { | ||
date +%Y%m%d | date +%Y%m%d | ||
| Line 110: | Line 133: | ||
}} | }} | ||
<!--T:32--> | |||
Although it does not identify source tree state uniquely, so avoid it if possible. | Although it does not identify source tree state uniquely, so avoid it if possible. | ||
== Tips == | == Tips == <!--T:33--> | ||
=== A sample Git PKGBUILD === | === A sample Git PKGBUILD === <!--T:34--> | ||
# Maintainer: Dave Reisner <d@falconindy.com> | # Maintainer: Dave Reisner <d@falconindy.com> | ||
# Contributor: William Giokas (KaiSforza) <1007380@gmail.com> | # Contributor: William Giokas (KaiSforza) <1007380@gmail.com> | ||
| Line 155: | Line 179: | ||
} | } | ||
=== Git Submodules === | === Git Submodules === <!--T:35--> | ||
Git submodules are a little tricky to do. The idea is to add the URLs of the submodules themselves directly to the sources array and then reference them during prepare(). This could look like this: | Git submodules are a little tricky to do. The idea is to add the URLs of the submodules themselves directly to the sources array and then reference them during prepare(). This could look like this: | ||
source=("git://somewhere.org/something/something.git" | <!--T:36--> | ||
source=("git://somewhere.org/something/something.git" | |||
"git://somewhere.org/mysubmodule/mysubmodule.git") | "git://somewhere.org/mysubmodule/mysubmodule.git") | ||