path: root/README.pod

=encoding utf8

=head1 NAME

pacpur - a PUR helper that minimizes user interaction

=head1 SYNOPSIS

Usage: I<pacpur> E<lt>operationE<gt> [ options ] [ target(s) ]

=head1 DESCRIPTION

Pacpur is an Parabola User Repository (PUR) helper aiming at speed and simplicity
and is designed to minimize user prompt interaction. It is a fork of the Pacpur
program, customized to recommend only FSDG-fit software. It uses an uncluttered
interface and makes use of the full secured RPC interface to solve the dependency
tree. It will also automatically prompt for sudo access when needed. It is built
upon the well designed auracle C++ and expac C backends.

Invoking pacpur consists of supplying an operation, any applicable options, and
usually one or more targets. A I<target> is usually a package name or a search
string.

=head1 USERBASE TARGET

Pacpur is targeted at B<advanced users> who want some degree of automation for
repetitive tasks. As such, the user is expected to be familiar with the PUR
manual build process with makepkg and its configuration options, as well as
being knowledgeable about sudo and gpg configuration.

Two sets of command line options are provided: commands which call the pacman
binary and extend it with PUR functions B<(-S, -Ss, -Si, -Sw, -Su, -Qu, -Sc, -Scc)>,
and I<-p/--pur> can be added to only apply these to the PUR. As such, pacpur can be
used by users who prefer to have a single tool to manage the officialand PUR
repositories, or by users who prefer to keep their PUR frontend separated from pacman.

=head1 OPERATIONS

=head2 Pacman extension operations

=over 4

=item B<-S, -Ss, -Si, -Sw, -Su, -Qu, -Sc, -Scc>

Pacpur wraps all B<pacman operations> and by default extends respectively its
sync, search, info, download only, system upgrade, upgrades check, clean and
clean all functions to the PUR. This extension behavior is optional and can be
disabled with the I<-r/--repo> flag, and used with the variable set with the
I<-p/--pur> flag. Pacpur will also pass any other pacman operations and their
related options to the pacman binary.

=back

=head2 General operations

=over 4

=item B<-v, --version>

Display version and quit.

=item B<-h, --help>

Display the help message and quit.

=back

=head1 OPTIONS

=head2 Pacman extension options

=over 4

=item B<-p, --pur>

When used with pacman extended operations, only search, build, install, upgrade
or clean I<target(s)> from the PUR.

=item B<-r, --repo>

When used with pacman extended operations, only search, build, install, upgrade
or clean I<target(s)> from the repositories.

=back

=head2 General options

=over 4

=item B<-e, --edit>

Edit build files when cloning or building I<target(s)>. Overrides the
I<displaybuildfiles> config option and always fully shows the build files.
Can also be used as a standalone command.

=item B<-q, --quiet>

Show less information for search and query operations. Search will only show
package names and not version, group, and description information.

=item B<--devel>

When used with upgrade and check operations, also consider PUR development
packages. Supported are I<cvs>, I<svn>, I<git>, I<hg>, I<bzr> and I<darcs>
development packages, as well as I<daily> and I<nightly> build packages.

=item B<--foreign>

When used with buildonly, sync and upgrade operations, also consider already
installed foreign dependencies when solving the dependency tree.

=item B<--ignore> I<target(s)>

Ignore a I<target> upgrade. Can be used more than once. Also accepts a comma
delimited list as a single argument. Packages listed in pacman's
I<IgnorePkg> directive are honored.

=item B<--needed>

Do not reinstall I<target(s)> that are already up-to-date. The build of
development packages that are found up-to-date after the source checkout will
be skipped. Supported are I<svn>, I<git>, I<hg> and I<bzr> development
packages, as well as I<daily> and I<nightly> build packages.

=item B<--noconfirm>

Perform commands without confirmation from the user.

=item B<--noedit>

Perform commands without editing any installation files. Overrides the
I<--edit> option.
=item B<--rebuild>

Always rebuild packages regardless of any existing file in I<$PKGDEST> directory,
and regardless of up-to-date status of development packages.

=item B<--silent>

