PKGBUILD advice

tardo · 2007-07-12 20:35:24

I've been through hundreds of PKGBUILDs in the AUR and I find it disappointing that the majority of them fail to conform to the PKGBUILD standards (hint: read this!). I'm not exactly sure about the reason for this, even though there's a huge line on the AUR front page saying that PKGBUILDs must conform to the standards... So I'm going to write this short post about common mistakes I see, and hopefully contributors will fix them. Please read the entire post.

The main reason I'm doing this is because I now refuse to mark PKGBUILDs as safe unless they conform to standards. If I did otherwise, contributors get the wrong impression that there is nothing wrong with their package. I get tired of leaving one line comments asking to fix something that's been stated over and over. So without further ado...

I'll start with the common mistakes:

1. The order of fields is important. Believe it or not, it makes it much easier to read. pkgname is first, pkgver second, pkgrel third and so on. There seems to be no problem with the first four fields but after that it gets messy. arch=() ALWAYS comes after pkgdesc and before url. license=() ALWAYS comes after url and before depends/makedepends.

2. The license field is NOT a string, it's an array. license=('GPL') is correct, license="GPL" is wrong. Again, a trivial mistake.

3. Use || return 1 on ALL make and patch lines. make || return 1. make DESTDIR=$startdir/pkg || return 1. patch -Np1 -i patch.file || return 1. I've seen many packages that error on make install, yet makepkg completes the pacakge.

4. If your license field has anything other than a common license, the license MUST be installed to $startdir/pkg/usr/share/licenses/$pkgname/LICENSE (or whatever the file is called, eg COPYING, Copyright.txt, etc). There should be no exceptions here. Common licenses can be found in /usr/share/licenses/common.

5. For everyone that uses makepkg -g >> PKGBUILD, and I'm pretty sure everyone does, please don't leave the md5sum on the last line, it takes a few keyboard strokes to put it right after source=().

6. Every PKGBUILD submitted to the AUR MUST have a Contributor field, where you specify your name (or nick) and a working email. Do NOT use Maintainer, that is reserved for devs and TUs only. There should be no exceptions to this rule.

7. Get rid of all the unneeded fields in the PKGBUILD. If it doesn't need provides/conflicts/groups/options etc, it doesn't need to be there.

8. When using a sourceforge link for source(), the only tld used should be downloads.sourceforge.net (or downloads.sf.net). Do NOT link to specific mirrors (and please do not use dl.sourceforge.net).

9. Try to avoid using custom variables. Especially in the meta fields. They should only be used if and only if the PKGBUILD will not build without it (examples, kernel pkgbuilds). When custom variables are used, they MUST start with an _, eg. _realpkgname, _altsource, etc.

10. This isn't a mistake, more of a preference, but I like to use quotations in my arrays, e.g. license=('GPL'), arch=('i686' 'x86_64'), etc. It just appears neater.

Here is an example PKGBUILD:

# Contributor: tardo <tardo at nagi-fanboi dot net>
pkgname=graphicsmagick
pkgver=1.1.7
pkgrel=1
pkgdesc="A set of commandline tools and programming APIs for manipulating, editing, and converting raster \
      and vector images"
arch=('i686' 'x86_64')
url="http://www.graphicsmagick.org/"
license=('custom')
depends=('freetype2' 'libtiff' 'libwmf' 'libxml2' 'ghostscript' 'bzip2' \
        'libsm' 'lcms')
