\input texinfo
@settitle Aura
@dircategory Arch Linux
@direntry
* Aura: (aura).  A package manager for Arch Linux and the AUR.
@end direntry
@paragraphindent 0

@copying
Aura - A package manager for Arch Linux and the AUR.

Copyright @copyright{} 2012 - 2024 Colin Woodbury

@quotation
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
@end quotation
@end copying

@titlepage
@title Aura User Guide
@page
@vskip 0pt plus 1fill
@insertcopying
@end titlepage

@contents

@node Top
@top Aura User Guide

Aura 4.0.0 by Colin Woodbury and contributors, 2012 - 2024

Aura helps you install and manage software on your system. It provides
all the functionality that @code{pacman} does, plus more, including
system sanity checks, package analysis, and automated AUR package
installation.

If you opened this manual on the command line via @code{info aura}, you
can navigate it as follows:

@itemize @bullet
@item g: Jump to a manual page. Supports TAB completion.
@item i: Jump to an entry in the Index. Supports TAB completion.
@item m: Select a menu item. Supports TAB completion.
@item [: Go to the next page.
@item ]: Go to the previous page.
@item u: Jump up one level.
@item t: Jump to the top of the manual.
@item H: View more @code{info} command help.
@end itemize

If you're reading this in Emacs, then your bindings may be different
from the above.

@menu
* Philosophy::     Guiding principles for Aura's development.
* Installation::   Installing Aura from the AUR.
* Usage::          All Aura commands.
* Configuration::  Customising runtime behaviour.
* Appendix::       Localisation Guide, FAQs, etc.
* Index::          All available topics.
@end menu

@node Philosophy
@chapter Philosophy
@cindex Guiding principles for Aura's development @subentry philosophy

The Aura project began in 2012 as an answer to the shortcomings of
programs often called @emph{AUR helpers}. Certain ground rules were set
in the beginning to guide development. They are:

@heading Aura is Pacman

Aura doesn't just mimic @code{pacman}; it @strong{is} @code{pacman}. All
@code{pacman} operations and their sub-options are accepted, as-is.

@heading Arch is Arch - AUR is AUR

Aura does not augment or alter Pacman's commands in any way.

@code{-S} yields repository packages and @emph{only} those. In Aura, the
@code{-A} operation is introduced for obtaining AUR packages. @code{-A}
comes with sub-options you're used to (@code{-u}, @code{-s}, @code{-i},
etc.) and adds new ones to enhance AUR interaction.

@heading Downgradibility

Aura allows you to downgrade individual packages to previous versions
with @code{-C}. It also handles snapshots of your entire system, so that
you can roll back whole sets of packages when problems arise. The option
@code{-B} will save a package state, and @code{-Br} will restore a state
you select. @code{-Au} also invokes a save automatically.

@heading Independence