Silence output. This will send the output of each packaging functions to text
files in the clone directory named I<pkgname-pkgver-pkgrel-arch-function.log>.
Additional pacman output for providers and cached packages installation will
also be hidden.

=back

=head2 Search options

=over 4

=item B<--by> <FIELD>, B<--searchby> <FIELD>

When searching the PUR, search by I<FIELD> where I<FIELD> is B<name>, B<name-desc>,
or B<maintainer> to search for packages by their name, name and description, or by
the package maintainer, respectively. The default is to search by name-desc.

=item B<--literal>

When searching the PUR, disable regex search and interpret target as a literal
string.

=item B<--sort> <KEY>, B<--rsort> <KEY>

When searching the PUR, sort the results in ascending or descending order,
respectively, by I<KEY> where I<KEY> is B<name>, B<votes> or B<popularity>.

=back

=head1 CONFIG FILE

=over 4

=item B<system config>

Pacpur honors a system-wide config file which will be looked for first at

  $XDG_CONFIG_DIRS/pacpur/config

and falling back to

  /etc/xdg/pacpur/config

=item B<user config>

User-defined configuration files overriding the general settings will be looked
for first at

  $XDG_CONFIG_HOME/pacpur/config

and falling back to

  $HOME/.config/pacpur/config

=back

=head1 CONFIG OPTIONS

The available options are:

=over 4

=item B<editor>

Define the editor. Default is B<$VISUAL>, with a fallback on B<$EDITOR> and I<nano>.

=item B<displaybuildfiles>

Display PKGBUILD and install script viewing prompt. Possible values are I<full>
to always display the full build files, I<diff> to only display the difference
since last build, and I<none> to disable the viewing prompt. Default is B<diff>.

=item B<silent>

Enable silent output. The makepkg output will be collected in the clone directory
or the I<$LOGDEST> directory should any error occur. Default is B<false>.

=item B<sortby>

When searching the PUR, sort the results by I<name>, number of I<votes> or
I<popularity>. Default is B<popularity>.

=item B<sortorder>

When searching the PUR, sort the results in I<ascending> or I<descending> order.
Default is B<descending>.

=item B<sudoloop>

Prevent sudo timeout. This option overrides the system-wide I<passwd_timeout>
sudo configuration and refreshes the sudo timestamp automatically in a loop when
building packages. Default is B<true>.

=back

=head1 ENVIRONMENT

=over 4

=item B<PURDEST>

Determines where the packages build files (PKGBUILD, .SRCINFO and install script
files) will be cloned. The I<-Sc> and I<-Scc> clean operations allow to remove
the untracked cloned files and the non locally installed cloned files, and all
cloned files, respectively.

If this environment variable is not defined, the clone directory will be set to

  $XDG_CACHE_HOME/pacpur

with a fall back to

  $HOME/.cache/pacpur

=item B<makeopts>

Internally used variable for passing options to makepkg, can be set externally to
add flags for pacpur to always pass to makepkg, such as I<-A>, which ignores the
arch field in a PKGBUILD to allow for building on other architectures regardless of
if that architecture has been added to the arch field

=back

In addition, makepkg environment variables are fully honored. See B<makepkg>(8).
In particular, the following variables are useful:

=over 4

=item B<PKGDEST>

Determines where the built packages will be stored. If using the existing
I</var/cache/pacman/pkg> pacman cache directory, ensure your user has proper
write permissions. Additionally, if added to the I<CacheDir> path option of
I<pacman.conf>, the I<-Sc> and I<-Scc> clean operations will enable removal of
non locally installed cached files and all cached files, respectively.

=item B<SRCDEST>

Determines where the source of packages will be stored. This will speed up the
upgrade of development packages. The I<-Sc> and I<-Scc> clean operations allow
to remove the non development packages source files and all source files,
respectively.

=item B<LOGDEST>

Determines where the build logs will be stored. By default, the I<--silent>
option will write build logs in the clone directory if the build fails, but
will remove them if the build succeeds.

=item B<BUILDDIR>

Determines where the packages will be built. By default, build will happen in
the defined clone directory, but build speed can be improved by using I</tmp>
located in volatile memory. This is however not recommended if big packages
need to be built on a low-memory machine.

=back

=head1 NOTES

