pacscript.texi

@node Pacscript, Sample Script, Files, Top
@chapter Pacscript
This chapter is a reference to the pacscript format.

@menu
* Sample Script:: Script with every key included.
* Keys::          List of keys and descriptions of their functionality.
@end menu

@node Sample Script, Keys, Pacscript,
@section Sample Script

Below is a list of every base variable/function/array. Each will be explained later. @xref{Keys}.

@example
pkgbase="bar" # @xref{pkgbase}
pkgname=("foo" "barfoo") # @xref{pkgname}
repology=("project: bar") # @xref{repology}
arch=('any' 'amd64' 'arm64') # @xref{arch}
pkgver="1.0.0" # @xref{pkgver}
pkgrel="3" # @xref{pkgrel}
epoch="4" # @xref{epoch}
url='https://foo.com/bar' # @xref{url}
source=(
  "https://github.com/Elsie19/foo/archive/refs/tags/$@{pkgver@}.zip"
  "https://github.com/Elsie19/foo/archive/refs/tags/foo.desktop"
) # @xref{source}
(...)sums=(
    "9cc57f2ca39c2d81aed7e3d82af0b5711863bd3403bb8f024c4c3b4ecf9652a4"
    'SKIP'
) # @xref{sums}
nosubmodules=("foo") # @xref{nosubmodules}
noextract=("bar") # @xref{noextract}
depends=("kdenlive") # @xref{depends}
makedepends=("ed>=1.20.1" "gcc") # @xref{makedepends}
checkdepends=("just") # @xref{checkdepends}
optdepends=("bar: not foo"
  "alacritty: a blazing fast terminal"
) # @xref{optdepends}
pacdeps=("dmenu" "tuner") # @xref{pacdeps}
breaks=("libbar-git") # @xref{breaks}
conflicts=("libfoo-git" "libfoo-bin" "libfoo-app") # @xref{conflicts}
makeconflicts=("ed") # @xref{makeconflicts}
checkconflicts=("just") # @xref{makeconflicts}
replaces=("alacritty") # @xref{replaces}
recommends=("ttf-fira-code") # @xref{recommends}
suggests=("bar: not foo"
  "alacritty: a blazing fast terminal"
) # @xref{suggests}
enhances=("foobar-bar") # @xref{enhances}
gives="libfoo" # @xref{gives}
pkgdesc="Ultimate program capable of foo and bar
Here is a long description started on a newline." # @xref{pkgdesc}
backup=('usr/share/pacstall/repo/pacstallrepo') # @xref{backup}
priority='essential' # @xref{priority}
maintainer=(
    "Mr. Person <mr.person@@protonmail.com>"
    "Other person <other@@gmail.com>"
) # @xref{maintainer}
mask=('fizzle') # @xref{mask}
provides=('foo') # @xref{provides}
incompatible=('debian:stretch' 'debian:sid' '*:jammy' '*:20.04') # @xref{incompatible}
compatible=('debian:stretch' 'debian:sid' '*:jammy' '*:20.04') # @xref{compatible}
license=('LGPL-2.1-or-later') # @xref{license}
external_connection=true # @xref{external_connection}

prepare() @{
  cd "$@{pkgname@}-$@{pkgver@}"
  ./autogen.sh
  ./configure
@} # @xref{prepare()}

build() @{
  cd "$@{pkgname@}-$@{pkgver@}"
  make -j"$@{NCPU@}" # Use this wherever you'd usually use $(nproc)
@} # @xref{build()}

check() @{
  cd "$@{pkgname@}-$@{pkgver@}"
  make checks
@} # @xref{check()}

package() @{
  cd "$@{pkgname@}-$@{pkgver@}"
  # It is recommended for paths to be condensed with
  # variables and to be wrapped by double quotes
  make install DESTDIR="$@{pkgdir@}"

  # If the package comes already compiled, use 'install'
  install -Dm755 "$@{pkgname@}" -t "$@{pkgdir@}/usr/bin"
@} # @xref{package()}

pre_install() @{
  echo "Do pre-unpacking stuff here"
@} # @xref{pre_install()}

pre_upgrade() @{
  # run if a previous version of this package exists
  echo "Do pre-unpacking stuff here"
@} # @xref{pre_upgrade()}

