The PKGFILE is the essence of Aati's packaging system, as it describes to Aati how to install and uninstall software through it. The PKGFILE is separated into two required TOML-like looking fields, [installation] and [removal]. Three optional ones are [win-installation] and [win-removal] that are meant for packages directing the any global target having Windows-specific installation instructions, and lastly [data] for declaring variables available throughout the PKGFILE. [data] is significant for declaring name and version variables in case your package is PKGFILE-only installable, unlike being hosted on an Aati Package Repository. If a Windows machine can't find the Windows-specific section it's gonna fallback to the default section, whether for installation or removal.



When Aati installs a package, it looks for the commands under the [installation] field. Commands under the [installation] field are ran knowing the current working directory, that is somewhere under the operating system's temporary directory, unlike commands under the [removal] field, which are ran without context at all. We'll get to this later in more detail.

Now, you may be wondering: "What are those commands that Aati can execute from the PKGFILE?"
Well, those commands currently are:

  • install: copies a file to a destination and (if it's a UNIX operating system) makes it an executable, e.g. install program $bin_dir/program
  • copy: copies a file to a destination only, e.g. copy lib.so $lib_dir/lib.so
  • system: invokes a system command, sh -c on UNIX and cmd /C on Windows, e.g. system curl https://picsum.photos/400 -Lo image.jpeg would download a random image to image.jpeg
  • delete: deletes a file from the system, e.g. delete $bin_dir/program

The PKGFILE also recognises a few global variables, which are currently limited to:

  • $bin_dir: directory for binary executables, that is .aati/bin under the user's home directory.
  • $lib_dir: directory for DLLs, that is .aati/lib under the user's home directory.
  • $home_dir: user home directory, ~ or $HOME for UNIX and %HOMEPATH% for Windows.

An Example of a PKGFILE summing up all of what we said above can be:

# Aati executes this section first while acknowledging the current
# working directory, this is why we can easily refer to files
# here using relative paths (i.e. application, library.so, image.jpeg)
install application $bin_dir/application
copy library.so $lib_dir/lib.so
system wget https://picsum.photos/400 -O image.jpeg
copy image.jpeg $home_dir/image.jpeg

# If Aati is running on a Windows system, Aati would prefer executing this
# section instead. If it was not found, however, it would fallback to the
# section above and execute it since it's the default
install application.exe $bin_dir/application.exe
copy library.dll $lib_dir/lib.dll
system curl https://picsum.photos/400 -Lo image.jpeg
copy image.jpeg $home_dir/image.jpeg

# Here there's no current working directory involved
# so all the commands in this section can't make use of it
delete $bin_dir/application
delete $lib_dir/lib.so
delete $home_dir/image.jpeg

# Same thing here: Unix systems won't care about this section
# Windows systems however will prefer running this over the
# default section, if it exists, like in this case
delete $bin_dir/application.exe
delete $lib_dir/lib.dll
delete $home_dir/image.jpeg

An Example of a PKGFILE-only installable package that downloads and installs Aati v0.1.0:

# Everything under this section is going to be a global variable
# throughout the PKGFILE. $name and $version are needed by Aati in case
# someone is installing this package from a PKGFILE only and not from
# a package archive (.tar.lz4-ending files) or an aati package repository.
# if they're not provided then the user will have to provide the name and
# the version as a command line argument.
name aati-old
version 0.1.0

repo_name aati
bin_name aati-old

system curl https://github.com/hharas/$repo_name/archive/refs/tags/v$version.tar.gz -Lo $repo_name.tar.gz
system tar -xzvf $repo_name.tar.gz
system cargo build --release --manifest-path $repo_name-$version/Cargo.toml
install $repo_name-$version/target/release/$repo_name $bin_dir/$bin_name
system rm -rf $repo_name.tar.gz $repo_name-$version

delete $bin_dir/$bin_name

About this wiki

commit 81dcbc29cc43b12700c0aee922ddc071579cbb59
Author: Husayn Haras <haras@disroot.org>
Date:   2023-11-25T17:52:58+03:00

better way of saying 'or'
Clone this wiki
https://git.sr.ht/~haras/aati-wiki (read-only)
git@git.sr.ht:~haras/aati-wiki (read/write)