summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am1
-rw-r--r--doc/PKGBUILD.5.txt44
-rw-r--r--doc/makepkg.8.txt9
-rw-r--r--doc/makepkg.conf.5.txt17
-rw-r--r--doc/pacman.8.txt132
-rw-r--r--doc/pacman.conf.5.txt16
6 files changed, 135 insertions, 84 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 2e656f61..748eb5fc 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -96,6 +96,7 @@ ASCIIDOC_OPTS = \
-a pacman_version="$(REAL_PACKAGE_VERSION)" \
-a pacman_date="`date +%Y-%m-%d`" \
-a pkgdatadir=$(pkgdatadir) \
+ -a localstatedir=$(localstatedir) \
-a sysconfdir=$(sysconfdir)
A2X_OPTS = \
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
index 8bdb3c69..e6c4a1fb 100644
--- a/doc/PKGBUILD.5.txt
+++ b/doc/PKGBUILD.5.txt
@@ -50,7 +50,7 @@ similar to `$_basekernver`.
*pkgrel*::
This is the release number specific to the Arch Linux release. This
allows package maintainers to make updates to the package's configure
- flags, for example. A pkgrel of 1 is typically used for each upstream
+ flags, for example. A pkgrel of '1' is typically used for each upstream
software release and is incremented for intermediate PKGBUILD updates. The
variable is not allowed to contain hyphens.
@@ -58,6 +58,15 @@ similar to `$_basekernver`.
This should be a brief description of the package and its functionality.
Try to keep the description to one line of text.
+*epoch*::
+ Used to force the package to be seen as newer than any previous versions
+ with a lower epoch, even if the version number would normally not trigger
+ such an upgrade. This value is required to be a positive integer; the
+ default value if left unspecified is '0'. This is useful when the version
+ numbering scheme of a package changes (or is alphanumeric), breaking normal
+ version comparison logic. See linkman:pacman[8] for more information on
+ version comparisons.
+
*url*::
This field contains a URL that is associated with the software being
packaged. This is typically the project's website.
@@ -147,6 +156,12 @@ name. The syntax is: `source=('filename::url')`.
needed at runtime. Packages in this list follow the same format as
depends.
+*checkdepends (array)*::
+ An array of packages that this package depends on to run its test suite,
+ but are not needed at runtime. Packages in this list follow the same
+ format as depends. These dependencies are only considered when the
+ check() function is present and is to be run by makepkg.
+
*optdepends (array)*::
An array of packages (and accompanying reasons) that are not essential for
base functionality, but may be necessary to make full use of the contents
@@ -186,8 +201,8 @@ name. The syntax is: `source=('filename::url')`.
in the options array. To reverse the default behavior, place an ``!'' at
the front of the option. Only specify the options you specifically want
to override, the rest will be taken from linkman:makepkg.conf[5].
- *NOTE:* 'force' is a special option only used in a linkman:PKGBUILD[5],
- do not use it unless you know what you are doing.
+ *NOTE:* 'force' is a now-removed option in favor of the top level 'epoch'
+ variable.
*strip*;;
Strip symbols from binaries and libraries. If you frequently
@@ -218,19 +233,18 @@ name. The syntax is: `source=('filename::url')`.
form `!distcc` with select packages that have problems building
with distcc.
+ *buildflags*;;
+ Allow the use of user-specific buildflags (CFLAGS, CXXFLAGS, LDFLAGS)
+ during build as specified in linkman:makepkg.conf[5]. More useful in
+ its negative form `!buildflags` with select packages that have problems
+ building with custom buildflags.
+
*makeflags*;;
Allow the use of user-specific makeflags during build as specified
in linkman:makepkg.conf[5]. More useful in its negative form
`!makeflags` with select packages that have problems building with
custom makeflags such as `-j2` (or higher).
- *force*;;
- Force the package to be upgraded by a pacman system upgrade
- operation, even if the version number would normally not trigger
- such an upgrade. This is useful when the version numbering scheme
- of a package changes (or is alphanumeric). See linkman:pacman[8] for
- more information on version comparisons.
-
build() Function
----------------
@@ -261,10 +275,18 @@ If you create any variables of your own in the build function, it is
recommended to use the bash `local` keyword to scope the variable to inside
the build function.
+check() Function
+----------------
+An optional check() function can be specified in which a packages test-suite
+may be run. This function is run between the build() and package() functions.
+The function is run in `bash -e` mode, meaning any command that exits with a
+non-zero status will cause the function to exit. Be sure any exotic commands
+used are covered by `checkdepends`.
+
package() Function
------------------
An optional package() function can be specified in addition to the build()
-function. This function is run immediately after the build() function. The
+function. This function is run after the build() and check() functions. The
function is run in `bash -e` mode, meaning any command that exits with a
non-zero status will cause the function to exit. When specified in combination
with the fakeroot BUILDENV option in linkman:makepkg.conf[5], fakeroot usage
diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt
index a2fdb3f3..3b83015e 100644
--- a/doc/makepkg.8.txt
+++ b/doc/makepkg.8.txt
@@ -53,7 +53,7 @@ Options
in linkman:makepkg.conf[5].
*--config* <`/path/to/config`>::
- Use an alternate config file instead of the `/etc/makepkg.conf` default;
+ Use an alternate config file instead of the `{sysconfdir}/makepkg.conf` default;
*-d, \--nodeps*::
Do not perform any dependency checks. This will let you override and
@@ -153,6 +153,13 @@ Options
Only build listed packages from a split package. The use of quotes is
necessary when specifying multiple packages. e.g. `--pkg "pkg1 pkg3"`
+*\--check*::
+ Run the check() function in the PKGBUILD, overriding the setting in
+ linkman:makepkg.conf[5].
+
+*\--nocheck*::
+ Do not run the check() function in the PKGBUILD or handle the checkdepends.
+
*\--noconfirm*::
(Passed to pacman) Prevent pacman from waiting for user input before
proceeding with operations.
diff --git a/doc/makepkg.conf.5.txt b/doc/makepkg.conf.5.txt
index 753b1792..020804cb 100644
--- a/doc/makepkg.conf.5.txt
+++ b/doc/makepkg.conf.5.txt
@@ -93,6 +93,11 @@ Options
be disabled for individual packages by placing `!ccache` in the
PKGBUILD options array.
+ *check*;;
+ Run the check() function if present in the PKGBUILD. This can be
+ enabled or disabled for individual packages through the use of
+ makepkg's `--check` and `--nocheck` options respectively.
+
**DISTCC_HOSTS=**"host1 ..."::
If using DistCC, this is used to specify a space-delimited list of hosts
running in the DistCC cluster. In addition, you will want to modify your
@@ -160,13 +165,6 @@ Options
that are located in opt/, you may need to add the directory to this
array. *NOTE:* Do not add the leading slash to the directory name.
-**STRIP_DIRS=(**bin lib sbin usr/{bin,lib} ...**)**::
- If `strip` is specified in the OPTIONS array, this variable will
- instruct makepkg where to look to for files to strip. If you build
- packages that are located in opt/, you may need to add the directory
- to this array. *NOTE:* Do not add the leading slash to the directory
- name.
-
**PURGE_TARGETS=(**usr/{,share}/info/dir .podlist *.pod...**)**::
If `purge` is specified in the OPTIONS array, this variable will
instruct makepkg which files to remove from the package. This is
@@ -192,10 +190,11 @@ Options
This value is used when querying a package to see who was the builder.
It is recommended you change this to your name and email address.
-*PKGEXT*, *SRCEXT*::
+**PKGEXT=**".pkg.tar.gz", **SRCEXT=**".src.tar.gz"::
+ Sets the compression used when making compiled or source packages. The
+ current valid suffixes are `.tar`, `.tar.gz`, `.tar,bz2` and `.tar.xz`.
Do not touch these unless you know what you are doing.
-
See Also
--------
linkman:makepkg[8], linkman:pacman[8], linkman:PKGBUILD[5]
diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt
index 3d14a42a..2b47a88c 100644
--- a/doc/pacman.8.txt
+++ b/doc/pacman.8.txt
@@ -79,6 +79,9 @@ to determine which packages need upgrading. This behavior operates as follows:
1.0a < 1.0alpha < 1.0b < 1.0beta < 1.0p < 1.0pre < 1.0rc < 1.0
Numeric:
1 < 1.0 < 1.1 < 1.1.1 < 1.2 < 2.0 < 3.0.0
++
+Additionally, packages can have an 'epoch' value defined that will override any
+version comparison and force an upgrade.
*-T, \--deptest*::
Check dependencies; this is useful in scripts such as makepkg to check
@@ -104,35 +107,12 @@ to determine which packages need upgrading. This behavior operates as follows:
Options
-------
-*\--asdeps*::
- Install packages non-explicitly; in other words, fake their install reason
- to be installed as a dependency. This is useful for makepkg and other
- build from source tools that need to install dependencies before building
- the package.
-
-*\--asexplicit*::
- Install packages explicitly; in other words, fake their install reason to
- be explicitly installed. This is useful if you want to mark a dependency
- as explicitly installed so it will not be removed by the '\--recursive'
- remove operation.
-
*-b, \--dbpath* <'path'>::
Specify an alternative database location (a typical default is
- ``/var/lib/pacman''). This should not be used unless you know what you are
+ ``{localstatedir}/lib/pacman''). This should not be used unless you know what you are
doing. *NOTE*: if specified, this is an absolute path and the root path is
not automatically prepended.
-*-d, \--nodeps*::
- Skips all dependency checks. Normally, pacman will always check a
- package's dependency fields to ensure that all dependencies are
- installed and there are no package conflicts in the system.
-
-*-f, \--force*::
- Bypass file conflict checks and overwrite conflicting files. If the
- package that is about to be installed contains files that are already
- installed, this option will cause all those files to be overwritten.
- This option should be used with care, ideally not at all.
-
*-r, \--root* <'path'>::
Specify an alternative installation root (default is ``/''). This should
not be used as a way to install software into ``/usr/local'' instead of
@@ -145,19 +125,22 @@ Options
*-v, \--verbose*::
Output paths such as as the Root, Conf File, DB Path, Cache Dirs, etc.
-*\--debug*::
- Display debug messages. When reporting bugs, this option is recommended
- to be used.
+*\--arch* <'arch'>::
+ Specify an alternate architecture.
*\--cachedir* <'dir'>::
Specify an alternative package cache location (a typical default is
- ``/var/cache/pacman/pkg''). Multiple cache directories can be specified,
+ ``{localstatedir}/cache/pacman/pkg''). Multiple cache directories can be specified,
and they are tried in the order they are passed to pacman. *NOTE*: this
is an absolute path, the root path is not automatically prepended.
*\--config* <'file'>::
Specify an alternate configuration file.
+*\--debug*::
+ Display debug messages. When reporting bugs, this option is recommended
+ to be used.
+
*\--logfile* <'file'>::
Specify an alternate log file. This is an absolute path, regardless of
the installation root setting.
@@ -166,6 +149,16 @@ Options
Bypass any and all ``Are you sure?'' messages. It's not a good idea to do
this unless you want to run pacman from a script.
+Transaction Options (apply to '-S', '-R' and '-U')
+--------------------------------------------------
+*-d, \--nodeps*::
+ Skips all dependency checks. Normally, pacman will always check a
+ package's dependency fields to ensure that all dependencies are
+ installed and there are no package conflicts in the system.
+
+*-k, \--dbonly*::
+ Adds/Removes the database entry only, leaves all files in place.
+
*\--noprogressbar*::
Do not show a progress bar when downloading files. This can be useful
for scripts that call pacman and capture the output.
@@ -174,19 +167,46 @@ Options
If an install scriptlet exists, do not execute it. Do not use this
unless you know what you are doing.
-*\--arch* <'arch'>::
- Specify an alternate architecture.
-
*-p, \--print*::
Only print the targets instead of performing the actual operation (sync,
- remove or upgrade). Use '\--print-format' to specify how targets are
- displayed. The default format string is "%l", which displays url with '-S',
- filename with '-U' and pkgname-pkgver with '-R'.
+ remove or upgrade). Use '\--print-format' to specify how targets are
+ displayed. The default format string is "%l", which displays url with
+ '-S', filename with '-U' and pkgname-pkgver with '-R'.
*\--print-format* <'format'>::
Specify a printf-like format to control the output of the '\--print'
- operation. The possible are attributes are : %n for pkgname, %v for pkgver, %l
- for location, %r for repo and %s for size.
+ operation. The possible are attributes are : %n for pkgname, %v for pkgver,
+ %l for location, %r for repo and %s for size.
+
+Upgrade Options (apply to 'S' and 'U')[[UO]]
+--------------------------------------------
+*-f, \--force*::
+ Bypass file conflict checks and overwrite conflicting files. If the
+ package that is about to be installed contains files that are already
+ installed, this option will cause all those files to be overwritten.
+ This option should be used with care, ideally not at all.
+
+*\--asdeps*::
+ Install packages non-explicitly; in other words, fake their install reason
+ to be installed as a dependency. This is useful for makepkg and other
+ build from source tools that need to install dependencies before building
+ the package.
+
+*\--asexplicit*::
+ Install packages explicitly; in other words, fake their install reason to
+ be explicitly installed. This is useful if you want to mark a dependency
+ as explicitly installed so it will not be removed by the '\--recursive'
+ remove operation.
+
+*\--ignore* <'package'>::
+ Directs pacman to ignore upgrades of package even if there is one
+ available. Multiple packages can be specified by separating them
+ with a comma.
+
+*\--ignoregroup* <'group'>::
+ Directs pacman to ignore upgrades of all packages in 'group' even if
+ there is one available. Multiple groups can be specified by
+ separating them with a comma.
Query Options[[QO]]
-------------------
@@ -274,9 +294,6 @@ Remove Options[[RO]]
or more target packages. This operation is recursive, and must be used
with care since it can remove many potentially needed packages.
-*-k, \--dbonly*::
- Removes the database entry only. Leaves all files in place.
-
*-n, \--nosave*::
Instructs pacman to ignore file backup designations. Normally, when a
file is removed from the system the database is checked to see if the
@@ -365,24 +382,6 @@ linkman:pacman.conf[5].
*\--needed*::
Don't reinstall the targets that are already up-to-date.
-*\--ignore* <'package'>::
- Directs pacman to ignore upgrades of package even if there is one
- available. Multiple packages can be specified by separating them
- with a comma.
-
-*\--ignoregroup* <'group'>::
- Directs pacman to ignore upgrades of all packages in 'group' even if
- there is one available. Multiple groups can be specified by
- separating them with a comma.
-
-
-Upgrade Options[[UO]]
---------------------
-*-k, \--dbonly*::
- Adds the database entries for the specified packages but do not install any
- of the files. On an upgrade operation, the existing package and all files
- will be removed and the database entry for the new package will be added.
-
Handling Config Files[[HCF]]
----------------------------
@@ -415,6 +414,25 @@ original=X, current=Y, new=Z::
necessary changes into the original file.
+Examples
+--------
+
+pacman -Ss ne.hack::
+ Search for regexp "ne.hack" in package database.
+
+pacman -S gpm::
+ Download and install gpm including dependencies.
+
+pacman -U /home/user/ceofhack-0.6-1-x86_64.pkg.tar.gz::
+ Install ceofhack-0.6-1 package from a local file.
+
+pacman -Syu::
+ Update package list and upgrade all packages afterwards.
+
+pacman -Syu gpm::
+ Update package list, upgrade all packages, and then install gpm if it
+ wasn't already installed.
+
Configuration
-------------
See linkman:pacman.conf[5] for more details on configuring pacman using the
diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt
index 0e8426af..ae4d7484 100644
--- a/doc/pacman.conf.5.txt
+++ b/doc/pacman.conf.5.txt
@@ -35,7 +35,7 @@ NoUpgrade = etc/passwd etc/group etc/shadow
NoUpgrade = etc/fstab
[core]
-Include = /etc/pacman.d/core
+Include = {sysconfdir}/pacman.d/core
[custom]
Server = file:///home/pkgs
@@ -57,13 +57,13 @@ Options
*DBPath =* path/to/db/dir::
Overrides the default location of the toplevel database directory. A
- typical default is ``/var/lib/pacman/''. Most users will not need to set
+ typical default is ``{localstatedir}/lib/pacman/''. Most users will not need to set
this option. *NOTE*: if specified, this is an absolute path and the root
path is not automatically prepended.
*CacheDir =* path/to/cache/dir::
Overrides the default location of the package cache directory. A typical
- default is ``/var/cache/pacman/pkg/''. Multiple cache directories can be
+ default is ``{localstatedir}/cache/pacman/pkg/''. Multiple cache directories can be
specified, and they are tried in the order they are listed in the config
file. If a file is not found in any cache directory, it will be downloaded
to the first cache directory with write access. *NOTE*: this is an absolute
@@ -72,7 +72,7 @@ Options
*LogFile =* '/path/to/file'::
Overrides the default location of the pacman log file. A typical default
- is ``/var/log/pacman.log''. This is an absolute path and the root directory
+ is ``{localstatedir}/log/pacman.log''. This is an absolute path and the root directory
is not prepended.
*HoldPkg =* package ...::
@@ -147,7 +147,7 @@ Options
*UseSyslog*::
Log action messages through syslog(). This will insert log entries into
- ``/var/log/messages'' or equivalent.
+ ``{localstatedir}/log/messages'' or equivalent.
*ShowSize*::
Display the size of individual packages for '\--sync' and '\--query' modes.
@@ -162,6 +162,10 @@ Options
than the percent of each individual download target. The progress
bar is still based solely on the current file download.
+*CheckSpace*::
+ Performs an approximate check for adequate available disk space before
+ installing packages.
+
Repository Sections
-------------------
Each repository section defines a section name and at least one location where
@@ -180,7 +184,7 @@ contain a file that lists the servers for that repository.
# use this repository first
Server = ftp://ftp.archlinux.org/core/os/arch
# next use servers as defined in the mirrorlist below
-Include = /etc/pacman.d/mirrorlist
+Include = {sysconfdir}/pacman.d/mirrorlist
--------
During parsing, pacman will define the `$repo` variable to the name of the