Aura has its own configuration file, its own local package cache, and
its own @url{https://github.com/fosskers/faur, Metadata Server} called
the Faur. The Faur in particular helps reduce traffic to the main AUR
server and allows us to provide unique package lookup schemes not
otherwise available.

@heading Multilingualism

English is the dominant language of computing and the internet. That
said, it's natural that some people are going to be more comfortable
working in their native language. From the beginning, Aura has been
built with multiple-language support in mind, making it very easy to add
new ones via the @url{https://projectfluent.org/,,Project Fluent}
format.

@node Installation
@chapter Installation
@cindex Installing Aura

Aura is software specific to @url{https://www.archlinux.org/,,Arch
Linux}. It should also work on Arch-derivatives like
@url{https://manjaro.org/, Manjaro}, but would not be useful on any
other Linux distribution.

There are several @code{aura} packages available. Aura was originally
written in Haskell, but a port to Rust was released in 2024 as the
@code{4.x} series.

@node From the AUR
@section From the AUR
@cindex Installing Aura from the AUR

@heading The Tagged Release

The recommended package is simply named @code{aura}. It uses
@code{cargo} to build a fresh binary on your machine, based on releases
made to Rust's crates.io.

@example
git clone https://aur.archlinux.org/aura.git
cd aura
makepkg -s
sudo pacman -U <the-package-file-that-makepkg-produces>
@end example

@heading The git-based Build

If instead you'd like to directly track updates to Aura's @code{master}
branch, install the git variant:

@example
git clone https://aur.archlinux.org/aura-git.git
cd aura-git
makepkg -s
sudo pacman -U <the-package-file-that-makepkg-produces>
@end example

@heading The Prebuilt Binary

Finally, if you don't wish to build Aura yourself or want to avoid any
trace of Rust tooling on your machine, there is a prebuilt binary of
Aura for @code{x86_64} machines:

@example
git clone https://aur.archlinux.org/aura-bin.git
cd aura-bin
makepkg -s
sudo pacman -U <the-package-file-that-makepkg-produces>
@end example

@node Building from Source
@section Building from Source
@cindex Building Aura yourself

If you already have Rust tooling installed on your machine and/or wish
to help develop Aura, you can also install it manually:

@example
git clone https://github.com/fosskers/aura.git
cd aura/rust
cargo install --path aura-pm
@end example

This will build and install the binary to @code{/home/YOU/.cargo/bin/}.

Keep in mind that this variant of Aura won't be tracked in Pacman's
database, and so it will be easier to miss updates. It also does not
install completions or other documentation files like manpages.

@node Post-installation
@section Post-installation
@cindex Post-installation

The first thing you should do is run @code{check}:

@example
aura check
@end example

This will scan your system for irregularities and suggest fixes. Second,
you should generate an Aura config file:

@example
aura conf --gen > ~/.config/aura/config.toml
@end example

Consider setting the @code{language} field here, if you wish to use Aura
in a language other than English. The available language codes are
viewable via:

@example
aura stats --lang
@end example

Aura will also automatically detect your locale via @code{LANG}, so you
only need to set @code{language} if you want a custom combination of
system language and Aura language.

@node Usage
@chapter Usage

@quotation
@strong{Attention}: As of the 4.x series, @code{sudo} is no longer
necessary when running Aura. When escalated privileges are required,
Aura will automatically prompt you.
@end quotation

@node Basics
@section Basics
@cindex Basic Usage

@heading Pacman Commands
@cindex Simple Pacman Commands

First and foremost, Aura is compatible with @code{pacman}. This gives us
access to the following commands:

@itemize @bullet
@item
@code{-S}: Search and install official packages.

@example
> aura -S firefox
@end example

@item
@code{-Q}: Query the database of installed packages.

@example
> aura -Qi firefox
Name            : firefox
Version         : 127.0.2-1
Description     : Fast, Private & Safe Web Browser
... etc ...
@end example

@item
@code{-R}: Remove installed packages.

@example
> aura -R firefox
@end example

@item
@code{-U}: Install a manually built package.

@example
> makepkg
... building ...
> aura -U aura-4.0.0-1-x86_64.pkg.tar.xz
@end example

@item
@code{-D}: Interact with Pacman's database directly.

@example
> aura -Dk
No database errors have been found!
@end example

@item
@code{-F}: Make queries regarding files owned by packages.

@example
> aura -Fl firefox
firefox usr/
firefox usr/bin/
firefox usr/bin/firefox
firefox usr/lib/
firefox usr/lib/firefox/
firefox usr/lib/firefox/Throbber-small.gif
firefox usr/lib/firefox/application.ini
... etc ...
@end example

@item
@code{-T}: Check if a dependency is satisfied.

@example
> aura -T firefox "qt>100"
qt>100
@end example
@end itemize

See @ref{Aura-as-Pacman} for a list of common Pacman idioms.

@heading Aura Commands
@cindex Simple Aura Commands

Aura also provides a number of new commands.

@itemize @bullet
@item
@code{-A}: Search and install packages from the AUR.

@example
> aura -A qlot
@end example

@ref{Installing AUR Packages}.

@item
@code{-B}: Create and restore snapshots of installed packages.

@example
> aura -B
aura :: Saved package state.
@end example

@ref{Package Set Snapshots}.

@item
@code{-C}: Downgrade installed packages.

@example
> aura -C qlot
aura :: What version of qlot do you want?
 0) 1.5.6-1
 1) 1.5.1-1
>>
@end example

@ref{Cache Handling and Downgrading}.

@item
@code{-L}: Search and inspect the ALPM log.

@example
> aura -Li firefox
Name           : firefox
First Install  : 2016-05-03 08:46
Upgrades       : 176
Recent Actions :
[2024-02-24T07:29:46+0900] [ALPM] upgraded firefox (122.0.1-1 -> 123.0-1)
[2024-03-11T16:42:37+0900] [ALPM] upgraded firefox (123.0-1 -> 123.0.1-1)
[2024-03-24T15:03:33+0900] [ALPM] upgraded firefox (123.0.1-1 -> 124.0.1-1)
@end example

@ref{Log Interaction}.

@item
@code{-O}: Handle "orphans" - dependencies whose parent package is no
  longer installed.

@example
> aura -O
asar 3.2.8-1
@end example

@ref{Managing Orphan Packages}.

@item
@code{check}: Validate your system.

@example
> aura check
aura :: Validating your system.
aura :: Environment
  [✓] locale -a contains LANG value? (en_US.UTF-8)
  [✓] Aura is localised to your LANG?
  [✓] EDITOR variable set?
  [✓] EDITOR value (emacs) is executable?
  [✓] Java environment set?
... etc. ...
@end example

@item
@code{conf}: Inspect or generate Aura configuration.

@example
> aura conf --gen > ~/.config/aura/config.toml
@end example

@ref{Configuration}.

@item
@code{deps}: View the dependency graph of given packages.

@example
> aura deps gcc --reverse --optional --limit=3 --open
@end example

@ref{Dependency Analysis}.

@item
@code{free}: List installed packages with potentially non-free software
licenses.

@example
> aura free
adobe-source-code-pro-fonts: custom
aspell-en: custom
blas: custom
boost: custom
boost-libs: custom
cantarell-fonts: custom:SIL
... etc. ...
@end example

@item
@code{stats}: View statistics about your machine and Aura itself.

@example
> aura stats
Host                 : yumi
User                 : colin
Distribution         : Arch Linux
Editor               : emacs
Installed packages   : 1144
Pacman Package Cache : 7.05GiB
Aura Package Cache   : 1.29GiB
Aura Build Cache     : 6.49GiB
/tmp Directory       : 11.31MiB
@end example

@item
@code{thanks}: Credit to the Pacman team, Aura's authors, and Aura's
translators.

@end itemize

@node Aura-as-Pacman
@section Aura-as-Pacman
@cindex Aura as a drop-in replacement for Pacman

@code{aura} can be used in place of @code{pacman} in all situations. At
the very least, this is two fewer letters to type!

Below are some common @code{pacman} idioms for managing your system. The
list is a handy reference but not exhaustive. For everything that
@code{pacman} is capable of, see @code{man pacman}.

To find out how to use Aura to interact with the AUR, see
@ref{Installing AUR Packages}.

@node Installing and updating official packages
@subsection Installing and updating official packages
@cindex -S, -U, Installing and updating official packages

@quotation
Note: Unlike with @code{pacman}, prefixing with @code{sudo} is not
necessary for "admin" actions. Aura knows when @code{sudo} is necessary
and will prompt you.
@end quotation

Install an official package:

@example
aura -S firefox
@end example

Update all official packages:

@example
aura -Syu
@end example

Install a package built with @code{makepkg}:

@example
aura -U foobar-1.2.3-1-x86_64.pkg.tar.xz
@end example

@node Removing Packages
@subsection Removing Packages
@cindex -R, Removing Packages

The package and all unneeded dependencies:

@example
aura -Rsu firefox
@end example

The package and everything that depends on it:

@example
aura -Rcu firefox
@end example

@node Querying your System
@subsection Querying your System
@cindex -Q, Querying your System

Searching an exact package:

@example
aura -Qi firefox
@end example

Searching a local package by description:

@example
> aura -Qs browser
local/firefox 127.0.2-1
    Fast, Private & Safe Web Browser
local/mathjax 3.2.2-1
    An open source JavaScript display engine for mathematics that works in all modern browsers
local/qt6-webengine 6.7.2-1 (qt6)
    Provides support for web applications using the Chromium browser project
@end example

Producing a list of installed packages:

@example
> aura -Q
aalib 1.4rc5-18
abcl 1.9.2-1
abseil-cpp 20240116.2-2
acl 2.3.2-1
... etc ...
@end example

@cindex Print the package which owns a given file
Discovering what package owns a certain file:

@example
> aura -Qo firefox
/usr/bin/firefox is owned by firefox 127.0.2-1
@end example

@cindex List all files owned by a package
Discovering which files are brought in by a package:

@example
> aura -Ql firefox
firefox /usr/
firefox /usr/bin/
firefox /usr/bin/firefox
firefox /usr/lib/
firefox /usr/lib/firefox/
firefox /usr/lib/firefox/Throbber-small.gif
firefox /usr/lib/firefox/application.ini
... etc ...
@end example

You can use @code{grep} to filter what you're looking for:

@example
> aura -Ql firefox | grep bin
firefox /usr/bin/
firefox /usr/bin/firefox
firefox /usr/lib/firefox/firefox-bin
@end example

@cindex Listing foreign packages
Listing all installed "foreign" packages:

@example
> aura -Qm
abcl 1.9.2-1
anki 2.1.66-1
babashka-bin 1.3.191-1
bashate 2.1.1-1
ccextractor 0.94-3
ccl 1.12.2-4
... etc ...
@end example

@node Clearing your Package Cache
@subsection Clearing your Package Cache

Pacman stores its built packages in @code{/var/cache/pacman/pkg/}. This
directory can grow quite large, but the following commands can help
selectively clear it.

@quotation
@strong{Tip}: The Aura command @code{-Cc} offers additional control over
clearing the cache, and targets Aura's cache as well.
@end quotation

Removing the tarballs of uninstalled packages:

@example
aura -Sc
@end example

Removing *all* tarballs:

@example
aura -Scc
@end example

@node Installing AUR Packages
@section Installing AUR Packages
@cindex Installing AUR Packages

Let's walk through the full process of installing an AUR package. This
will show us how to discover packages, install them, and upgrade them.

@quotation
@strong{Tip}: Just want to update all your AUR packages? Aura's author
uses @code{aura -Au}. Remember, no need to call @code{sudo} yourself.
@end quotation

@quotation
@strong{Tip}: For the full list of all options with detailed
descriptions, see @code{aura -Ah}.
@end quotation

@node Example Installation Process
@subsection Example Installation Process

The general order is search, confirm, install.

@node Searching for an AUR Package
@subsubsection Searching for an AUR Package
@cindex -As, Searching for an AUR Package

Let's say we want to install a package that can render @code{.md} README
files for us. First, we search the AUR for candidates:

@example
> aura -As readme
aur/python-grip 4.6.1-1 (22 | 0.00)
    Preview GitHub Markdown files like Readme locally before committing them
aur/python-grip-git 4.5.2-1 (15 | 0.00)
    Preview GitHub Markdown files like Readme locally before committing them.
aur/ruby-github-markup 4.0.2-1 (4 | 0.00)
    The code GitHub uses to render README.markup
aur/k810-conf 0.1-9 (3 | 0.00)
    Logitech K810 Keyboard Configurator, change function keys (F-keys) behavior. Read USAGE at https://aur.archlinux.org/cgit/aur.git/tree/README.md?h=k810-conf
aur/cargo-readme 3.3.1-1 (3 | 0.24)
    A cargo subcommand to generate README.md content from doc comments
... etc ...
@end example

By default, results are ordered by their vote count. If @code{-As}
filled the screen and we only wish to see a few results, we can filter
with @code{--limit}:

@example
> aura -As readme --limit 3
aur/python-grip 4.6.1-1 (22 | 0.00)
    Preview GitHub Markdown files like Readme locally before committing them
aur/python-grip-git 4.5.2-1 (15 | 0.00)
    Preview GitHub Markdown files like Readme locally before committing them.
aur/ruby-github-markup 4.0.2-1 (4 | 0.00)
    The code GitHub uses to render README.markup
@end example

@code{--abc} can be used to sort alphabetically instead.

@node Scrutinizing a Package
@subsubsection Scrutinizing a Package
@cindex -Ai, -Ap, Scrutinizing a Package

Alright, @code{python-grip} looks good. Let's take a closer look...

@example
> aura -Ai python-grip
Repository    : aur
Name          : python-grip
Version       : 4.6.1-1
AUR Status    : Up to Date
Maintainer    : pancho
Project URL   : https://github.com/joeyespo/grip
AUR URL       : https://aur.archlinux.org/packages/python-grip
License       : MIT
Groups        :
Provides      :
Depends On    : python python-docopt python-flask python-markdown python-path-and-address python-pygments python-requests
Make Deps     : python-setuptools
Optional Deps :
Check Deps    :
Votes         : 22
Popularity    : 0.00
Description   : Preview GitHub Markdown files like Readme locally before committing them
Keywords      :
Submitted     : 2017-02-09
Updated       : 2022-04-17
@end example

Does the PKGBUILD look alright?

@example
> aura -Ap python-grip
# Maintainer: pancho horrillo <pancho at pancho dot name>
# Contributor: Clayton Craft <clayton at craftyguy dot net>

pkgname=python-grip
pkgver=4.6.1
pkgrel=1
pkgdesc="Preview GitHub Markdown files like Readme locally before committing them"
arch=('any')
license=('MIT')
url="https://github.com/joeyespo/grip"
depends=('python' 'python-docopt' 'python-flask' 'python-markdown'
         'python-path-and-address' 'python-pygments' 'python-requests')
makedepends=('python-setuptools')
source=("$pkgname-$pkgver.tar.gz::https://github.com/joeyespo/grip/archive/v$pkgver.tar.gz")
sha256sums=('6bc3883f63395c566101187bc1f1d103641c99913b7122f942d56e108e649d83')

package() @{
  cd grip-$pkgver
  python setup.py install --root="$pkgdir" --optimize=1
  install -Dm644 LICENSE "$pkgdir"/usr/share/licenses/$pkgname/LICENSE
@}
@end example

Nothing nefarious here.

@quotation
@strong{Tip}: It's important to confirm the content of the PKGBUILD like
this, as these are raw Bash commands that will be executed on your
system during the build process.
@end quotation

@node A Normal Install
@subsubsection A Normal Install
@cindex -A, A normal installation

We're confident that this is a safe package to build, so we do:

@example
> aura -A python-grip
aura :: Determining dependencies...
aura :: Repository dependencies:
 python-docopt
aura :: AUR packages:
 python-grip
 python-path-and-address
aura :: Proceed? [Y/n]

... pacman output ...

aura :: Preparing build directories...
aura :: Building python-path-and-address...

... makepkg output ...

aura :: Done.
@end example

A few things to note:

@itemize @bullet
@item
@code{python-grip} has both official and AUR dependencies. These have to
be built and installed in a specific order for @code{python-grip} to even
build.
@item
Under the hood, Aura calls @code{makepkg} to drive the build and @code{pacman} to
finalise the installation.
@item
If two or more packages don't depend on each other, they'll be built one
after another and installed at the same time. This avoids needless user
prompting.
@end itemize

@cindex -x, makepkg output
@quotation
@strong{Tip}: Aura used to have an option @code{-x} to expose
@code{makepkg} output. This is now the default behaviour.
@end quotation

@node Automatically removing makedepends
@subsubsection Automatically removing makedepends
@cindex -Aa, -a, Automatically removing makedepends

There's a difference between the dependencies that a package needs to
build and the dependencies it needs to run. We call the former
"makedepends". Once a package is installed, we no longer need its
makedepends sitting around on our machine. Adding @code{-a} to @code{-A}
will automatically clear them out:

@example
> aura -Aa grimshot
aura :: Determining dependencies...
aura :: Repository dependencies:
 scdoc
aura :: AUR packages:
 grimshot
aura :: Proceed? [Y/n]

... the usual ...

aura :: Done.
checking dependencies...

Packages (1) scdoc-1.11.3-1

Total Removed Size:  0.03 MiB

:: Do you want to remove these packages? [Y/n]
@end example

@code{scdoc} was only necessary during the build, so we're prompted to
uninstall it.

If you'd like to turn this behaviour on permanently, you can set it
within config:

@example
[aur]
delmakedeps = true
@end example

@node Altering the PKGBUILD before building
@subsubsection Altering the PKGBUILD before building
@cindex hotedit, Altering the PKGBUILD before building

Sometimes you want to change something specific about how a package is
built. Without a tool like Aura, you'd clone the package from the AUR,
edit the PKGBUILD, and then run @code{makepkg}, handling dependencies
yourself.

Aura's @code{--hotedit} flag will let you edit a PKGBUILD on-the-fly. In
the example below, I add @code{echo "I CHANGED THE PKGBUILD"} to the
build commands:

@example
> aura -Aa python-grip --hotedit
aura :: Determining dependencies...

... the usual ...

aura :: Building python-grip...
aura :: Edit the PKGBUILD? [Y/n]

... Your EDITOR opens, and you save your changes to the real PKGBUILD file ...

==> Making package: python-grip 4.6.1-1 (Sat 13 Jul 2024 07:08:37 AM JST)
==> Starting package()...
I CHANGED THE PKGBUILD

... normal makepkg output, etc ...
@end example

Some things to note:

@itemize @bullet
@item
If @code{.install} or @code{.patch} files are present, @code{--hotedit}
will also prompt you to edit those.
@item
You can change the dependency lists, but this will only affect
@code{makepkg}'s dependency resolution, not Aura's. If you want Aura to
skip dependency checks completely because you know you're right (and you
know @code{makepkg} will succeed after you hotedit), use the
@code{--skipdepcheck} flag. See issue
@url{https://github.com/fosskers/aura/issues/605} for more information.
@item
If you want customizations to a PKGBUILD to apply to all future builds
of a package, it's recommended that you maintain a separate PKGBUILD and
call @code{makepkg} yourself.
@end itemize

If you'd like to always be prompted for hoteditting, you can set it
within config:

@example
[aur]
hotedit = true
@end example

@node PKGBUILD Analysis
@subsubsection PKGBUILD Analysis
@cindex shellcheck, PKGBUILD Analysis

If requested, Aura will run @url{https://www.shellcheck.net/,
Shellcheck} on PKGBUILDs to check for oddities:

@example
> aura -A goverlay-git --shellcheck

... the usual ...

aura :: Building goverlay-git...

In PKGBUILD line 32:
  for i in "$@{pkgname%-git@}.lpi"; do
           ^-------------------^ SC2066 (error): Since you double quoted this, it will not word split, and the loop will only run once.

For more information:
  https://www.shellcheck.net/wiki/SC2066 -- Since you double quoted this, it ...
aura :: Proceed? [Y/n]
@end example

If you'd like to always run @code{shellcheck} this way, you can set it
within config:

@example
[aur]
shellcheck = true
@end example

@node Jailed Building via pkgctl
@subsubsection Jailed Building via pkgctl
@cindex Jailed Building via pkgctl

For extra security, you can build packages in a @code{chroot}. This
ensures that the build process will not affect your existing filesystem.
For the moment, this option is gated by configuration; no CLI flag is
available:

@example
[aur]
chroot = ["fortls", "timelineproject-hg"]
@end example

This means that when these particular packages are built, it will be
done in a @code{chroot}. Transitive AUR dependencies will be injected
properly into the build environment.

@node Using a "build user"
@subsubsection Using a "build user"
@cindex build, builduser, Using a "build user"

The flags @code{--build} and @code{--builduser} can be used to alter
where the building occurs and under which user it occurs, respectively.
While usually not necessary by default, these can be useful for system
administrators who want stricter control.

@node Blindly Accepting all Prompts
@subsubsection Blindly Accepting all Prompts
@cindex noconfirm, Accept all prompts

Tired of pressing the @code{Enter} key? Or maybe you've automated
@code{aura} into a script. In these cases, you may want to accept all
prompts automatically. @code{pacman} exposes the @code{--noconfirm} flag
for this, which also affects Aura.

@node Updating your AUR Packages
@subsection Updating your AUR Packages
@cindex -Au, -u, Updating your AUR Packages

@code{aura -Au} is the standard command, and is run without @code{sudo}.

@example
> aura -Au
aura :: Fetching package information...
aura :: Comparing package versions...
aura :: AUR packages to upgrade:
 ghcup-hs-bin :: 0.1.22.0-1       -> 0.1.30.0-1
 tic-80-git   :: r2633.687fb340-1 -> r2883.3cf27c5e-1
 yed          :: 1:3.23.2-1       -> 1:3.24-1
aura :: Determining dependencies...
aura :: Repository dependencies:

... redacted ...

aura :: AUR packages:
 ghcup-hs-bin
 tic-80-git
 yed
aura :: Proceed? [Y/n]
@end example

The options that apply to normal @code{-A}, like @code{-a} and
@code{--hotedit}, also apply here. Of course, it's simplest to set those
in config if you know your preferences. See @code{aura -Ah} for more
options.

@node Displaying PKGBUILD Changes
@subsubsection Displaying PKGBUILD Changes
@cindex -k, Displaying PKGBUILD Changes

Hey wait a minute, aren't we supposed to check PKGBUILDs before building
packages? @code{-k} will show us any changes that were made to a
PKGBUILD compared to the version we have installed:

@example
> aura -Auk
aura :: Fetching package information...
aura :: Comparing package versions...
aura :: AUR packages to upgrade:
 ghcup-hs-bin :: 0.1.22.0-1 -> 0.1.30.0-1
 yed          :: 1:3.23.2-1 -> 1:3.24-1
aura :: Determining dependencies...
aura :: AUR packages:
 ghcup-hs-bin
 yed
aura :: Proceed? [Y/n]
aura :: Preparing build directories...
aura :: Building yed...
aura :: Display diffs of build files? [Y/n]
diff --git a/.SRCINFO b/.SRCINFO
index bc810a7..32f1f1f 100644
--- a/.SRCINFO
+++ b/.SRCINFO
@@ -1,6 +1,6 @@
 pkgbase = yed
        pkgdesc = Very powerful graph editor written in java
-       pkgver = 3.23.2
+       pkgver = 3.24
        pkgrel = 1
        epoch = 1
        url = http://www.yworks.com/en/products_yed_about.html
@@ -9,11 +9,11 @@ pkgbase = yed
        license = custom
        depends = hicolor-icon-theme
        depends = java-runtime
-       source = https://www.yworks.com/resources/yed/demo/yEd-3.23.2.zip
+       source = https://www.yworks.com/resources/yed/demo/yEd-3.24.zip
        source = yed.desktop
        source = yed
        source = graphml+xml-mime.xml
-       sha256sums = 4f96611718df696de2f33eeb2cd78bfbbdacce52390afea8d00441b6fb175e20
+       sha256sums = 842909f6e4c15399b660f316056499e63e931f95ade43d850045d852d3128947
        sha256sums = cc6957cde6eba0d82ea523b0257f8c91fd1e330a1e2ad7d64890e48a2450aa98
        sha256sums = 731b54c6e731704efe9847d78e2df474d59042452ace29d2786d76891295249e
        sha256sums = e751b69ed8a25faf46d4e4016ed8f1774abc88679067934a6081348e3d6fc332
diff --git a/PKGBUILD b/PKGBUILD
index f9ea04e..cb06126 100644
--- a/PKGBUILD
+++ b/PKGBUILD
@@ -10,7 +10,7 @@
 # https://github.com/michaellass/AUR

 pkgname=yed
-pkgver=3.23.2
+pkgver=3.24
 pkgrel=1
 epoch=1
 pkgdesc='Very powerful graph editor written in java'
@@ -22,7 +22,7 @@ source=("https://www.yworks.com/resources/yed/demo/yEd-$@{pkgver@}.zip"
         'yed.desktop'
         'yed'
         'graphml+xml-mime.xml')
-sha256sums=('4f96611718df696de2f33eeb2cd78bfbbdacce52390afea8d00441b6fb175e20'
+sha256sums=('842909f6e4c15399b660f316056499e63e931f95ade43d850045d852d3128947'
             'cc6957cde6eba0d82ea523b0257f8c91fd1e330a1e2ad7d64890e48a2450aa98'
             '731b54c6e731704efe9847d78e2df474d59042452ace29d2786d76891295249e'
             'e751b69ed8a25faf46d4e4016ed8f1774abc88679067934a6081348e3d6fc332')
aura :: Proceed? [Y/n]
@end example

Once again, nothing evil-looking here. If you'd like to always see diffs
like this, you can set it within config:

@example
[aur]
diff = true
@end example

@node Including *-git Packages
@subsubsection Including *-git Packages
@cindex Including *-git Packages

The AUR has many packages postfixed with @code{-git}, @code{-svn}, etc.
These typically pull straight from the @code{master} branch of some code
respository, and so comparing version numbers to detect updates doesn't
always work.

@code{--git} will consider all such packages for updates:

@example
> aura -Au --git
aura :: Fetching package information...
aura :: Comparing package versions...
aura :: AUR packages to upgrade:
 ghcup-hs-bin :: 0.1.22.0-1 -> 0.1.30.0-1
 yed          :: 1:3.23.2-1 -> 1:3.24-1
aura :: VCS packages to rebuild:
 clasp-cl-git
 libmgba-git
 mgba-qt-git
 timelineproject-hg
aura :: Determining dependencies...
aura :: Repository dependencies:
 qt6-tools
aura :: AUR packages:
 clasp-cl-git
 ghcup-hs-bin
 mgba-git
 timelineproject-hg
 yed
aura :: Proceed? [Y/n]
@end example

If you'd like to always consider such packages with @code{-u}, you can
set it within config:

@example
[aur]
git = true
@end example


@node Package Storage Locations
@subsection Package Storage Locations
@cindex directories, Package Storage Locations

This page explains all important filepaths for Aura. Build paths can be
configured in @code{~/.config/aura/config.toml}, see
@ref{Configuration}.

@heading Where are packages built?

By default, packages are built within @code{~/.cache/aura/builds/}. Were
a package specified in the @code{chroot} list in config, then it will
instead be built in a @code{chroot}.

@heading Where are packages stored?

Once built, all packages are sent to Aura's cache:
@code{~/.cache/aura/cache/}.

This directory can grow quite large, but can be cleaned with @code{-Cc}
(see @ref{Cache Handling and Downgrading}). See also @code{aura stats}
for a view of various Aura-related directory sizes.

@heading What other filepaths are there?

Aura stores clones of known AUR packages in
@code{~/.cache/aura/packages/}, and saved package set states in
@code{~/.cache/aura/snapshots/}.

Also also reads your @code{pacman} and @code{makepkg} configuration,
which are generally expected to be at @code{/etc/pacman.conf} and
@code{/etc/makepkg.conf} respectively, but it will respect the usual
environment variables that alter those paths.

@node Cache Handling and Downgrading
@section Cache Handling and Downgrading
@cindex Cache Handling and Downgrading

The @code{-C} command is used to interact with the Package Cache. It
takes into account both the official Pacman cache and Aura's.

@node Searching the Cache
@subsection Searching the Cache
@cindex -Ci, -Cs, Searching the Cache

@code{-Cs} shows us what's available in the cache.

@example
> aura -Cs firefox
/var/cache/pacman/pkg/firefox-127.0.2-1-x86_64.pkg.tar.zst
/var/cache/pacman/pkg/firefox-126.0.1-1-x86_64.pkg.tar.zst
@end example

We can get more intelligent output via @code{-Ci}:

@example
> aura -Ci firefox
Name               : firefox
Latest             : 127.0.2-1 [installed]
Created            : 2024-06-29 04-12-38
Signature          : Yes
Tarball Size       : 69.01MiB
Available Versions : 127.0.2-1, 126.0.1-1
@end example

@node Downgrading a Package
@subsection Downgrading a Package
@cindex -C, Downgrading a Package

Let's say the newest version of some package is somehow broken. Let's
downgrade:

@example
> aura -C firefox
aura :: What version of firefox do you want?
 0) 127.0.2-1
 1) 126.0.1-1