options=('!libtool')
source=(http://downloads.sourceforge.net/sourceforge/graphicsmagick/GraphicsMagick-$pkgver.tar.gz)
md5sums=('9dec2209500b44c617a789b4072ed724')

build() {
  cd $startdir/src/GraphicsMagick-$pkgver
  ./configure --prefix=/usr
  make || return 1
  make DESTDIR=$startdir/pkg install || return 1
  install -D -m 644 Copyright.txt $startdir/pkg/usr/share/licenses/$pkgname/Copyright.txt
}

Apparently there was a goal to have 2500 pkgs marked safe sometime in the past, then dropped to 2000. We still haven't met that goal when it should be quite easy to do so. Usually by the time I've gone through the 10th or so PKGBUILD, I'm already fed up of leaving comments telling contributors to fix a no-brainer.

It should take very little effort to fix these mistakes, and I'd really like to reach the 2500 milestone, so help us out people. I'm usually on IRC all the time, so if you have questions about a PKGBUILD, please ask.

Last edited by tardo (2007-07-18 15:05:58)

Lone_Wolf · 2007-07-12 21:07:05

tardo wrote:

3. Use || return 1 on ALL make and patch lines. make || return 1. make DESTDIR=$startdir/pkg || return 1. patch -Np1 -i patch.file || return 1. I've seen many packages that error on make install, yet makepkg completes the pacakge.

Is this valid for tools like scons also ?

tardo wrote:

8. When using a sourceforge link for source(), the only tld used should be downloads.sourceforge.net (or downloads.sf.net). Do NOT link to specific mirrors (and please do not use dl.sourceforge.net).

For a long time this didn't work with sourceforge, possibly due to their mirror system.
It DOES work now.
Note : there are also dev maintained packages in current and extra that do not comply with this rule;

general comments :

The pkg guidelines also talks about a packager field, is this useful for Aur packages ?

Atm there is no explanation of the meaning of the entries in the .install files in the guidelines :
When is what entry used and for what purpose ?

tardo · 2007-07-12 21:16:05

Is this valid for tools like scons also ?

Yes. All other build systems as well (jam, python, custom install scripts)

For a long time this didn't work with sourceforge, possibly due to their mirror system

It always worked for me, though I modified my /etc/hosts to choose the nearest mirror instead of their default.

The pkg guidelines also talks about a packager field, is this useful for Aur packages ?

No, this is used in binary packages only.

Atm there is no explanation of the meaning of the entries in the .install files in the guidelines :
When is what entry used and for what purpose ?

man PKGBUILD. Currently there are no standards for the .install files and I'm not picky about these as long as they don't do anything malicious.

Note : there are also dev maintained packages in current and extra that do not comply with this rule;

Unfortunately I have no power over devs, neither do I have access to repos other than community and AUR. Maybe if devs see this, they too will try to conform to standards. But this shouldn't stop you from fixing your PKGBUILDs. Every PKGBUILD in community that I've built has been modified to conform to the standards.

Last edited by tardo (2007-07-12 21:26:32)

tardo · 2007-07-12 23:00:38

Let me add, if you fix your PKGBUILDs, send me an email with your AUR username, and I'll run through all of them.

PenguinFlavored · 2007-07-13 02:13:55

1. Didn't know about this one, I'll keep it in mind.
8. Thanks for the tip about dl.sourceforge.net I would always run across PKGBUILDs with this, and the download wouldn't start, so I did the other (bad) option, and used a specific mirror.

Is namcap being updated anymore. The repo at https://xentac.net/svn/namcap/trunk doesn't work anymore. I use this tool to _validate_ my packages, is this the way to go any longer?

How about making this thread a sticky?

tardo · 2007-07-13 02:35:02

namcap will only validate that the PKGBUILD has the required fields. It doesn't check for standards.

Cerebral · 2007-07-13 03:13:40

Is namcap being updated anymore. The repo at https://xentac.net/svn/namcap/trunk doesn't work anymore. I use this tool to _validate_ my packages, is this the way to go any longer?

I use namcap on my packages. There's a namcap pkg in [extra], in case you didn't know - it pulls sources down from http://projects.xennet.org/namcap/

Borosai · 2007-07-13 05:39:22

So what's the reasoning behind ALWAYS placing the arch and license arrays where you've listed above? If it's for readability, I don't think it helps. I actually find it clearer to place the url string after the pkgdesc string, followed by the license and arch arrays... it just reads better in my opinion.

Other than that, everything is very clear.

tardo · 2007-07-13 06:34:51

The arch position was decided by ganja_guru (x86_64 dev). The rest is based off PKBUILD.proto in cvs or /var/abs

[vEX] · 2007-07-13 09:07:06

Do you wrap install files in single/double quotes (ie: install='pkg.install') or do you just write it out (ie: install=pkg.install)?

[vEX] · 2007-07-13 09:18:16

tardo wrote:

3. Use || return 1 on ALL make and patch lines. make || return 1. make DESTDIR=$startdir/pkg || return 1. patch -Np1 -i patch.file || return 1. I've seen many packages that error on make install, yet makepkg completes the pacakge.

This should also be address with official maintainers, just checking the PKGBUILDs for the most recent packages on the main page shows a lot of PKGBUILDS missing || return 1 on the make install line. I don't want to point fingers or anything, I'm just saying that there are official packages that miss this as well, and if you use one of those PKGBUILDs as a base (instead of PKGBUILD.proto) you'll probably get it wrong as well.

Perhaps namcap can be updated to use some regexp that checks that any line starting with make ends with || return 1 (something like $make(.*?)|| return 1^)?

tardo · 2007-07-13 09:44:38

[vEX] wrote:

Do you wrap install files in single/double quotes (ie: install='pkg.install') or do you just write it out (ie: install=pkg.install)?

install is a string, hence intall="$pkgname.install" and install=$pkgname.install both work. I don't mind either.

iphitus · 2007-07-13 10:04:02

Borosai wrote:

So what's the reasoning behind ALWAYS placing the arch and license arrays where you've listed above? If it's for readability, I don't think it helps. I actually find it clearer to place the url string after the pkgdesc string, followed by the license and arch arrays... it just reads better in my opinion.
Other than that, everything is very clear.

Most things like ordering are just convention. There is no "requirement" or "rule" that they are like that, but it makes sense to anyway.

For example, one place where I disagree is md5sums, I prefer to leave them at the end, as they make more sense there. They're modified frequently, so they're easier to access at the end, and easier to replace.

But on the whole, all of the above are great advice. I think this thread should be wikified, linked to, and stickied. wikified so it stays up to date.

James

ezzetabi · 2007-07-13 15:45:44

We should also decide a standard about how to manage packages that needs copyrighted files in order to work.
At the moment in the aur I saw at least three different solutions:
1- asking the user to copy the copyrighted files in the PKGBUILD directory and putting filename and relative md5 in the PKGBUILD file as source and using them. E.g. cedega.
2- just install the software without them and just make a post install note, the user manually has to copy the files. E.g. doom 3.
3- install the software and start a script after installation that asks for the files. E.g. descent.

IMO the first is the best solution since it makes a complete package and makes the eventual removal clean, but you can't make binary packages, while the last is the worse since it may stops pacman at half work waiting for user input.
Anyhow, whatever it is decided I think a standard rule is needed.

Edit: fixed descent's url.

Last edited by ezzetabi (2007-07-13 15:49:54)

klixon · 2007-07-13 19:12:44

tardo wrote:

I'll start with the common mistakes:

Thanks for pointing this out...
Thank god i only have 1 package in AUR.

Lone_Wolf · 2007-07-13 21:41:05

ezzetabi wrote:

IMO the first is the best solution since it makes a complete package and makes the eventual removal clean, but you can't make binary packages, while the last is the worse since it may stops pacman at half work waiting for user input.
Anyhow, whatever it is decided I think a standard rule is needed.

I also feel that the first is the best solution.
Since these packages are very unlikely to make it into community or current/extra/unstable/testing repos due to license issues, imo the lack of binary packages for them are not a problem.

ezzetabi · 2007-07-14 13:14:54

About copyrighted files needed for a program to work I have an other idea...
It is an evolution of the idea #2, install the package without them, add a note in the post_install post_upgrade .install file and delete that files (if they exists) when uninstalling with pre_uninstall field...

Secondly, according to `tardo' the [bold]man PKGBUILD[/bold] is wrong and so should be updated.
I just made pacman -Suy and I can read:
license (array)
[...] simply reference it in the license field (e.g. license=("GPL")). If the package provides a license not found in
/usr/share/licenses/common, then you should include the license in the package itself and set license=("custom") or license=("custom:LicenseName"). [...]

This have at least two mistakes, the examples use " instead of ' and you must copy the license not just should.

DaNiMoTh · 2007-07-14 13:43:30

Just for information: http://bbs.archlinux.org/viewtopic.php? … 00#p265900
---
Why AUR doesn't reject PKGBUILD that doesn't respect that standards?

Lone_Wolf · 2007-07-14 20:26:46

ezzetabi wrote:

About copyrighted files needed for a program to work I have an other idea...
It is an evolution of the idea #2, install the package without them, add a note in the post_install post_upgrade .install file and delete that files (if they exists) when uninstalling with pre_uninstall field...

Often more is needed than simply copying these copyrighted files.
If we don't take care of that in the PKGBUILD, the user will have to perform the necessary actions manually.
This is error-prone and imo the main function of pkgbuilds is to alllow users to build/run programs without having to do such manual labor.

example from my Aur fs2_open package :

# extracting files from retail version, MediaVP files and movies"
    msg "extracting/copying necessary files"
    cd $startdir/src

# extract retail vp files from data1.cab
    for group in "Basic Install Files" "Intel Anims" "Music Compressed" "High Res Files"
      do unshield -d temp/retailvp -g "$group" -L -j x data1.cab
    done
    install -D -m644 -t $startdir/pkg/usr/share/$pkgname temp/retailvp/*/*
    unshield -d temp -g "Hud Config Files" -L -j x data1.cab
    install -D -m644 -t $startdir/pkg/usr/share/$pkgname/data/players temp/hud_config_files/*

# other retail vp files
    install -D -m644 -t $startdir/pkg/usr/share/$pkgname tango1_fs2.vp tango2_fs2.vp tango3_fs2.vp

# movies
    install -D -m644 -t $startdir/pkg/usr/share/$pkgname/data/movies *.MVE

# SCP media files
    install -D -m644 -t $startdir/pkg/usr/share/$pkgname/mediavps mv*.vp 
    unrar x mp-710_effects.rar temp/mediavps
    unrar x mp-710_models.rar temp/mediavps
    install -D -m644 -t $startdir/pkg/usr/share/$pkgname/mediavps temp/mediavps/*

# setting all filenames to lowercase
    tmv-l $startdir/pkg/usr/share/$pkgname/

All lines above, except the ones between the last 2 comments are needed to put the copyrighted files in the right place.
Even if the binary could be build without those files/actions (which i doubt) , the resulting program would be very crippled.

: edited for typo

Last edited by Lone_Wolf (2007-07-14 22:51:15)

madhatter · 2007-07-14 22:18:54

Short question: How should I treat the arch-variable when I have a cross-platform script (e.g. python scripts)?

ezzetabi · 2007-07-15 08:14:40

@madhatter
If it works in both Arch linuces you should put arch=('i686' 'x86_64'). The fact it may works in other systems is not a matter of your PKGBUILD file.

@Love_Wolf
As I said I agree with you, as you can see here and also here.
Yet, since packages from the AUR often go in the Community repo as binary. The `ones who decide' may prefer an other way.

Edit: typo.

Last edited by ezzetabi (2007-07-15 08:16:05)

Lone_Wolf · 2007-07-15 09:35:10

@ezzetabi : my mistake , it's clear we have the same opinion.

If #2 would become the official standard, we'd have to make wiki entries for manual instructions and refer to that in the packagebuilds.

This approach would work, but imo has a lot of disadvantages.

ezzetabi · 2007-07-15 15:39:17

We can also make scripts that do the job, if they are not executed automatically after installation they won't be intrusive. In this case a good idea is using the pkgname as prefix and a standard know suffix like '-cfinst' (where cf means copyrighted files). Those scripts should check if the copyrighted files are already in the system and if they are not ask the user for them and installing making patching if needed.
Anyhow the pre_remove function have to do the opposite work removing those files.

As you said it has disadvantages since this way won't use the power of pacman at all and it much more error prone than a simpler PKGBUILD.

mitsoko · 2007-07-16 20:18:27

also i think you need to || return 1 for configure and autogen; if they fail the most immediate error will lie with the next process ...

ezzetabi · 2007-07-17 09:16:27

EVERY program that failing will damage the package must be protected with || install 1 or with some sort of fallback.

Arch Linux

#1 2007-07-12 20:35:24

PKGBUILD advice

#2 2007-07-12 21:07:05

Re: PKGBUILD advice

#3 2007-07-12 21:16:05

Re: PKGBUILD advice

#4 2007-07-12 23:00:38

Re: PKGBUILD advice

#5 2007-07-13 02:13:55

Re: PKGBUILD advice

#6 2007-07-13 02:35:02

Re: PKGBUILD advice

#7 2007-07-13 03:13:40

Re: PKGBUILD advice

#8 2007-07-13 05:39:22

Re: PKGBUILD advice

#9 2007-07-13 06:34:51

Re: PKGBUILD advice

#10 2007-07-13 09:07:06

Re: PKGBUILD advice

#11 2007-07-13 09:18:16

Re: PKGBUILD advice

#12 2007-07-13 09:44:38

Re: PKGBUILD advice

#13 2007-07-13 10:04:02

Re: PKGBUILD advice

#14 2007-07-13 15:45:44

Re: PKGBUILD advice

#15 2007-07-13 19:12:44

Re: PKGBUILD advice

#16 2007-07-13 21:41:05

Re: PKGBUILD advice

#17 2007-07-14 13:14:54

Re: PKGBUILD advice

#18 2007-07-14 13:43:30

Re: PKGBUILD advice

#19 2007-07-14 20:26:46

Re: PKGBUILD advice

#20 2007-07-14 22:18:54

Re: PKGBUILD advice

#21 2007-07-15 08:14:40

Re: PKGBUILD advice

#22 2007-07-15 09:35:10

Re: PKGBUILD advice

#23 2007-07-15 15:39:17

Re: PKGBUILD advice

#24 2007-07-16 20:18:27

Re: PKGBUILD advice

#25 2007-07-17 09:16:27

Re: PKGBUILD advice

Board footer