This article aims to assist users creating their own packages using theports–likeArch build system, also for submission inArch User Repository. It covers creation of aPKGBUILD(5)—a package build description file sourced bymakepkg to create a binary package from source.

For instructions regarding existing rules and ways to improve package quality, seeArch package guidelines.

Packages in Arch Linux are built using themakepkg utility and the information stored in aPKGBUILD file. Whenmakepkg runs, it searches for aPKGBUILD in the current directory and follows the instructions in it to acquire the required files and/or compile them to be packed within a package filepkgname.pkg.tar.zst. The resulting package contains binary files and installation instructions ready to be installed bypacman.

An Arch package is no more than atar(1) archive, or atarball, compressed usingzstd(1), which contains the following files generated bymakepkg:

• The binary files to install.
• .PKGINFO: contains all the metadata needed by pacman to deal with packages, dependencies, etc.
• .BUILDINFO: contains information needed for reproducible builds, also seeBUILDINFO(5).
• .MTREE: contains hashes and timestamps of the files, which are included in the local database so that pacman can verify the integrity of the package.
• .INSTALL: an optional file used to execute commands after the install/upgrade/remove stage (this file is present only if specified in thePKGBUILD).
• .Changelog: an optional file kept by the package maintainer documenting the changes of the package.

First, ensure that the necessary tools areinstalled: themeta packagebase-devel should be sufficient; it pulls inmake(1) and additional tools needed for compiling from source.

The key tool for building packages ismakepkg (provided bypacman). The tasks it performs can be found inArch package guidelines#Makepkg duties.

Download the source tarball of the software you want to package, extract it, and follow the author's steps to install the program. Make a note of all commands and/or steps needed to compile and install it. You will be repeating those same commands in thePKGBUILD file.

Most software authors stick to the 3-step build cycle:

$ ./configure$ make# make install

This is a good time to make sure the program is working correctly.

It is recommended to followBuilding in a clean chroot to ensure that packages and configuration of your system do not lead to mistakes in thePKGBUILD. This is a more robust and correct way to build packages and will often catch missing dependencies that you did not realize were needed because they already existed in your system.

Whenmakepkg is run, it looks for aPKGBUILD file in the current working directory. If it finds one, it downloads the software's source code and compiles it according to the instructions specified in thePKGBUILD file. The instructions must be fully interpretable by theBash shell.

After successful completion, the resulting binaries and metadata of the package, i.e. package version and dependencies, are packed in apkgname.pkg.tar.zst package file. The newly created package can be installed by simply usingmakepkg --install which will call pacman in the background, or by directly usingpacman -Upkgname.pkg.tar.zst.

To start building a new package, first create a new directory for the package and change current directory into this one. Then, aPKGBUILD file needs to be created: a prototypePKGBUILD found in/usr/share/pacman/ can be used or you can start from aPKGBUILD from another package. The latter may be a good choice if a similar package already exists.

makepkg predefines the following variables that should be used by packagers to refer to temporary locations during the build process:

srcdir

This points to the directory wheremakepkg extracts or symlinks all files in the source array.

pkgdir

This points to the directory wheremakepkg bundles the installed package, which becomes the root directory of your built package.

They containabsolute paths, which means you do not have to worry about your working directory if you use these variables properly.

When building a package,makepkg will invoke the following five functions if they have been defined in thePKGBUILD. Functionpackage() is required in everyPKGBUILD and will always be invoked. If any of the other functions is not defined,makepkg will simply skip the invocation of that function.

During the build, the functions are invoked in the order in which they are listed here.

Also seePKGBUILD(5) § PACKAGING FUNCTIONS.

With this function, commands that are used to prepare sources for building are run, such aspatching. This function runs right after package extraction, beforepkgver() and the build function. If extraction is skipped (makepkg --noextract), thenprepare() is not run.

