diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.gitignore | 2 | ||||
| -rw-r--r-- | doc/Makefile.am | 8 | ||||
| -rw-r--r-- | doc/PKGBUILD.5.txt | 141 | ||||
| -rw-r--r-- | doc/footer.txt | 2 | ||||
| -rw-r--r-- | doc/index.txt | 12 | ||||
| -rw-r--r-- | doc/libalpm.3.txt | 2 | ||||
| -rw-r--r-- | doc/makepkg.8.txt | 40 | ||||
| -rw-r--r-- | doc/makepkg.conf.5.txt | 32 | ||||
| -rw-r--r-- | doc/pacman-key.8.txt | 100 | ||||
| -rw-r--r-- | doc/pacman.8.txt | 22 | ||||
| -rw-r--r-- | doc/pacman.conf.5.txt | 121 | ||||
| -rw-r--r-- | doc/pkgdelta.8.txt | 42 | ||||
| -rw-r--r-- | doc/repo-add.8.txt | 57 | ||||
| -rw-r--r-- | doc/submitting-patches.txt | 6 | ||||
| -rw-r--r-- | doc/translation-help.txt | 34 | ||||
| -rw-r--r-- | doc/vercmp.8.txt | 2 |
16 files changed, 479 insertions, 144 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index a6f4df7f..a7f33e55 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -3,7 +3,9 @@ libalpm.3 makepkg.8 makepkg.conf.5 pacman.8 +pacman-key.8 pacman.conf.5 +pkgdelta.8 repo-add.8 repo-remove.8 vercmp.8 diff --git a/doc/Makefile.am b/doc/Makefile.am index e8f6df09..4fb57803 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -8,6 +8,8 @@ ASCIIDOC_MANS = \ makepkg.8 \ repo-add.8 \ vercmp.8 \ + pkgdelta.8 \ + pacman-key.8 \ PKGBUILD.5 \ makepkg.conf.5 \ pacman.conf.5 \ @@ -20,6 +22,8 @@ HTML_MANPAGES = \ makepkg.8.html \ repo-add.8.html \ vercmp.8.html \ + pkgdelta.8.html \ + pacman-key.8.html \ PKGBUILD.5.html \ makepkg.conf.5.html \ pacman.conf.5.html \ @@ -41,6 +45,8 @@ EXTRA_DIST = \ makepkg.8.txt \ repo-add.8.txt \ vercmp.8.txt \ + pkgdelta.8.txt \ + pacman-key.8.txt \ PKGBUILD.5.txt \ PKGBUILD-example.txt \ makepkg.conf.5.txt \ @@ -134,6 +140,8 @@ 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 +pkgdelta.8 pkgdelta.8.html: pkgdelta.8.txt +pacman-key.8 pacman-key.8.html: pacman-key.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 ab49f7b7..af3a3880 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -1,5 +1,5 @@ ///// -vim:set ts=4 sw=4 syntax=asciidoc noet: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// PKGBUILD(5) =========== @@ -16,12 +16,12 @@ PKGBUILD Description ----------- -This manual page is meant to describe general rules about PKGBUILDs. Once a +This manual page describes general rules about PKGBUILDs. Once a PKGBUILD is written, the actual package is built using makepkg and installed with pacman. -NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'. -Also located there are other example files such as a ChangeLog and an install +NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}' +along with other example files such as a ChangeLog and an install script. You can copy the provided PKGBUILD.proto file to a new package build directory and make customizations to suit your needs. @@ -30,33 +30,33 @@ Options and Directives ---------------------- The following is a list of standard options and directives available for use in a PKGBUILD. These are all understood and interpreted by makepkg, and most -will be directly transferred to the built package. +of them will be directly transferred to the built package. If you need to create any custom variables for use in your build process, it is -recommended to name your custom variables with an '_' (underscore) prefix. +recommended to prefix their name with an '_' (underscore). This will prevent any possible name clashes with internal makepkg variables. For example, to store the base kernel version in a variable, use something similar to `$_basekernver`. *pkgname (array)*:: - The name of the package. This has be a unix-friendly name as it will be - used in the package filename. Members of the array are not allowed to start - with hyphens. + Either the name of the package or an array of names for split packages. + Because it will be used in the package filename, this has to be unix-friendly. + Members of the array are not allowed to start with hyphens. *pkgver*:: - The version of the software as released from the author (e.g. '2.7.1'). + The version of the software as released from the author (e.g., '2.7.1'). 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 - software release and is incremented for intermediate PKGBUILD updates. The + flags, for example. This is typically set to '1' for each new upstream + software release and incremented for intermediate PKGBUILD updates. The variable is not allowed to contain hyphens. *pkgdesc*:: This should be a brief description of the package and its functionality. - Try to keep the description to one line of text. + Try to keep the description to one line of text and not use the package's name. *epoch*:: Used to force the package to be seen as newer than any previous versions @@ -69,50 +69,49 @@ similar to `$_basekernver`. *url*:: This field contains a URL that is associated with the software being - packaged. This is typically the project's website. + packaged. Typically the project's website. *license (array)*:: This field specifies the license(s) that apply to the package. - Commonly-used licenses are found in '/usr/share/licenses/common'. If you + Commonly used licenses can be found in '/usr/share/licenses/common'. If you see the package's license there, simply reference it in the license - field (e.g. `license=('GPL')`). If the package provides a license not - found in '/usr/share/licenses/common', then you should include the license + field (e.g., `license=('GPL')`). If the package provides a license not + available in '/usr/share/licenses/common', then you should include it in the package itself and set `license=('custom')` or `license=('custom:LicenseName')`. The license should be placed in - '$pkgdir/usr/share/licenses/$pkgname' when building the package. If - multiple licenses are applicable for a package, list all of them: + '$pkgdir/usr/share/licenses/$pkgname/' when building the package. If + multiple licenses are applicable, list all of them: `license=('GPL' 'FDL')`. *install*:: Specifies a special install script that is to be included in the package. This file should reside in the same directory as the PKGBUILD, and will be copied into the package by makepkg. It does not need to be included - in the source array (e.g. `install=pkgname.install`). + in the source array (e.g., `install=pkgname.install`). *changelog*:: Specifies a changelog file that is to be included in the package. This file should reside in the same directory as the PKGBUILD, and will be copied into the package by makepkg. It does not need to be included - in the source array (e.g. `changelog=$pkgname.changelog`). + in the source array (e.g., `changelog=$pkgname.changelog`). *source (array)*:: An array of source files required to build the package. Source files - must either reside in the same directory as the PKGBUILD file, or be a - fully-qualified URL that makepkg will use to download the file. In order - to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver - variables if possible when specifying the download location. Any files - that are compressed will automatically be extracted, unless found in - the noextract array listed below. + must either reside in the same directory as the PKGBUILD, or be a + fully-qualified URL that makepkg can use to download the file. + To make the PKGBUILD as useful as possible, use the `$pkgname` and `$pkgver` + variables if possible when specifying the download location. Compressed files + will be extracted automatically unless found in + the noextract array described below. + -It is also possible to specify an optional filename, which is helpful +It is also possible to change the name of the downloaded file, which is helpful with weird URLs and for handling multiple source files with the same name. The syntax is: `source=('filename::url')`. *noextract (array)*:: An array of filenames corresponding to those from the source array. Files listed here will not be extracted with the rest of the source files. This - is useful for packages which use compressed data which is downloaded but - not necessary to uncompress. + is useful for packages that use compressed data directly. *md5sums (array)*:: This array contains an MD5 hash for every source file specified in the @@ -133,31 +132,36 @@ name. The syntax is: `source=('filename::url')`. example, one could install all KDE packages by installing the 'kde' group. *arch (array)*:: - Defines on which architectures the given package is available (e.g. + Defines on which architectures the given package is available (e.g., `arch=('i686' 'x86_64')`). Packages that contain no architecture specific - files may use arch=('any'). + files should use arch=('any'). *backup (array)*:: - A space-delimited array of filenames, without preceding slashes, that + An array of filenames, without preceding slashes, that should be backed up if the package is removed or upgraded. This is commonly used for packages placing configuration files in /etc. See Handling Config Files in linkman:pacman[8] for more information. *depends (array)*:: - An array of packages that this package depends on to run. Packages in + An array of packages this package depends on to run. Entries in this list should be surrounded with single quotes and contain at least the package name. Entries can also include a version requirement of the form 'name<>version', where <> is one of five comparisons: >= (greater than or equal to), <= (less than or equal to), = (equal to), > (greater than), or < (less than). ++ +If the dependency name appears to be a library (ends with .so), makepkg will +try to find a binary that depends on the library in the built package and +append the version needed by the binary. Appending the version yourself +disables auto detection. *makedepends (array)*:: - An array of packages that this package depends on to build, but are not + An array of packages this package depends on to build but are not 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, + An array of packages 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. @@ -177,7 +181,7 @@ name. The syntax is: `source=('filename::url')`. same format as depends. Versioned conflicts are also supported. *provides (array)*:: - An array of ``virtual provisions'' that this package provides. This allows + An array of ``virtual provisions'' this package provides. This allows a package to provide dependencies other than its own package name. For example, the dcron package can provide 'cron', which allows packages to depend on 'cron' rather than 'dcron OR fcron'. @@ -186,9 +190,13 @@ name. The syntax is: `source=('filename::url')`. dependency of other packages. Provisions involving the '>' and '<' operators are invalid as only specific versions of a package may be provided. ++ +If the provision name appears to be a library (ends with .so), makepkg will +try to find the library in the built package and append the correct +version. Appending the version yourself disables auto detection. *replaces (array)*:: - An array of packages that this package should replace, and can be used + An array of packages this package should replace. This can be used to handle renamed/combined packages. For example, if the 'j2re' package is renamed to 'jre', this directive allows future upgrades to continue as expected even though the package has moved. Sysupgrade is currently @@ -223,6 +231,9 @@ name. The syntax is: `source=('filename::url')`. *zipman*;; Compress man and info pages with gzip. + *upx*;; + Compress binary executable files using UPX. + *ccache*;; Allow the use of ccache during build. More useful in its negative form `!ccache` with select packages that have problems building @@ -248,27 +259,27 @@ name. The syntax is: `source=('filename::url')`. build() Function ---------------- -In addition to the above directives, the optional build() bash function usually +In addition to the above directives, the optional build() function usually comprises the remainder of the PKGBUILD. This is directly sourced and executed by makepkg, so anything that bash or the system has available is available for use here. 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 `makedepends`. -All of the above variables such as `pkgname` and `pkgver` are available for use -in the build function. In addition, makepkg defines three variables for your -use during the build and install process. These three variables are as follows: +All of the above variables such as `$pkgname` and `$pkgver` are available for use +in the build function. In addition, makepkg defines the following three +variables for use during the build and install process: *startdir*:: - This contains the absolute path to the directory where the PKGBUILD was + This contains the absolute path to the directory where the PKGBUILD is located, which is usually the output of `$(pwd)` when makepkg is started. *srcdir*:: - This points to the directory where makepkg extracts or copies all source + This contains the directory where makepkg extracts, or copies, all source files. *pkgdir*:: - This points to the directory where makepkg bundles the installed package + This contains the directory where makepkg bundles the installed package (this directory will become the root directory of your built package). If you create any variables of your own in the build function, it is @@ -301,9 +312,9 @@ Each split package uses a corresponding packaging function with name `package_foo()`, where `foo` is the name of the split package. All options and directives for the split packages default to the global values -given within the PKGBUILD. However, some of these can be overridden within each -split package's packaging function. The following variables can be overridden: -`pkgver`, `pkgrel`, `pkgdesc`, `arch`, `license`, `groups`, `depends`, +given in the PKGBUILD. Nevertheless, the following ones can be overridden within +each split package's packaging function: +`pkgver`, `pkgrel`, `epoch`, `pkgdesc`, `arch`, `license`, `groups`, `depends`, `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, `options`, `install` and `changelog`. @@ -321,31 +332,37 @@ Pacman has the ability to store and execute a package-specific script when it installs, removes, or upgrades a package. This allows a package to configure itself after installation and perform an opposite action upon removal. -The exact time the script is run varies with each operation: +The exact time the script is run varies with each operation, and should be +self-explanatory. Note that during an upgrade operation, none of the install +or remove scripts will be called. + +Scripts are passed either one or two ``full version strings'', where a full +version string is either 'pkgver-pkgrel' or 'epoch:pkgver-pkgrel' if epoch is +non-zero. *pre_install*:: - script is run right before files are extracted. One argument is passed: - new package version. + Run right before files are extracted. One argument is passed: + new package full version string. *post_install*:: - script is run right after files are extracted. One argument is passed: - new package version. + Run right after files are extracted. One argument is passed: + new package full version string. *pre_upgrade*:: - script is run right before files are extracted. Two arguments are passed - in the following order: new package version, old package version. + Run right before files are extracted. Two arguments are passed in this + order: new package full version string, old package full version string. *post_upgrade*:: - script is run after files are extracted. Two arguments are passed - in the following order: new package version, old package version. + Run after files are extracted. Two arguments are passed in this order: + new package full version string, old package full version string. *pre_remove*:: - script is run right before files are removed. One argument is passed: - old package version. + Run right before files are removed. One argument is passed: + old package full version string. *post_remove*:: - script is run right after files are removed. One argument is passed: - old package version. + Run right after files are removed. One argument is passed: + old package full version string. To use this feature, create a file such as 'pkgname.install' and put it in the same directory as the PKGBUILD script. Then use the install directive: @@ -363,7 +380,7 @@ makepkg supports building development versions of packages without having to manually update the pkgver in the PKGBUILD. This was formerly done using the separate utility 'versionpkg'. In order to utilize this functionality, your PKGBUILD must use correct variable names depending on the SCM being fetched -from. +from (e.g., 'makepkg-git', 'mplayer-svn'). *CVS*:: The generated pkgver will be the date the package is built. diff --git a/doc/footer.txt b/doc/footer.txt index 2ffb0092..a1325427 100644 --- a/doc/footer.txt +++ b/doc/footer.txt @@ -1,5 +1,5 @@ ///// -vim:set ts=4 sw=4 syntax=asciidoc noet: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// See the pacman website at http://www.archlinux.org/pacman/[] for current diff --git a/doc/index.txt b/doc/index.txt index c04ca8a9..5fd3f3bc 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -41,7 +41,9 @@ configuration files dealing with pacman. * linkman:makepkg[8] * linkman:makepkg.conf[5] * linkman:pacman[8] +* linkman:pacman-key[8] * linkman:pacman.conf[5] +* linkman:pkgdelta[8] * linkman:repo-add[8] * linkman:vercmp[8] @@ -105,9 +107,9 @@ link:ftp://ftp.archlinux.org/other/pacman/[]. To install, download the newest available source tarball, unpack it in a directory, and run the three magic commands: - $ ./configure - $ make - # make install + $ ./configure + $ make + # make install You may wish to read the options presented by `./configure --help` in order to set appropriate paths and build options that are correct for your system. @@ -130,7 +132,7 @@ these trees). The current development tree can be fetched with the following command: - git clone git://projects.archlinux.org/pacman.git pacman + git clone git://projects.archlinux.org/pacman.git pacman which will fetch the full development history into a directory named pacman. You can browse the source as well using @@ -204,5 +206,5 @@ pacman is Copyright (C) 2006-2011 Pacman Development Team version 2 or later. ///// -vim: set ts=2 sw=2 syntax=asciidoc et: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// diff --git a/doc/libalpm.3.txt b/doc/libalpm.3.txt index b7a892c7..e2ea32c0 100644 --- a/doc/libalpm.3.txt +++ b/doc/libalpm.3.txt @@ -1,5 +1,5 @@ ///// -vim:set ts=4 sw=4 syntax=asciidoc noet: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// libalpm(3) ========== diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt index 57d6f6eb..3206a906 100644 --- a/doc/makepkg.8.txt +++ b/doc/makepkg.8.txt @@ -1,5 +1,5 @@ ///// -vim:set ts=4 sw=4 syntax=asciidoc noet: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// makepkg(8) ========== @@ -11,24 +11,24 @@ makepkg - package build utility Synopsis -------- -makepkg [options] +'makepkg' [options] Description ----------- -makepkg is a script to automate the building of packages. The requirements for +'makepkg' is a script to automate the building of packages. The requirements for using the script are a build-capable \*nix platform and a custom build script for each package you wish to build (known as a PKGBUILD). See linkman:PKGBUILD[5] for details on creating your own build scripts. The advantage to a script-based build is that the work is only done once. Once -you have the build script for a package, makepkg will do the rest: download and +you have the build script for a package, 'makepkg' will do the rest: download and validate source files, check dependencies, configure the build-time settings, build the package, install the package into a temporary root, make customizations, generate meta-info, and package the whole thing up for pacman to use. -NOTE: makepkg uses your current locale by default and does not unset it when +NOTE: 'makepkg' uses your current locale by default and does not unset it when building packages. If you wish to share your build output with others when seeking help or for other purposes, you may wish to run "`LC_ALL=C makepkg`" so your logs and output are not localized. @@ -48,10 +48,6 @@ Options *-c, \--clean*:: Clean up leftover work files and directories after a successful build. -*-C, \--cleancache*:: - Removes all cached source files from the directory specified in `SRCDEST` - in linkman:makepkg.conf[5]. - *\--config* <file>:: Use an alternate config file instead of the +{sysconfdir}/makepkg.conf+ default. @@ -89,7 +85,13 @@ Options using "`makepkg -g >> PKGBUILD`". *--skipinteg*:: - Do not perform any integrity checks, just print a warning instead. + Do not perform any integrity checks (checksum and PGP) on source files. + +*\--skipchecksums*:: + Do not verify checksums of source files. + +*\--skippgpcheck*:: + Do not verify PGP signatures of source files. *-h, \--help*:: Output syntax and command line options. @@ -151,8 +153,7 @@ Options all source files of the package need to be present or downloadable. *\--pkg <list>*:: - Only build listed packages from a split package. The use of quotes is - necessary when specifying multiple packages. e.g. `--pkg "pkg1 pkg3"` + Only build listed packages from a split package. *\--check*:: Run the check() function in the PKGBUILD, overriding the setting in @@ -161,6 +162,18 @@ Options *\--nocheck*:: Do not run the check() function in the PKGBUILD or handle the checkdepends. +*\--sign*:: + Sign the resulting package with gpg, overriding the setting in + linkman:makepkg.conf[5]. + +*\--nosign*:: + Do not create a signature for the built package. + +*\--key* <key>:: + Specify a key to use when signing packages, overriding the GPGKEY setting + in linkman:makepkg.conf[5]. If not specified in either location, the + default key from the keyring will be used. + *\--noconfirm*:: (Passed to pacman) Prevent pacman from waiting for user input before proceeding with operations. @@ -194,6 +207,9 @@ Environment Variables Folder where the downloaded sources will be stored. Overrides the corresponding value defined in linkman:makepkg.conf[5]. +**BUILDDIR=**"/path/to/folder":: + Folder where the package will be built. Overrides the corresponding + value defined in linkman:makepkg.conf[5]. Configuration ------------- diff --git a/doc/makepkg.conf.5.txt b/doc/makepkg.conf.5.txt index 30ddf0a6..a0ea2d77 100644 --- a/doc/makepkg.conf.5.txt +++ b/doc/makepkg.conf.5.txt @@ -1,5 +1,5 @@ ///// -vim:set ts=4 sw=4 syntax=asciidoc noet: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// makepkg.conf(5) =============== @@ -70,7 +70,7 @@ Options This is often used to set the number of jobs used, for example, `-j2`. Other flags that make accepts can also be passed. -**BUILDENV=(**fakeroot !distcc color !ccache check**)**:: +**BUILDENV=(**fakeroot !distcc color !ccache check !sign**)**:: This array contains options that affect the build environment, the defaults are shown here. All options should always be left in the array; to enable or disable an option simply remove or place an ``!'' at the front of the @@ -98,12 +98,31 @@ Options enabled or disabled for individual packages through the use of makepkg's `--check` and `--nocheck` options respectively. + *sign*;; + Generate a PGP signature file using GnuPG. This will execute `gpg + --detach-sign --use-agent` on the built package to generate a detached + signature file, using the GPG agent if it is available. The signature + file will be the entire filename of the package with a ``.sig'' + extension. + **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 `MAKEFLAGS`. -**OPTIONS=(**strip !docs libtool emptydirs zipman**)**:: +**BUILDDIR=**"/path/to/folder":: + If this value is not set, packages will by default be built in + subdirectories of the directory that makepkg is called from. This + option allows setting the build location to another folder. + Incorrect use of `$startdir` in a PKGBUILD may cause building with + this option to fail. + + +**GPGKEY=**"":: + Specify a key to use for gpg signing instead of the default key in the + keyring. Can be overridden with makepkg's `--key` option. + +**OPTIONS=(**strip docs libtool emptydirs zipman purge !upx**)**:: This array contains options that affect the default packaging. They are equivalent to options that can be placed in the PKGBUILD; the defaults are shown here. All options should always be left in the array; to enable or @@ -135,6 +154,10 @@ Options Remove files specified by the `PURGE_TARGETS` variable from the package. + *upx*;; + Compress binary executable files using UPX. Additional options + can be passed to UPX by specifying the `UPXFLAGS` variable. + **INTEGRITY_CHECK=(**check1 ...**)**:: File integrity checks to use. Multiple checks may be specified; this affects both generation and checking. The current valid options are: @@ -192,7 +215,8 @@ Options **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`. + current valid suffixes are `.tar`, `.tar.gz`, `.tar,bz2`, `.tar.xz`, and + `.tar.Z`. Do not touch these unless you know what you are doing. See Also diff --git a/doc/pacman-key.8.txt b/doc/pacman-key.8.txt new file mode 100644 index 00000000..c8ce0264 --- /dev/null +++ b/doc/pacman-key.8.txt @@ -0,0 +1,100 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +pacman-key(8) +============= + + +Name +---- +pacman-key - manage pacman's list of trusted keys + + +Synopsis +-------- +'pacman-key' [options] + + +Description +----------- +'pacman-key' is a wrapper script for GnuPG used to manage pacman's keyring, which +is the collection of PGP keys used to check signed packages and databases. It +provides the ability to import and export keys, fetch keys from keyservers and +update the key trust database. + +More complex keyring management can be achieved using GnuPG directly combined with +the `--homedir` option pointing at the pacman keyring (located in ++{sysconfdir}/pacman.d/gnupg+ by default). + + +Options +------- +*-a, \--add* [file(s)]:: + Add the key(s) contained in the specified file or files to pacman's + keyring. If a key already exists, update it. + +*\--config* <file>:: + Use an alternate config file instead of the +{sysconfdir}/pacman.conf+ + default. + +*-d, \--delete* <keyid(s)>:: + Remove the key(s) identified by the specified keyid(s) from pacman's + keyring. + +*-e, \--export* [keyid(s)]:: + Export key(s) identified by the specified keyid(s) to 'stdout'. If no keyid + is specified, all keys will be exported. + +*\--edit-key * <keyid(s)>:: + Present a menu for key management task on the specified keyids. Useful for + adjusting a keys trust level. + +*-f, \--finger* [keyid(s)]:: + List a fingerprint for each specified keyid, or for all known keys if no + keyids are specified. + +*\--gpgdir* <dir>:: + Set an alternate home directory for GnuPG. If unspecified, the value is + read from +{sysconfdir}/pacman.conf+. + +*-h, \--help*:: + Output syntax and command line options. + +*--import* <dir(s)>:: + Adds keys from pubring.gpg into pacman's keyring and imports ownertrust + values from trustdb.gpg in the specified directories. + +*--import-dirs* <dir(s)> :: + Imports ownertrust values from trustdb.gpg in the specified directories. + +*--init*:: + Ensure the keyring is properly initialized and has the required access + permissions. + +*-l, \--list-keys* [keyid(s)]:: + Lists all or specified keys from the public keyring. + +*--list-sigs* [keyid(s)]:: + Same as --list-keys, but the signatures are listed too. + +*-r, \--receive* <keyserver> <keyid(s)>:: + Fetch the specified keyids from the specified key server URL. + +*\--reload*:: + Reloads the keys from the keyring package. + +*-u, \--updatedb*:: + Equivalent to \--check-trustdb in GnuPG. + +* -v, \--verify* <signature>:: + Verify the given signature file. + +*-V, \--version*:: + Displays the program version. + + +See Also +-------- +linkman:pacman[8], linkman:pacman.conf[5] + +include::footer.txt[] diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt index a4d41d0e..3240022d 100644 --- a/doc/pacman.8.txt +++ b/doc/pacman.8.txt @@ -1,5 +1,5 @@ ///// -vim:set ts=4 sw=4 syntax=asciidoc noet: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// pacman(8) ========= @@ -13,7 +13,6 @@ Synopsis -------- 'pacman' <operation> [options] [targets] - Description ----------- Pacman is a package management utility that tracks installed packages on a Linux @@ -69,13 +68,18 @@ Operations interprets ">" as redirection to file.) + In addition to packages, groups can be specified as well. For example, if -gnome is a defined package group, then `pacman -S gnome` will install every -package in the gnome group, as well as the dependencies of those packages. +gnome is a defined package group, then `pacman -S gnome` will provide a +prompt allowing you to select which packages to install from a numbered list. +The package selection is specified using a space separated list of package +numbers. Sequential packages may be selected by specifying the first and last +package numbers separated by a hyphen (`-`). Excluding packages is achieved by +prefixing a number or range of numbers with a caret (`^`). + Packages that provide other packages are also handled. For example, `pacman -S foo` will first look for a foo package. If foo is not found, packages that provide the same functionality as foo will be searched for. If any package is -found, it will be installed. +found, it will be installed. A selection prompt is provided if multiple packages +providing foo are found. + You can also use `pacman -Su` to upgrade all packages that are out of date. See <<SO,Sync Options>> below. When upgrading, pacman performs version comparison @@ -149,6 +153,14 @@ Options Display debug messages. When reporting bugs, this option is recommended to be used. +*\--gpgdir* <dir>:: + Specify a directory of files used by GnuPG to verify package signatures (a + typical default is +{sysconfdir}/pacman.d/gnupg+). This directory should contain + two files: `pubring.gpg` and `trustdb.gpg`. `pubring.gpg` holds the public keys + of all packagers. `trustdb.gpg` contains a so-called trust database, which + specifies that the keys are authentic and trusted. *NOTE*: this is an absolute + path, the root path is not automatically prepended. + *\--logfile* <file>:: Specify an alternate log file. This is an absolute path, regardless of the installation root setting. diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt index dcaeed7f..e793e78b 100644 --- a/doc/pacman.conf.5.txt +++ b/doc/pacman.conf.5.txt @@ -1,5 +1,5 @@ ///// -vim:set ts=4 sw=4 syntax=asciidoc noet: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// pacman.conf(5) ============== @@ -69,6 +69,15 @@ Options to the first cache directory with write access. *NOTE*: this is an absolute path, the root path is not automatically prepended. +*GPGDir =* path/to/gpg/dir:: + Overrides the default location of the directory containing configuration + files for GnuPG. A typical default is +{sysconfdir}/pacman.d/gnupg/+. + This directory should contain two files: `pubring.gpg` and `trustdb.gpg`. + `pubring.gpg` holds the public keys of all packagers. `trustdb.gpg` + contains a so-called trust database, which specifies that the keys are + authentic and trusted. + *NOTE*: this is an absolute path, the root path is not automatically + prepended. *LogFile =* '/path/to/file':: Overrides the default location of the pacman log file. A typical default @@ -147,13 +156,14 @@ Options packages are only cleaned if not installed locally and not present in any known sync database. +*SigLevel =* ...:: + Set the default signature verification level. For more information, see + <<SC,Package and Database Signature Checking>> below. + *UseSyslog*:: Log action messages through syslog(). This will insert log entries into +{localstatedir}/log/messages+ or equivalent. -*ShowSize*:: - Display the size of individual packages for '\--sync' and '\--query' modes. - *UseDelta*:: Download delta files instead of complete packages if possible. Requires the xdelta3 program to be installed. @@ -168,6 +178,10 @@ Options Performs an approximate check for adequate available disk space before installing packages. +*VerbosePkgLists*:: + Displays name, version and size of target packages formatted + as a table for upgrade, sync and remove operations. + Repository Sections ------------------- Each repository section defines a section name and at least one location where @@ -183,27 +197,99 @@ contain a file that lists the servers for that repository. -------- [core] -# use this repository first -Server = ftp://ftp.archlinux.org/core/os/arch +# use this server first +Server = ftp://ftp.archlinux.org/$repo/os/$arch # next use servers as defined in the mirrorlist below Include = {sysconfdir}/pacman.d/mirrorlist -------- +The order of repositories in the configuration files matters; repositories +listed first will take precedence over those listed later in the file when +packages in two repositories have identical names, regardless of version +number. + +*Include =* path:: + Include another config file. This file can include repositories or + general configuration options. Wildcards in the specified paths will get + expanded based on linkman:glob[7] rules. + +*Server =* url:: + A full URL to a location where the database, packages, and signatures (if + available) for this repository can be found. ++ During parsing, pacman will define the `$repo` variable to the name of the current section. This is often utilized in files specified using the 'Include' directive so all repositories can use the same mirrorfile. pacman also defines the `$arch` variable to the value of `Architecture`, so the same mirrorfile can even be used for different architectures. +*SigLevel =* ...:: + Set the signature verification level for this repository. For more + information, see <<SC,Package and Database Signature Checking>> below. + +Package and Database Signature Checking +--------------------------------------- +The 'SigLevel' directive is valid in both the `[options]` and repository +sections. If used in `[options]`, it sets a default value for any repository +that does not provide the setting. + +* If set to *Never*, no signature checking will take place. +* If set to *Optional* , signatures will be checked when present, but unsigned + databases and packages will also be accepted. +* If set to *Required*, signatures will be required on all packages and + databases. + +Alternatively, you can get more fine-grained control by combining some of +the options and prefixes described below. All options in a config file are +processed in top-to-bottom, left-to-right fashion, where later options override +and/or supplement earlier ones. If 'SigLevel' is specified in a repository +section, the starting value is that from the `[options]` section, or the +built-in system default as shown below if not specified. + +The options are split into two main groups, described below. Terms used such as +``marginally trusted'' are terms used by GnuPG, for more information please +consult linkman:gpg[1]. + +When to Check:: + These options control if and when signature checks should take place. + + *Never*;; + All signature checking is suppressed, even if signatures are present. + + *Optional* (default);; + Signatures are checked if present; absence of a signature is not an + error. An invalid signature is a fatal error, as is a signature from a + key not in the keyring. + + *Required*;; + Signatures are required; absence of a signature or an invalid signature + is a fatal error, as is a signature from a key not in the keyring. + +What is Allowed:: + These options control what signatures are viewed as permissible. Note that + neither of these options allows acceptance of invalid or expired + signatures, or those from revoked keys. + + *TrustedOnly* (default);; + If a signature is checked, it must be in the keyring and fully trusted; + marginal trust does not meet this criteria. + + *TrustAll*;; + If a signature is checked, it must be in the keyring, but is not + required to be assigned a trust level (e.g., unknown or marginal + trust). + +Options in both groups can additionally be prefixed with either *Package* or +*Database*, which will cause it to only take effect on the specified object +type. For example, `PackageTrustAll` would allow marginal and unknown trust +level signatures for packages. + +The built-in default is the following: + -------- -Server = ftp://ftp.archlinux.org/$repo/os/$arch +SigLevel = Optional TrustedOnly -------- -The order of repositories in the configuration files matters; repositories -listed first will take precedence over those listed later in the file when -packages in two repositories have identical names, regardless of version -number. - Using Your Own Repository ------------------------- If you have numerous custom packages of your own, it is often easier to generate @@ -215,11 +301,12 @@ directory with these packages so pacman can find it when run with '\--refresh'. The above command will generate a compressed database named '/home/pkgs/custom.db.tar.gz'. Note that the database must be of the form -'\{treename\}.db.tar.gz', where '\{treename\}' is the name of the section defined in -the configuration file. That's it! Now configure your custom section in the -configuration file as shown in the config example above. Pacman will now use your -package repository. If you add new packages to the repository, remember to -re-generate the database and use pacman's '\--refresh' option. +'\{treename\}.db.tar.{ext}', where '\{treename\}' is the name of the section +defined in the configuration file and '\{ext\}' is a valid compression type as +documented in linkman:repo-add[8]. That's it! Now configure your custom section +in the configuration file as shown in the config example above. Pacman will now +use your package repository. If you add new packages to the repository, +remember to re-generate the database and use pacman's '\--refresh' option. For more information on the repo-add command, see ``repo-add \--help'' or linkman:repo-add[8]. diff --git a/doc/pkgdelta.8.txt b/doc/pkgdelta.8.txt new file mode 100644 index 00000000..3804c5d9 --- /dev/null +++ b/doc/pkgdelta.8.txt @@ -0,0 +1,42 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +pkgdelta(8) +========= + +Name +---- +pkgdelta - package delta generation utility + + +Synopsis +-------- +'pkgdelta' [-q] <package1> <package2> + + +Description +----------- +'pkgdelta' is used to create package delta files between two versions of the +same package. These files are essentially binary patches. linkman:pacman[8] can +download deltas instead of full package upgrades, and use them with the +previous versions of packages (in the package cache) to synthesize the upgraded +version of the packages. This likely reduces download sizes for upgrades +significantly. + +'pkgdelta' requires linkman:xdelta3[1] to do its job. + +Options +------- +*-q, \--quiet*:: + Be quiet. Do not output anything but warnings and errors. + +Examples +-------- + + $ pkgdelta libreoffice-3.3.2-1-x86_64.pkg.tar.xz libreoffice-3.3.2-2-x86_64.pkg.tar.xz + +See Also +-------- +linkman:pacman[8], linkman:xdelta3[1] + +include::footer.txt[] diff --git a/doc/repo-add.8.txt b/doc/repo-add.8.txt index 75f49ef5..79b5a7ef 100644 --- a/doc/repo-add.8.txt +++ b/doc/repo-add.8.txt @@ -1,5 +1,5 @@ ///// -vim:set ts=4 sw=4 syntax=asciidoc noet: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// repo-add(8) ========== @@ -10,26 +10,55 @@ repo-add - package database maintenance utility Synopsis -------- -repo-add [-d] [-f] [-q] <path-to-db> <package1> [<package2> ...] +'repo-add' [options] <path-to-db> <package|delta> [<package|delta> ...] -repo-remove [-q] <path-to-db> <packagename> [<packagename2> ...] +'repo-remove' [options] <path-to-db> <packagename|delta> [<packagename|delta> ...] Description ----------- -repo-add and repo-remove are two scripts to help build a package database for +'repo-add' and 'repo-remove' are two scripts to help build a package database for packages built with linkman:makepkg[8] and installed with linkman:pacman[8]. +They also handle package deltas produced by linkman:pkgdelta[8]. -repo-add will update a package database by reading a built package file. -Multiple packages to add can be specified on the command line. +'repo-add' will update a package database by reading a built package or package +delta file. Multiple packages and/or deltas to add can be specified on the +command line. -repo-remove will update a package database by removing the package name -specified on the command line. Multiple packages to remove can be specified -on the command line. +'repo-remove' will update a package database by removing the package name or +delta specified on the command line. Multiple packages and/or delta to remove +can be specified on the command line. +A package database is a tar file, optionally compressed. Valid extensions are +``.db'' or ``.files'' followed by an archive extension of ``.tar'', +``.tar.gz'', ``.tar.bz2'', ``.tar.xz'', or ``.tar.Z''. The file does not need +to exist, but all parent directories must exist. -Options -------- + +Common Options +-------------- +*-q, \--quiet*:: + Force this program to keep quiet and run silent except for warning and + error messages. + +*-s, \--sign*:: + Generate a PGP signature file using GnuPG. This will execute `gpg + --detach-sign --use-agent` on the generated database to generate a detached + signature file, using the GPG agent if it is available. The signature file + will be the entire filename of the database with a ``.sig'' extension. + +*-k, \--key* <key>:: + Specify a key to use when signing packages. Can also be specified using + the GPGKEY environmental variable. If not specified in either location, the + default key from the keyring will be used. + +*-v, \--verify*:: + Verify the PGP signature of the database before updating the database. + If the signature is invalid, an error is produced and the update does not + proceed. + +repo-add 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. @@ -39,12 +68,8 @@ Options 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] +linkman:makepkg[8], linkman:pacman[8], linkman:pkgdelta[8] include::footer.txt[] diff --git a/doc/submitting-patches.txt b/doc/submitting-patches.txt index e6853c5f..34287683 100644 --- a/doc/submitting-patches.txt +++ b/doc/submitting-patches.txt @@ -20,7 +20,7 @@ started with GIT if you have not worked with it before. The pacman code can be fetched using the following command: - git clone git://projects.archlinux.org/pacman.git + git clone git://projects.archlinux.org/pacman.git Creating your patch @@ -32,7 +32,7 @@ Creating your patch The -s allows you to credit yourself by adding a "Signed Off By" line to indicate who has "signed" the patch - who has approved it. - Signed-off-by: Aaron Griffin <aaron@archlinux.org> + Signed-off-by: Aaron Griffin <aaron@archlinux.org> Please use your real name and email address. Feel free to "scramble" the address if you're afraid of spam. @@ -94,5 +94,5 @@ aren't their own. -- ///// -vim: set ts=2 sw=2 syntax=asciidoc et: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// diff --git a/doc/translation-help.txt b/doc/translation-help.txt index d95b5135..ef86dbfe 100644 --- a/doc/translation-help.txt +++ b/doc/translation-help.txt @@ -40,15 +40,15 @@ not worried about any local translations being overwritten. The .tx/ directory is checked into the git repository so is preconfigured with the two project resources (See `tx status` output for a quick overview). - tx pull -f - poedit po/<mylang>.po - poedit lib/libalpm/po/<mylang>.po - tx push -t -l <mylang> + tx pull -f + poedit po/<mylang>.po + poedit lib/libalpm/po/<mylang>.po + tx push -t -l <mylang> Or to just push one of the two available resources: - tx push -r archlinux-pacman.pacman-pot -t -l fi - tx push -r archlinux-pacman.libalpm-pot -t -l fi + tx push -r archlinux-pacman.pacman-pot -t -l fi + tx push -r archlinux-pacman.libalpm-pot -t -l fi See the <<Notes,Notes>> section for additional hints on translating. @@ -79,7 +79,7 @@ Incremental Updates If you have more advanced needs you will have to get a copy of the pacman repository. - git clone git://projects.archlinux.org/pacman.git pacman + git clone git://projects.archlinux.org/pacman.git pacman Next, you will need to run `./autogen.sh` and `./configure` in the base directory to generate the correct Makefiles. At this point, all necessary @@ -91,11 +91,11 @@ We need to first update the main message catalog file. Navigate into either the work on first, and execute the following command. If you are working in the `po/` tree, replace 'libalpm.pot' with 'pacman.pot': - make libalpm.pot-update + make libalpm.pot-update Next, update your specific language's translation file: - make <po file>-update + make <po file>-update At this point, you can do the translation. To submit your changes, either email the new `.po` file to the mailing-list with *[translation]* in the subject, or @@ -104,7 +104,7 @@ submit a GIT-formatted patch (please do not include any `.pot` file changes). As a shortcut, all translation files (including `.pot` files) can be updated with the following command: - make update-po + make update-po Adding a New Language ~~~~~~~~~~~~~~~~~~~~~ @@ -133,16 +133,16 @@ msgid and msgstr 'variables' can be on as many lines as necessary. Line breaks are ignored- if you need a literal line break, use an `\n` in your string. The following two translations are equivalent: - msgstr "This is a test translation" + msgstr "This is a test translation" - msgstr "" - "This is a test translation" + msgstr "" + "This is a test translation" If you want to test the translation (for example, the frontend one): - rm *.gmo stamp-po - make - cp <lang code>.gmo /usr/share/locale/<lang code>/LC_MESSAGES/pacman.mo + rm *.gmo stamp-po + make + cp <lang code>.gmo /usr/share/locale/<lang code>/LC_MESSAGES/pacman.mo Translating Manpages @@ -160,5 +160,5 @@ check there first before undergoing a translation effort to ensure you are not duplicating efforts. ///// -vim: set ts=2 sw=2 syntax=asciidoc et: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// diff --git a/doc/vercmp.8.txt b/doc/vercmp.8.txt index f2fc5305..a3bc5611 100644 --- a/doc/vercmp.8.txt +++ b/doc/vercmp.8.txt @@ -1,5 +1,5 @@ ///// -vim:set ts=4 sw=4 syntax=asciidoc noet: +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: ///// vercmp(8) ========= |