>>> 1
loading packages...
warning: downgrading package firefox (127.0.2-1 => 126.0.1-1)
resolving dependencies...
looking for conflicting packages...

Packages (1) firefox-126.0.1-1

Total Installed Size:  239.53 MiB
Net Upgrade Size:       -1.34 MiB

:: Proceed with installation? [Y/n]
@end example

In fact, @code{-C} works even if we no longer have that package
installed. All that matters is whether you have a copy of the old
version in your cache.

@node Cleaning the Cache
@subsection Cleaning the Cache
@cindex -Cc, Cleaning the Cache

@code{-Cc} can help keep our cache small.

@example
> aura -Cc 2
aura :: Current cache size: 8.31GiB
aura :: 2 of each package file will be kept. The rest will be deleted.
aura :: Proceed? [Y/n]
aura :: 34.45MiB freed.
@end example

@node Managing Orphan Packages
@section Managing Orphan Packages
@cindex -O, Managing Orphan Packages

Orphan packages are those marked as @code{Installed as a dependency for
another package}, but which are missing the parent package that depended
on them. This can occur when a package with many dependencies is
installed and then later removed via a single @code{-R} (without
@code{-su}). Or when a package is upgraded, and the new version no
longer requires a certain dependency.

In these cases, the dependencies are left behind and becomes orphans,
chewing up disk space.

