Difference between revisions of "Talk:Arch packaging standards"

From ArchWiki
Jump to: navigation, search
(Add a note about bash variable handling: re, close)
 
(96 intermediate revisions by 26 users not shown)
Line 1: Line 1:
==Comments==
+
== .install files ==
* What encoding (ascii ? UTF-8 ?) should be used for text files in submitted packages ? --[[User:Airbag|Airbag]] 13:43, 15 August 2006 (PDT)
+
  
* Please remove the cd "$srcdir..." no-op from the examples on the page.  See: https://bugs.archlinux.org/task/34314
+
Something more should be said about .install files. Mention that there are also examples in {{ic|/usr/share/pacman}} but it also needs some explanation on how they work. --[[User:Mauro2|Mauro2]] ([[User_talk:Mauro2|talk]]) 05:30, 15 October 2012 (UTC)
[[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 20:55, 14 March 2013 (UTC)
+
  
==Suggestions==
+
== Fields order ==
* Many comments here are quite old.  What's the policy on removing them? [[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 21:13, 14 March 2013 (UTC)
+
* Shouldn't we suggest using SHA1 hash and not the already broken one (MD5)? [[User:Tomato|Tomato]] 15:47, 25 August 2010 (EDT)
+
* The section about custom variables ("_blah=blah") is misleading. Nowadays custom variables are a common practice since they can simplify and/or modularize the PKGBUILD a great deal. The parts where they are recommended to not to be used should be modified. --[[User:Det|Det]] 13:13, 14 September 2010 (EDT)
+
* I've recently found that packages that used bundles libraries tend to segfault. Should we suggest the removal of bundled libraries and instead use system libraries?
+
* How about adding https://wiki.archlinux.org/index.php/Web_application_package_guidelines to the list? --[[User:Trontonic|Trontonic]] 11:18, 29 February 2012 (EST)
+
* Something more should be said about .install files.  Mention that there are also examples in /usr/share/pacman but it also needs some explanation on how they work.
+
  
==Proposed revision (shouldn't this already be added...?)==
+
[[Arch_Packaging_Standards#Package_etiquette]] states: "It is common practice to preserve the order of the PKGBUILD fields as shown above." But this is not true. Common practice is to use {{ic|/usr/share/pacman/PKGBUILD.proto}} as a template, and the order of fields in that prototype has a far greater influence on packages in the wild than this page. This page should edited to reflect the current state of {{ic|PKGBUILD.proto}}. Perhaps this page should state: "It is common practice to order PKGBUILD fields so they match the order of fields in {{ic|PKGBUILD.proto}}. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 14:32, 19 October 2013 (UTC)
====Directories====
+
Is something like /usr/include/{pkg} allowed?
+
Is something like /usr/lib/{pkg}-{versionnumber} allowed? Same for /usr/share?
+
  
====Package Etiquette====
+
== Punctuation in PKGBUILD ==
 +
What is the official guidance regarding ending a pkgdesc in a period or using commas and English prose punctuation in general?
  
 +
[[https://bbs.archlinux.org/viewtopic.php?pid=1288063 Link]] to discussion thread.
  
...<br>
+
[[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 15:17, 14 June 2013 (UTC)
file, or alternatively by exporting the PACKAGER environment variable before building packages with makepkg:
+
<b>$</b> export PACKAGER="John Doe@<b>email</b>"
+
  
====Architectures====
+
==Package naming==
 +
* Package names should consist of '''alphanumeric characters only'''; all letters should be '''lowercase'''.
 +
:--unsigned
  
...<br>
+
::This is a guideline, but I see some packages with hypens and underscores (tesseract-data-chi_sim), dots (gstreamer0.10), plus (libxml++) and even at-signs (kde-l10n-ca@valencia). A package with uppercase name is libreoffice-bn-IN. According to the makepkg source, the allowed chars are: {{ic|[:alnum:]+_.@-}}. [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)
depending on which architectures it can be built on. <s>You can also use</s> <b>State</b> 'any' for architecture independent packages.
+
  
...
+
:::"alphanumeric characters only" rule is ridiculous, 85% of official packages break this rule. I think it should be changed to allow hypens. It makes package names more readable. In regards to other characters, the + sign breaks [https://aur.archlinux.org/rpc.php AUR search] ([https://aur.archlinux.org/rpc.php?type=search&arg=a++ example], [https://aur.archlinux.org/rpc.php?type=search&arg=a%2B%2B should be escaped]). [[User:Axper|axper]] ([[User talk:Axper|talk]]) 11:19, 11 May 2014 (UTC)
====Licenses====
+
  
 +
* Package names should NOT be suffixed with the upstream major release version number (e.g. we don't want libfoo2 if upstream calls it libfoo v2.3.4) in case the library and its dependencies are expected to be able to keep using the most recent library version with each respective upstream release. However, for some software or dependencies, this can not be assumed. In the past this has been especially true for widget toolkits such as GTK and Qt. Software that depends on such toolkits can usually not be trivially ported to a new major version. As such, in cases where software can not trivially keep rolling alongside its dependencies, package names should carry the major version suffix (e.g. gtk2, gtk3, qt4, qt5). For cases where most dependencies can keep rolling along the newest release but some can't (for instance closed source that needs libpng12 or similar), a deprecated version of that package might be called libfoo1 while the current version is just libfoo.
 +
:--unsigned
  
*Add 'custom' to the licenses array. Optionally, <s>you can</s> replace 'custom' with 'custom:"name of license"'.
+
* Package versions '''should be the same as the version released by the author'''. Versions can include letters if need be (eg, nmap's version is 2.54BETA32). '''Version tags may not include hyphens!''' Letters, numbers, and periods only.
 +
:--unsigned
  
...<br>
+
::This rule needs to get more stricter. Having a slash in the version breaks filenames. For craziness, I tried setting up a pkgver containing all characters from 0x01 to 0xff which makes makepkg throw a Bash syntax error. The current packages have versions matching {{ic}[[alnum:]._+~]+} (and a colon for epoch, a hypen for pkgrel). What about limiting to those characters? Debian has a similar set, see [https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version their policy docs] [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)
When pacman gets the ability to filter on licenses (<b>i.e., make pacman download only GPL and BSD licensed software"</b>) dual (or more) licenses will be treated by pacman using ''''or'''', rather than ''''and'''' logic, thus pacman will consider ...
+
  
====Submitting Packages to the AUR====
+
* Package releases are '''specific to Arch Linux packages'''. These allow users to differentiate between newer and older package builds. When a new package version is first released, the '''release count starts at 1'''. Then as fixes and optimizations are made, the package will be '''re-released''' to the Arch Linux public and the '''release number will increment'''. When a new version comes out, the release count resets to 1. Package release tags follow the '''same naming restrictions as version tags'''.
 +
:--unsigned
  
<s>The submitted PKGBUILDs MUST NOT build applications already in any of the official binary repositories under any circumstances. Exception to this strict rule may only be packages having extra features enabled and/or patches in compare to the official ones. In such an occasion the pkgname array should be different to express that difference.</s> <i>This gets repeated word for word in [[#Packaging Standards]]</i>
+
* Why is there no mentioning of suffixes for different build sources, such as vcs sources (-git, -hg, …) or binary distributions (-bin)? IMO this is an important part of the package naming conventions in AUR. [[User:Fordprefect|Fordprefect]] ([[User talk:Fordprefect|talk]]) 13:43, 10 May 2016 (UTC)
  
- I see no problem in repeating it here as regularly there are users not following that rule. [[User:Snowman|Snowman]]
+
== Is it acceptable for build() to start by removing directories? ==
  
 +
I just downloaded a PKGBUILD whose build() function begins with the following:
  
 +
find ./ -maxdepth 1 -mindepth 1 -type d  -exec rm -r {} \;
  
...<br>
+
It seems to me that a PKGBUILD has no business doing this and that it is potentially dangerous. I admit that its danger will typically require people to do non-standard things and, arguably, things they would be better advised not to do anyway. But it still seems to me to invite trouble.
To ensure the security of pkgs submitted to the AUR please ensure that <b>the md5sum values</b> have <b>been</b> correctly filled.  The md5sum's can b...
+
  
===Additional Guidelines===
+
I don't remember seeing this in a PKGBUILD before but I can't find anything definitely ruling it out.
Be sure to read the above guidelines first'''--''' important points are listed on this page that will not be repeated in the following guideline pages...
+
  
===Package Releases===
+
Is it acceptable for a build function to start by removing directories in this way? Is it safe?
Package releases are specific to Arch Linux packages. These allow users to differentiate between newer and older package builds. When a new package version is first released, the release count starts at 1. Then as fixes and optimizations are made, the package will be re-released to the Arch Linux public and the release number will increment. When a new version comes out, the release count resets to 1. Package release tags follow the same naming restrictions as version tags.
+
  
Examples of when to change the package release number:
+
--[[User:Margali|cfr]] ([[User talk:Margali|talk]]) 03:03, 27 February 2014 (UTC)
  
* Changing pkgdesc -> do NOT bump (unless it is severely wrong or something)
+
: I'd argue that this is an acceptable thing to do, at least in some cases. As an example, consider [http://www.talend.com/products/data-integration Talend Open Studio DI]: a single source file provides files for Windows, Linux, Mac OS, PowerPC (?) and Solaris. In response, the {{AUR|talend-open-studio-di}} PKGBUILD simply removes them. Does removing those files invite trouble? Yes. But removing files seems like an integral tool in the package maintainer's toolkit, and plenty of other weird stuff happens in PKGBUILDs too. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 02:20, 3 March 2014 (UTC)
* Changing deps -> bump
+
* Changing makedeps -> do NOT bump, ever
+
* Changing optdeps -> do NOT bump (unless very important functionality provided)
+
* Changing build stuff (i.e changing PKGBUILD but no change to resulting binary) -> do NOT bump
+
  
(based on aur-general discussion: https://mailman.archlinux.org/pipermail/aur-general/2011-April/014247.html)
+
== Update "Submitting packages to the AUR" section ==
  
===Adding system users===
+
The line
 +
 +
> One can easily build a tarball containing all the required files by using '''makepkg --source'''. This makes a tarball named $pkgname-$pkgver-$pkgrel.src.tar.gz, which can then be uploaded to the AUR.
 +
 +
in the "Submitting packages to the AUR" section on this page should be updated to refer to '''mkaurball''', which is now apparently required to build valid AUR source packages automatically.
  
Some packages require the addition of system users. For them to be ignored by things such as lightdm, tthey have to be in the sub-1000 UID space. Looking at packages in ABS, these users are simply added with an <tt>useradd -u ...</tt>. However, there is no guideline or authoritative list that I can find which lists which UID is used for what, which is free, or how to register a UID for a specific system user. It would be nice to see a section about it here.
+
(Sorry, I am new to the ABS, so I won't change this page myself. I would probably miss something.)
  
--[[User:OlivierMehani|OlivierMehani]] 19:31, 13 October 2011 (EDT)
+
--[[User:Drawm|Drawm]] ([[User talk:Drawm|talk]]) 14:57, 27 August 2014 (UTC)
  
See https://wiki.archlinux.org/index.php/DeveloperWiki:UID_/_GID_Database
+
:I would argue that the section should not even be here - there is already [[Arch User Repository#Submitting packages]], and "submitting packages to AUR" has little to do with the official packaging standards. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:14, 27 August 2014 (UTC)
  
I thinks it's a bit too specific to be listed here.
+
::You would argue correctly, although I haven't checked if there's something worth being merged. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:39, 28 August 2014 (UTC)
  
[[User:Snowman|Snowman]] 20:45, 13 October 2011 (EDT)
+
::: I agree that this section needs to be edited or deleted, and I was going to do it myself, but don't see any "edit" buttons anywhere on the main page. Maybe this section should just provide the link to the correct information in [[Arch User Repository#Submitting packages]]. Whoever can edit this, it needs to be done because it gives incorrect information, which I and others have tried to follow only to be told by the AUR that it won't work. [[User:Colinkeenan|Colinkeenan]] ([[User talk:Colinkeenan|talk]]) 23:25, 28 September 2014 (UTC)
 +
 
 +
::::You're right, I've just fixed it. However the two sections should really be merged, maybe keep the AUR rules here and the instructions in the [[AUR]] article? -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 01:46, 29 September 2014 (UTC)
 +
 
 +
::::: Since the move to AUR4 this section is outdated. IMHO it should not even be here. A link to [[Arch User Repository#Submitting packages]] should be sufficient since the rules are clearly stated there. --[[User:Edh|Edh]] ([[User talk:Edh|talk]]) 08:50, 1 April 2016 (UTC)
 +
 
 +
::::::The two sections don't seem to overlap completely, i.e. they should be merged; I've done [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=429246&oldid=394881 this] for the moment. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:38, 2 April 2016 (UTC)
 +
 
 +
== <s>/selinux</s> ==
 +
 
 +
Someone with privileges could edit the page and point that selinux itself and they needed packages could install in /selinux as an exception in the directory section.
 +
 
 +
{{unsigned|21:00, 25 May 2015‎|Jristz}}
 +
 
 +
:The selinux packages are not in the [[official repositories]]. Be it a justified exception or not, I don't see any reason why this should be mentioned in the ''official'' guidelines. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:29, 25 May 2015 (UTC)
 +
 
 +
== <s>Minor style inconsistency</s> ==
 +
 
 +
"~/.makepkg.conf" is missing an ic-tag in the [[Arch_packaging_standards#Package etiquette|Package etiquette]] section. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 21:47, 16 August 2016 (UTC)
 +
 
 +
== <s>Add a note about bash variable handling</s> ==
 +
 
 +
State that among other {{ic|pkgdir}}, {{ic|srcdir}} respectively any variable which might contain spaces should be quoted whenever used. This would probably be a good addition to the [[Arch_packaging_standards#Package etiquette|Package etiquette]] bullet list. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 21:50, 16 August 2016 (UTC)
 +
 
 +
:Via [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=446832&oldid=446829], thanks -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 22:55, 16 August 2016 (UTC)

Latest revision as of 22:55, 16 August 2016

.install files

Something more should be said about .install files. Mention that there are also examples in /usr/share/pacman but it also needs some explanation on how they work. --Mauro2 (talk) 05:30, 15 October 2012 (UTC)

Fields order

Arch_Packaging_Standards#Package_etiquette states: "It is common practice to preserve the order of the PKGBUILD fields as shown above." But this is not true. Common practice is to use /usr/share/pacman/PKGBUILD.proto as a template, and the order of fields in that prototype has a far greater influence on packages in the wild than this page. This page should edited to reflect the current state of PKGBUILD.proto. Perhaps this page should state: "It is common practice to order PKGBUILD fields so they match the order of fields in PKGBUILD.proto. Ichimonji10 (talk) 14:32, 19 October 2013 (UTC)

Punctuation in PKGBUILD

What is the official guidance regarding ending a pkgdesc in a period or using commas and English prose punctuation in general?

[Link] to discussion thread.

Graysky (talk) 15:17, 14 June 2013 (UTC)

Package naming

  • Package names should consist of alphanumeric characters only; all letters should be lowercase.
--unsigned
This is a guideline, but I see some packages with hypens and underscores (tesseract-data-chi_sim), dots (gstreamer0.10), plus (libxml++) and even at-signs (kde-l10n-ca@valencia). A package with uppercase name is libreoffice-bn-IN. According to the makepkg source, the allowed chars are: [:alnum:]+_.@-. Lekensteyn (talk) 22:38, 1 February 2014 (UTC)
"alphanumeric characters only" rule is ridiculous, 85% of official packages break this rule. I think it should be changed to allow hypens. It makes package names more readable. In regards to other characters, the + sign breaks AUR search (example, should be escaped). axper (talk) 11:19, 11 May 2014 (UTC)
  • Package names should NOT be suffixed with the upstream major release version number (e.g. we don't want libfoo2 if upstream calls it libfoo v2.3.4) in case the library and its dependencies are expected to be able to keep using the most recent library version with each respective upstream release. However, for some software or dependencies, this can not be assumed. In the past this has been especially true for widget toolkits such as GTK and Qt. Software that depends on such toolkits can usually not be trivially ported to a new major version. As such, in cases where software can not trivially keep rolling alongside its dependencies, package names should carry the major version suffix (e.g. gtk2, gtk3, qt4, qt5). For cases where most dependencies can keep rolling along the newest release but some can't (for instance closed source that needs libpng12 or similar), a deprecated version of that package might be called libfoo1 while the current version is just libfoo.
--unsigned
  • Package versions should be the same as the version released by the author. Versions can include letters if need be (eg, nmap's version is 2.54BETA32). Version tags may not include hyphens! Letters, numbers, and periods only.
--unsigned
This rule needs to get more stricter. Having a slash in the version breaks filenames. For craziness, I tried setting up a pkgver containing all characters from 0x01 to 0xff which makes makepkg throw a Bash syntax error. The current packages have versions matching {{ic}[[alnum:]._+~]+} (and a colon for epoch, a hypen for pkgrel). What about limiting to those characters? Debian has a similar set, see their policy docs Lekensteyn (talk) 22:38, 1 February 2014 (UTC)
  • Package releases are specific to Arch Linux packages. These allow users to differentiate between newer and older package builds. When a new package version is first released, the release count starts at 1. Then as fixes and optimizations are made, the package will be re-released to the Arch Linux public and the release number will increment. When a new version comes out, the release count resets to 1. Package release tags follow the same naming restrictions as version tags.
--unsigned
  • Why is there no mentioning of suffixes for different build sources, such as vcs sources (-git, -hg, …) or binary distributions (-bin)? IMO this is an important part of the package naming conventions in AUR. Fordprefect (talk) 13:43, 10 May 2016 (UTC)

Is it acceptable for build() to start by removing directories?

I just downloaded a PKGBUILD whose build() function begins with the following:

find ./ -maxdepth 1 -mindepth 1 -type d  -exec rm -r {} \;

It seems to me that a PKGBUILD has no business doing this and that it is potentially dangerous. I admit that its danger will typically require people to do non-standard things and, arguably, things they would be better advised not to do anyway. But it still seems to me to invite trouble.

I don't remember seeing this in a PKGBUILD before but I can't find anything definitely ruling it out.

Is it acceptable for a build function to start by removing directories in this way? Is it safe?

--cfr (talk) 03:03, 27 February 2014 (UTC)

I'd argue that this is an acceptable thing to do, at least in some cases. As an example, consider Talend Open Studio DI: a single source file provides files for Windows, Linux, Mac OS, PowerPC (?) and Solaris. In response, the talend-open-studio-diAUR PKGBUILD simply removes them. Does removing those files invite trouble? Yes. But removing files seems like an integral tool in the package maintainer's toolkit, and plenty of other weird stuff happens in PKGBUILDs too. Ichimonji10 (talk) 02:20, 3 March 2014 (UTC)

Update "Submitting packages to the AUR" section

The line

> One can easily build a tarball containing all the required files by using makepkg --source. This makes a tarball named $pkgname-$pkgver-$pkgrel.src.tar.gz, which can then be uploaded to the AUR.

in the "Submitting packages to the AUR" section on this page should be updated to refer to mkaurball, which is now apparently required to build valid AUR source packages automatically.

(Sorry, I am new to the ABS, so I won't change this page myself. I would probably miss something.)

--Drawm (talk) 14:57, 27 August 2014 (UTC)

I would argue that the section should not even be here - there is already Arch User Repository#Submitting packages, and "submitting packages to AUR" has little to do with the official packaging standards. -- Lahwaacz (talk) 15:14, 27 August 2014 (UTC)
You would argue correctly, although I haven't checked if there's something worth being merged. -- Kynikos (talk) 03:39, 28 August 2014 (UTC)
I agree that this section needs to be edited or deleted, and I was going to do it myself, but don't see any "edit" buttons anywhere on the main page. Maybe this section should just provide the link to the correct information in Arch User Repository#Submitting packages. Whoever can edit this, it needs to be done because it gives incorrect information, which I and others have tried to follow only to be told by the AUR that it won't work. Colinkeenan (talk) 23:25, 28 September 2014 (UTC)
You're right, I've just fixed it. However the two sections should really be merged, maybe keep the AUR rules here and the instructions in the AUR article? -- Kynikos (talk) 01:46, 29 September 2014 (UTC)
Since the move to AUR4 this section is outdated. IMHO it should not even be here. A link to Arch User Repository#Submitting packages should be sufficient since the rules are clearly stated there. --Edh (talk) 08:50, 1 April 2016 (UTC)
The two sections don't seem to overlap completely, i.e. they should be merged; I've done this for the moment. — Kynikos (talk) 03:38, 2 April 2016 (UTC)

/selinux

Someone with privileges could edit the page and point that selinux itself and they needed packages could install in /selinux as an exception in the directory section.

—This unsigned comment is by Jristz (talk) 21:00, 25 May 2015‎. Please sign your posts with ~~~~!

The selinux packages are not in the official repositories. Be it a justified exception or not, I don't see any reason why this should be mentioned in the official guidelines. -- Lahwaacz (talk) 21:29, 25 May 2015 (UTC)

Minor style inconsistency

"~/.makepkg.conf" is missing an ic-tag in the Package etiquette section. -- Edh (talk) 21:47, 16 August 2016 (UTC)

Add a note about bash variable handling

State that among other pkgdir, srcdir respectively any variable which might contain spaces should be quoted whenever used. This would probably be a good addition to the Package etiquette bullet list. -- Edh (talk) 21:50, 16 August 2016 (UTC)

Via [1], thanks -- Alad (talk) 22:55, 16 August 2016 (UTC)