The tools in this suite help to build and prepare for AUR upload even complicated repository setups with additional files, makepkg-templates and rewrites. This tutorial explains some practical situation where they can be of aid.
Suppose a repository that provides a PKGBUILD stored alongside all other project data.
examplepackage
├── Makefile
├── PKGBUILD
├── README.md
└── src
├── main.c
├── Makefile
└── ...
Only the PKGBUILD is relevant for distribution to the AUR. A .SRCINFO is also required for that, but it can be generated from the PKGBUILD, so tracking it on the project's main branch would be redundant. To prepare this repository for AUR upload, simply execute aurbranch.
> aurbranch
creating refs/heads/aurIt will then ask for a commit message, generate the .SRCINFO from the PKGBUILD and commits them as the first revision of a branch named aur. As this branch did not previously exist, it also sets up a remote named exactly like the package (examplepackage in this case) and configure the branch to track the master branch of this remote. So consequently, uploading can be invoked with
> git push aurWhenever a new release should be distributed to the AUR, just repeat these two commands.
A few revisions later, an installation script made its way into the repository, which is referred in the PKGBUILD by install=examplepackage.install. A desktop entry was also added.
examplepackage
├── examplepackage.install
├── examplepackage.desktop
├── Makefile
├── PKGBUILD
├── README.md
└── src
├── main.c
├── Makefile
└── ...
Both are needed by the PKGBUILD and should thus be included in the AUR branch. To achieve this, they are simply added to the aurbranch command line.
> aurbranch examplepackage.*As the PKGBUILD gets more complex, automatically generating the .SRCINFO file with makepkg --printsrcinfo program is not sufficient any longer. It has to be edited manually and thus is now included in the main branch.
examplepackage
├── examplepackage.install
├── examplepackage.desktop
├── Makefile
├── PKGBUILD
├── README.md
├── src
│ ├── main.c
│ ├── Makefile
│ └── ...
└── .SRCINFO
To stop aurbranch from generating it and instead make it use the existing one, add it to the command line, too.
> aurbranch examplepackage.* .SRCINFOTo make it more visible, you may want to keep the file without its leading dot and rename while composing the revision, which you can do with a colon.
> aurbranch examplepackage.* SRCINFO:.SRCINFOWith complex command lines like these, it may be useful to store them in a little script inside your repository. Then your co-maintainers also see how to upload new versions.
> echo 'aurbranch examplepackage.* SRCINFO:.SRCINFO' > distribute
> chmod +x distribute
> git add distribute
> git commit -m 'add AUR upload directive'Many maintainer keep related _PKGBUILD_s collected in a central repository. Usually, files specific to a package are kept in a directory named after the corresponding pkgbase. Common files reside outside.
collection
├── desktop.install
├── one
│ ├── PKGBUILD
│ ├── one.desktop
│ └── desktop.install -> ../desktop.install
├── two
│ ├── PKGBUILD
│ ├── two.desktop
│ └── desktop.install -> ../desktop.install
└── three
└── PKGBUILD
The aurbranch helper is aware of this setup. When run from within a subdirectory of the repository it places all paths as seen from this perspective and creates branches and remotes named aur/pkgbase with the pkgbase extracted from the PKGBUILD. So new revisions for the distribution branches aur/one, aur/two and aur/three can be composed and sent like so.
> ( cd one; aurbranch one.desktop one.install )
> ( cd two; aurbranch two.desktop two.install )
> ( cd three; aurbranch )
> git push aur/one ; git push aur/two ; git push aur/threeAs renaming on the fly can also change paths, the symbolic links are not even needed.
> ( cd one; aurbranch one.desktop ../desktop.install:desktop.install )
> ( cd two; aurbranch two.desktop ../desktop.install:desktop.install )
> ( cd three; aurbranch )As _PKGBUILD_s in such collections often share code parts, it can be wise to externalize them in templates. A template marker like # template input; name=build takes their place in the PKGBUILD.
collection
├── build-1.template
├── desktop-1.template
├── desktop.install
├── one
│ ├── PKGBUILD
│ └── one.desktop
├── two
│ ├── PKGBUILD
│ └── two.desktop
└── three
└── PKGBUILD
Before makepkg is able to work with these now, executing makepkg-template -t .. has to be called from inside the directories to insert the content of the template into the file again, surrounded by # template begin ... and template end ... markers. But adding this expanded variant to the repository not only replicates code that is already contained in the templates, but also causes the _PKGBUILD_s to change whenever their templates change. It would be better to just keep the # template input; ... lines in the repository as they were, but have a command that can build the package from there.
This is exactly what makepkg-expanded does. It just needs to be told where to find the templates.
> ( cd one; makepkg-expanded -t .. )
==> Making package: one ...When moved to a common folder named makepkg-templates in the repository root, even this option can be omitted.
collection
├── desktop.install
├── makepkg-templates
│ ├── build-1.template
│ └── desktop-1.template
├── one
│ ├── PKGBUILD
│ └── one.desktop
├── two
│ ├── PKGBUILD
│ └── two.desktop
└── three
└── PKGBUILD
And another flag builds all _PKGBUILD_s that can be found at once with
makepkg-expanded -aApart from the package and intermediate files makepkg leaves, this also produces a temporary file PKGBUILD.expanded besides each original _PKGBUILD_s, which you may want to add to your .gitignore as well as the .SRCINFO automatically generated by aurbranch.
A PKGBUILD uploaded to the AUR should be self-contained and not rely on any external templates. The .SRCINFO should also be created only from the expanded PKGBUILD. So expansion should also happen before throwing in aurbranch. Luckily, makepkg-expanded can not only invoke makepkg, but run any program, even arbitrary shell code.
makepkg-expanded -r 'aurbranch -p "$1" *' -aA few things are automatically taken care of by makepkg-expanded here. Firstly, clean-templates strips the resulting PKGBUILD from template markers and similar redundant content for better readability so that it looks fine for anyone inspecting your package from the AUR web interface. The wild card * in snippet passed with the -r option will automatically exclude the original PKGBUILD, and the -p option will direct aurbranch to use the expanded PKGBUILD instead of the original.
You may have noticed that aurbranch proposes a message to describe the commit to the AUR distribution branch with. This will be taken the last commit message affecting any of the files composing the commit. But it does not know that the PKGBUILD it uses here was generated from the templates and thus ignore changes in the templates. It can be told to consider them for the message, but not actually add them, by passing them in with an empty name.
makepkg-expanded -r 'aurbranch -p "$1" ../makepkg-templates: *' -aNote that their path has to be specified relative to the directories the _PKGBUILD_s reside is, as aurbranch is run from there. Again makepkg-expanded includes automatisms to ease life here. It passes the name of the expanded PKGBUILD, the corresponding original and all the template directories to the code snippet as parameters. They just have to be prefixed with a colon, which some bash trickery can do.
makepkg-expanded -r 'aurbranch -p "$1" ${@/%/:} *' -aThere is only one caveat left: When there are any stray untracked files in the directory, the wild card catches them, too. While testing, this is most probably the case for the package.tar.xz, the src and pkg directories and any sources left from building the package. So it can be useful to restrict * to files tracked by Git. This can be done by filtering it in Git's ls-files.
makepkg-expanded -r 'aurbranch -p "$1" ${@/%/:} $(git ls-files *)' -aThis command for the -r option is that commonly useful that makepkg-expanded provides -b as a shorthand for it.
When adopting a package, it comes with a history to build up on. Especially when integrating a newly adopted package into a collection, it should be pulled into the repository as a distribution branch so that aurbranch can add further commits on top of it. The auradopt program can configure branch and remote. When creating a branch anew, it will also pull in the history from the remote it set up.
auradopt package-nameFor more complicated project configurations, you may want to look at offbranch which is used by aurbranch internally to commit the files to a branch not checked out.