The @code{-O} command can help deal with these.

@example
> aura -O
python-docopt
python-flask
python-path-and-address
@end example

Weird! Are they really not needed?

@example
> aura -Qi python-docopt
Name            : python-docopt
Version         : 0.6.2-7
Description     : Pythonic argument parser, that will make you smile
Architecture    : any
URL             : https://github.com/docopt/docopt
Licenses        : MIT
Groups          : None
Provides        : None
Depends On      : python
Optional Deps   : None
Required By     : None
Optional For    : None
Conflicts With  : None
Replaces        : None
Installed Size  : 83.17 KiB
Packager        : Evangelos Foutras <evangelos@@foutrelis.com>
Build Date      : Thu Oct 31 09:48:34 2019
Install Date    : Fri Jun 12 09:43:12 2020
Install Reason  : Installed as a dependency for another package
Install Script  : No
Validated By    : Signature
@end example

Sure enough, @code{Required By: None}.

@node Uninstalling Orphans
@subsection Uninstalling Orphans
@cindex -Oj, Uninstalling Orphans

Clearing orphans doesn't just save us space now - it saves the space of
all future upgrades we won't have to download anymore.

@code{-Oj} will uninstall all such packages. Under the hood, it passes
@code{-Rsu} to @code{pacman}, hence there are more packages to uninstall
than first appeared in the @code{-O} list previously.

