[arch-projects] [ABS] [RFC] abs(8)

[matt mooney]

abs(8)
======
:doctype: manpage
:man source: abs
:man manual: ABS Manual
:man version: %%ABS_VERSION%%


Name
----
abs - the Arch Build System utility


SYNOPSIS
--------
[verse]
'abs'  [-h] [--version] [--abs-root=<path>]
     [--build-dir=<path>] [--pkg-dir=<path>]
     [--noconfirm]
     <command>... [<pkgspec>...]


Description
-----------
*`abs`* is a utility used to interact with the 'Arch Build System', *ABS*(7). It
provides a rich set of commands to facilitate building packages from source
code.

The *``ABS tree''* contains the PKGBUILDs used by Arch Linux for creating
packages: it is a snapshot of the official package database and the central
structure with which *`abs`* operates. `abs` allows full or partial
synchronization of the ABS tree through a `<pkgspec>`.

Every `abs` '<command>' takes zero or more `<pkgspec>` arguments. Each
`<pkgspec>` defines a nonempty set of packages. The union of `<pkgspec>s` is
known as the *working set* for that invocation of `abs`. If a `<pkgspec>` is not
given, the *working set* is generated entirely from the configuration variables
set in 'abs.conf'.

The Package Specification
~~~~~~~~~~~~~~~~~~~~~~~~~
A '<pkgspec>' is composed of three parts: an architecture (``<arch>''), a
repository (``<repo>''), and a package name (``<pkg>''). The fully specified
`<pkgspec>` is `<arch>/<repo>/<pkg>`; however, *`abs`* can deduce the
`<pkgspec>` from variables set in the configuration file. Valid package
specifications are *`<pkg>`*, *`<repo>/<pkg>`*, and *`<arch>/<repo>/<pkg>`*.

When a `<pkgspec>` is not fully specified, the *`repos`* variable determines the
precedence of the repositories to search, and the *`arch`* variable determines
which architectures to include.

Please see *abs.conf*(5) for more details.


Options
-------
*-h, --help*::
	Print the synopsis and command list.

*--version*::
	Print the ABS version and exit.

*--abs-root*=<path>::
	Path to the ABS tree.

*--build-dir*=<path>::
	Path to the build directory.

*--pkg-dir*=<path>::
	Path to the directory where packages will be output.

*--noconfirm*::
	Bypass all confirmation messages generated by *`pacman`*.


Commands
--------
*build*::
	Build packages in the *ABS tree*. The 'ABS files' for each package in
	the *working set* are copied into a subdirectory and built; moreover,
	missing dependencies are automatically added to the *working set* and
	treated as if they were explicitly included. Files created during the
	build process are stored within a subdirectory named for the package and
	will *not* be overwritten across builds. The resulting packages will be
	in *`pkgdir`*. '%%ABS_BUILD_DIR%%' is provided for building packages,
	but you can use a different build directory.

	*-b, --builddeps*;;
		Build missing dependencies. The 'default' setting.

	*-d, --nodeps*;;
		Do not perform dependency checks. A build failure will occur if
		build dependencies are missing (i.e., *`makedepends`* is not
		empty).

	*-f, --force*;;
		Recopy ABS files to the build directory. This overwrites the old
		package subdirectory.

	*-s, --syncdeps*;;
		Install missing dependencies using *`pacman`*.

*clean*::
	Clean the build directory. The files created during the build process
	are removed from each package in the build directory.

	*-p, --package*;;
		Revert patches to the ABS files and source code.

*install*::
	Install packages. The packages will be installed using *`pacman`*, which
	should be used for further management operations. All packages found in
	the *`pkgdir`* that are newer than an installed version will be
	reinstalled.

*patch*::
	Apply patches to packages in the *ABS tree*. Packages that are not
	already in the build directory will be retrieved, accordingly. The 'ABS
	files' are copied into a subdirectory and patched; next, the source code
	will be downloaded and patched. If a package in the *working set* has
	formerly been patched, it will be skipped.
// The following line is needed to get the correct indentation!!
 +
	The patches must be in the unified format and located under
	*`patchdir`*; the default is '%%ABS_PATCH_DIR%%'. This should consist of
	subdirectories containing the patches. Each subdirectory is to be named
	after the package to which its patches will be applied.
// The following line is needed to get the correct indentation!!
 +
	The PKGBUILD patch must be named *PKGBUILD.patch*; the remaining patches
	must end in *.patch* and be for the packages source code. The patches
	are applied from the source directory in an unspecified manner. (A
	patch series may be supported in the future!)

*sync*::
	Synchronize the *ABS tree* with the current snapshot. It allows full or
	partial syncing of repositories; however, it overwrites the part of the
	ABS tree that is newly synced. Without arguments, the *`pkgs`* in
	*`repos`* are synchronized. If the user running this command does not
	have write access to the ABS root directory, the command will fail.

	*-r, --rsync*;;
		Synchronize the ABS tree using rsync. The *`syncserver`* must be
		running '`rsyncd`'. This is the 'default' method.

	*-t, --tarball*;;
		Synchronize the ABS tree using a tarball. The first functioning
		server in *`mirrorlist`* that contains the ABS tarball will be
		used.

NOTE: When synchronizing the *ABS tree*, only one of the two methods can be used
at a time. The options are mutually exclusive and an error will occur if both
options are given.


Examples
--------
A sample workflow to build and install *`abs`*:

*abs sync x86_64/extra/abs*::
	Sync the *ABS tree* with only the abs package.

*abs patch x86_64/extra/abs*::
	Add my innovative patch set.

*abs build x86_64/extra/abs*::
	Build the package.

*abs install x86_64/extra/abs*::
	Install the package.

*abs clean x86_64/extra/abs*::
	Clean the build directory but leave my innovative patch set applied.

This is quite a tedious process for a single package. Fortunately, *`abs`*
supports chaining the commands together.

*abs sync patch build install clean x86_64/extra/abs*::
	One caveat though, the order of the commands is important but not
	enforced.


Environment
-----------
*ABS_ROOT*::
	The path to the *ABS tree*. Overrides the value set in
	'%%ABS_CONF_FILE%%' and can also be set with `--abs-root`.

*ABS_BUILD_DIR*::
	The path to the ABS build directory. Overrides the value set in
	'%%ABS_CONF_FILE%%' and can also be set with `--build-dir`.


Files
-----
*%%ABS_ROOT%%*::
	The default location of the ABS tree.

*%%ABS_CONF_FILE%%*::
	System-wide configuration file. The configuration variables and file
	format are described in *abs.conf*(5).


See Also
--------
*abs.conf*(5), *ABS*(7), *PKGBUILD*(5),


include::footer.txt[]