diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.gitignore | 1 | ||||
| -rw-r--r-- | doc/Makefile.am | 7 | ||||
| -rw-r--r-- | doc/PKGBUILD.5.txt | 46 | ||||
| -rw-r--r-- | doc/footer.txt | 3 | ||||
| -rw-r--r-- | doc/index.txt | 3 | ||||
| -rw-r--r-- | doc/makepkg.8.txt | 9 | ||||
| -rw-r--r-- | doc/makepkg.conf.5.txt | 17 | ||||
| -rw-r--r-- | doc/pacman.8.txt | 134 | ||||
| -rw-r--r-- | doc/pacman.conf.5.txt | 16 | ||||
| -rw-r--r-- | doc/repo-add.8.txt | 12 | ||||
| -rw-r--r-- | doc/vercmp.8.txt | 71 |
11 files changed, 229 insertions, 90 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index f047aaa9..a6f4df7f 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -6,6 +6,7 @@ pacman.8 pacman.conf.5 repo-add.8 repo-remove.8 +vercmp.8 *.css *.html *.xml diff --git a/doc/Makefile.am b/doc/Makefile.am index c2391b71..00a0e88d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -7,6 +7,7 @@ ASCIIDOC_MANS = \ pacman.8 \ makepkg.8 \ repo-add.8 \ + vercmp.8 \ PKGBUILD.5 \ makepkg.conf.5 \ pacman.conf.5 \ @@ -18,6 +19,7 @@ HTML_MANPAGES = \ pacman.8.html \ makepkg.8.html \ repo-add.8.html \ + vercmp.8.html \ PKGBUILD.5.html \ makepkg.conf.5.html \ pacman.conf.5.html \ @@ -38,6 +40,7 @@ EXTRA_DIST = \ pacman.8.txt \ makepkg.8.txt \ repo-add.8.txt \ + vercmp.8.txt \ PKGBUILD.5.txt \ PKGBUILD-example.txt \ makepkg.conf.5.txt \ @@ -60,7 +63,7 @@ dist-hook: $(MAKE) $(AM_MAKEFLAGS) all if USE_GIT_VERSION -GIT_VERSION := $(shell sh -c 'git describe --abbrev=4 | sed s/^v//')-dirty +GIT_VERSION := $(shell sh -c 'git describe --abbrev=4 --dirty | sed s/^v//') REAL_PACKAGE_VERSION = $(GIT_VERSION) else REAL_PACKAGE_VERSION = $(PACKAGE_VERSION) @@ -96,6 +99,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 = \ @@ -128,6 +132,7 @@ $(HTML_OTHER): asciidoc.conf pacman.8 pacman.8.html: pacman.8.txt makepkg.8 makepkg.8.html: makepkg.8.txt repo-add.8 repo-add.8.html: repo-add.8.txt +vercmp.8 vercmp.8.html: vercmp.8.txt PKGBUILD.5 PKGBUILD.5.html: PKGBUILD.5.txt PKGBUILD-example.txt makepkg.conf.5 makepkg.conf.5.html: makepkg.conf.5.txt pacman.conf.5 pacman.conf.5.html: pacman.conf.5.txt diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index 8bdb3c69..c0fa5948 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -45,12 +45,12 @@ similar to `$_basekernver`. *pkgver*:: The version of the software as released from the author (e.g. '2.7.1'). - The variable is not allowed to contain hyphens. + The variable is not allowed to contain colons or hyphens. *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/footer.txt b/doc/footer.txt index 8290f3c4..2ffb0092 100644 --- a/doc/footer.txt +++ b/doc/footer.txt @@ -18,13 +18,14 @@ Authors Current maintainers: +* Allan McRae <allan@archlinux.org> * Dan McGee <dan@archlinux.org> * Xavier Chantry <shiningxc@gmail.com> -* Aaron Griffin <aaron@archlinux.org> Past contributors: * Judd Vinet <jvinet@zeroflux.org> * Aurelien Foret <aurelien@archlinux.org> +* Aaron Griffin <aaron@archlinux.org> See the 'AUTHORS' file for additional contributors. diff --git a/doc/index.txt b/doc/index.txt index 3741c81e..0e037ac6 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -43,6 +43,7 @@ configuration files dealing with pacman. * linkman:pacman[8] * linkman:pacman.conf[5] * linkman:repo-add[8] +* linkman:vercmp[8] Changelog ~~~~~~~~~ @@ -194,7 +195,7 @@ Pacman/libalpm frontends: Copyright --------- -pacman is Copyright (C) 2006-2010 Pacman Development Team +pacman is Copyright (C) 2006-2011 Pacman Development Team <pacman-dev@archlinux.org> and Copyright (C) 2002-2006 Judd Vinet <jvinet@zeroflux.org> and is licensed through the GNU General Public License, version 2 or later. 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..8f91e408 100644 --- a/doc/pacman.8.txt +++ b/doc/pacman.8.txt @@ -79,6 +79,11 @@ 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, version strings can have an 'epoch' value defined that will +overrule any version comparison (unless the epoch values are equal). This is +specified in an `epoch:version-rel` format. For example, `2:1.0-1` is always +greater than `1:3.6-1`. *-T, \--deptest*:: Check dependencies; this is useful in scripts such as makepkg to check @@ -104,35 +109,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 +127,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 +151,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 +169,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 +296,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 +384,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 +416,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 diff --git a/doc/repo-add.8.txt b/doc/repo-add.8.txt index 81bf8377..75f49ef5 100644 --- a/doc/repo-add.8.txt +++ b/doc/repo-add.8.txt @@ -10,7 +10,7 @@ repo-add - package database maintenance utility Synopsis -------- -repo-add [-q] <path-to-db> <package1> [<package2> ...] +repo-add [-d] [-f] [-q] <path-to-db> <package1> [<package2> ...] repo-remove [-q] <path-to-db> <packagename> [<packagename2> ...] @@ -30,11 +30,19 @@ on the command line. Options ------- +*-d, \--delta*:: + Automatically generate and add a delta file between the old entry and the + new one, if the old package file is found next to the new one. + +*-f, \--files*:: + Tells repo-add also to create and include a list of the files in the + specified packages. This is useful for creating databases listing all files + in a given sync repository for tools that may use this information. + *-q, \--quiet*:: Force this program to keep quiet and run silent except for warning and error messages. - See Also -------- linkman:makepkg[8], linkman:pacman[8] diff --git a/doc/vercmp.8.txt b/doc/vercmp.8.txt new file mode 100644 index 00000000..f2fc5305 --- /dev/null +++ b/doc/vercmp.8.txt @@ -0,0 +1,71 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +vercmp(8) +========= + +Name +---- +vercmp - version comparsion utility + + +Synopsis +-------- +'vercmp' <version1> <version2> + + +Description +----------- +'vercmp' is used to determine the relationship between two given version +numbers. It outputs values as follows: + +* < 0 : if ver1 < ver2 +* = 0 : if ver1 == ver2 +* > 0 : if ver1 > ver2 + +Version comparsion operates as follows: + + Alphanumeric: + 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, version strings can have an 'epoch' value defined that will +overrule any version comparison (unless the epoch values are equal). This is +specified in an `epoch:version-rel` format. For example, `2:1.0-1` is always +greater than `1:3.6-1`. + + +Options +------- +*-h, \--help*:: + Display syntax for the given operation. If no operation was supplied + then the general syntax is shown. + +Examples +-------- + + $ vercmp 1 2 + -1 + + $ vercmp 2 1 + 1 + + $ vercmp 2.0-1 1.7-6 + 1 + + $ vercmp 2.0 2.0-13 + 0 + + $ vercmp 4.34 1:001 + -1 + +Configuration +------------- +There is none. + +See Also +-------- +linkman:pacman[8], linkman:makepkg[8], linkman:libalpm[3] + +include::footer.txt[] |