@example
> aura -Oj
checking dependencies...

Package (5)              Old Version  Net Change

python-itsdangerous      1.1.0-4       -0.11 MiB
python-werkzeug          1.0.1-2       -2.13 MiB
python-docopt            0.6.2-7       -0.08 MiB
python-flask             1.1.2-2       -0.80 MiB
python-path-and-address  2.0.1-1       -0.01 MiB

Total Removed Size:  3.12 MiB

:: Do you want to remove these packages? [Y/n]
@end example

@node Adopting an Orphan
@subsection Adopting an Orphan
@cindex -Oa, Adopting an Orphan

Changing a package's install reason from "dependency" to "explicitly
installed" is possible via @code{pacman} alone, but Aura offers a
shorthand:

@example
> aura -Oa python-path-and-address
python-path-and-address: install reason has been set to 'explicitly installed'
@end example

@node Forgotten Top-level Packages
@subsection Forgotten Top-level Packages
@cindex -Oe, Forgotten Top-level Packages

The dual concept of the "orphan" would be the "elderly"; in this case,
top-level packages which aren't depended on by anything else.

@example
> aura -Oe
abcl 1.9.2-1
alsa-utils 1.2.12-1
anki 2.1.66-1
aspell-en 2020.12.07-1
babashka-bin 1.3.191-1
base 3-2
base-devel 1-1
... etc ...
@end example

If you notice anything here that you don't remember installing or that
you don't need anymore, you can remove it. Consider also @code{aura
check} for a list of such top-level packages that haven't been updated
in the past year.

@node Package Set Snapshots
@section Package Set Snapshots
@cindex Package Set Snapshots

Arch Linux (and Linux in general) used to have a reputation of breaking
every time packages were upgraded. Around 2010, Aura's author used to
run Arch on a Macbook, and such catastrophic breakage @emph{did} occur
every six months or so. But fast-forward to the present day, and such
problems are rare. Even so, the idea of "whole system rollback" is
spreading, and even since those early Arch-on-Mac days, Aura has had the
@code{-B} command for saving and restoring entire package sets.

@node Saving a Package Set
@subsection Saving a Package Set
@cindex -B, Saving a Package Set

@example
> aura -B
aura :: Saved package state.
@end example

This saves a file like @code{2024.07(Jul).09.21.07.02.json} to
@code{~/.cache/aura/snapshots/}. If we take a peek inside, we see:

@example
@{
  "time": [2024, 196, 3, 54, 43, 311735304, 0, 0, 0],
  "pinned": false,
  "packages": @{
    "libmm-glib": "1.22.0-1",
    "fcitx5-mozc": "2.26.4632.102.g4d2e3bd-2",
    "graphviz": "11.0.0-1",
    "mailcap": "2.1.54-1",
    "libsm": "1.2.4-1",
    "containerd": "1.7.18-1",
... etc ...
@end example

Simple enough - a list of all installed packages with their versions.
We'll talk about @code{pinned} later.

These files are in JSON format in case other tools wish to read them.

@node Restoring a Package Set
@subsection Restoring a Package Set
@cindex -Br, Restoring a Package Set

Let's say I removed some packages a few days ago but am now having
issues, and I want to rollback to the system state I had at the time.
Let's see that happen:

@example
> aura -Br
aura :: Select a snapshot to restore:
 0) 2024-07-09 21-07-02
 1) 2024-07-12 22-56-43
 2) 2024-07-12 22-59-18
 3) 2024-07-12 23-04-25
 4) 2024-07-12 23-19-29 [pinned]
 5) 2024-07-14 03-54-37
 6) 2024-07-14 03-54-43
