Variables

Built-in Variables

Package Info

pkgname

This is what Pacstall records as the name of the built package. Use the following naming schema:

• Keep it lowercase
• Pacscripts that install from a deb file should be called pkgname-deb
• Pacscripts that install from a git repository should be called pkgname-git
• Pacscripts that install an appimage should be called pkgname-app
• Pacscripts that install the binary of the package should be called pkgname-bin
• If a Pacscript does not fall under any of the categories above, use pkgname

pkgbase

If this is not provided in a pacscript, then it is assumed that it is a singular pkgname, and a .SRCINFO file assumes that pkgbase is equal to that singular pkgname. If using package splitting (opens in a new tab), pkgname is treated like an array, and multiple packages can be built. To split out the packages, they should define the functions package_pkgname(), and can override the following variables inside of them: gives, pkgdesc, arch, url, license, depends, checkdepends, optdepends, pacdeps, provides, checkconflicts, conflicts, breaks, replaces, enhances, recommends, priority, backup, repology.

repology

This is what Pacup (opens in a new tab) uses to get the latest version of your packaged program for updating the pacscript. Read this (opens in a new tab) to know how to add it to your repository.

If the repology variable isn't present in the pacscript, Pacup will refuse to update it.

arch

This array is used to define what architectures your pacscripts will work on. If your package works on any architecture, leave it out completely, or if you really want to, put arch=('any') or arch=('all').

Two variables, $CARCH and $AARCH are also available to you, and are linked to the current running architecture. You can get the value that $CARCH would be on your system by running dpkg --print-architecture, and $AARCH by running echo $HOSTTYPE (with two exceptions, starred below). These are differentiated in the given list with CARCH/AARCH (if only one is listed, the variables are equal).

Pacstall supports all architectures that have an official Debian port (opens in a new tab). These are currently:

• amd64/x86_64
• arm64/aarch64
• armel/arm
• armhf/armv7h*
• i386/i686*
• mips64el
• ppc64el
• riscv64
• s390x

pkgver

This is the version number. It should ideally (but not required) be using semver (opens in a new tab). As long as the version number can be handled by dpkg --validate-version, it is valid.

pkgrel

This is used when you wish to trigger an update on users computers but pkgver has not been updated. This could be used if you fix a dependency in a pacscript, or perhaps you forgot to add a line to the building process. It is implicitly set to 1 if not included, and should not be included by default. Every time pkgver is updated, pkgrel should be removed.

epoch

This variable is used to forcibly upgrade a package in any circumstance. In most cases, a pkgrel bump will work just fine, but certain circumstances may require an upgrade that breaks normal comparison logic (opens in a new tab). It is assumed to be 0 by default (opens in a new tab), and if used, should be a small integer.

url

This variable is used to show the homepage/website of the package (if any).

incompatible

This array is a list of distros/versions that cannot be used to build this package, for example due to outdated dependencies. Elements follow a schema of $distro:$version, where either $distro or $version can be a glob character ('*'), but not both. $version can be a distro name (jammy, noble, sid, etc) or a version number (22.04, 16.04, etc).

compatible

This is the opposite of incompatible. compatible will only build on distros/versions found inside.

pkgdesc

This is a variable that sets the description of the package. Try to keep it as close as possible to upstream. This variable can be multi-lined for extended descriptions. Do not end the short description (first line) with a period. For example:

pkgdesc="Provide limited super user privileges to specific users
Sudo is a program designed to allow a sysadmin to give limited root
privileges to users and log root activity. The basic philosophy is to give
as few privileges as possible but still allow people to get their work done."

license

An array of licenses that this package is licensed under. Valid licenses are listed in https://spdx.org/licenses/ (opens in a new tab). Custom licenses can be included with the prefix custom:.

maintainer

An array of keys that contain the name and contact email of the package maintainer(s). The primary maintainer of the package should be listed first, and others after them. Subsequent maintainers will be marked as "Uploaders" in the final package. The keys take the form like this:

"my name <email here>"

custom_fields

This is an optional list of Debian control fields not already used by Pacstall's variables. If you want to provide a custom field to the control file of a built package, you may do so with the following format options:

custom_fields=(
  "Banana: this is a valid field"
  "My-Field: this is also a valid field"
  "Third-One: even this
  is a valid field"
)

There are a few restrictions on field names:

• The following cannot be used: Depends, Package, Version, Architecture, Section, Priority, Essential, Vcs-Git, Build-Depends, Build-Depends-Arch, Build-Conflicts, Build-Conflicts-Arch, Provides, Conflicts, Breaks, Enhances, Recommends, Suggests, Replaces, Homepage, License, Maintainer, Uploaders, Description, Installed-Size
• Numbers and spaces are not allowed
• The first letter must be capital, and all others must be lowercase
• Hyphens should be used for multiword fields, and follow the same capitalization rule for each word
• Hyphens cannot be the first or last character in the field name

Package Sources

source

This is an array with URLs as elements. These will be downloaded by pacstall before the prepare function. source can be created many different ways, and is incredibly powerful in functionality.

Inside a source array, you have the following schema:

• Elements can be optionally prefixed with dest:: which will instruct pacstall to download (or copy) that archive to the name dest.
  • Note that dest is not where the final extracted output of a download would be, but where the download is going to.
• Git sources must have their URL prefixed with git+ if the URL does not end with .git.
• Git sources may end in #branch=, #tag=, or #commit=, followed by their respective contents.
  • If this is not provided, then it is assumed to clone from HEAD of the repository. This is often the master or main branch.
• To use sources relative in location to the pacscript, there are two main options:
  • Use file:// for installing local archives relative to the pacscript. Generally will look like file://${PWD}/example.zip or file:///home/pacstall/example.zip.
  • For installing files relative to the pacscript from the pacstall-programs repository, list the file plainly, like "example.desktop". The file should be stored in the same folder as the pacscript, in packages/${pkgname}/. This is useful for avoiding large echos in pacscripts, but should only be used for standard text files, or potentially small images for icons. Larger archives should be stored externally.
• Deb sources can only be provided one entry. More complex array options are described below.

An example with every option added (not functional) would look like:

custom-location.zip::git+file://example.com/archive.tar.xz?h=file#branch=master

Extraction method is calculated from the initial url basename and not dest, so an example like above would still extract with the correct method. The following extensions can be extracted by default:

• *.zip
• *.tar.gz/*.tgz
• *.tar.bz2/*.tbz2
• *.tar.bz/*.tbz
• *.tar.xz/*.txz
• *.tar.zst/*.tzst
• *.gz
• *.bz2
• *.xz
• *.lz
• *.lzma
• *.zst
• *.7z
• *.rar
• *.lz4
• *.tar

If using an archive that contains a *.tar.* extension that is not covered by any of the above listed, pacstall will attempt to extract it with the regular *.tar method. If pacstall does not recognize the extension, it will not try to extract it. If you do not want to extract a certain source, see noextract.

You may define architecture specific sources like source_$arch, and you can define distro sources like source_$DISTRO, where $DISTRO can be either ubuntu or debian, or a codename of a release, such as jammy or bookworm. If you want to combine both a distro and architecture, you may do source_${DISTRO}_${arch}. A CI maintained file in pacstall/pacstall-programs (opens in a new tab) will provide an up-to-date list of the supported releases.

Enhanced arrays can also be used in conjunction with the existing normal arrays, as a way to append. They append in order of increasing specificity:

*sums

These sets of arrays are used in relation to source and are used to verify the integrity of the downloaded package. The following hashing programs can be used for the name of the sums array:

1. sha256sums
2. sha512sums
3. sha384sums
4. sha224sums
5. sha1sums
6. md5sums
7. b2sums

Along with these sums arrays, the same $arch and $DISTRO rules from source apply.

If you do not wish to check the hash of a certain file, you may put SKIP as the element corresponding to the location of the file in source.

nosubmodules

Use this array to prevent pacstall from cloning submodules for any source array with dest where dest is included in this array. For example:

source=(
  "rpk::https://github.com/rhino-linux/rhino-pkg.git"
  "https://github.com/tamton-aquib/stuff.nvim.git"
)
nosubmodules=("rpk")

noextract

Use this array like you would with nosubmodules except this is for when you do not want a source to be extracted.

backup

In dpkg, files in /etc are set as "configuration files", meaning that by default they will not be removed when one runs apt remove pkg, but will with apt purge pkg. This array should be filled with file paths (without the leading slash), and every file in it will be set as a configuration file. Do not include any files that will be unpacked in /etc, as that is already handled by dpkg. There is one special exception you may add to a key, and that is a leading r:, which instructs dpkg to delete that file on the next upgrade. If you include r: in a key, that file cannot appear in the binary package.

external_connection

Because Pacstall runs builds in an isolated environment, internet connection is by default not permitted inside of the packaging functions. If a package needs to connect to the internet for these functions (often for cargo builds, certain python builds, and occasionally making a git connection), the variable external_connection=true must be provided. By default, this is not included, and is assumed false.

Package Dependencies

depends

This is an array used to declare runtime dependencies of a package. As with source, this array can be enhanced by $arch and/or $DISTRO. Along with that, you can also add version constraints, which take the following schema:

1. Any dependency can optionally have the following format:
   1. pkg>=version
   2. pkg<=version
   3. pkg>version
   4. pkg<version
   5. pkg=version
2. Dependencies can be alternative, so that if the first package cannot be found or it's dependency constraints cannot be satisfied, will attempt to find the alternative package: pkg | pkg2. These constraints apply to all dependency arrays, with the exception of pacdeps.

makedepends

This is an array used to declare build-time dependencies. Everything from depends apply here.

checkdepends

This is an array used to declare dependencies needed for testing in the check function. These are installed at the same time as makedepends. Everything from depends apply here.

optdepends

This is an array used to declare optional dependencies. Everything from depends apply here, with one addition, that being the requirement of a description, which takes the form of pkg: description here. Remember that pkg in this case can be any version constraint, including an alternative, so this is valid:

"libidk:i386<5.2.3 | libidk:i386>1.2.5: provides libidk support"

If at build time the user decides not to install a package in optdepends, it will be logged as Suggests (opens in a new tab).

pacdeps

This is an array that is used to declare dependencies on other pacstall packages. Functionally, they will be installed like makedepends (before building) and will be logged like depends (required). Unlike the other *depends arrays, these cannot use version constraints, but may still be enhanced by $arch and/or $DISTRO.

Package Relations

breaks

This is an array that declares packages that cannot be installed alongside this package. Any package declared in breaks can be unpacked alongside this package, but both cannot exist. Essentially, this is what you should use to declare incompatibilities between packages that do not have file path conflicts.

This array can be enhanced by $arch and/or $DISTRO.

conflicts

This is an array similar to breaks, except it declares that packages cannot be unpacked at the same time, likely due to having files in the same locations.

This array can be enhanced by $arch and/or $DISTRO.

makeconflicts

This is an array used to declare packages that cannot be installed on the system at build-time, usually because of a package conflict with a build-time dependency.

This array can be enhanced by $arch and/or $DISTRO.

checkconflicts

This is an array used to declare packages that cannot be installed on the system for testing in the check function, usually because of a package conflict with a check dependency.

This array can be enhanced by $arch and/or $DISTRO.

replaces

This is an array that declares packages that has files that can be overwritten by this package (opens in a new tab). This functionality is available only in conjunction with breaks.

If you want to replace whole packages (opens in a new tab), instead of simply taking over files, you should have replaces alongside conflicts.

This array can be enhanced by $arch and/or $DISTRO.

provides

A list of packages that this package can satisfy as a dependency. For instance, the package foobar-plus could satisfy foobar, so you would have this:

provides=("foobar")

This array can be enhanced by $arch and/or $DISTRO.

recommends

A list of packages that this package does not depend on, but may receive improved functionality from, and most users would want to have included with their install. Packages marked "Recommends" have stronger weight than packages marked "Suggests", but can still be opted out of, unlike depends.

This array can be enhanced by $arch and/or $DISTRO.

suggests

A list of packages that this package does not depend on, but may receive improved functionality from. This is most useful for when building static packages, to use instead of optdepends, as optdepends that are installed on the system are marked as depends.

This array can be enhanced by $arch and/or $DISTRO.

enhances

A list of packages that this package can satisfy as a suggested package or recommended package. For instance, if the package foobar recommends foobar-extras, in foobar-extras you would have:

enhances=("foobar")

This array can be enhanced by $arch and/or $DISTRO.

gives

This variable is used generally in conjunction with pkgname, in which gives will override the name that the package will take. General examples look like:

pkgname="foo-git"
gives="foo"

In order to distinguish the pacstall name and the installed package name.

This variable can be enhanced by $arch and/or $DISTRO. However, unlike the arrays, entries do not append, but instead override. They override in order of increasing specificity:

priority

Sets the priority (opens in a new tab) of a package. It can have the following values if included:

1. essential
2. required
3. important
4. standard
5. optional (default)

mask

An array containing apt or pacstall package names. Once this package is installed, anything inside mask will be prevented from showing up in apt and pacstall search results, or anything relating to dpkg. Once the package is removed, the effect reverses and mask contents will be visible again.