pre_remove() @{
  # remove extra directories before an upgrade or removal
  rm -rf somedir
@} # @xref{pre_remove()}

post_install() @{
  echo "Do post-unpacking stuff here"
@} # @xref{post_install()}

post_upgrade() @{
  # run if a previous version of this package exists
  echo "Do post-unpacking stuff here"
@} # @xref{post_upgrade()}

post_remove() @{
  # remove directories that are not removed during removal
  rm -rf somedir
@} # @xref{post_remove()}
@end example

@node Keys, , Pacscript,
@section Keys
This section is dedicated to describing every valid key in a pacscript. You will more than likely not use all of these.

@menu
---- Package Metadata Variables ----

* pkgbase::      Split packaging functionality.
* pkgname::      Naming packages.
* repology::     Linking package versions.
* arch::         Controlling architecture building.
* pkgver::       Controlling versioning.
* pkgrel::       Control pacscript file versioning.
* epoch::        Control forcible upgrades.
* url::          Adding a useful link to project.
* incompatible:: Declaring package incompatiblities.
* compatible::   Declaring package compatiblities.
* pkgdesc::      Adding descriptions to packages.
* license::      Licensing package.
* maintainer::   Adding maintainers.

---- Package Sources ----

* source::              Adding sources.
* sums::                Hashchecking sources.
* nosubmodules::        Preventing submodules from being cloned.
* noextract::           Preventing archives from being extracted.
* backup::              Denoting files as configuration files.
* external_connection:: Allowing internet connection during packaging.

---- Package Dependencies ----

* depends::      Creating dependency links between packages.
* makedepends::  Creating build dependency links between packages.
* checkdepends:: Creating testing dependency links between packages.
* optdepends::   Creating optional dependency links between packages.
* pacdeps::      Creating pacstall dependency links between packages.

---- Package Relations ----

(All package relations may use version constraints.)

* breaks::         Denoting package conflicts.
* conflicts::      Denoting package path conflicts.
* makeconflicts::  Denoting makedepends conflicts.
* checkconflicts:: Denoting checkdepends conflicts.
* replaces::       Denoting packages that can be overwritten by package.
* provides::       Denoting a list of packages that this package can satisfy as a dependency.
* recommends::     Denoting a list of packages can improve functionality of this package.
* suggests::       Similar to optdepends but used for distributing built packages.
* enhances::       List of packages that this package can satisfy as a suggested package or recommended package.
* gives::          Override package name.
* priority::       Sets priority of package.
* mask::           Hide results from package managers.

---- Functions ----

------ Packaging Scripts ------

* prepare():: Preparing packages.
* build()::   Building packages.
* check()::   Sanity checking packages.
* package():: Install packages.

------ Maintainer Scripts ------

* pre_remove()::
* pre_install()::
* pre_upgrade()::
* post_remove()::
* post_install()::
* post_upgrade()::
@end menu

