Aura Documentation¶

Preface¶

This is a design document for version 2 of Aura. Note that specifications are written in present tense, as in, “Aura does this” even if at the time of writing those features aren’t implemented yet. This is to ensure that the document can act as a reference for Aura’s behaviour post-release.

Mission Statement¶

Aura is a cross-distribution package manager for GNU/Linux systems. It is based around a distribution-specific Hook system for custom build/install behaviour, while maintaining a custom interface across all distros. Aura itself provides:

• Dependency management.
• Package downloading.
• Package-state backups/restoration.

Aura’s authors recognize that attempting to create universal standards can be problematic, but that is precisely why Aura exists. By having a unified interface over multiple packaging standards, users can transition between distributions more easily, and distribution developers can avoid reinventing the wheel by writing their own package management software.

Functionality¶

General¶

By default, Aura handles three types of packages:

Repository Packages

Prebuilt binaries available direct from the user’s Distribution.

Foreign Packages

Packages that generally need to be compiled by the user. Their versioning/source locations may be managed by the Distribution is some way.

Local Packages

Packages installed on the user’s system. Records of them and the files belonging to them are stored in a database, and package files themselves are stored in a cache (in /var/cache/ or elsewhere).

A number of operations can be performed on these package types, as explained below.

Program Flow¶

Common Behaviour¶

As can be gleamed from the program flow chart, the “capital letter” operators pertaining to packages share the same functionality metaphors.

• Installation: aura -{S,F,L} <packages>
• Searching: aura -{S,F,L}s <regexp-like-pattern>

Output sample:

$> aura -Ss nvidia
extra/nvidia 337.25-3 [installed]
    NVIDIA drivers for linux
extra/nvidia-304xx 304.121-5
    NVIDIA drivers for linux, 304xx legacy branch
extra/nvidia-304xx-libgl 304.121-2
    NVIDIA drivers libraries symlinks, 304xx legacy branch

Aura will fail silently when no pattern is given.

• Info Lookups: aura -{S,F,L}i <packages>

To the question, “What does it mean to install a local package?” consider the following the use cases:

$> aura -L foo-1.2-1.pkg.tar.gz  -- Installing a prebuilt package tarball.

$> aura -L bar
aura >=> Which version of `bar` do you want?
1. bar-1.1.1-1
2. bar-1.2.1-1
3. bar-1.2.3-1
>>  -- You choose which to install from your _local_ cache.

Local Package Removal¶

Local packages may be removed singularly, or in groups.

Usage:

• Just the packages named: aura -R <packages>
• Packages named and all deps (recursive): aura -Rr <packages>

Local Package Backups¶

The state of locally installed packages may be recorded and restored at a later date.

Usage:

• Store a snapshot of all installed packages: aura -B

  • This record is stored in /var/cache/aura/states.
  • Filenames are of the form: YYYY.MM.MonthName.DD.HH.MM.
  • The data itself is stored as JSON to ease use by other tools.

• Restore a snapshot: aura -Br

{ "date": "2014-04-09",
  "time": "20:00",
  "packages": [ { "pkgname": "alsa-lib",
                  "version": "1.0.27.2-1" },
                // more packages here
              ]
}

+----------+--------+----------+---------+
| Dep Name | Parent | Status   | Version |
+==========+========+==========+=========+
| foo      | None   | Local    | 1.2.3   |
| foo      | bar    | Incoming | < 1.2.3 |
| foo      | baz    | Incoming | > 1.2.3 |
+----------+--------+----------+---------+
| curl     | git    | Local    | 7.36.0  |
| curl     | pacman | Incoming | 7.37.0  |
+----------+--------+----------+---------+
| lua      | vlc    | Incoming | 5.2.3   |
| lua      | conky  | Incoming | 5.2.2   |
+----------+--------+----------+---------+

// As JSON:
{ [ { "Name": "foo",
      "Local": { "Parent": "None",
                 "Version": "1.2.3" },
      "Incoming": [ { "Parent": "bar",
                      "Version": "< 1.2.3" },
                    { "Parent": "baz",
                      "Version": "> 1.2.3" }
                  ]
    },
    { "Name": "curl",
      "Local": { "Parent": "git"
                 "Version": "7.36.0" },
      "Incoming": [ { "Parent": "pacman",
                      "Version": "7.37.0" }
                  ]
    },
    { "Name": "lua",
      "Local": "None",
      "Incoming": [ { "Parent": "vlc",
                      "Version": "5.2.3" },
                      { "Parent": "conky",
                        "Version": "5.2.2" }
                  ]
    }
  ]
}