When it is not clear whether to put something inprepare() orbuild(), one rule of thumb is to put inprepare() the steps that should run exactly once after extracting the sources, and put inbuild() the steps which would make sense to re-run after any manual edits to the extracted files.

pkgver() runs after the sources are fetched, extracted andprepare() executed. So you can update the pkgver variable during a makepkg stage.

This is particularly useful if you aremaking git/svn/hg/etc. packages, where the build process may remain the same, but the source could be updated every day, even every hour. The old way of doing this was to put the date into the pkgver field which, if the software was not updated, makepkg would still rebuild it thinking the version had changed. Some useful commands for this aregit describe,hg identify -ni, etc. Please test these before submitting aPKGBUILD, as a failure in thepkgver() function can stop a build in its tracks.

Now, you need to implement thebuild() function in thePKGBUILD file. This function uses common shell commands inBash syntax to automatically compile software and create a directory calledpkg to install the software to. This allowsmakepkg to package files without having to sift through your file system.

The first step in thebuild() function is to change into the directory created by uncompressing the source tarball.makepkg will change the current directory to$srcdir before executing thebuild() function. Therefore, in most cases, like suggested in/usr/share/pacman/PKGBUILD.proto, the first command will look like this:

cd "$pkgname-$pkgver"

Now, you need to list the same commands you used when you manually compiled the software. Thebuild() function in essence automates everything you did by hand and compiles the software in the fakeroot build environment. If the software you are packaging uses a configure script, it is good practice to use--prefix=/usr when building packages for pacman. A lot of software installs files relative to the/usr/local directory, which should only be done if you are manually building from source. All Arch Linux packages should use the/usr directory. As seen in the/usr/share/pacman/PKGBUILD.proto file, the next two lines often look like this:

./configure --prefix=/usrmake

Place for calls tomake check and similar testing routines. It is highly recommended to havecheck() as it helps to make sure software has been built correctly and works fine with its dependencies.

Users who do not need it (and occasionally maintainers who can not fix a package for this to pass) can disable it by adding!check into theoptions array inPKGBUILD/makepkg.conf(5) or callmakepkg with--nocheck flag.

If you are testing a GUI application, you canrun it in a virtual xserver.

The final step is to put the compiled files in a directory wheremakepkg can retrieve them to create a package. This by default is thepkg directory—a simple fakeroot environment. Thepkg directory replicates the hierarchy of the root file system of the software's installation paths. If you have to manually place files under the root of your filesystem, you should install them in thepkg directory under the same directory structure. For example, if you want to install a file to/usr/bin, it should instead be placed under$pkgdir/usr/bin. Very few install procedures require the user to copy dozens of files manually. Instead, for most software, callingmake install will do so. The final line should look like the following in order to correctly install the software in thepkg directory:

make DESTDIR="$pkgdir" install

makepkg --repackage runs only thepackage() function, so it creates a package without building. This may save time e.g. if you have changed just thedepends variable of the package.

As you are writing thebuild() function, you will want to test your changes frequently to ensure there are no bugs. You can do this using themakepkg command in the directory containing thePKGBUILD file. With a properly formattedPKGBUILD, makepkg will create a package; with a broken or unfinishedPKGBUILD, it will raise an error.

If makepkg finishes successfully, it will place a file namedpkgname-pkgver.pkg.tar.zst in your working directory. This package can be installed with thepacman -U command. However, just because a package file was built does not imply that it is fully functional. It might conceivably contain only the directory and no files whatsoever if, for example, a prefix was specified improperly. You can usepacman's query functions to display a list of files contained in the package withpacman -Qlppkgname, and the dependencies it requires withpacman -Qippkgname.

If the package looks sane, then you are done! However, if you plan on releasing thePKGBUILD file, it is imperative that you check and double-check the contents of thedepends array.

Also ensure that the package binaries actuallyrun flawlessly! It is annoying to release a package that contains all necessary files, but crashes because of some obscure configuration option that does not quite work well with the rest of the system. If you are only going to compile packages for your own system, though, you do not need to worry too much about this quality assurance step, as you are the only person suffering from mistakes, after all.