@node pkgbase, pkgname, Keys, Keys
@subsection pkgbase
If this is not provided in a pacscript, then it is assumed that it is a singular @ref{pkgname}, and a @file{.SRCINFO} file assumes that @ref{pkgbase} is equal to that singular @samp{pkgname}. If using @url{https://wiki.archlinux.org/title/PKGBUILD#pkgbase, package splitting}, @samp{pkgname} is treated like an array, and multiple packages can be built.

To split out the packages, they should define the functions @samp{package_pkgname()}, and can override the following variables inside of them: @samp{gives}, @samp{pkgdesc}, @samp{arch}, @samp{url}, @samp{license}, @samp{depends}, @samp{checkdepends}, @samp{optdepends}, @samp{pacdeps}, @samp{provides}, @samp{checkconflicts}, @samp{conflicts}, @samp{breaks}, @samp{replaces}, @samp{enhances}, @samp{recommends}, @samp{priority}, @samp{backup}, @samp{repology}.

@quotation Caution
In most cases, this should @strong{not} be provided in a pacscript. Only use this for split packages (pacscripts that build multiple packages from the same source).
@end quotation

@node pkgname, repology, pkgbase, Keys
@subsection pkgname
This is what Pacstall records as the name of the built package. Use the following naming schema:

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

@quotation Important
The package suffix (@samp{-deb}, @samp{-git}, etc) must match the filename of the pacscript. If @code{pkgname="foo-deb"}, the file must be named @file{foo-deb.pacscript}. If there is no suffix, the file should be named @file{foo.pacscript}.
@end quotation

@node repology, arch, pkgname, Keys
@subsection repology
This is what @url{https://github.com/pacstall/pacup, Pacup} uses to get the latest version of your packaged program for updating the pacscript. @xref{Top,,, pacup, The Pacup Manual} 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.

@node arch, pkgver, repology, Sample Script
@subsection arch
This array is used to define what architectures your pacscripts will work on. Besides the usual architecture specifiers, you have available @samp{any} and @samp{all}:

@multitable @columnfractions 0.1 0.9
@headitem Name @tab Function

@item @samp{any} @tab Package can be compiled on @emph{any} system, but will only run on the compiled architecture (compiled programs)
@item @samp{all} @tab Package can run on @emph{all} systems, regardless of architecture (scripts usually)
@end multitable

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

Pacstall supports all architectures that have an @url{https://www.debian.org/ports/, official Debian port}. These are currently:

@itemize
@item @samp{amd64}/@samp{x86_64}
@item @samp{arm64}/@samp{aarch64}
@item @samp{armel}/@samp{arm}
@item @samp{armhf}/@samp{armv7h}
@item @samp{i386}/@samp{i686}
@item @samp{mps64el}
@item @samp{ppc64el}
@item @samp{riscv64}
@item @samp{s390x}
@end itemize

@quotation Important
While both @samp{$CARCH} and @samp{$AARCH} will always be accessible to a pacscript, only one naming scheme may be used in the arch array. This means you cannot mix and match, like @code{arch=('amd64' 'i686')} or @code{arch=('arm64' 'aarch64')}. The naming scheme used will determine which enhanced arrays will be available. @xref{source} for more on enhanced arrays.
@end quotation

@node pkgver, pkgrel, arch, Keys
@subsection pkgver
This is the version number. It should ideally (but not required) be using @url{https://semver.org/, semver}. As long as the version number can be handled by @code{dpkg --validate-version}, it is valid.

@node pkgrel, epoch, pkgver, Keys
@subsection pkgrel
This is used when you wish to trigger an update on users computers but @ref{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 @samp{1} if not included, and should not be included by default. Every time pkgver is updated, @samp{pkgrel} should be removed.

@node epoch, url, pkgrel, Keys
@subsection epoch
This variable is used to forcibly upgrade a package in any circumstance. In most cases, a @samp{pkgrel} bump will work just fine, but certain circumstances may require an upgrade that breaks @url{https://wiki.archlinux.org/title/PKGBUILD#epoch, normal comparison logic}. It is assumed to be @samp{0} @url{https://www.debian.org/doc/debian-policy/ch-controlfields.html#version, by default}, and if used, should be a small integer.

@quotation Caution
Use this @emph{sparingly}, as any package using @samp{epoch} cannot remove the @samp{epoch} on the next @samp{pkgver} update.
@end quotation

@node url, incompatible, epoch, Keys
@subsection url
This variable is used to show the homepage/website of the package (if any).

@node incompatible, compatible, url, Keys
@subsection 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 @samp{$distro:$version}, where either @samp{$distro} or @samp{$version} can be a glob character (@samp{*}), but not both. @samp{$version} can be a distro name (@samp{jammy}, @samp{noble}, @samp{sid}, etc) or a version number (@samp{22.04}, @samp{16.04}, etc).

@node compatible, pkgdesc, incompatible, Keys
@subsection compatible
Allowed distros/versions that a package can build on. @xref{incompatible} for more information.

@node pkgdesc, license, compatible, Keys
@subsection 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:

@example
pkgdesc="Short and Sweet"
@end example

@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."
@end example

@node license, maintainer, pkgdesc, Keys
@subsection license
An array of licenses that this package is licensed under. Valid licenses are listed in @url{https://spdx.org/licenses/, SPDX}. Custom licenses can be included with the prefix @samp{custom:}.

@node maintainer, source, license, Keys
@subsection 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:

@example
"my name <email here>"
@end example

@node source, sums, maintainer, Keys
@subsection source
This is an array with URLs as elements. These will be downloaded by pacstall before the @ref{prepare()} function. @ref{source} can be created many different ways, and is incredibly powerful in functionality.

Inside a @samp{source} array, you have the following schema:

@itemize
@item Elements can be optionally prefixed with @samp{dest::} which will instruct pacstall to download (or copy) that archive to the name @samp{dest}.

@itemize @minus
@item Note that @samp{dest} is @strong{not} where the final @emph{extracted} output of a download would be, but where the @emph{download} is going to.
@end itemize

@item Git sources must have their URL prefixed with @samp{git+} if the URL does not end with @file{.git}.
@item Git sources may end in @samp{#branch=}, @samp{#tag=}, or @samp{#commit=}, followed by their respective contents.

@itemize @minus
@item If this is not provided, then it is assumed to clone from @samp{HEAD} of the repository. This is often the @samp{master} or @samp{main} branch.
@end itemize

@item To use sources relative in location to the pacscript, there are two main options:

@itemize @minus
@item Use @samp{file://} for installing local archives relative to the pacscript. Generally will look like @samp{file://$@{PWD@}/example.zip} or @samp{file:///home/pacstall/example.zip}.

@item For installing files relative to the pacscript from the @samp{pacstall-programs} repository, list the file plainly, like @samp{"example.desktop"}. The file should be stored in the same folder as the pacscript, in @samp{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.
@end itemize

@item Deb sources can only be provided one entry. More complex array options are described below.

@end itemize

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

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

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

@itemize
@item @samp{*.zip}
@item @samp{*.tar.gz}/@samp{*.tgz}
@item @samp{*.tar.bz2}/@samp{*.tbz2}
@item @samp{*.tar.bz}/@samp{*.tbz}
@item @samp{*.tar.zst}/@samp{*.tzst}
@item @samp{*.gz}
@item @samp{*.bz2}
@item @samp{*.xz}
@item @samp{*.lz}
@item @samp{*.lzma}
@item @samp{*.zst}
@item @samp{*.7z}
@item @samp{*.rar}
@item @samp{*.lz4}
@item @samp{*.tar}
@end itemize

If using an archive that contains a @samp{*.tar.*} extension that is not covered by any of the above listed, pacstall will attempt to extract it with the regular @samp{*.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, @ref{noextract}.

You may define architecture specific sources like @samp{source_$arch}, and you can define distro sources like @samp{source_$DISTRO}, where @samp{$DISTRO} can be either @samp{ubuntu} or @samp{debian}, or a codename of a release, such as @samp{jammy} or @samp{bookworm}. If you want to combine both a distro and architecture, you may do @samp{source_$@{DISTRO@}_$@{arch@}}. A CI maintained file in @url{@value{GITHUBREPOURL}/blob/master/distrolist, @value{SHORTHANDREPO}} 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:

@multitable @columnfractions .25 .39
@headitem Order @tab Array
@item Least specific @tab @samp{source}
@item @tab @samp{source_$arch}
@item @tab @samp{source_$distrobase}
@item @tab @samp{source_$distrorel}
@item @tab @samp{source_$@{distrobase@}_$arch}
@item Most specific @tab @samp{source_$@{distrorel@}_$arch}
@end multitable

@quotation Important
@samp{-deb} packages can only use one source entry. Use the enhanced arrays to provide for multiple targets. For @samp{-deb} packages, enhanced @samp{source} and @ref{sums} arrays will override instead of append. This is not the case for the other enhanced arrays.
@end quotation

@node sums, nosubmodules, source, Keys
@subsection sums
These sets of arrays are used in relation to @samp{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:

@enumerate
@item @samp{sha256sums}
@item @samp{sha512sums}
@item @samp{sha384sums}
@item @samp{sha224sums}
@item @samp{sha1sums}
@item @samp{md5sums}
@item @samp{b2sums}
@end enumerate

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

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

@node nosubmodules, noextract, sums, Keys
@subsection nosubmodules
Use this array to prevent pacstall from cloning submodules for any source array with @samp{dest} where @samp{dest} is included in this array. For example:

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

@node noextract, backup, nosubmodules, Keys
@subsection noextract
Use this array like you would with @ref{nosubmodules} except this is for when you do not want a source to be extracted.

@node backup, external_connection, noextract, Keys
@subsection backup
In @code{dpkg}, files in @file{/etc} are set as "configuration files", meaning that by default they will not be removed when one runs apt remove pkg, but will with @code{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 @file{/etc}, as that is already handled by @code{dpkg}.

There is one special exception you may add to a key, and that is a leading @samp{r:}, which instructs @code{dpkg} to delete that file on the next upgrade (generally used for outdated config files). If you include @samp{r:} in a key, that file @emph{cannot} appear in the binary package.

@node external_connection, depends, backup, Keys
@subsection external_connection
@c TODO: PACKAGING FUNCTIONS
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 @code{cargo} builds, certain @code{python} builds, and occasionally making a git connection), the variable @code{external_connection=true} must be provided. By default, this is not included, and is assumed @code{false}.

@node depends, makedepends, external_connection, Keys
@subsection depends
This is an array used to declare runtime dependencies of a package. As with @ref{source}, this array can be enhanced by @samp{$arch} and/or @samp{$DISTRO}. Along with that, you can @emph{also} add version constraints, which take the following schema:

@enumerate

@item Any dependency can optionally have the following format:

@enumerate
@item @samp{pkg>=version}
@item @samp{pkg<=version}
@item @samp{pkg>version}
@item @samp{pkg<version}
@item @samp{pkg=version}
@end enumerate

@item
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: @samp{pkg | pkg2}. These constraints apply to all dependency arrays, with the exception of @ref{pacdeps}.

@end enumerate

@node makedepends, checkdepends, depends, Keys
@subsection makedepends
This is an array used to declare build-time dependencies. Everything from @ref{depends} apply here.

@node checkdepends, optdepends, makedepends, Keys
@subsection checkdepends
This is an array used to declare dependencies needed for testing in the @ref{check()} function. These are installed at the same time as @ref{makedepends}. Everything from @ref{depends} apply here.

@node optdepends, pacdeps, checkdepends, Keys
@subsection optdepends
This is an array used to declare optional dependencies. Everything from @ref{depends} apply here, with one addition, that being the requirement of a description, which takes the form of @samp{pkg: description here}. Remember that @samp{pkg} in this case can take any version constraint, including an alternative, so this is valid:

@example
"libidk:i386<5.2.3 | libidk:i386>1.2.5: provides libidk support"
@end example

If at build time the user decides not to install a package in @samp{optdepends}, it will be logged as @url{https://www.debian.org/doc/debian-policy/ch-relationships.html#binary-dependencies-depends-recommends-suggests-enhances-pre-depends, Suggests}.

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

@node breaks, conflicts, pacdeps, Keys
@subsection breaks
This is an array that declares packages that cannot be installed alongside this package. Any package declared in @ref{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 @emph{not} have file path conflicts.

This array can be enhanced by @samp{$arch} and/or @samp{$DISTRO}.

@node conflicts, makeconflicts, breaks, Keys
@subsection conflicts
This is an array similar to @ref{breaks}, except it declares that packages @emph{cannot} be unpacked at the same time, likely due to having files in the same locations.

This array can be enhanced by @samp{$arch} and/or @samp{$DISTRO}.

@node makeconflicts, checkconflicts, conflicts, Keys
@subsection 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 @samp{$arch} and/or @samp{$DISTRO}.

@node checkconflicts, replaces, makedepends, Keys
@subsection checkconflicts
This is an array used to declare packages that cannot be installed on the system for testing in the @ref{check()} function, usually because of a package conflict with a check dependency.

This array can be enhanced by @samp{$arch} and/or @samp{$DISTRO}.

@node replaces, provides, checkconflicts, Keys
@subsection replaces
This is an array that declares packages that has files @url{https://www.debian.org/doc/debian-policy/ch-relationships#overwriting-files-in-other-packages, that can be overwritten by this package}. This functionality is available only in conjunction with @ref{breaks}.

This array can be enhanced by @samp{$arch} and/or @samp{$DISTRO}.

@node provides, recommends, replaces, Keys
@subsection provides
A list of packages that this package can satisfy as a dependency. For instance, the package @samp{foobar-plus} could satisfy @samp{foobar}, so you would have this:

@example
provides=("foobar")
@end example

This array can be enhanced by @samp{$arch} and/or @samp{$DISTRO}.

@node recommends, suggests, provides, Keys
@subsection 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 @ref{depends}.

This array can be enhanced by @samp{$arch} and/or @samp{$DISTRO}.

@node suggests, enhances, recommends, Keys
@subsection 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 @ref{optdepends}, as optdepends that are installed on the system are marked as @ref{depends}.

This array can be enhanced by @samp{$arch} and/or @samp{$DISTRO}.

@node enhances, gives, suggests, Keys
@subsection enhances
A list of packages that this package can satisfy as a suggested package or recommended package. For instance, if the package @samp{foobar} recommends @samp{foobar-extras}, in @samp{foobar-extras} you would have:

@example
enhances=("foobar")
@end example

This array can be enhanced by @samp{$arch} and/or @samp{$DISTRO}.

@node gives, priority, enhances, Keys
@subsection gives
This variable is used generally in conjunction with @ref{pkgname}, in which @samp{gives} will override the name that the package will take. General examples look like:

@example
pkgname="foo-git"
gives="foo"
@end example

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

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

@multitable @columnfractions .25 .38
@headitem Order @tab Variable
@item Least specific
@tab @samp{gives}
@item @tab @samp{gives_$arch}
@item @tab @samp{gives_$distrobase}
@item @tab @samp{gives_$distrorel}
@item @tab @samp{gives_$@{distrobase@}_$arch}
@item Most specific @tab @samp{gives_$@{distrorel@}_$arch}
@end multitable

@node priority, mask, gives, Keys
@subsection priority
Sets the @url{https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities, priority} of a package. It can have the following values if included:

@enumerate
@item @samp{essential}
@item @samp{required}
@item @samp{important}
@item @samp{standard}
@item @samp{optional} (default)

@end enumerate

@quotation Caution
Do not include @samp{priority} unless you know what you're attempting to do.
@end quotation

@node mask, prepare(), priority, Keys
@subsection mask
An array containing @code{apt} or @code{pacstall} package names. Once this package is installed, anything inside @samp{mask} will be prevented from showing up in @code{apt} and @code{pacstall} search results, or anything relating to @code{dpkg}. Once the package is removed, the effect reverses and @samp{mask} contents will be visible again.

@quotation Caution
Do not use @samp{mask} unless you know what you're doing.
@end quotation

@node prepare(), build(), mask, Keys
@subsection prepare()
This function is run to prepare a package for building. The starting location will always be @samp{$@{srcdir@}}.

@node build(), check(), prepare(), Keys
@subsection build()
This function is run to compile/build a package. Use multicore building whenever possible. You get get the amount of cores with the variable @samp{$@{NCPU@}}. The starting location will always be @samp{$@{srcdir@}}.

@node check(), package(), build(), Keys
@subsection check()
This function is run to run sanity checks on packages, typically coming from the projects testing suite. The starting location will always be @samp{$@{srcdir@}}.

@node package(), pre_remove(), check(), Keys
@subsection package()
This function is used to install the package to its staging area. The most important part of this function is to install to @samp{$@{pkgdir@}}. Check your build system for how to install to a certain root directory. The starting location will always be @samp{$@{srcdir@}}.

@node pre_remove(), , package(), Keys
@subsection pre_remove()
This function is run before the a package is removed. It is the @url{https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html, Debian prerm script}.

@node pre_install(), pre_upgrade(), pre_remove(), Keys
@subsection pre_install()
This function is run before the deb unpacks onto the system. It is the Debian @samp{preinst} script.

@node pre_upgrade(), post_remove(), pre_install(), Keys
@subsection pre_upgrade()
This function works just like @ref{pre_install()}, but runs instead if the package is already on the system. If @samp{pre_install()} is provided but not @ref{pre_upgrade()}, then @samp{pre_install()} runs as pre_upgrade. If only @samp{pre_upgrade()} is provided, then it will not run on initial install, but will on every upgrade after.

@node post_remove(), post_install(), pre_upgrade(), Keys
@subsection post_remove()
This function is run after the package is removed. It is the Debian @samp{postrm} script.

@node post_install(), post_upgrade(), post_remove(), Keys
@subsection post_install()
This function is run after the package is installed. It is the Debian @samp{postinst} script.

@node post_upgrade(), , post_install(), Keys
@subsection post_upgrade()
This function is run after a package upgrade. The same rules from @ref{pre_upgrade()} and @ref{pre_install()} apply for @samp{post_upgrade()} and @ref{post_install()}.