~haras/aati

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.

[installation]
...

[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:

[installation]
# 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

[win-installation]
# 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

[removal]
# 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

[win-removal]
# 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:

[data]
# 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

[installation]
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

[removal]
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)