=over 4

=item B<sudo configuration>

To be used with minimal password prompting, I<sudo> should be configured
accordingly to allow sudo access. See B<sudoers>(5). If you disable the
I<sudoloop> config option, you might also want to disable the I<passwd_timeout>
sudo parameter to avoid password prompt timeout.

=item B<pacman misc options>

Miscellaneous options enabled in I<pacman.conf> are taken into account. Thus,
colored output can be enabled with the I<Color> option, while a detailed interface
displaying name, version and size of packages formatted as a table is available
through the I<VerbosePkgLists> option.

=item B<build files comparison>

To allow build files comparison, the I<displaybuildfiles> default config option
is set to I<diff>. Although the clone directory (set by default to
I<$XDG_CACHE_HOME/pacpur>) can be changed through the alternative I<$PURDEST>
environment variable, it should always be set to a persistent location.

=item B<interactive PKGBUILDs>

Packages requiring user input while building are not supported and might fail
to install properly. There is currently no official directive about these
interactive PKGBUILDs, but some of the official pacman developers expressed
the opinion that PKGBUILDs should always provide default compilation options.

=item B<host name error>

If a lot of "Could not connect to the PUR" and "Timeout was reached" messages
are displayed while searching or requesting info for packages despite the
internet connection working correctly, ensure your local I<DNS server> is
correctly configured to improve name lookups. Using Google's primary DNS
(8.8.8.8 and 8.8.4.4) might also help.

=back

=head1 SEE ALSO

B<auracle>(1), B<pacman>(8), B<makepkg>(8), B<sudoers>(5)

=head1 MAINTAINER

The Parabola Team <assist@lists.parabola.nu>

=head1 UPSTREAM MAINTAINER

E5ten E<lt>e5ten.arch@gmail.comE<gt>

https://github.com/E5ten/pacaur

=head1 ORIGINAL AUTHOR

Remy Marquis E<lt>remy.marquis@gmail.comE<gt>

If you feel great pity for the present maintainer that has to constantly cope
with users that don't want to read man pages and refuse to take responsibility
for their own system, you can send me funny cat pictures. Alternatively, you
can send a donation via PayPal to the above email address.

I would also suggest to donate to a charitable organization of your choice
should you believe that your money could make a bigger difference there.
Thank you!

All credits go to all direct or indirect contributors. Many thanks to all of
you!

=head1 TRANSLATORS

B<[ca] - Català> - Alex "alexhenrie" Henrie

B<[da] - Dansk> - Filip "filipkemuel" Kemuel

B<[de] - Deutsch> - Marco "BigBoot" Kirchner, "HerrNieschnell", "pszalanski", Stefan "rumpelsepp" Tatschner, Tilman "Tblue" Blumenbach

B<[es] - Español> - Germán "gosella" Osella Massa, Ismael "ChuckDaniels87" González, Pablo "jristz" Lezaeta Reyes

B<[fi] - Suomi> - "durazell"

B<[fr] - Français> - "spider-mario", "Neitsab", Antoine "Nevax07" Gravelot

B<[hu] - Magyar> - "avelkei"

B<[it] - Italiano> - Demenico "NoMore201" Lezzi, Giovanni "ItachiSan" Santini

B<[ja] - 日本語> - Colin "fosskers" Woodbury, TSUYUSATO "MakeNowJust" Kitsune

B<[nl] - Nederlands> - "Yoshi2889", Willem "14mRh4X0r" Mulder

B<[pl] - Polski> - Tomasz "Ludvick" Niedzielski

B<[pt] - Português> - Thiago "thiagowfx" Barroso Perrotta, Rafael "rccavalcanti" Cavalcanti

B<[ru] - Русский> - "kyak"

B<[sk] - Slovenčina> - Pavol "pakapusta" Kapusta, Juraj "DoctorJellyface" Fiala

B<[sl] - Slovenščina> - Žan "tofiffe" Skamljič

B<[sr] - Српски / srpski> - Slobodan "Faenriis" Terzić

B<[tr] - Türkçe> - Volkan "wakeup" Gezer

B<[zh_CN] - 简体中文> - "Victorique "victoriqueko" Ko, kizayoi"