diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 1 | ||||
| -rw-r--r-- | doc/PKGBUILD.5.txt | 44 | ||||
| -rw-r--r-- | doc/makepkg.8.txt | 9 | ||||
| -rw-r--r-- | doc/makepkg.conf.5.txt | 17 | ||||
| -rw-r--r-- | doc/pacman.8.txt | 132 | ||||
| -rw-r--r-- | doc/pacman.conf.5.txt | 16 |
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 |