After testing package functionality, check it for errors usingnamcap:

$ namcap PKGBUILD$ namcappkgname.pkg.tar.zst

Namcap will:

• checkPKGBUILD contents for common errors and package file hierarchy for unnecessary/misplaced files,
• scan allELF files in the package usingldd(1), automatically reporting which packages with required shared libraries are missing fromdepends and which can be omitted as transitive dependencies,
• heuristically search for missing and redundant dependencies,

and much more.

Get into the habit of checking your packages withnamcap to avoid having to fix the simplest mistakes after package submission.

You can usepkgctl fromdevtools to check if the package can be built where no other packages are already installed. While in the PKGBUILD directory:

$ pkgctl build

And check the output for potential errors or warnings. If the package depends on other AUR packages, those packages must be built and brought into chroot jail:

$ pkgctl build -I path/to/somepkg.tar.gz -I ...

Refer topkgctl-build(1) for more options.

Please readAUR submission guidelines for a detailed description of the submission process.

1. Download the source tarball of the software to package.
2. Try compiling the package and installing it into an arbitrary directory.
3. Copy over the prototype/usr/share/pacman/PKGBUILD.proto and rename it toPKGBUILD in a temporary working directory.
4. Edit thePKGBUILD according to the needs of your package.
5. Runmakepkg and check whether the package builds correctly.
6. If not, repeat the previous two steps.

• Before you can automate the package building process, you should have done it manually at least once unless you knowexactly what you are doingin advance, in which case you would not be reading this in the first place. Unfortunately, although a good bunch of program authors stick to the 3-step build cycle of "./configure;make;make install", this is not always the case, and things can get real ugly if you have to apply patches to make everything work at all. Rule of thumb: If you cannot get the program to compile from the source tarball, and make it install itself to a defined, temporary subdirectory, you do not even need to try packaging it. There is not any magic pixie dust inmakepkg that makes source problems go away.
• In a few cases, the packages are not even available as source and you have to use something likesh installer.run to get it to work. You will have to do quite a bit of research (read READMEs, INSTALL instructions, man pages, perhaps ebuilds from Gentoo or other package installers, possibly even the MAKEFILEs or source code) to get it working. In some really bad cases, you have to edit the source files to get it to work at all. However,makepkg needs to be completely autonomous, with no user input. Therefore if you need to edit the makefiles, you may have to bundle a custom patch with thePKGBUILD and install it from inside theprepare() function, or you might have to issue somesed commands from inside theprepare() function.

The process of updating checksums for new software releases can be automated by theupdpkgsums tool; seeMakepkg#Generate new checksums for details.

PKGBUILDs for some packages can be generated automatically.

• Haskell:cblrepo,arch-hs
• Node.js:nodejs-npm2arch^AUR
• Perl:perl-cpanplus-dist-arch^AUR
• Python:pipman-git^AUR,pip2arch-git^AUR,python-pypi2pkgbuild^AUR
• Ruby:gem2arch^AUR,pacgem^AUR
• Rust:cargo-pkgbuild^AUR,cargo-aur-bin^AUR

pkgctl (from thedevtools package) supportsnvchecker integration in the form of a.nvchecker.toml configuration file (which should be placed in the same directory as thePKGBUILD). See the pacman package's.nvchecker.toml configuration file for an example.

You can then usepkgctl version check to check if a new upstream version has been released (compared to the one specified aspkgver in thePKGBUILD) andpkgctl version upgrade to update thePKGBUILD accordingly. Seepkgctl-version(1) for more details.

• How to correctly create a patch file.
• Arch Linux Classroom IRC Logs of classes about creating PKGBUILDs.
• Fakeroot approach for package installation

• About Arch
• Package development

• Pages or sections flagged with Template:Merge