>>> 0
loading packages...
resolving dependencies...
looking for conflicting packages...

Packages (21) asar-3.2.8-1  cdparanoia-10.2-9  grimshot-1.9-1  gst-plugins-base-1.24.5-2
              kirigami2-5.116.0-1  meson-1.4.1-1  mgba-qt-git-0.11.0.r8251.6853080b9-1
              mgba-sdl-0.10.3-2  musl-1.2.5-1  neofetch-7.1.0-2  ninja-1.12.1-1  pkgstats-3.2.18-1
              python-tqdm-4.66.4-1  qt5-graphicaleffects-5.15.14-1  qt5-multimedia-5.15.14+kde+r2-1
              qt5-quickcontrols-5.15.14-1  qt5-quickcontrols2-5.15.14+kde+r5-1  typst-1:0.11.1-1
              webui-2.5.0+beta.1+14+gb65608df-1  xf86-input-libinput-1.4.0-1  xorg-server-21.1.13-1

Total Installed Size:  86.50 MiB

:: Proceed with installation? [Y/n]
@end example

This reinstalls the old versions of those packages and removes anything
currently installed that wasn't at the time of the snapshot.

@node Clearing out old Saved States
@subsection Clearing out old Saved States
@cindex -Bc, Clearing out old Saved States

Especially if you have automatic state-saving with @code{-Au} turned on,
these snapshot files can build up quickly. You might not even have most
of the packages necessary to roll back to those early states if you've
recently used @code{-Cc}. Let's clear out the old, unusable ones:

@example
> aura -Bc
aura :: Remove stale snapshots? [Y/n]
aura :: Done.
@end example

"Stale" refers to snapshots for which the corresponding tarball of some
package no longer exists on your system. You can confirm the overall
state of your snapshots with @code{aura check}.

If you have edited a snapshot file to change the @code{pinned} field to
@code{true}, then @code{-Bc} will never remove it.

@node Log Interaction
@section Log Interaction
@cindex Log Interaction

Pacman keeps an extensive log file, but doesn't really offer any way to
interact with it. Aura has the @code{-L} command to perform some
interesting lookups.

@node View the Log File
@subsection View the Log File
@cindex -L, View the Log File

To print the content of the entire log file:

@example
> aura -L | bat
[2016-05-03 04:13] [PACMAN] Running 'pacman -r /mnt -Sy --cachedir=/mnt/var/cache/pacman/pkg base base-devel'
[2016-05-03 04:13] [PACMAN] synchronizing package lists
[2016-05-03 04:26] [ALPM] transaction started
[2016-05-03 04:26] [ALPM] installed linux-api-headers (4.4.1-1)
[2016-05-03 04:26] [ALPM] installed tzdata (2016d-1)
[2016-05-03 04:26] [ALPM] installed iana-etc (20160314-1)
[2016-05-03 04:26] [ALPM] installed filesystem (2015.09-1)
[2016-05-03 04:26] [ALPM] installed glibc (2.23-1)
... etc ...
@end example

A blast from the past! Looks like I set up Arch on this laptop in 2016.
And what was the most recent thing that happened (pressing @code{G})?

@example
... etc ...
[2024-07-14T13:53:16+0900] [ALPM] transaction completed
[2024-07-14T13:53:16+0900] [ALPM] running '30-systemd-daemon-reload-system.hook'...
[2024-07-14T13:53:16+0900] [ALPM] running '30-systemd-update.hook'...
[2024-07-14T13:53:16+0900] [ALPM] running 'gtk-update-icon-cache.hook'...
[2024-07-14T13:53:16+0900] [ALPM] running 'update-desktop-database.hook'...
@end example

@node Search the Log File
@subsection Search the Log File
@cindex -Ls, Search the Log File

@code{-Ls} returns all log lines that match a given string:

@example
> aura -Ls firefox
[2016-05-03 08:45] [PACMAN] Running 'pacman -S firefox'
[2016-05-03 08:46] [ALPM] installed firefox (46.0-2)
[2016-05-07 11:09] [ALPM] upgraded firefox (46.0-2 -> 46.0.1-1)
[2016-06-19 14:30] [ALPM] upgraded firefox (46.0.1-1 -> 47.0-1)
[2016-06-23 15:46] [ALPM] upgraded firefox (47.0-1 -> 47.0-2)
[2016-07-25 07:25] [ALPM] upgraded firefox (47.0-2 -> 47.0.1-1)
... etc ...
@end example

@node Query all Logs for a Package
@subsection Query all Logs for a Package
@cindex -Li, Query all Logs for a Package

More interesting than just a raw search is @code{-Li}:

@example
> aura -Li firefox
Name           : firefox
First Install  : 2016-05-03 08:46
Upgrades       : 176
Recent Actions :
[2024-02-24T07:29:46+0900] [ALPM] upgraded firefox (122.0.1-1 -> 123.0-1)
[2024-03-11T16:42:37+0900] [ALPM] upgraded firefox (123.0-1 -> 123.0.1-1)
[2024-03-24T15:03:33+0900] [ALPM] upgraded firefox (123.0.1-1 -> 124.0.1-1)
[2024-06-03T05:18:15+0900] [ALPM] upgraded firefox (124.0.1-1 -> 126.0.1-1)
[2024-06-29T13:17:29+0900] [ALPM] upgraded firefox (126.0.1-1 -> 127.0.2-1)
@end example

Neat! I often use this to check the last time I updated a particular
package.

@node Dependency Analysis
@section Dependency Analysis
@cindex Dependency Analysis

Sometimes you might notice a certain package that you don't recognize
nonetheless being updated, and you'd like to know where it came from. Or
perhaps you'd like to know what the affect of installing some package
might be, in terms of dependency load. The output of @code{-Qi} and
@code{-Si} includes dependency information, but only one layer deep in
either direction. In these cases, @code{aura deps} is a useful command.

@cindex deps --open
By default it writes a @code{.png} to the current directory, but with
@code{--open} will output to @code{/tmp} and open the image in the
default viewer instead. If the image isn't opening in the viewer you
prefer, you can alter it in @code{~/.config/mimeapps.list}. For
instance:

@example
[Default Applications]
image/png=swayimg.desktop
@end example

The available @code{.desktop} entries can be found in @code{/usr/share/applications/}.

@node Displaying Dependencies
@subsection Displaying Dependencies
@cindex deps, Displaying Dependencies

Try these commands for yourself to view their image-based output.

@example
> aura deps sbcl --open
@end example

It looks like @code{sbcl} is fairly self-contained. Many packages are
not, and their output needs to be limited to render usefully. For
instance...

@example
> aura deps gcc --open
@end example

Hmm, too big. Let's try again, but with @code{--limit} this time:

@example
> aura deps gcc --limit=3 --open
@end example

If you notice this command taking a long time, halt it and add
@code{--limit}.

@node Display Reverse Dependencies
@subsection Display Reverse Dependencies
@cindex Display Reverse Dependencies

If we're curious what chain a packages depends on something, we can review that with @code{--reverse}:

@example
> aura deps gcc --reverse --open
@end example

Note that cyan nodes indicate AUR packages.

@node Configuration
@chapter Configuration
@cindex Configuration