class Package p where
  -- Converts a package name to its ADT form. Upon failure,
  -- yields its name wrapped in a `Left`.
  package :: Text -> IO (Either Text p)

  -- All Packages must be able to present their prime information
  -- in a standard way for Aura output functions.
  render :: p -> PkgInfo

{-# LANGUAGE RankNTypes #-}

data Hooks p = Hooks { info   :: Package p => Text -> IO [p]
                     , search :: Package p => Text -> IO [p]
                     , -- more to come
                     }

Total download size : xx MiB
Net upgrade size    : xx MiB

⇒ New package needed:
repository/package        1.0-1            (required by xxx) (Net change: ±xx MiB)

⇒ New package release:
repository/package        1.0-1    -->    1.0-<green>2</green> (Net change: ±xx MiB)

⇒ New package version:
repository/package        1.0-1    -->    1.<green>2-1</green> (Net change: ±xx MiB)

{-# LANGUAGE OverloadedStrings #-}

Arch Linux Specifics¶

Coding Standards¶

data Package = Package { nameOf    :: String
                       , versionOf :: Version
                       , depsOf    :: [Package] }
                       deriving (Eq, Show)

1.3.5¶

• Aura now uses version 5 of the aur package, to fix a critial bug
• Updated Spanish and Polish

1.3.4¶

• Bash parser bug fix. Fixes some packages.

1.3.3¶

• Bash parser extended to be able to handle bash array expansions. This enables packages with more (Bash-wise) complex PKGBUILDs to build properly.

1.3.2.1¶

• -Ai and -As show popularity values.
• aur4 is no longer referenced.
• Yes/No prompts are now localized.
• Aura can be built with stack.
• Updated German translation.

1.3.1.0¶

• Aura builds against GHC 7.10.
• Updated German and Russian translations.

1.3.0.4¶

• Must use –builduser when building as root.
• Bug fix regarding –needed.
• Updated Portuguese translation.

1.3.0.3¶

• Pacman flags –ignore and –ignoregroup now work.
• Bug fixes.

1.3.0.2¶

• (Bug fix) If a user tries to install a package in IgnorePkg, they will now be prompted.
• Man page updated.
• Dependencies updated.

1.3.0.1¶

• (Bug fix) Tarballs are now downloaded from a URL provided by the RPC.

1.3.0.0¶

• Last major version of Aura 1! We have entered the design phase for Aura 2, the implementation of which will transform Aura into a multi-distro package management platform.
• Aura 1 itself has entered “legacy” mode. The only releases to be made on Aura 1 after this will be of 1.3.0.x. You’ll likely never see 1.3.1.x.
• Befitting a major release, we have:
  • New AUR interaction layer via the aur package. This fixes nasty “AUR lookup failed” errors.
  • http-conduit dropped for wreq, which is much easier to use.
  • Better version number parsing/comparison on installation/upgrading.
  • Package state backups have had their format changed. This BREAKS _all_ previously saved states. Please delete your old ones!
  • Implemented extended –needed functionality for the AUR side of Aura. AUR packages won’t build if they’re already installed.
  • Indonesian translations!
  • Other updated translations.

1.2.3.4¶

• zsh completions completely redone (thanks to Sauyon Lee!) Having aur-git installed will let you auto-complete on AUR packages.

1.2.3.3¶

• -As –{head,tail} can now be passed numbers to truncate the results to any number you want. The default is 10.
• Updated Russian translation.

1.2.3.2¶

• Expanded Bash completions:

  Aura Only

  • Expanded completion for all options and search sub-options
  • Package completion for -M/–abssync
  • Completion for orphans using self-generated list

  Pacman

  • Include completion for all pacman options
  • Directory or file completion for some common options

• Use –dryrun with -A and -M install options to test everything up until actual building would occur (dependency checks, etc.)

1.2.3.1¶

• Network.HTTP.Conduit errors are now caught properly and don’t crash aura.
• customizepkg usage corrected.
• zsh completions slightly expanded.

1.2.3.0¶

• Moved to Network.HTTP.Conduit from Network.Curl This fixes the AUR connection issues. Binary size has increased by quite a bit.

1.2.2.1¶

• -Ai now shows dependencies.

1.2.2.0¶

• Happy New Year!
• makepkg’s –ignorearch flag is now visible to Aura. This allows users to build AUR packages on ARM devices without worrying about architecture restrictions in PKGBUILDs.
• Use –head and –tail to truncate -As results.
• -B now uses local time.
• Bug fixes and translation updates

1.2.1.3¶

• -As results now sort by vote. Use –abc to sort alphabetically.
• “[installed]” will now be shown in -As results if you have it.
• Fixed Bash parsing bug involving \ in arrays
• Fixed broken -C
• Updated Italian translation
• Updated French translation

1.2.1.2¶

• Happy Canadian Thanksgiving
• Bug fixes

1.2.1.1¶

• Norwegian translation added!
• Dependency checks slightly faster
• –hotedit and –custom can now be used together
• Bug fixes

1.2.1.0¶

• New builduser option
• Prelude.head bug fixed
• Dependency checking is faster
• New -k output
• –absdeps works properly now
• Other bug fixes

1.2.0.2¶

• Bug fixes and spelling corrections.

1.2.0.1¶

• Fixes dependency build order bug.

1.2.0.0¶

• New operator -M for building ABS packages. Has its own family of options.
• Pre-built binary package available (x86_64 only)
• Updates to Aura are now prioritized like pacman updates.
• Dependency checking is now faster.
• Use -Ccc to clean the cache of only packages not saved in any package record.
• -Ai now shows Maintainer name.
• Extensive API changes.

1.1.6.2¶

• New option –no-pp. Disables use of powerpill, even if you have it.
• This is a light release, as major work is being done on version 1.2 on another development branch.

1.1.6.1¶

• Compatable with pacman 4.1
• All pacman-color support removed
• -As output slightly altered to match pacman.
• Bug fixes.

1.1.6.0¶

• New option –build for specifying AUR package build path.
• Vote number now shown in -As output.
• Fixed Repo/AUR name collision bug.
• API Change: Argument order for functions in Aura/Languages changed.

1.1.5.0¶

• customizepkg now usable with Aura. Activate with the –custom option.
• API Change: Aura/Pkgbuilds now a set of libraries as Aura/Pkgbuild/*

1.1.4.3¶

• Fixed flaw in -Br.
• Fixed repititious -Ad output.
• API Change: Aura/AurConnection renamed to Aura/AUR
• API Change: function names in Aura/Languages now have better names.

1.1.4.2¶

• Haskell deps have been moved back to makedepends.
• haskell-http removed as dependency.
• API Change: function naming conventions in Aura/Languages.hs has been changed. The localisation guide was also updated to reflect this.

1.1.4.1¶

• Support for the $LANG environment variable.
• Aura will now pause before post-build installation if the package database lock exists. This means you can run multiple instances of Aura and avoid crashes.

1.1.4.0¶

• Serbian translation added. Thank you, Filip Brcic!
• Fixed bug that was breaking aura -Ss.

1.1.3.0¶

• Changed –save and –restore to -B and -Br. –save is now just an alias for -B, but –restore must be used with -B.
• New option -Bc for removing old unneeded package states.
• -Br output is now sorted better and makes more sense.
• Bash Parser can now properly parse if blocks, meaning packages that have conditional dependencies based on architecutre will now build properly.
• API Change: Aura.General is now Aura.Core
• Dep Change: haskell-url no longer needed.

1.1.2.1¶

• Added message to –save.

1.1.2.0¶

• Bash parser completely rewritten.
• Bug fixes (thanks to the new parser)

1.1.1.0¶

• New option –devel. Rebuilds all devel packages installed.
• Italian translation added! Thank you Bob Valantin!
• Support for powerpill added. It will be used if installed, unless the PACMAN variable is specifically set to something different.
• Aura can now handle PKGBUILDs that produce multiple .pkg.tar files.
• Bug fixes

1.1.0.0¶

• New –save and –restore options.
• New option -Ak for showing PKGBUILD diffs when upgrading.
• New option –aurignore for ignoring AUR packages.
• Aura now reads color.conf.
• Massive breaking API changes everywhere.
• Aura now runs on the Aura Monad.
• Code is quite cleaner now.

1.0.8.1¶

• Bash completions added.
• zsh completions added.
• Changed –conf to –viewconf
• Fixed bug involving “symlink” Haskell error.

1.0.8.0¶

• Moved certain general functions to Aura.Utils
• Moved -L, -O, -A functions out of aura.hs.
• –hotedit functionality altered (fix).
• The license message is now more badass.

1.0.7.0¶

• New libraries: Aura.Time, Aura.State
• Moved -C functionality to Aura.C
• New secret option you don’t get to find out about until 1.1
• Fixed manually alignment stupidity with -Li.
• Bug fixes

1.0.6.0¶

• New libraries: ColourDiff, Data.Algorithm.Diff, Aura.Pkgbuilds
• Aura.AuraLib split into Aura.General, Aura.Build, Aura.Dependencies
• New secret option you don’t get to find out about until 1.1

1.0.5.0¶

• Fixed bug where packages with + in their name couldn’t be searched or built.
• -As now allows multi-word searches, as it always should have.
• pacman-color integration is more complete. Still does not read the color.conf directly.

1.0.4.0¶

• Added French translation. Thanks to Ma Jiehong!
• Added Russian translation. Thanks to Kyrylo Silin!
• Fixed bug where packages with dots in their name wouldn’t build.

1.0.3.2¶

• Moved haskell dependencies out of makedepends field and into depends field in PKGBUILD. Makedepends can usually be ignored after building, but haskell packages are a pain to rebuild and reregister at every build. It’s more realistic to just keep them installed. This is what other haskell packages in the AUR do as well.
• Fixed pacman-color issues.

1.0.3.1¶

• Added –auradebug option.

1.0.3.0¶

• Compatibility with AUR 2.0 added.

• Portuguese translation added. Thanks to Henry “Ingvij” Kupty!

• Support for pacman-color added. Run sudo with -E a la:

  sudo -E aura -Ayu

• Fixed backslash parsing bug in Bash.

1.0.2.2¶

• Fixed parsing bug in Bash. If one package fell victim, a whole -Au session would fail.

1.0.2.1¶

• Added License info to source files.
• Fixed virtual package recognition bug.
• Altered version conflict error message.
• Fixed bug in Bash parser that would occasionally break parsing.

1.0.2.0¶

• Bug fixes.
• Extended the Bash parser. PKGBUILDs that had bash variables in their dependency arrays will now be parsed correctly.

1.0.1.0¶

• German translation (use with –german). Thanks to Lukas Niederbremer!
• Spanish translation (use with –spanish) Thanks to Alejandro Gómez!
• Replaced regex-posix with regex-pcre.
• -As now highlights properly.
• Moved a number of modules to Aura/

1.0.0.0¶

• Fixed -V message in terminals other than urxvt.
• New haskell-ansi-terminal library to do this.

0.10.0.0¶

• Internet access moved to Network.Curl library.

• Bash.hs library created to help with PKGBUILD parsing. Can currently handle string expansions a la:

  "this-is-{awesome,neat}" => ["this-is-awesome","this-is-neat"]
  

0.9.2.3¶

• Dependency determining speed up.
• Added AUR URL to -Ai.

0.9.3.2¶

• Swedish translation. Thanks to Fredrik Haikarainen!

0.9.2.0¶

• -Ai and -As!

0.9.1.0¶

• -Au is about 20 times faster.

0.9.?.?¶

• Polish translation. Thanks to Chris “Kwpolska” Warrick!
• Croatian translation. Thanks to Denis Kasak!

0.9.0.0¶

• New -O operation for dealing with orphan packages.
• A man page!

0.8.0.0¶

• Help message now supports multiple languages.
• Broke “no overlapping options” convention.
• -Cz is now -Cb.
• New option -Ad. Lists _all_ dependencies of an AUR package. This is to aid pre-building research. This option shows information you can’t get from looking at PKGBUILDS!

0.7.3.0¶

• New option –conf. Lets you quickly view your pacman.conf.

0.7.2.3¶

• –log is now -L.
• New option -Ls. Search the log file via a regex.
• New option -Li. Reports information on a given package that has had any appearance in the log file.

0.7.0.0¶

• –hotedit option added.
• Shell library added.

0.6.0.0¶

• Aura passes proper exit codes to the shell upon completion.

1.2.0.0¶

• The Great Abstraction
• New -M option for building packages from the ABS.
• This will make A and M run on the same backend.
• Depedency checks will be unrestricted and beautiful.

1.3.0.0¶

• Milestone for “legacy” Aura. Last stable version as a pacman-reliant AUR helper.

2.0.0.0¶

• Aura becomes a core for multi-distro package management.
• It exposes a Hook interface for writing distro-specific install behaviour.
• These Hooks may or may not bolt directly to a preexisting package manager, as Aura 1 did.
• The preferred method is to write Haskell bindings to the libraries those managers use, for more direct control.

What You Need¶

1. The aura source code. Get it at: https://github.com/aurapm/aura

2. An editor. Whichever one you like.

   Vim users, run the following easter-egg command to unlock a better version:

   :! perl -e "system('hpdfv' =~ tr/a-z/x-za-w/r)"
   

   Emacs users can achieve a similar enhanced version with:

   M-! perl -e "system('ylp' =~ tr/a-z/x-za-w/r)"
   

3. 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.

4. Minimal Haskell knowledge. You’ll see just how much below.

5. 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.

Getting Started¶

data Language = English
              | Japanese
                deriving (Eq,Enum,Show)

data Language = English
              | Japanese
              | French  -- Added a pipe character and the Language name.
                deriving (Eq,Enum,Show)

langFromEnv :: String -> Language
langFromEnv = \case
    "ja" -> Japanese
    _    -> English

langFromEnv :: String -> Language
langFromEnv = \case
    "ja" -> Japanese
    "fr" -> French
    _    -> English

-----------------
-- aura functions
-----------------
executeOpts_1 :: Language -> String
executeOpts_1 = \case
    Japanese -> "矛盾しているオプションあり。"
    _        -> "Conflicting flags given!"

SomeLanguage -> "The message."

----------------
-- aura functions
----------------
executeOpts_1 :: Language -> String
executeOpts_1 = \case
    Japanese -> "矛盾しているオプションあり。"
    French   -> "Arguments contradictoires!"
    _        -> "Conflicting flags given!"

-----------------------
-- Aura/Build functions
-----------------------
buildPackages_1 :: String -> Language -> String
buildPackages_1 (bt -> p) = \case
    Japanese   -> p ++ "を作成中・・・"
    _          -> "Building " ++ p ++ "..."

-----------------------
-- Aura/Build functions
-----------------------
buildPackages_1 :: String -> Language -> String
buildPackages_1 (bt -> p) = \case
    Japanese   -> p ++ "を作成中・・・"
    French     -> "Construction de " ++ p ++ "…"
    _          -> "Building " ++ p ++ "..."

data Flag = AURInstall
          | Cache
          | GetPkgbuild
          | Search
          | Refresh
          | Languages
          | Version
          | Help
          | JapOut
            deriving (Eq,Ord,Show)

data Flag = AURInstall
          | Cache
          | GetPkgbuild
          | Search
          | Refresh
          | Languages
          | Version
          | Help
          | JapOut
          | FrenchOut  -- Here.
            deriving (Eq,Ord,Show)

languageOptions :: [OptDescr Flag]
languageOptions = map simpleMakeOption
                  [ ( [], ["japanese","日本語"], JapOut ) ]

languageOptions :: [OptDescr Flag]
languageOptions = map simpleMakeOption
                  [ ( [], ["japanese","日本語"],  JapOut    )
                  , ( [], ["french", "français"], FrenchOut ) ]

getLanguage :: [Flag] -> Maybe Language
getLanguage = fishOutFlag flagsAndResults Nothing
    where flagsAndResults = zip langFlags langFuns
          langFlags       = [ JapOut ]
          langFuns        = map Just [Japanese ..]

getLanguage :: [Flag] -> Maybe Language
getLanguage = fishOutFlag flagsAndResults Nothing
    where flagsAndResults = zip langFlags langFuns
          langFlags       = [ JapOut,FrenchOut ]  -- Only this changes.
          langFuns        = map Just [Japanese ..]

For Haskell Study¶

Aura code has examples of:

• Monad Transformers => src/Aura/Monad/Aura.hs
• Parsec => Bash/Parser.hs - Applicative Functors => src/Bash/Parser.hs
• Regular Expressions => src/Aura/Utils.hs
• CLI flag handling => src/Aura/Flags.hs
• Shell escape codes => src/Aura/Colour/Text.hs or src/Shell.hs

For Aura Hacking¶

The main function is housed in src/aura.hs. All function dispatches occur here. General libraries also housed in the root folder:

• src/Bash/ (A custom Bash script parser and simplifier)
• src/Data/Algorithm/Diff (A classic diff algorithm)
• src/Network/HTTP (A copy of key functions from Network.HTTP)
• src/Internet (For https requests)
• src/Shell (Shell access in the IO Monad)
• src/Utilities (Random helper functions)

Aura specific libraries are housed in Aura/. The main areas are:

• src/Aura/ (General Aura-specific libraries)
• src/Aura/Commands/ (Functions that back the main capital letter Aura operations)
• src/Aura/Monad/ (Everything to do with the Aura Monad)
• src/Aura/Packages/ (Backends for handling various package types)
• src/Aura/Pkgbuild/ (Functions for handling PKGBUILDs)
• src/Aura/Settings/ (Settings for the ReaderT portion of the Aura Monad)

The Aura Monad¶

Many functions in the Aura code are within the Aura Monad. The Aura Monad is a stack of Monad Transformers, but is in essence a glorified IO Monad.

{-# LANGUAGE GeneralizedNewtypeDeriving #-}

import Control.Monad.Reader
import Control.Monad.Error

import Aura.Settings.Base (Settings)

---

newtype Aura a = A { runA :: ErrorT AuraError (ReaderT Settings IO) a }
  deriving (Monad, MonadError AuraError, MonadReader Settings, MonadIO, Functor)

runAura :: Aura a -> Settings -> IO (Either AuraError a)
runAura a = runReaderT $ runErrorT (runA a)

data AuraError = M String deriving (Eq,Show)

instance Error AuraError where
    noMsg  = strMsg "No error message given."
    strMsg = M

The Aura Monad is an ErrorT at the top, meaning its binding (>>=) behaviour is the same as an Error Monad. This allows failure to halt actions partway through.

It is a ReaderT and has a MonadReader instance, meaning we can obtain the local runtime settings by using the ask function anywhere we wish in a function within the Aura Monad.

It is IO at its base and has a MonadIO instance, meaning we can perform IO actions with liftIO in any function in the Aura Monad. To extract it’s inner value, we use the helper function runAura.

foo :: Whatever -> Aura Whatever
foo w = ask >>= \ss -> do
  ...  -- Rest of the function.

-- For example, if I only need the cache path from Settings...
foo :: Whatever -> Aura Whatever
foo w = asks cachePathOf >>= \path -> do
  ...  -- Rest of the function.

String Dispatching¶

No Strings meant for user-viewed output are hardcoded. All current translations of all Strings are kept in Aura/Languages.hs. Messages are fetched by helper functions after being passed the current runtime Language stored in Settings. This leads to:

1. More advanced String manipulation, regardless of spoken language.
2. More convenient translation work.
3. (Unfortunately) larger executable size.

See the Language Localisation Guide for more information.

New with Version 1.1¶

• --save option. Stores a record of all installed packages.
• --restore option. Restores a state stored with --save. Good for reversing system breakage.
• -k suboption of -A. Shows PKGBUILD diffs when installing / upgrading.
• --aurignore option. Ignores given AUR packages when installing / upgrading.
• Bash and zsh completions now available.
• Aura now reads pacman-color’s /etc/pacman.d/color.conf if available. This affects the colours in -Ai and -As.
• Aura now stores the most recent PKGBUILD when installing a package. This is so -Ak has something to diff with when upgrading next.
• Much cleaner code.

On the Horizon¶

• Fish completions.
• Reworked PKGBUILD parser.
• Haskell binding to libalpm.

A big thanks to all of Aura’s users! I couldn’t have got this far without your support.

Aura Github Page Aura Bitbucket Page Aura AUR Page Aura Wiki Page