For certain settings we use all the time (e.g. language, build paths,
etc.), Aura is configurable via @code{~/.config/aura/config.toml} in the
@url{https://en.wikipedia.org/wiki/TOML, TOML format}. This file, with
sensible defaults, can be generated via:

@example
aura conf --gen > ~/.config/aura/config.toml
@end example

Below are the specifics of each field.

@heading General Settings
@cindex [general], configuration block

@multitable @columnfractions .18 .18 .63
@headitem Field @tab Type @tab Purpose
@item cpus
@tab int
@tab Affects parallelism in various algorithms
@item editor
@tab string
@tab The editor opened with @code{--hotedit}
@item elevator
@tab string
@tab A code to specify the human language of Aura's output messages
@item language
@tab string
@tab A code to specify the human language of Aura's output messages
@item noconfirm
@tab bool
@tab Automatically accept all prompts
@end multitable

See @code{aura stats --lang} for available language codes.

@heading AUR Package Building
@cindex [aur], configuration block

@multitable @columnfractions .18 .18 .63
@headitem Field @tab Type @tab Purpose
@item build
@tab string
@tab A path to the build cache Aura should use
@item cache
@tab string
@tab A path in which to store built package tarballs
@item clones
@tab string
@tab A path in which to clone package metadata
@item hashes
@tab string
@tab A path in which to store the git hash of the latest build
@item builduser
@tab string
@tab An alternate user to build as
@item chroot
@tab string list
@tab Packages to build with @code{pkgctl build} in a chroot
@item ignores
@tab string list
@tab Packages to never update
@item git
@tab bool
@tab Force update all VCS packages during @code{-Au}
@item hotedit
@tab bool
@tab Prompt to edit build files (PKGBUILD, etc.) before building
@item shellcheck
@tab bool
@tab Run @code{shellcheck} over PKGBUILDs before building
@item diff
@tab bool
@tab Display PKGBUILD diffs during upgrades
@item delmakedeps
@tab bool
@tab Remove makedeps after building
@item clean
@tab bool
@tab Delete a package's build directory after building
@item warn_unknowns
@tab bool
@tab If @code{false}, suppress warnings about unknown packages.
@item nocheck
@tab bool
@tab Don't run the @code{check()} function while building
@item skipdepcheck
@tab bool
@tab Don't perform dependency checking at all
@item reverse
@tab bool
@tab Always reverse the search results
@end multitable

Fields of type @code{string list} look like this:

@example
ignores = ["foo", "bar", "baz"]
@end example

@heading Package Snapshots
@cindex [backups], configuration block

@multitable @columnfractions .18 .18 .63
@headitem Field @tab Type @tab Purpose
@item snapshots
@tab string
@tab A path in which to store snapshot files
@item automatic
@tab bool
@tab Automatically save a snapshot during @code{-Au}
@end multitable

@node Appendix
@chapter Appendix

@node AUR Search Behaviour
@section AUR Search Behaviour
@cindex AUR Search Behaviour

Aura uses its own metadata server called
@url{https://github.com/fosskers/faur, the Faur} ("Fast AUR") to power
@code{-Ai}, @code{-As}, and @code{-Av}. The behaviour of @code{-As} in
particular is slightly different from usual searches on the AUR website
as well as what other alternate package managers provide, but the result
is a vast improvement in performance, simplicity of design, and ease of
maintenance.

Below are the details of the performance techniques, as well as how
search results are affected.

@heading Term Indices

The Faur does not use a database, instead keeping all package data in
memory. In order to enable efficient lookups based on arbitrary search
terms, it constructs "term indices" whose keys are single terms found in
a package's name, description, and keywords. These keys then refer back
to the set of package names where they were found.

For instance, the key for @code{nintendo} points to a set of 168 package
names somehow related to Nintendo. With those names in hand, it's
trivial to retrieve their full package data via another @code{name -> data}
index.

@heading "And" Semantics

If instead you had run @code{aura -As nintendo switch}, two index calls
would be made and their results combined via Set Intersection. So, you'd
only have results that contained both terms. This actually makes the
overall search faster, because there are fewer subsequent lookups to
perform, and less JSON to render.

In general, this architecture enables @code{O(k * logn)} performance for
lookups, where @code{k} is the number of search terms. In layman's
terms, "real fast".

@heading Result Sorting

Before returning the JSON, results are internally sorted by vote and
then truncated to the top 50 results. This may punish some searches in
some cases, but for the majority of user searches, this would result in
what the user expected. Most searches don't even need all 50 results;
you mostly care about the top entries anyway.

@heading Input Sanitization

Were a package originally called @code{great-fun-package}, its name
would be split on @code{-} and registered to all three keys of
@code{great}, @code{fun}, and @code{package}. So a search of any of
those terms would find it.

Likewise, if you had run @code{aura -As great-fun}, that input would be
split as well and sent as @code{great} and @code{fun} separately,
triggering the And Semantics described above.

@heading No Regex or Partial Terms
@cindex Why no regex search?

However, a search for @code{pack} would not have found
@code{great-fun-package}. As seen above, only full terms can match a key
in the indices. This is the main difference between the Faur and the
AUR.

@quotation
Why can't you just compare the search terms against all the keys?
@end quotation

Because that would result in @code{O(k * n)} performance, or in layman's
terms, "real slow". I'd have to change the name to Saur.

The moral of the story is: search with full terms and use "And
Semantics" to get better results.

@node Localisation Guide
@section Localisation Guide
@cindex Localising Aura

Welcome! こんにちは! Saluton!

If you're reading this then it's likely that you want to help localise
Aura into another language. Arch users everywhere can benefit from your
contribution, and it's a great opportunity to contribute to Free
Software.

What you need:

@enumerate
@item
@url{https://github.com/fosskers/aura, The Aura source code}.
@item
An editor. Whichever one you like.
@item
@code{git}. As Aura is hosted on github, cloning, making changes and
adding pull requests will be easiest if you have a working git/github
setup.
@item
A brain (hopefully yours) with a language in it. As for me, no hablo
español, Я не могу говорить по-русски, nor do I يتكلم العربية, so that's
where you come in.
@end enumerate

@node Localisation
@subsection Localisation

The first thing to determine is whether you are extending some existing
translations or writing a new set. If you're extending an existing set,
skip to Step Two, @ref{Translate the English}.

Aura utilises Mozilla's @url{https://projectfluent.org/, Fluent Project}
for localisation. The format is text-based and straight-forward, and
also allows for special plural handling. See the
@url{https://projectfluent.org/fluent/guide/, Fluent Guide} for more
information.

In the examples below, we will pretend to add localisations for Latin.

@node Establish a new Localisation File
@subsubsection Establish a new Localisation File

You will find all localisation files under @code{rust/aura-pm/i18n/}.
There is a subdirectory for each language. To add one for Latin, we
first @url{https://simplelocalize.io/data/locales/, look up its locale
code} and find it to be @code{la-VA}, associated with Vatican City.

@example
mkdir la-VA
cp en-US/aura_pm.ftl la-VA/
@end example

We have copied over the English translations as a base.

@node Translate the English
@subsubsection Translate the English

The top section of the file looks like:

@example
language-name = English

# AUR Packages (-A)
A-install-deps = Determining dependencies...
A-install-repo-pkgs = Repository dependencies:
A-install-aur-pkgs = AUR packages:
A-install-path-comp = Failed to extract final component of: @{ $path @}
A-install-ignored = @{ $file @} is marked "ignored". Install anyway?
@end example

@code{language-name} is important. This is the output used in @code{aura
stats --lang}. We could make this:

@example
language-name = Lingua Latina
@end example

Then we continue, line by line, replacing the original English with
Latin. For example:

@example
A-build-continue = Permanere aliis packages aedificationem?
@end example

Some lines have "slots" of the format @code{@{ $foo @}}, where a value
coming from Aura will be used to complete the message:

@example
+A-build-e-filename = Defecit e filename eliciunt: @{ $file @}
-A-build-e-filename = Failed to extract filename from: @{ $file @}
@end example

@quotation
@strong{Tip}: If you don't translate every line, Fluent will
automatically fall back to English for the ones that are missing. No
error will occur.
@end quotation

If you add a @code{#} to the beginning of a line, that will make it a
"comment", thus disabling it.

@example
# Note: Translate this after I finish conquering the barbarian hordes.
# A-u-fetch-info = Fetching package information...
@end example

@node Tell the Rust Code about the New Language
@subsubsection (Optional) Tell the Rust Code about the New Language

If you're capable with Rust, you can register the new language yourself.
Otherwise, I will do it after you submit your translations.

First, in @code{rust/aura-pm/src/lib.rs}, we tell the Rust about the new locale:

@example
pub const LATIN: LanguageIdentifier = langid!("la-VA");
@end example

Then, within @code{rust/aura-pm/src/localization.rs}, we update the
@code{identifier_from_locale} function to include the language code for
Latin:

@example
pub(crate) fn identifier_from_locale<S>(locale: S) -> Option<LanguageIdentifier>
where
    S: AsRef<str>,
@{
    match code_and_country(locale.as_ref()) @{
        ("en", _) => Some(aura_pm::ENGLISH),
        // ... other languages ...
        ("la", _) => Some(aura_pm::LATIN),
        _ => None,
    @}
@}
@end example

Next, we add a command-line flag for Latin within
@code{rust/aura-pm/src/flags.rs}:

@example
pub struct Args @{
    /// Output in Latin (alias: Latinus).
    #[clap(
        group = "language",
        long,
        global = true,
        alias = "latinus",
        hide_short_help = true,
        display_order = 10
    )]
    pub latin: bool,
    // ... more flags ...
@end example

Thanks to the @code{alias}, we can turn on Latin with either
@code{--latin} or @code{--latinus}. Make sure to add both variants to
the @code{AURA_GLOBALS} list. This is important for interaction with
Pacman.

Finally, back in @code{localization.rs}, we can give credit to ourselves
for having added Latin:

@example
pub(crate) const TRANSLATORS: &[(&str, &str)] = &[
    // ... other languages ...
    ("Korean", "\"Nioden\""),
    ("Latin", "Maximus Decimus Meridius")
    ("Norwegian", "\"chinatsun\""),
    // ... other languages ...
];
@end example

Strength and honour, General.

@node Open a Pull Request
@subsubsection Open a Pull Request

With the translations complete, you'll need to tell us about it on
Github. Once your changes are looked over, we'll release a new version
of Aura with your language included as soon as possible. Provided you
followed the above instructions, this shouldn't take long. Furthermore,
chances are we won't be able to proofread the translation itself, as we
probably don't speak your language. You could hide your doomsday
take-over plans in the code and no one would know.

You've done a great thing by increasing Aura's usability. Your name will
be included in both Aura's README and in its @code{thanks} message. Thank you
for your hard work!

@node Questions regarding Localisation
@subsection Questions regarding Localisation
@cindex Questions regarding Localisation

@heading How do I test my translations?

You will need to do Step Three first. See @ref{Tell the Rust Code about
the New Language}. To view your translation progress, you can run:

@example
cargo run -- stats --lang
@end example

To see your translations in action, run some command:

@example
cargo run -- -Au --latin
@end example

@heading Which locale code should I choose?

@quotation
My language is associated with multiple countries. Which locale code
should I choose?
@end quotation

The general rule is "the country it came from". This applies to
languages like Spanish and Portuguese, whose countries established
colonies across the world that now outpopulate their land of origin.
German and French as well, which have strong footholds in Europe across
many countries. The exception is English, as @code{en-US} is the dominant
locale of technology and the internet.

If the country and language name don't match, then pick the place with
the most native speakers. This would apply to languages like Farsi
(Persian), primarily spoken in Iran.

If the language has a language code but not any associated country, like
Esperanto, then invent one (e.g. @code{eo-EO}). Fluent
@url{https://github.com/kellpossible/cargo-i18n/issues/52, won't know
the difference}.

If for political reasons you have difficulty recognizing the country
currently associated with the language, we ask you to put those concerns
aside at least for the naming of the directory. Within Aura's code,
output messages are selected based on the language portion of the locale
only, not the country, so you're free to set it as you wish. Further, if
you wish to provide separate localisations for a specific country whose
language is shared across many (for instance, the various @code{zh}
Chinese languages), Aura's code can be altered to specifically dispatch
on that country. Please bring it up when discussing your submission.

If you're still unsure, please ask.

@node FAQ
@section Frequently Asked Questions
@cindex faq, Frequently Asked Questions

@heading Why doesn't package XYZ build?

If you're on the most recent version of Aura and are still having
problems, this could be for a few reasons:

@itemize @bullet
@item
There is something wrong with the upstream package source files or a
dependency. Try checking the comments on the AUR page for that package:
@code{aura -Ao <pkg>}
@item
The build environment of that package is somehow polluted. Try deleting
everything found in @code{~/.cache/aura/builds/<naughty-package>/}.
@item
You've found a real bug in Aura.
@url{https://github.com/fosskers/aura/issues, PLease report it!}
@end itemize

@heading Why can't I do partial/regex searches with @code{-As}?

Aura uses its own metadata server tuned for performance. You're
encouraged to always search with full terms, like:

@example
aura -As firefox
@end example

and not

@example
aura -As firef
@end example

See @ref{AUR Search Behaviour} for why this is.

@heading How do I debug a problem?
@cindex How to debug

To display extra output during Aura's operation, pass
@code{--log-level=info}. If Aura is failing mysteriously somewhere, that
output will at least let us know how far it got internally. Even more
detail will be printed with @code{--log-level=debug}.

@heading Why did you rewrite Aura in Rust?
@cindex Why rust?

Haskell is an excellent language. However, I had specific reasons to
move to Rust:

@enumerate
@item
To gain access to the @code{alpm} bindings already available for Rust.
@item
To make Aura easier to install.
@item
To open up Aura to more potential contributors.
@item
To reduce Aura's binary size.
@item
To improve Aura's CLI interface and @code{--help} messages.
@item
To improve Aura's performance.
@end enumerate

If you're thinking that I could have done any of that in Haskell, you
may be right, but I didn't want to.

See also the @url{https://github.com/fosskers/aura/discussions/657, original discussion}.

@heading Why did you write a custom metadata server?
@cindex faur

@url{https://github.com/fosskers/faur, The Faur} yields the same JSON
format as the usual AUR RPC, but offers new endpoints. The primary
functionality I required was "provides"-based lookup, but for AUR
packages. The simplest way to achieve that was to write my own server,
so I did.

An example of provides-based searching would be:

@quotation
I want to know all of the packages that think they are @code{gcc}.
@end quotation

We can search that like so:

@example
> aura -Av gcc
aur/gcc-git 13.0.0_r197401.g33be3ee36a7-1 (15 | 0.00)
    The GNU Compiler Collection - C and C++ frontends (git version)
aur/gccrs-git 14.0.1_r213484.g646046091b7-1 (2 | 0.00)
    The GNU Compiler Collection - C and C++ frontends (git version)
aur/gcc-snapshot 15.0.1.snapshot20240707-1 (1 | 0.32)
    The GNU Compiler Collection - C and C++ frontends (snapshot)
@end example

Any of these packages, if installed, "provides" the "package identity"
of @code{gcc}. Should another package require @code{gcc} as a
dependency, any of these will satisfy the resolver.

Having Aura communicate with a server under my control also helps reduce
the load on the AUR RPC.

Note that the data in the Faur is at any time no more than 1 hour older
than that found on the AUR.

@node Index
@unnumbered Index
@printindex cp

@bye
