From 076b6184de2b20e9b26225d93f6f3a7030504109 Mon Sep 17 00:00:00 2001 From: Eli Schwartz Date: Thu, 3 May 2018 00:10:21 -0400 Subject: Ensure better text editor automatic filetype detection Since we no longer use vim-specific modelines, use the .asciidoc file extension which is, well, reserved for asciidoc formatted files. This should presumably work everywhere without needing editor-specific workarounds and configuration. Also add a shebang to makepkg.conf to indicate it contains bash content. Signed-off-by: Eli Schwartz Signed-off-by: Allan McRae --- doc/BUILDINFO.5.asciidoc | 70 +++++ doc/BUILDINFO.5.txt | 70 ----- doc/Makefile.am | 68 ++--- doc/PKGBUILD.5.asciidoc | 525 +++++++++++++++++++++++++++++++++++++ doc/PKGBUILD.5.txt | 525 ------------------------------------- doc/alpm-hooks.5.asciidoc | 128 +++++++++ doc/alpm-hooks.5.txt | 128 --------- doc/footer.asciidoc | 32 +++ doc/footer.txt | 32 --- doc/index.asciidoc | 261 ++++++++++++++++++ doc/index.txt | 261 ------------------ doc/libalpm.3.asciidoc | 37 +++ doc/libalpm.3.txt | 37 --- doc/makepkg-template.1.asciidoc | 118 +++++++++ doc/makepkg-template.1.txt | 118 --------- doc/makepkg.8.asciidoc | 349 ++++++++++++++++++++++++ doc/makepkg.8.txt | 349 ------------------------ doc/makepkg.conf.5.asciidoc | 269 +++++++++++++++++++ doc/makepkg.conf.5.txt | 269 ------------------- doc/pacman-key.8.asciidoc | 145 ++++++++++ doc/pacman-key.8.txt | 145 ---------- doc/pacman.8.asciidoc | 568 ++++++++++++++++++++++++++++++++++++++++ doc/pacman.8.txt | 568 ---------------------------------------- doc/pacman.conf.5.asciidoc | 371 ++++++++++++++++++++++++++ doc/pacman.conf.5.txt | 371 -------------------------- doc/pkgdelta.8.asciidoc | 53 ++++ doc/pkgdelta.8.txt | 53 ---- doc/repo-add.8.asciidoc | 94 +++++++ doc/repo-add.8.txt | 94 ------- doc/submitting-patches.asciidoc | 101 +++++++ doc/submitting-patches.txt | 101 ------- doc/translation-help.asciidoc | 153 +++++++++++ doc/translation-help.txt | 153 ----------- doc/vercmp.8.asciidoc | 72 +++++ doc/vercmp.8.txt | 72 ----- 35 files changed, 3380 insertions(+), 3380 deletions(-) create mode 100644 doc/BUILDINFO.5.asciidoc delete mode 100644 doc/BUILDINFO.5.txt create mode 100644 doc/PKGBUILD.5.asciidoc delete mode 100644 doc/PKGBUILD.5.txt create mode 100644 doc/alpm-hooks.5.asciidoc delete mode 100644 doc/alpm-hooks.5.txt create mode 100644 doc/footer.asciidoc delete mode 100644 doc/footer.txt create mode 100644 doc/index.asciidoc delete mode 100644 doc/index.txt create mode 100644 doc/libalpm.3.asciidoc delete mode 100644 doc/libalpm.3.txt create mode 100644 doc/makepkg-template.1.asciidoc delete mode 100644 doc/makepkg-template.1.txt create mode 100644 doc/makepkg.8.asciidoc delete mode 100644 doc/makepkg.8.txt create mode 100644 doc/makepkg.conf.5.asciidoc delete mode 100644 doc/makepkg.conf.5.txt create mode 100644 doc/pacman-key.8.asciidoc delete mode 100644 doc/pacman-key.8.txt create mode 100644 doc/pacman.8.asciidoc delete mode 100644 doc/pacman.8.txt create mode 100644 doc/pacman.conf.5.asciidoc delete mode 100644 doc/pacman.conf.5.txt create mode 100644 doc/pkgdelta.8.asciidoc delete mode 100644 doc/pkgdelta.8.txt create mode 100644 doc/repo-add.8.asciidoc delete mode 100644 doc/repo-add.8.txt create mode 100644 doc/submitting-patches.asciidoc delete mode 100644 doc/submitting-patches.txt create mode 100644 doc/translation-help.asciidoc delete mode 100644 doc/translation-help.txt create mode 100644 doc/vercmp.8.asciidoc delete mode 100644 doc/vercmp.8.txt (limited to 'doc') diff --git a/doc/BUILDINFO.5.asciidoc b/doc/BUILDINFO.5.asciidoc new file mode 100644 index 00000000..3db1e12f --- /dev/null +++ b/doc/BUILDINFO.5.asciidoc @@ -0,0 +1,70 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +BUILDINFO(5) +============ + +Name +---- +BUILDINFO - Makepkg package build information file + + +Synopsis +-------- +This manual page describes the format of a BUILDINFO file found in the root of +a package created by makepkg. The file contains a description of the package's +build environment. The information is formatted in key-value pairs separated by +a '=', one value per line. Arrays are represented multiple keys with the same +value. + + +Description +----------- + +This is a description of the contents of version '1' of the +BUILDINFO file format. + +*format*:: + Denotes the file format version, represented by a plain positive integer. + +*pkgname*:: + The name of the package. + +*pkgbase*:: + + The base name of a package, usually the same as the pkgname except for + split packages. + +*pkgver*:: + The version of the package including pkgrel and epoch. + +*pkgarch*:: + The architecture of the package. + +*pkgbuild_sha256sum*:: + The sha256sum in hex format of the PKGBUILD used to build the package. + +*packager*:: + The details of the packager that built the package. + +*builddate*:: + The build date of the package in epoch. + +*builddir*:: + The directory where the package was built. + +*buildenv (array)*:: + The build environment specified in makepkg.conf. + +*options (array)*:: + The options set specified when building the package. + +*installed (array)*:: + The installed packages at build time including the version information of + the package. Formatted as "$pkgname-$pkgver-$pkgrel-$pkgarch". + +See Also +-------- +linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5] + +include::footer.asciidoc[] diff --git a/doc/BUILDINFO.5.txt b/doc/BUILDINFO.5.txt deleted file mode 100644 index a7e6b2e4..00000000 --- a/doc/BUILDINFO.5.txt +++ /dev/null @@ -1,70 +0,0 @@ -///// -vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: -///// -BUILDINFO(5) -============ - -Name ----- -BUILDINFO - Makepkg package build information file - - -Synopsis --------- -This manual page describes the format of a BUILDINFO file found in the root of -a package created by makepkg. The file contains a description of the package's -build environment. The information is formatted in key-value pairs separated by -a '=', one value per line. Arrays are represented multiple keys with the same -value. - - -Description ------------ - -This is a description of the contents of version '1' of the -BUILDINFO file format. - -*format*:: - Denotes the file format version, represented by a plain positive integer. - -*pkgname*:: - The name of the package. - -*pkgbase*:: - - The base name of a package, usually the same as the pkgname except for - split packages. - -*pkgver*:: - The version of the package including pkgrel and epoch. - -*pkgarch*:: - The architecture of the package. - -*pkgbuild_sha256sum*:: - The sha256sum in hex format of the PKGBUILD used to build the package. - -*packager*:: - The details of the packager that built the package. - -*builddate*:: - The build date of the package in epoch. - -*builddir*:: - The directory where the package was built. - -*buildenv (array)*:: - The build environment specified in makepkg.conf. - -*options (array)*:: - The options set specified when building the package. - -*installed (array)*:: - The installed packages at build time including the version information of - the package. Formatted as "$pkgname-$pkgver-$pkgrel-$pkgarch". - -See Also --------- -linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5] - -include::footer.txt[] diff --git a/doc/Makefile.am b/doc/Makefile.am index 3eff9194..8dec4ab1 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -47,24 +47,24 @@ HTML_DOCS = \ EXTRA_DIST = \ asciidoc.conf \ asciidoc-override.css \ - alpm-hooks.5.txt \ - pacman.8.txt \ - makepkg.8.txt \ - makepkg-template.1.txt \ - repo-add.8.txt \ - vercmp.8.txt \ - pkgdelta.8.txt \ - pacman-key.8.txt \ - PKGBUILD.5.txt \ + alpm-hooks.5.asciidoc \ + pacman.8.asciidoc \ + makepkg.8.asciidoc \ + makepkg-template.1.asciidoc \ + repo-add.8.asciidoc \ + vercmp.8.asciidoc \ + pkgdelta.8.asciidoc \ + pacman-key.8.asciidoc \ + PKGBUILD.5.asciidoc \ PKGBUILD-example.txt \ - makepkg.conf.5.txt \ - pacman.conf.5.txt \ - BUILDINFO.5.txt \ - libalpm.3.txt \ - footer.txt \ - index.txt \ - submitting-patches.txt \ - translation-help.txt \ + makepkg.conf.5.asciidoc \ + pacman.conf.5.asciidoc \ + BUILDINFO.5.asciidoc \ + libalpm.3.asciidoc \ + footer.asciidoc \ + index.asciidoc \ + submitting-patches.asciidoc \ + translation-help.asciidoc \ Doxyfile \ $(ASCIIDOC_MANS) \ $(DOXYGEN_MANS) @@ -130,11 +130,11 @@ A2X_OPTS = \ --xsltproc-opts='-param man.endnotes.list.enabled 0 -param man.endnotes.are.numbered 0' # These rules are due to the includes and files of the asciidoc text -$(ASCIIDOC_MANS): asciidoc.conf footer.txt Makefile.am - $(AM_V_GEN)a2x $(A2X_OPTS) --asciidoc-opts="$(ASCIIDOC_OPTS) --out-file=./$@.xml" $(srcdir)/$@.txt +$(ASCIIDOC_MANS): asciidoc.conf footer.asciidoc Makefile.am + $(AM_V_GEN)a2x $(A2X_OPTS) --asciidoc-opts="$(ASCIIDOC_OPTS) --out-file=./$@.xml" $(srcdir)/$@.asciidoc -%.html: %.txt - $(AM_V_GEN)asciidoc $(ASCIIDOC_OPTS) -o - $*.txt | \ +%.html: %.asciidoc + $(AM_V_GEN)asciidoc $(ASCIIDOC_OPTS) -o - $*.asciidoc | \ sed -e 's/\r$$//' > $@ HACKING.html: ../HACKING @@ -142,7 +142,7 @@ HACKING.html: ../HACKING sed -e 's/\r$$//' > $@ # Customizations for certain HTML docs -$(HTML_MANPAGES): asciidoc.conf footer.txt Makefile.am +$(HTML_MANPAGES): asciidoc.conf footer.asciidoc Makefile.am $(HTML_OTHER): asciidoc.conf Makefile.am %.html: ASCIIDOC_OPTS += -a linkcss -a toc -a icons -a max-width=960px -a stylesheet=asciidoc-override.css %.8.html: ASCIIDOC_OPTS += -d manpage @@ -150,18 +150,18 @@ $(HTML_OTHER): asciidoc.conf Makefile.am %.3.html: ASCIIDOC_OPTS += -d manpage # Dependency rules -alpm-hooks.5 alpm-hooks.5.html: alpm-hooks.5.txt -pacman.8 pacman.8.html: pacman.8.txt -makepkg.8 makepkg.8.html: makepkg.8.txt -makepkg-template.1 makepkg-template.1.html: makepkg-template.1.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 -libalpm.3 libalpm.3.html: libalpm.3.txt +alpm-hooks.5 alpm-hooks.5.html: alpm-hooks.5.asciidoc +pacman.8 pacman.8.html: pacman.8.asciidoc +makepkg.8 makepkg.8.html: makepkg.8.asciidoc +makepkg-template.1 makepkg-template.1.html: makepkg-template.1.asciidoc +repo-add.8 repo-add.8.html: repo-add.8.asciidoc +vercmp.8 vercmp.8.html: vercmp.8.asciidoc +pkgdelta.8 pkgdelta.8.html: pkgdelta.8.asciidoc +pacman-key.8 pacman-key.8.html: pacman-key.8.asciidoc +PKGBUILD.5 PKGBUILD.5.html: PKGBUILD.5.asciidoc PKGBUILD-example.txt +makepkg.conf.5 makepkg.conf.5.html: makepkg.conf.5.asciidoc +pacman.conf.5 pacman.conf.5.html: pacman.conf.5.asciidoc +libalpm.3 libalpm.3.html: libalpm.3.asciidoc # this one is just a symlink repo-remove.8: repo-add.8 $(RM) repo-remove.8 diff --git a/doc/PKGBUILD.5.asciidoc b/doc/PKGBUILD.5.asciidoc new file mode 100644 index 00000000..9634bd15 --- /dev/null +++ b/doc/PKGBUILD.5.asciidoc @@ -0,0 +1,525 @@ +PKGBUILD(5) +=========== + +Name +---- +PKGBUILD - Arch Linux package build description file + + +Synopsis +-------- +PKGBUILD + + +Description +----------- +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}' +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. + + +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 +of them will be directly transferred to the built package. The mandatory +fields for a minimally functional PKGBUILD are *pkgname*, *pkgver*, *pkgrel* +and *arch*. + +If you need to create any custom variables for use in your build process, it is +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)*:: + Either the name of the package or an array of names for split packages. + Valid characters for members of this array are alphanumerics, and any of + the following characters: ```@ . _ + -`''. Additionally, names are not + allowed to start with hyphens or dots. + +*pkgver*:: + The version of the software as released from the author (e.g., '2.7.1'). + The variable is not allowed to contain colons, forward slashes, hyphens + or whitespace. ++ +The `pkgver` variable can be automatically updated by providing a `pkgver()` +function in the PKGBUILD that outputs the new package version. +This is run after downloading and extracting the sources and running the +`prepare()` function (if present), so it can use those files in determining the +new `pkgver`. This is most useful when used with sources from version control +systems (see below). + +*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. 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. + +*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. + +*pkgdesc*:: + This should be a brief description of the package and its functionality. + Try to keep the description to one line of text and to not use the package's + name. + +*url*:: + This field contains a URL that is associated with the software being + packaged. This is typically the project's web site. + +*license (array)*:: + This field specifies the license(s) that apply to the package. + 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 + 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, 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`). + +*changelog*:: + Specifies a changelog file that is to be included in the package. + The changelog file should end in a single newline. + 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`). + +*source (array)*:: + An array of source files required to build the package. Source files + 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 simplify the maintenance of PKGBUILDs, use the `$pkgname` and `$pkgver` + variables when specifying the download location, if possible. + Compressed files will be extracted automatically unless found in the + noextract array described below. ++ +Additional architecture-specific sources can be added by appending an +underscore and the architecture name e.g., 'source_x86_64=()'. There must be a +corresponding integrity array with checksums, e.g. 'md5sums_x86_64=()'. ++ +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')`. ++ +makepkg also supports building developmental versions of packages using sources +downloaded from version control systems (VCS). For more information, see +<> below. ++ +Files in the source array with extensions `.sig`, `.sign` or, `.asc` are +recognized by makepkg as PGP signatures and will be automatically used to verify +the integrity of the corresponding source file. + +*validpgpkeys (array)*:: + An array of PGP fingerprints. If this array is non-empty, makepkg will + only accept signatures from the keys listed here and will ignore the + trust values from the keyring. If the source file was signed with a + subkey, makepkg will still use the primary key for comparison. ++ +Only full fingerprints are accepted. They must be uppercase and must not +contain whitespace characters. + +*noextract (array)*:: + An array of file names 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 that use compressed data directly. + +*md5sums (array)*:: + This array contains an MD5 hash for every source file specified in the + source array (in the same order). makepkg will use this to verify source + file integrity during subsequent builds. If 'SKIP' is put in the array + in place of a normal hash, the integrity check for that source file will + be skipped. To easily generate md5sums, run ``makepkg -g >> PKGBUILD''. + If desired, move the md5sums line to an appropriate location. + +*sha1sums, sha256sums, sha384sums, sha512sums (arrays)*:: + Alternative integrity checks that makepkg supports; these all behave + similar to the md5sums option described above. To enable use and generation + of these checksums, be sure to set up the `INTEGRITY_CHECK` option in + linkman:makepkg.conf[5]. + +*groups (array)*:: + An array of symbolic names that represent groups of packages, allowing + you to install multiple packages by requesting a single target. For + 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., + `arch=('i686' 'x86_64')`). Packages that contain no architecture specific + files should use `arch=('any')`. Valid characters for members of this array + are alphanumerics and ```_`''. + +*backup (array)*:: + An array of file names, 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 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 automatic detection. ++ +Additional architecture-specific depends can be added by appending an +underscore and the architecture name e.g., 'depends_x86_64=()'. + +*makedepends (array)*:: + 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. ++ +Additional architecture-specific makedepends can be added by appending an +underscore and the architecture name e.g., 'makedepends_x86_64=()'. + +*checkdepends (array)*:: + 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. ++ +Additional architecture-specific checkdepends can be added by appending an +underscore and the architecture name e.g., 'checkdepends_x86_64=()'. + +*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 + of this package. optdepends are currently for informational purposes only + and are not utilized by pacman during dependency resolution. The format + for specifying optdepends is: + + optdepends=('python: for library bindings') ++ +Additional architecture-specific optdepends can be added by appending an +underscore and the architecture name e.g., 'optdepends_x86_64=()'. + +*conflicts (array)*:: + An array of packages that will conflict with this package (i.e. they + cannot both be installed at the same time). This directive follows the + same format as depends. Versioned conflicts are supported using the + operators as described in `depends`. ++ +Additional architecture-specific conflicts can be added by appending an +underscore and the architecture name e.g., 'conflicts_x86_64=()'. + +*provides (array)*:: + 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'. ++ +Versioned provisions are also possible, in the 'name=version' format. For +example, dcron can provide 'cron=2.0' to satisfy the 'cron>=2.0' 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 automatic detection. ++ +Additional architecture-specific provides can be added by appending an +underscore and the architecture name e.g., 'provides_x86_64=()'. + +*replaces (array)*:: + 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. Versioned replaces are + supported using the operators as described in `depends`. ++ +Sysupgrade is currently the only pacman operation that utilizes this field. +A normal sync or upgrade will not use its value. ++ +Additional architecture-specific replaces can be added by appending an +underscore and the architecture name e.g., 'replaces_x86_64=()'. + +*options (array)*:: + This array allows you to override some of makepkg's default behavior + when building packages. To set an option, just include the option name + 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 now-removed option in favor of the top level 'epoch' + variable. + + *strip*;; + Strip symbols from binaries and libraries. If you frequently + use a debugger on programs or libraries, it may be helpful to + disable this option. + + *docs*;; + Save doc directories. If you wish to delete doc directories, + specify `!docs` in the array. + + *libtool*;; + Leave libtool (.la) files in packages. Specify `!libtool` to + remove them. + + *staticlibs*;; + Leave static library (.a) files in packages. Specify `!staticlibs` to + remove them (if they have a shared counterpart). + + *emptydirs*;; + Leave empty directories in packages. + + *zipman*;; + Compress man and info pages with gzip. + + *ccache*;; + Allow the use of ccache during build. More useful in its negative + form `!ccache` with select packages that have problems building + with ccache. + + *distcc*;; + Allow the use of distcc during build. More useful in its negative + form `!distcc` with select packages that have problems building + with distcc. + + *buildflags*;; + Allow the use of user-specific buildflags (CPPFLAGS, 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). + + *debug*;; + Add the user-specified debug flags (DEBUG_CFLAGS, DEBUG_CXXFLAGS) to + their counterpart buildflags as specified in linkman:makepkg.conf[5]. + When used in combination with the `strip' option, a separate package + containing the debug symbols is created. + + +Packaging Functions +------------------- +In addition to the above directives, PKGBUILDs require a set of functions that +provide instructions to build and install the package. As a minimum, the +PKGBUILD must contain a `package()` function which installs all the package's +files into the packaging directory, with optional `prepare()`, `build()`, and +`check()` functions being used to create those files from source. + +*package() Function*:: + The `package()` function is used to install files into the directory that + will become the root directory of the built package and is run after all + the optional functions listed below. The packaging stage is run using + fakeroot to ensure correct file permissions in the resulting package. + All other functions will be run as the user calling makepkg. + +*prepare() Function*:: + An optional `prepare()` function can be specified in which operations to + prepare the sources for building, such as patching, are performed. This + function is run after the source extraction and before the `build()` + function. The `prepare()` function is skipped when source extraction + is skipped. + +*build() Function*:: + The optional `build()` function is use to compile and/or adjust the source + files in preparation to be installed by the `package()` function. This is + directly sourced and executed by makepkg, so anything that Bash or the + system has available is available for use here. Be sure any exotic + commands used are covered by the `makedepends` array. ++ +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 package's + test-suite may be run. This function is run between the `build()` and + `package()` functions. Be sure any exotic commands used are covered by the + `checkdepends` array. + +All of the above variables such as `$pkgname` and `$pkgver` are available for +use in the packaging functions. In addition, makepkg defines the following +variables: + +*srcdir*:: + This contains the directory where makepkg extracts, or copies, all source + files. ++ +All of the packaging functions defined above are run starting inside `$srcdir` + +*pkgdir*:: + This contains the directory where makepkg bundles the installed package. + This directory will become the root directory of your built package. This + variable should only be used in the `package()` function. + +*startdir*:: + This contains the absolute path to the directory where the PKGBUILD is + located, which is usually the output of `$(pwd)` when makepkg is started. + Use of this variable is deprecated and strongly discouraged. + + +Package Splitting +----------------- +makepkg supports building multiple packages from a single PKGBUILD. This is +achieved by assigning an array of package names to the `pkgname` directive. +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 in the PKGBUILD. Nevertheless, the following ones can be overridden within +each split package's packaging function: +`pkgdesc`, `arch`, `url`, `license`, `groups`, `depends`, `optdepends`, +`provides`, `conflicts`, `replaces`, `backup`, `options`, `install`, and +`changelog`. + +Note that makepkg does not consider split package `depends` when checking +if dependencies are installed before package building and with `--syncdeps`. +All packages required to make the package are required to be specified in +the global `depends` and `makedepends` arrays. + +An optional global directive is available when building a split package: + +*pkgbase*:: + The name used to refer to the group of packages in the output of makepkg + and in the naming of source-only tarballs. If not specified, the first + element in the `pkgname` array is used. Valid characters for this + variable are alphanumerics, and any of the following characters: + ```@ . _ + -`''. Additionally, the variable is not allowed to start with + hyphens or dots. + + +Install/Upgrade/Remove Scripting +-------------------------------- +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, and should be +self-explanatory. Note that during an upgrade operation, none of the install +or remove functions 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*:: + Run right before files are extracted. One argument is passed: + new package full version string. + +*post_install*:: + Run right after files are extracted. One argument is passed: + new package full version string. + +*pre_upgrade*:: + 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*:: + Run after files are extracted. Two arguments are passed in this order: + new package full version string, old package full version string. + +*pre_remove*:: + Run right before files are removed. One argument is passed: + old package full version string. + +*post_remove*:: + 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: + + install=pkgname.install + +The install script does not need to be specified in the source array. A +template install file is available in '{pkgdatadir}' as 'proto.install' for +reference with all of the available functions defined. + + +Using VCS Sources[[VCS]] +------------------------ +Building a developmental version of a package using sources from a version +control system (VCS) is enabled by specifying the source in the form +`source=('directory::url#fragment?query')`. Currently makepkg supports the +Bazaar, Git, Subversion, and Mercurial version control systems. For other +version control systems, manual cloning of upstream repositories must be done +in the `prepare()` function. + +The source URL is divided into four components: + +*directory*:: + (optional) Specifies an alternate directory name for makepkg to download + the VCS source into. + +*url*:: + The URL to the VCS repository. This must include the VCS in the URL protocol + for makepkg to recognize this as a VCS source. If the protocol does not + include the VCS name, it can be added by prefixing the URL with `vcs+`. For + example, using a Git repository over HTTPS would have a source URL in the + form: + `git+https://...`. + +*fragment*:: + (optional) Allows specifying a revision number or branch for makepkg to checkout + from the VCS. For example, to checkout a given revision, the source line would + have the format `source=(url#revision=123)`. The available fragments depends on + the VCS being used: + + *bzr*;; + revision (see `'bzr help revisionspec'` for details) + + *git*;; + branch, commit, tag + + *hg*;; + branch, revision, tag + + *svn*;; + revision + +*query*:: + (optional) Allows specifying whether a VCS checkout should be checked for + PGP-signed revisions. The source line should have the format + `source=(url#fragment?signed)` or `source=(url?signed#fragment)`. Currently + only supported by Git. + +Example +------- +The following is an example PKGBUILD for the 'patch' package. For more +examples, look through the build files of your distribution's packages. For +those using Arch Linux, consult the Arch Build System (ABS) tree. + +[source,sh] +------------------------------- +include::PKGBUILD-example.txt[] +------------------------------- + + +See Also +-------- +linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5] + +include::footer.asciidoc[] diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt deleted file mode 100644 index 795dde45..00000000 --- a/doc/PKGBUILD.5.txt +++ /dev/null @@ -1,525 +0,0 @@ -PKGBUILD(5) -=========== - -Name ----- -PKGBUILD - Arch Linux package build description file - - -Synopsis --------- -PKGBUILD - - -Description ------------ -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}' -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. - - -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 -of them will be directly transferred to the built package. The mandatory -fields for a minimally functional PKGBUILD are *pkgname*, *pkgver*, *pkgrel* -and *arch*. - -If you need to create any custom variables for use in your build process, it is -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)*:: - Either the name of the package or an array of names for split packages. - Valid characters for members of this array are alphanumerics, and any of - the following characters: ```@ . _ + -`''. Additionally, names are not - allowed to start with hyphens or dots. - -*pkgver*:: - The version of the software as released from the author (e.g., '2.7.1'). - The variable is not allowed to contain colons, forward slashes, hyphens - or whitespace. -+ -The `pkgver` variable can be automatically updated by providing a `pkgver()` -function in the PKGBUILD that outputs the new package version. -This is run after downloading and extracting the sources and running the -`prepare()` function (if present), so it can use those files in determining the -new `pkgver`. This is most useful when used with sources from version control -systems (see below). - -*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. 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. - -*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. - -*pkgdesc*:: - This should be a brief description of the package and its functionality. - Try to keep the description to one line of text and to not use the package's - name. - -*url*:: - This field contains a URL that is associated with the software being - packaged. This is typically the project's web site. - -*license (array)*:: - This field specifies the license(s) that apply to the package. - 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 - 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, 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`). - -*changelog*:: - Specifies a changelog file that is to be included in the package. - The changelog file should end in a single newline. - 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`). - -*source (array)*:: - An array of source files required to build the package. Source files - 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 simplify the maintenance of PKGBUILDs, use the `$pkgname` and `$pkgver` - variables when specifying the download location, if possible. - Compressed files will be extracted automatically unless found in the - noextract array described below. -+ -Additional architecture-specific sources can be added by appending an -underscore and the architecture name e.g., 'source_x86_64=()'. There must be a -corresponding integrity array with checksums, e.g. 'md5sums_x86_64=()'. -+ -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')`. -+ -makepkg also supports building developmental versions of packages using sources -downloaded from version control systems (VCS). For more information, see -<> below. -+ -Files in the source array with extensions `.sig`, `.sign` or, `.asc` are -recognized by makepkg as PGP signatures and will be automatically used to verify -the integrity of the corresponding source file. - -*validpgpkeys (array)*:: - An array of PGP fingerprints. If this array is non-empty, makepkg will - only accept signatures from the keys listed here and will ignore the - trust values from the keyring. If the source file was signed with a - subkey, makepkg will still use the primary key for comparison. -+ -Only full fingerprints are accepted. They must be uppercase and must not -contain whitespace characters. - -*noextract (array)*:: - An array of file names 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 that use compressed data directly. - -*md5sums (array)*:: - This array contains an MD5 hash for every source file specified in the - source array (in the same order). makepkg will use this to verify source - file integrity during subsequent builds. If 'SKIP' is put in the array - in place of a normal hash, the integrity check for that source file will - be skipped. To easily generate md5sums, run ``makepkg -g >> PKGBUILD''. - If desired, move the md5sums line to an appropriate location. - -*sha1sums, sha256sums, sha384sums, sha512sums (arrays)*:: - Alternative integrity checks that makepkg supports; these all behave - similar to the md5sums option described above. To enable use and generation - of these checksums, be sure to set up the `INTEGRITY_CHECK` option in - linkman:makepkg.conf[5]. - -*groups (array)*:: - An array of symbolic names that represent groups of packages, allowing - you to install multiple packages by requesting a single target. For - 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., - `arch=('i686' 'x86_64')`). Packages that contain no architecture specific - files should use `arch=('any')`. Valid characters for members of this array - are alphanumerics and ```_`''. - -*backup (array)*:: - An array of file names, 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 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 automatic detection. -+ -Additional architecture-specific depends can be added by appending an -underscore and the architecture name e.g., 'depends_x86_64=()'. - -*makedepends (array)*:: - 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. -+ -Additional architecture-specific makedepends can be added by appending an -underscore and the architecture name e.g., 'makedepends_x86_64=()'. - -*checkdepends (array)*:: - 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. -+ -Additional architecture-specific checkdepends can be added by appending an -underscore and the architecture name e.g., 'checkdepends_x86_64=()'. - -*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 - of this package. optdepends are currently for informational purposes only - and are not utilized by pacman during dependency resolution. The format - for specifying optdepends is: - - optdepends=('python: for library bindings') -+ -Additional architecture-specific optdepends can be added by appending an -underscore and the architecture name e.g., 'optdepends_x86_64=()'. - -*conflicts (array)*:: - An array of packages that will conflict with this package (i.e. they - cannot both be installed at the same time). This directive follows the - same format as depends. Versioned conflicts are supported using the - operators as described in `depends`. -+ -Additional architecture-specific conflicts can be added by appending an -underscore and the architecture name e.g., 'conflicts_x86_64=()'. - -*provides (array)*:: - 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'. -+ -Versioned provisions are also possible, in the 'name=version' format. For -example, dcron can provide 'cron=2.0' to satisfy the 'cron>=2.0' 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 automatic detection. -+ -Additional architecture-specific provides can be added by appending an -underscore and the architecture name e.g., 'provides_x86_64=()'. - -*replaces (array)*:: - 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. Versioned replaces are - supported using the operators as described in `depends`. -+ -Sysupgrade is currently the only pacman operation that utilizes this field. -A normal sync or upgrade will not use its value. -+ -Additional architecture-specific replaces can be added by appending an -underscore and the architecture name e.g., 'replaces_x86_64=()'. - -*options (array)*:: - This array allows you to override some of makepkg's default behavior - when building packages. To set an option, just include the option name - 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 now-removed option in favor of the top level 'epoch' - variable. - - *strip*;; - Strip symbols from binaries and libraries. If you frequently - use a debugger on programs or libraries, it may be helpful to - disable this option. - - *docs*;; - Save doc directories. If you wish to delete doc directories, - specify `!docs` in the array. - - *libtool*;; - Leave libtool (.la) files in packages. Specify `!libtool` to - remove them. - - *staticlibs*;; - Leave static library (.a) files in packages. Specify `!staticlibs` to - remove them (if they have a shared counterpart). - - *emptydirs*;; - Leave empty directories in packages. - - *zipman*;; - Compress man and info pages with gzip. - - *ccache*;; - Allow the use of ccache during build. More useful in its negative - form `!ccache` with select packages that have problems building - with ccache. - - *distcc*;; - Allow the use of distcc during build. More useful in its negative - form `!distcc` with select packages that have problems building - with distcc. - - *buildflags*;; - Allow the use of user-specific buildflags (CPPFLAGS, 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). - - *debug*;; - Add the user-specified debug flags (DEBUG_CFLAGS, DEBUG_CXXFLAGS) to - their counterpart buildflags as specified in linkman:makepkg.conf[5]. - When used in combination with the `strip' option, a separate package - containing the debug symbols is created. - - -Packaging Functions -------------------- -In addition to the above directives, PKGBUILDs require a set of functions that -provide instructions to build and install the package. As a minimum, the -PKGBUILD must contain a `package()` function which installs all the package's -files into the packaging directory, with optional `prepare()`, `build()`, and -`check()` functions being used to create those files from source. - -*package() Function*:: - The `package()` function is used to install files into the directory that - will become the root directory of the built package and is run after all - the optional functions listed below. The packaging stage is run using - fakeroot to ensure correct file permissions in the resulting package. - All other functions will be run as the user calling makepkg. - -*prepare() Function*:: - An optional `prepare()` function can be specified in which operations to - prepare the sources for building, such as patching, are performed. This - function is run after the source extraction and before the `build()` - function. The `prepare()` function is skipped when source extraction - is skipped. - -*build() Function*:: - The optional `build()` function is use to compile and/or adjust the source - files in preparation to be installed by the `package()` function. This is - directly sourced and executed by makepkg, so anything that Bash or the - system has available is available for use here. Be sure any exotic - commands used are covered by the `makedepends` array. -+ -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 package's - test-suite may be run. This function is run between the `build()` and - `package()` functions. Be sure any exotic commands used are covered by the - `checkdepends` array. - -All of the above variables such as `$pkgname` and `$pkgver` are available for -use in the packaging functions. In addition, makepkg defines the following -variables: - -*srcdir*:: - This contains the directory where makepkg extracts, or copies, all source - files. -+ -All of the packaging functions defined above are run starting inside `$srcdir` - -*pkgdir*:: - This contains the directory where makepkg bundles the installed package. - This directory will become the root directory of your built package. This - variable should only be used in the `package()` function. - -*startdir*:: - This contains the absolute path to the directory where the PKGBUILD is - located, which is usually the output of `$(pwd)` when makepkg is started. - Use of this variable is deprecated and strongly discouraged. - - -Package Splitting ------------------ -makepkg supports building multiple packages from a single PKGBUILD. This is -achieved by assigning an array of package names to the `pkgname` directive. -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 in the PKGBUILD. Nevertheless, the following ones can be overridden within -each split package's packaging function: -`pkgdesc`, `arch`, `url`, `license`, `groups`, `depends`, `optdepends`, -`provides`, `conflicts`, `replaces`, `backup`, `options`, `install`, and -`changelog`. - -Note that makepkg does not consider split package `depends` when checking -if dependencies are installed before package building and with `--syncdeps`. -All packages required to make the package are required to be specified in -the global `depends` and `makedepends` arrays. - -An optional global directive is available when building a split package: - -*pkgbase*:: - The name used to refer to the group of packages in the output of makepkg - and in the naming of source-only tarballs. If not specified, the first - element in the `pkgname` array is used. Valid characters for this - variable are alphanumerics, and any of the following characters: - ```@ . _ + -`''. Additionally, the variable is not allowed to start with - hyphens or dots. - - -Install/Upgrade/Remove Scripting --------------------------------- -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, and should be -self-explanatory. Note that during an upgrade operation, none of the install -or remove functions 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*:: - Run right before files are extracted. One argument is passed: - new package full version string. - -*post_install*:: - Run right after files are extracted. One argument is passed: - new package full version string. - -*pre_upgrade*:: - 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*:: - Run after files are extracted. Two arguments are passed in this order: - new package full version string, old package full version string. - -*pre_remove*:: - Run right before files are removed. One argument is passed: - old package full version string. - -*post_remove*:: - 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: - - install=pkgname.install - -The install script does not need to be specified in the source array. A -template install file is available in '{pkgdatadir}' as 'proto.install' for -reference with all of the available functions defined. - - -Using VCS Sources[[VCS]] ------------------------- -Building a developmental version of a package using sources from a version -control system (VCS) is enabled by specifying the source in the form -`source=('directory::url#fragment?query')`. Currently makepkg supports the -Bazaar, Git, Subversion, and Mercurial version control systems. For other -version control systems, manual cloning of upstream repositories must be done -in the `prepare()` function. - -The source URL is divided into four components: - -*directory*:: - (optional) Specifies an alternate directory name for makepkg to download - the VCS source into. - -*url*:: - The URL to the VCS repository. This must include the VCS in the URL protocol - for makepkg to recognize this as a VCS source. If the protocol does not - include the VCS name, it can be added by prefixing the URL with `vcs+`. For - example, using a Git repository over HTTPS would have a source URL in the - form: - `git+https://...`. - -*fragment*:: - (optional) Allows specifying a revision number or branch for makepkg to checkout - from the VCS. For example, to checkout a given revision, the source line would - have the format `source=(url#revision=123)`. The available fragments depends on - the VCS being used: - - *bzr*;; - revision (see `'bzr help revisionspec'` for details) - - *git*;; - branch, commit, tag - - *hg*;; - branch, revision, tag - - *svn*;; - revision - -*query*:: - (optional) Allows specifying whether a VCS checkout should be checked for - PGP-signed revisions. The source line should have the format - `source=(url#fragment?signed)` or `source=(url?signed#fragment)`. Currently - only supported by Git. - -Example -------- -The following is an example PKGBUILD for the 'patch' package. For more -examples, look through the build files of your distribution's packages. For -those using Arch Linux, consult the Arch Build System (ABS) tree. - -[source,sh] -------------------------------- -include::PKGBUILD-example.txt[] -------------------------------- - - -See Also --------- -linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5] - -include::footer.txt[] diff --git a/doc/alpm-hooks.5.asciidoc b/doc/alpm-hooks.5.asciidoc new file mode 100644 index 00000000..1d19f96e --- /dev/null +++ b/doc/alpm-hooks.5.asciidoc @@ -0,0 +1,128 @@ +alpm-hooks(5) +============= + +NAME +---- + +alpm-hooks - alpm hook file format + +SYNOPSIS +-------- + +-------- +[Trigger] (Required, Repeatable) +Operation = Install|Upgrade|Remove (Required, Repeatable) +Type = File|Package (Required) +Target = (Required, Repeatable) + +[Action] (Required) +Description = ... (Optional) +When = PreTransaction|PostTransaction (Required) +Exec = (Required) +Depends = (Optional) +AbortOnFail (Optional, PreTransaction only) +NeedsTargets (Optional) +-------- + +DESCRIPTION +----------- + +libalpm provides the ability to specify hooks to run before or after +transactions based on the packages and/or files being modified. Hooks consist +of a single '[Action]' section describing the action to be run and one or more +'[Trigger]' section describing which transactions it should be run for. Hook +file names are required to have the suffix ".hook". Hooks are run in +alphabetical order of their file name. + +TRIGGERS +-------- + +Hooks must contain at least one '[Trigger]' section that determines which +transactions will cause the hook to run. If multiple trigger sections are +defined the hook will run if the transaction matches *any* of the triggers. + +*Operation =* Install|Upgrade|Remove:: + Select the type of operation to match targets against. May be specified + multiple times. Installations are considered an upgrade if the package or + file is already present on the system regardless of whether the new package + version is actually greater than the currently installed version. For File + triggers, this is true even if the file changes ownership from one package + to another. Required. + +*Type =* File|Package:: + Select whether targets are matched against transaction packages or files. + See CAVEATS for special notes regarding File triggers. Required. + +*Target =* :: + The file path or package name to match against the active transaction. + File paths refer to the files in the package archive; the installation root + should *not* be included in the path. Shell-style glob patterns are + allowed. It is possible to invert matches by prepending a file with an + exclamation mark. May be specified multiple times. Required. + +ACTIONS +------- + +*Description =* ...:: + An optional description that describes the action being taken by the + hook for use in front-end output. + +*Exec =* :: + Command to run. Command arguments are split on whitespace. Values + containing whitespace should be enclosed in quotes. Required. + +*When =* PreTransaction|PostTransaction:: + When to run the hook. Required. + +*Depends =* :: + Packages that must be installed for the hook to run. May be specified + multiple times. + +*AbortOnFail*:: + Causes the transaction to be aborted if the hook exits non-zero. Only + applies to PreTransaction hooks. + +*NeedsTargets*:: + Causes the list of matched trigger targets to be passed to the running hook + on 'stdin'. + +OVERRIDING HOOKS +---------------- + +Hooks may be overridden by placing a file with the same name in a higher +priority hook directory. Hooks may be disabled by overriding them with +a symlink to '/dev/null'. + +EXAMPLES +-------- + +-------- +# Force disks to sync to reduce the risk of data corruption + +[Trigger] +Operation = Install +Operation = Upgrade +Operation = Remove +Type = Package +Target = * + +[Action] +Depends = coreutils +When = PostTransaction +Exec = /usr/bin/sync +-------- + +CAVEATS +------- + +There are situations when file triggers may act in unexpected ways. Hooks are +triggered using the file list of the installed, upgraded, or removed package. +When installing or upgrading a file that is extracted with a '.pacnew' +extension, the original file name is used in triggering the hook. When +removing a package, all files owned by that package can trigger a hook whether +or not they were actually present on the file system before package removal. + +PostTransaction hooks will *not* run if the transaction fails to complete for +any reason. + +include::footer.asciidoc[] diff --git a/doc/alpm-hooks.5.txt b/doc/alpm-hooks.5.txt deleted file mode 100644 index eb56054e..00000000 --- a/doc/alpm-hooks.5.txt +++ /dev/null @@ -1,128 +0,0 @@ -alpm-hooks(5) -============= - -NAME ----- - -alpm-hooks - alpm hook file format - -SYNOPSIS --------- - --------- -[Trigger] (Required, Repeatable) -Operation = Install|Upgrade|Remove (Required, Repeatable) -Type = File|Package (Required) -Target = (Required, Repeatable) - -[Action] (Required) -Description = ... (Optional) -When = PreTransaction|PostTransaction (Required) -Exec = (Required) -Depends = (Optional) -AbortOnFail (Optional, PreTransaction only) -NeedsTargets (Optional) --------- - -DESCRIPTION ------------ - -libalpm provides the ability to specify hooks to run before or after -transactions based on the packages and/or files being modified. Hooks consist -of a single '[Action]' section describing the action to be run and one or more -'[Trigger]' section describing which transactions it should be run for. Hook -file names are required to have the suffix ".hook". Hooks are run in -alphabetical order of their file name. - -TRIGGERS --------- - -Hooks must contain at least one '[Trigger]' section that determines which -transactions will cause the hook to run. If multiple trigger sections are -defined the hook will run if the transaction matches *any* of the triggers. - -*Operation =* Install|Upgrade|Remove:: - Select the type of operation to match targets against. May be specified - multiple times. Installations are considered an upgrade if the package or - file is already present on the system regardless of whether the new package - version is actually greater than the currently installed version. For File - triggers, this is true even if the file changes ownership from one package - to another. Required. - -*Type =* File|Package:: - Select whether targets are matched against transaction packages or files. - See CAVEATS for special notes regarding File triggers. Required. - -*Target =* :: - The file path or package name to match against the active transaction. - File paths refer to the files in the package archive; the installation root - should *not* be included in the path. Shell-style glob patterns are - allowed. It is possible to invert matches by prepending a file with an - exclamation mark. May be specified multiple times. Required. - -ACTIONS -------- - -*Description =* ...:: - An optional description that describes the action being taken by the - hook for use in front-end output. - -*Exec =* :: - Command to run. Command arguments are split on whitespace. Values - containing whitespace should be enclosed in quotes. Required. - -*When =* PreTransaction|PostTransaction:: - When to run the hook. Required. - -*Depends =* :: - Packages that must be installed for the hook to run. May be specified - multiple times. - -*AbortOnFail*:: - Causes the transaction to be aborted if the hook exits non-zero. Only - applies to PreTransaction hooks. - -*NeedsTargets*:: - Causes the list of matched trigger targets to be passed to the running hook - on 'stdin'. - -OVERRIDING HOOKS ----------------- - -Hooks may be overridden by placing a file with the same name in a higher -priority hook directory. Hooks may be disabled by overriding them with -a symlink to '/dev/null'. - -EXAMPLES --------- - --------- -# Force disks to sync to reduce the risk of data corruption - -[Trigger] -Operation = Install -Operation = Upgrade -Operation = Remove -Type = Package -Target = * - -[Action] -Depends = coreutils -When = PostTransaction -Exec = /usr/bin/sync --------- - -CAVEATS -------- - -There are situations when file triggers may act in unexpected ways. Hooks are -triggered using the file list of the installed, upgraded, or removed package. -When installing or upgrading a file that is extracted with a '.pacnew' -extension, the original file name is used in triggering the hook. When -removing a package, all files owned by that package can trigger a hook whether -or not they were actually present on the file system before package removal. - -PostTransaction hooks will *not* run if the transaction fails to complete for -any reason. - -include::footer.txt[] diff --git a/doc/footer.asciidoc b/doc/footer.asciidoc new file mode 100644 index 00000000..5812aa72 --- /dev/null +++ b/doc/footer.asciidoc @@ -0,0 +1,32 @@ + +See the pacman website at https://www.archlinux.org/pacman/[] for current +information on pacman and its related tools. + + +Bugs +---- +Bugs? You must be kidding; there are no bugs in this software. But if we +happen to be wrong, send us an email with as much detail as possible to +mailto:pacman-dev@archlinux.org[]. + + +Authors +------- + +Current maintainers: + +* Allan McRae +* Andrew Gregory +* Dan McGee +* Dave Reisner + +Past major contributors: + +* Judd Vinet +* Aurelien Foret +* Aaron Griffin +* Xavier Chantry +* Nagy Gabor + +For additional contributors, use `git shortlog -s` on the pacman.git +repository. diff --git a/doc/footer.txt b/doc/footer.txt deleted file mode 100644 index 5812aa72..00000000 --- a/doc/footer.txt +++ /dev/null @@ -1,32 +0,0 @@ - -See the pacman website at https://www.archlinux.org/pacman/[] for current -information on pacman and its related tools. - - -Bugs ----- -Bugs? You must be kidding; there are no bugs in this software. But if we -happen to be wrong, send us an email with as much detail as possible to -mailto:pacman-dev@archlinux.org[]. - - -Authors -------- - -Current maintainers: - -* Allan McRae -* Andrew Gregory -* Dan McGee -* Dave Reisner - -Past major contributors: - -* Judd Vinet -* Aurelien Foret -* Aaron Griffin -* Xavier Chantry -* Nagy Gabor - -For additional contributors, use `git shortlog -s` on the pacman.git -repository. diff --git a/doc/index.asciidoc b/doc/index.asciidoc new file mode 100644 index 00000000..48510830 --- /dev/null +++ b/doc/index.asciidoc @@ -0,0 +1,261 @@ +Pacman Home Page +================ + +A simple library-based package manager. + +Introduction +------------ +pacman is a utility which manages software packages in Linux. It uses simple +compressed files as a package format, and maintains a text-based package +database (more of a hierarchy), just in case some hand tweaking is necessary. + +pacman does not strive to "do everything." It will add, remove and upgrade +packages in the system, and it will allow you to query the package database for +installed packages, files and owners. It also attempts to handle dependencies +automatically and can download packages from a remote server. + +History +~~~~~~~ +Version 2.0 of pacman introduced the ability to sync packages (the '\--sync' +option) with a master server through the use of package databases. Prior to +this, packages would have to be installed manually using the '\--add' and +'\--upgrade' operations. + +Version 3.0 was the switch to a two-part pacman -- a back-end named libalpm +(library for Arch Linux Package Management) and the familiar pacman front-end. +Speed in many cases was improved, along with dependency and conflict resolution +being able to handle a much wider variety of cases. The switch to a +library-based program should also make it easier in the future to develop +alternative front ends. + +Version 4.0 added package signing and verification capabilities to the entire +makepkg/repo-add/pacman toolchain via GnuPG and GPGME. + +Version 5.0 added support for pre/post-transaction hooks and sync database file +list operations. + +Documentation +------------- + +Man Pages +~~~~~~~~~ +There are several man pages available for the programs, utilities, and +configuration files dealing with pacman. + +* linkman:alpm-hooks[5] +* linkman:PKGBUILD[5] +* linkman:libalpm[3] +* 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] + +Changelog +~~~~~~~~~ +For a good idea of what is going on in pacman development, take a look at the +link:https://projects.archlinux.org/pacman.git/[Git summary page] for the +project. + +See the most recent +link:https://projects.archlinux.org/pacman.git/tree/NEWS[NEWS] +file for a not-as-frequently-updated list of changes. However, this should +contain the biggest changes in a format more concise than the commit log. + + +Releases +-------- + +[frame="none",grid="none",options="autowidth",cols="3*a"] +|====== +| +[frame="topbot",grid="none",options="header,autowidth"] +!====== +!Version !Date +!5.0.1 !2016-02-23 +!5.0.0 !2016-01-30 +!4.2.1 !2015-02-20 +!4.2.0 !2014-12-19 +!4.1.2 !2013-06-18 +!4.1.1 !2013-05-07 +!4.1.0 !2013-04-01 +!4.1.0rc1 !2013-03-09 +!4.0.3 !2012-04-07 +!4.0.2 !2012-02-11 +!4.0.1 !2011-11-20 +!4.0.0 !2011-10-13 +!4.0.0rc2 !2011-09-22 +!4.0.0rc1 !2011-08-11 +!3.5.4 !2011-08-10 +!3.5.3 !2011-06-07 +!3.5.2 !2011-04-18 +!3.5.1 !2011-03-23 +!3.5.0 !2011-03-16 +!3.4.3 !2011-01-22 +!3.4.2 !2010-12-29 +!3.4.1 !2010-09-03 +!3.4.0 !2010-06-16 +!3.3.3 !2009-11-10 +!3.3.2 !2009-10-05 +!3.3.1 !2009-09-22 +!3.3.0 !2009-08-02 +!3.2.2 !2009-01-05 +!3.2.1 !2008-08-26 +!3.2.0 !2008-07-30 +!3.1.4 !2008-04-01 +!====== +| +[frame="topbot",grid="none",options="header,autowidth"] +!====== +!Version !Date +!3.1.3 !2008-03-06 +!3.1.2 !2008-02-20 +!3.1.1 !2008-01-20 +!3.1.0 !2008-01-09 +!3.0.6 !2007-09-16 +!3.0.5 !2007-06-17 +!3.0.4 !2007-05-08 +!3.0.3 !2007-04-28 +!3.0.2 !2007-04-23 +!3.0.1 !2007-04-04 +!3.0.0 !2007-03-25 +!2.9.8 !2006-02-02 +!2.9.7 !2005-09-16 +!2.9.7-TEST3 !2005-09-11 +!2.9.7-TEST2 !2005-09-07 +!2.9.7-TEST !2005-08-19 +!2.9.6 !2005-06-10 +!2.9.5 !2005-01-11 +!2.9.4 !2004-12-20 +!2.9.3 !2004-12-19 +!2.9.2 !2004-09-25 +!2.9.1 !2004-09-25 +!2.9 !2004-09-18 +!2.8.4 !2004-08-23 +!2.8.3 !2004-08-04 +!2.8.2 !2004-07-22 +!2.8.1 !2004-07-17 +!2.8 !2004-07-03 +!2.7.9 !2004-04-30 +!2.7.8 !2004-04-29 +!====== +| +[frame="topbot",grid="none",options="header,autowidth"] +!====== +!Version !Date +!2.7.7 !2004-04-15 +!2.7.6 !2004-04-04 +!2.7.5 !2004-03-02 +!2.7.4 !2004-02-18 +!2.7.3 !2004-02-07 +!2.7.2 !2004-01-04 +!2.7.1 !2003-12-21 +!2.7 !2003-11-25 +!2.6.4 !2003-10-17 +!2.6.3 !2003-10-01 +!2.6.2 !2003-09-29 +!2.6.1 !2003-09-15 +!2.6 !2003-09-03 +!2.5.1 !2003-07-12 +!2.5 !2003-05-30 +!2.4.1 !2003-04-19 +!2.4 !2003-04-11 +!2.3.2 !2003-03-17 +!2.3.1 !2003-03-14 +!2.3 !2003-02-27 +!2.2 !2002-12-11 +!2.1 !2002-09-16 +!2.0 !2002-08-09 +!1.23 !2002-04-30 +!1.22 !2002-04-12 +!1.21 !2002-04-03 +!1.2 !2002-03-18 +!1.1 !2002-03-10 +!1.0 !2002-02-25 +!====== + +|====== + +Source code for all releases is available at +link:https://sources.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 + +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. + +Development +----------- + +Mailing List +~~~~~~~~~~~~ +There is a mailing list devoted to pacman development, hosted by Arch Linux. +link:https://mailman.archlinux.org/mailman/listinfo/pacman-dev/[Subscribe] or +link:https://mailman.archlinux.org/pipermail/pacman-dev/[view the archives]. + +Source Code +~~~~~~~~~~~ +Development of pacman is currently done in Git. The central repository is +hosted by Arch Linux, although some of the developers have their own trees (ask +on the above mailing lists if you are interested in finding the locations of +these trees). + +The current development tree can be fetched with the following command: + + 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 +link:https://projects.archlinux.org/pacman.git/[cgit]. HTTP/HTTPS URLs are also +available for cloning purposes; these URLs are listed at the above page. + +If you are interested in hacking on pacman, it is highly recommended you join +the mailing list mentioned above, as well as take a quick glance at our +link:HACKING.html[HACKING] document. +link:submitting-patches.html[submitting-patches] is also a recommended read. + +Not as familiar with code as you'd like to be, but still want to help out? If +you speak a foreign language, you can help by either creating or updating a +translation file for your native language. Instructions can be found in +link:translation-help.html[translation-help]. + +Other Utilities +~~~~~~~~~~~~~~~ +Although the package manager itself is quite simple, many scripts have been +developed that help automate building and installing packages. These are used +extensively in link:https://www.archlinux.org/[Arch Linux]. Most of these utilities +are available in the Arch Linux projects +link:https://projects.archlinux.org/[code browser]. + +Utilities available: + +* link:https://projects.archlinux.org/abs.git/[abs] - ABS (Arch Build System), scripts to download & use the Arch Linux PKGBUILD tree +* link:https://projects.archlinux.org/dbscripts.git/[dbscripts] - scripts used by Arch Linux to manage the main package repositories +* link:https://projects.archlinux.org/devtools.git/[devtools] - tools to assist in packaging and dependency checking +* link:https://projects.archlinux.org/namcap.git/[namcap] - a package analysis utility written in python +* link:https://projects.archlinux.org/srcpac.git/[srcpac] - a bash build-from-source pacman wrapper + +Bugs +---- +If you find bugs (which is quite likely), please email them to the pacman-dev +mailing last at mailto:pacman-dev@archlinux.org[] with specific information +such as your command-line, the nature of the bug, and even the package database +if it helps. + +You can also post a bug to the Arch Linux bug tracker +link:https://bugs.archlinux.org/index.php?project=3[Flyspray]. Be sure to file +bugs under the Pacman project. + +Copyright +--------- +pacman is Copyright (C) 2006-2018 Pacman Development Team + and Copyright (C) 2002-2006 Judd Vinet + and is licensed through the GNU General Public License, +version 2 or later. diff --git a/doc/index.txt b/doc/index.txt deleted file mode 100644 index 48510830..00000000 --- a/doc/index.txt +++ /dev/null @@ -1,261 +0,0 @@ -Pacman Home Page -================ - -A simple library-based package manager. - -Introduction ------------- -pacman is a utility which manages software packages in Linux. It uses simple -compressed files as a package format, and maintains a text-based package -database (more of a hierarchy), just in case some hand tweaking is necessary. - -pacman does not strive to "do everything." It will add, remove and upgrade -packages in the system, and it will allow you to query the package database for -installed packages, files and owners. It also attempts to handle dependencies -automatically and can download packages from a remote server. - -History -~~~~~~~ -Version 2.0 of pacman introduced the ability to sync packages (the '\--sync' -option) with a master server through the use of package databases. Prior to -this, packages would have to be installed manually using the '\--add' and -'\--upgrade' operations. - -Version 3.0 was the switch to a two-part pacman -- a back-end named libalpm -(library for Arch Linux Package Management) and the familiar pacman front-end. -Speed in many cases was improved, along with dependency and conflict resolution -being able to handle a much wider variety of cases. The switch to a -library-based program should also make it easier in the future to develop -alternative front ends. - -Version 4.0 added package signing and verification capabilities to the entire -makepkg/repo-add/pacman toolchain via GnuPG and GPGME. - -Version 5.0 added support for pre/post-transaction hooks and sync database file -list operations. - -Documentation -------------- - -Man Pages -~~~~~~~~~ -There are several man pages available for the programs, utilities, and -configuration files dealing with pacman. - -* linkman:alpm-hooks[5] -* linkman:PKGBUILD[5] -* linkman:libalpm[3] -* 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] - -Changelog -~~~~~~~~~ -For a good idea of what is going on in pacman development, take a look at the -link:https://projects.archlinux.org/pacman.git/[Git summary page] for the -project. - -See the most recent -link:https://projects.archlinux.org/pacman.git/tree/NEWS[NEWS] -file for a not-as-frequently-updated list of changes. However, this should -contain the biggest changes in a format more concise than the commit log. - - -Releases --------- - -[frame="none",grid="none",options="autowidth",cols="3*a"] -|====== -| -[frame="topbot",grid="none",options="header,autowidth"] -!====== -!Version !Date -!5.0.1 !2016-02-23 -!5.0.0 !2016-01-30 -!4.2.1 !2015-02-20 -!4.2.0 !2014-12-19 -!4.1.2 !2013-06-18 -!4.1.1 !2013-05-07 -!4.1.0 !2013-04-01 -!4.1.0rc1 !2013-03-09 -!4.0.3 !2012-04-07 -!4.0.2 !2012-02-11 -!4.0.1 !2011-11-20 -!4.0.0 !2011-10-13 -!4.0.0rc2 !2011-09-22 -!4.0.0rc1 !2011-08-11 -!3.5.4 !2011-08-10 -!3.5.3 !2011-06-07 -!3.5.2 !2011-04-18 -!3.5.1 !2011-03-23 -!3.5.0 !2011-03-16 -!3.4.3 !2011-01-22 -!3.4.2 !2010-12-29 -!3.4.1 !2010-09-03 -!3.4.0 !2010-06-16 -!3.3.3 !2009-11-10 -!3.3.2 !2009-10-05 -!3.3.1 !2009-09-22 -!3.3.0 !2009-08-02 -!3.2.2 !2009-01-05 -!3.2.1 !2008-08-26 -!3.2.0 !2008-07-30 -!3.1.4 !2008-04-01 -!====== -| -[frame="topbot",grid="none",options="header,autowidth"] -!====== -!Version !Date -!3.1.3 !2008-03-06 -!3.1.2 !2008-02-20 -!3.1.1 !2008-01-20 -!3.1.0 !2008-01-09 -!3.0.6 !2007-09-16 -!3.0.5 !2007-06-17 -!3.0.4 !2007-05-08 -!3.0.3 !2007-04-28 -!3.0.2 !2007-04-23 -!3.0.1 !2007-04-04 -!3.0.0 !2007-03-25 -!2.9.8 !2006-02-02 -!2.9.7 !2005-09-16 -!2.9.7-TEST3 !2005-09-11 -!2.9.7-TEST2 !2005-09-07 -!2.9.7-TEST !2005-08-19 -!2.9.6 !2005-06-10 -!2.9.5 !2005-01-11 -!2.9.4 !2004-12-20 -!2.9.3 !2004-12-19 -!2.9.2 !2004-09-25 -!2.9.1 !2004-09-25 -!2.9 !2004-09-18 -!2.8.4 !2004-08-23 -!2.8.3 !2004-08-04 -!2.8.2 !2004-07-22 -!2.8.1 !2004-07-17 -!2.8 !2004-07-03 -!2.7.9 !2004-04-30 -!2.7.8 !2004-04-29 -!====== -| -[frame="topbot",grid="none",options="header,autowidth"] -!====== -!Version !Date -!2.7.7 !2004-04-15 -!2.7.6 !2004-04-04 -!2.7.5 !2004-03-02 -!2.7.4 !2004-02-18 -!2.7.3 !2004-02-07 -!2.7.2 !2004-01-04 -!2.7.1 !2003-12-21 -!2.7 !2003-11-25 -!2.6.4 !2003-10-17 -!2.6.3 !2003-10-01 -!2.6.2 !2003-09-29 -!2.6.1 !2003-09-15 -!2.6 !2003-09-03 -!2.5.1 !2003-07-12 -!2.5 !2003-05-30 -!2.4.1 !2003-04-19 -!2.4 !2003-04-11 -!2.3.2 !2003-03-17 -!2.3.1 !2003-03-14 -!2.3 !2003-02-27 -!2.2 !2002-12-11 -!2.1 !2002-09-16 -!2.0 !2002-08-09 -!1.23 !2002-04-30 -!1.22 !2002-04-12 -!1.21 !2002-04-03 -!1.2 !2002-03-18 -!1.1 !2002-03-10 -!1.0 !2002-02-25 -!====== - -|====== - -Source code for all releases is available at -link:https://sources.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 - -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. - -Development ------------ - -Mailing List -~~~~~~~~~~~~ -There is a mailing list devoted to pacman development, hosted by Arch Linux. -link:https://mailman.archlinux.org/mailman/listinfo/pacman-dev/[Subscribe] or -link:https://mailman.archlinux.org/pipermail/pacman-dev/[view the archives]. - -Source Code -~~~~~~~~~~~ -Development of pacman is currently done in Git. The central repository is -hosted by Arch Linux, although some of the developers have their own trees (ask -on the above mailing lists if you are interested in finding the locations of -these trees). - -The current development tree can be fetched with the following command: - - 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 -link:https://projects.archlinux.org/pacman.git/[cgit]. HTTP/HTTPS URLs are also -available for cloning purposes; these URLs are listed at the above page. - -If you are interested in hacking on pacman, it is highly recommended you join -the mailing list mentioned above, as well as take a quick glance at our -link:HACKING.html[HACKING] document. -link:submitting-patches.html[submitting-patches] is also a recommended read. - -Not as familiar with code as you'd like to be, but still want to help out? If -you speak a foreign language, you can help by either creating or updating a -translation file for your native language. Instructions can be found in -link:translation-help.html[translation-help]. - -Other Utilities -~~~~~~~~~~~~~~~ -Although the package manager itself is quite simple, many scripts have been -developed that help automate building and installing packages. These are used -extensively in link:https://www.archlinux.org/[Arch Linux]. Most of these utilities -are available in the Arch Linux projects -link:https://projects.archlinux.org/[code browser]. - -Utilities available: - -* link:https://projects.archlinux.org/abs.git/[abs] - ABS (Arch Build System), scripts to download & use the Arch Linux PKGBUILD tree -* link:https://projects.archlinux.org/dbscripts.git/[dbscripts] - scripts used by Arch Linux to manage the main package repositories -* link:https://projects.archlinux.org/devtools.git/[devtools] - tools to assist in packaging and dependency checking -* link:https://projects.archlinux.org/namcap.git/[namcap] - a package analysis utility written in python -* link:https://projects.archlinux.org/srcpac.git/[srcpac] - a bash build-from-source pacman wrapper - -Bugs ----- -If you find bugs (which is quite likely), please email them to the pacman-dev -mailing last at mailto:pacman-dev@archlinux.org[] with specific information -such as your command-line, the nature of the bug, and even the package database -if it helps. - -You can also post a bug to the Arch Linux bug tracker -link:https://bugs.archlinux.org/index.php?project=3[Flyspray]. Be sure to file -bugs under the Pacman project. - -Copyright ---------- -pacman is Copyright (C) 2006-2018 Pacman Development Team - and Copyright (C) 2002-2006 Judd Vinet - and is licensed through the GNU General Public License, -version 2 or later. diff --git a/doc/libalpm.3.asciidoc b/doc/libalpm.3.asciidoc new file mode 100644 index 00000000..79ea5409 --- /dev/null +++ b/doc/libalpm.3.asciidoc @@ -0,0 +1,37 @@ +libalpm(3) +========== + +Name +---- +libalpm - Arch Linux Package Management (ALPM) library + + +Synopsis +-------- +For ease of access, the libalpm manual has been split up into several sections. + +*TODO:* Yes, this man page needs a lot of work. Once we get around to doing +good Doxygen documentation, it will improve. We promise. + +*alpm_databases*:: Database Functions +*alpm_interface*:: Interface Functions +*alpm_list*:: List Functions +*alpm_log*:: Logging Functions +*alpm_misc*:: Miscellaneous Functions +*alpm_packages*:: Package Functions +*alpm_sync*:: Sync Functions +*alpm_trans*:: Transaction Functions + + +Configuration +------------- +See linkman:pacman.conf[5] for more details on configuring libalpm using the +'pacman.conf' file. + + +See Also +-------- +linkman:alpm-hooks[5], linkman:makepkg[8], linkman:pacman[8], +linkman:pacman.conf[5] + +include::footer.asciidoc[] diff --git a/doc/libalpm.3.txt b/doc/libalpm.3.txt deleted file mode 100644 index e75fb880..00000000 --- a/doc/libalpm.3.txt +++ /dev/null @@ -1,37 +0,0 @@ -libalpm(3) -========== - -Name ----- -libalpm - Arch Linux Package Management (ALPM) library - - -Synopsis --------- -For ease of access, the libalpm manual has been split up into several sections. - -*TODO:* Yes, this man page needs a lot of work. Once we get around to doing -good Doxygen documentation, it will improve. We promise. - -*alpm_databases*:: Database Functions -*alpm_interface*:: Interface Functions -*alpm_list*:: List Functions -*alpm_log*:: Logging Functions -*alpm_misc*:: Miscellaneous Functions -*alpm_packages*:: Package Functions -*alpm_sync*:: Sync Functions -*alpm_trans*:: Transaction Functions - - -Configuration -------------- -See linkman:pacman.conf[5] for more details on configuring libalpm using the -'pacman.conf' file. - - -See Also --------- -linkman:alpm-hooks[5], linkman:makepkg[8], linkman:pacman[8], -linkman:pacman.conf[5] - -include::footer.txt[] diff --git a/doc/makepkg-template.1.asciidoc b/doc/makepkg-template.1.asciidoc new file mode 100644 index 00000000..1cf39fb2 --- /dev/null +++ b/doc/makepkg-template.1.asciidoc @@ -0,0 +1,118 @@ +makepkg-template(1) +=================== + +Name +---- +makepkg-template - package build templating utility + + +Synopsis +-------- +'makepkg-template' [options] + + +Description +----------- +'makepkg-template' is a script to ease the work of maintaining multiple similar +PKGBUILDs. It allows you to move most of the code from the PKGBUILD into a +template file and uses markers to allow in-place updating of existing PKGBUILDs +if the template has been changed. + +Template files can contain any code allowed in a PKGBUILD. You can think of +them like external files included with "." or "source", but they will be +inlined into the PKGBUILD by 'makepkg-template' so you do not depend on the +template file when building the package. + +Markers are bash comments in the form of: + + # template start; key=value; key2=value2; ... + +and + + # template end; + +Currently used keys are: name (mandatory) and version. Template names are limited to +alphanumerics, "@", "+", ".", "-", and "_". Versions are limited to numbers and ".". + +For initial creation there is a one line short cut which does not need an end marker: + + # template input; key=value; + +Using this short-cut will result in 'makepkg-template' replacing it with start +and end markers and the template code on the first run. + +Template files should be stored in one directory and filenames should be +"$template_name-$version.template" with a symlink "$template_name.template" +pointing to the most recent template. If the version is not set in the marker, +'makepkg-template' will automatically use the target of "$template_name.template", +otherwise the specified version will be used. This allows for easier +verification of untrusted PKGBUILDs if the template is trusted. You verify the +non-template code and then use a command similar to this: + + diff -u <(makepkg-template -o -) PKGBUILD + +Template files may also contain markers leading to nested templates in the +resulting PKGBUILD. If you use markers in a template, please set the version +you used/tested with in the start/input marker so other people can properly +recreate from templates. + + +Options +------- +*-p, \--input* :: + Read the package script `build script` instead of the default. + +*-o, \--output* :: + Write the updated file to `build script` instead of overwriting the input file. + +*-n, \--newest*:: + Always use the newest available template file. + +*\--template-dir* :: + Change the dir where we are looking for template files. This option may be + given multiple times in which case files found in directory given last will + take precedence. + + +Example PKGBUILD +---------------- + + pkgname=perl-config-simple + pkgver=4.58 + pkgrel=1 + pkgdesc="simple configuration file class" + arch=('any') + license=('PerlArtistic' 'GPL') + depends=('perl') + source=("http://search.cpan.org/CPAN/authors/id/S/SH/SHERZODR/Config-Simple-${pkgver}.tar.gz") + md5sums=('f014aec54f0a1e2e880d317180fce502') + _distname="Config-Simple" + + # template start; name=perl-module; version=1.0; + _distdir="${_distname}-${pkgver}" + url="https://metacpan.org/release/${_distname}" + options+=('!emptydirs') + + build() { + cd "$srcdir/$_distdir" + perl Makefile.PL INSTALLDIRS=vendor + make + } + + check() { + cd "$srcdir/$_distdir" + make test + } + + package() { + cd "$srcdir/$_distdir" + make DESTDIR="$pkgdir" install + } + # template end; + + +See Also +-------- +linkman:makepkg[8], linkman:PKGBUILD[5] + +include::footer.asciidoc[] diff --git a/doc/makepkg-template.1.txt b/doc/makepkg-template.1.txt deleted file mode 100644 index fcb19b07..00000000 --- a/doc/makepkg-template.1.txt +++ /dev/null @@ -1,118 +0,0 @@ -makepkg-template(1) -=================== - -Name ----- -makepkg-template - package build templating utility - - -Synopsis --------- -'makepkg-template' [options] - - -Description ------------ -'makepkg-template' is a script to ease the work of maintaining multiple similar -PKGBUILDs. It allows you to move most of the code from the PKGBUILD into a -template file and uses markers to allow in-place updating of existing PKGBUILDs -if the template has been changed. - -Template files can contain any code allowed in a PKGBUILD. You can think of -them like external files included with "." or "source", but they will be -inlined into the PKGBUILD by 'makepkg-template' so you do not depend on the -template file when building the package. - -Markers are bash comments in the form of: - - # template start; key=value; key2=value2; ... - -and - - # template end; - -Currently used keys are: name (mandatory) and version. Template names are limited to -alphanumerics, "@", "+", ".", "-", and "_". Versions are limited to numbers and ".". - -For initial creation there is a one line short cut which does not need an end marker: - - # template input; key=value; - -Using this short-cut will result in 'makepkg-template' replacing it with start -and end markers and the template code on the first run. - -Template files should be stored in one directory and filenames should be -"$template_name-$version.template" with a symlink "$template_name.template" -pointing to the most recent template. If the version is not set in the marker, -'makepkg-template' will automatically use the target of "$template_name.template", -otherwise the specified version will be used. This allows for easier -verification of untrusted PKGBUILDs if the template is trusted. You verify the -non-template code and then use a command similar to this: - - diff -u <(makepkg-template -o -) PKGBUILD - -Template files may also contain markers leading to nested templates in the -resulting PKGBUILD. If you use markers in a template, please set the version -you used/tested with in the start/input marker so other people can properly -recreate from templates. - - -Options -------- -*-p, \--input* :: - Read the package script `build script` instead of the default. - -*-o, \--output* :: - Write the updated file to `build script` instead of overwriting the input file. - -*-n, \--newest*:: - Always use the newest available template file. - -*\--template-dir* :: - Change the dir where we are looking for template files. This option may be - given multiple times in which case files found in directory given last will - take precedence. - - -Example PKGBUILD ----------------- - - pkgname=perl-config-simple - pkgver=4.58 - pkgrel=1 - pkgdesc="simple configuration file class" - arch=('any') - license=('PerlArtistic' 'GPL') - depends=('perl') - source=("http://search.cpan.org/CPAN/authors/id/S/SH/SHERZODR/Config-Simple-${pkgver}.tar.gz") - md5sums=('f014aec54f0a1e2e880d317180fce502') - _distname="Config-Simple" - - # template start; name=perl-module; version=1.0; - _distdir="${_distname}-${pkgver}" - url="https://metacpan.org/release/${_distname}" - options+=('!emptydirs') - - build() { - cd "$srcdir/$_distdir" - perl Makefile.PL INSTALLDIRS=vendor - make - } - - check() { - cd "$srcdir/$_distdir" - make test - } - - package() { - cd "$srcdir/$_distdir" - make DESTDIR="$pkgdir" install - } - # template end; - - -See Also --------- -linkman:makepkg[8], linkman:PKGBUILD[5] - -include::footer.txt[] diff --git a/doc/makepkg.8.asciidoc b/doc/makepkg.8.asciidoc new file mode 100644 index 00000000..b15e3a67 --- /dev/null +++ b/doc/makepkg.8.asciidoc @@ -0,0 +1,349 @@ +makepkg(8) +========== + +Name +---- +makepkg - package build utility + + +Synopsis +-------- +'makepkg' [options] [ENVVAR=value] [ENVVAR+=value] ... + + +Description +----------- +'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 +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 +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. + + +Options +------- +*-A, \--ignorearch*:: + Ignore a missing or incomplete arch field in the build script. This is + for rebuilding packages from source when the PKGBUILD may be slightly + outdated and not updated with an `arch=('yourarch')` field. + +*-c, \--clean*:: + Clean up leftover work files and directories after a successful build. + +*\--config* :: + Use an alternate configuration file instead of the +{sysconfdir}/makepkg.conf+ + default. + +*-d, \--nodeps*:: + Do not perform any dependency checks. This will let you override and + ignore any dependencies required. There is a good chance this option + will break the build process if all of the dependencies are not + installed. + +*-e, \--noextract*:: + Do not extract source files or run the prepare() function (if present); + use whatever source already exists in the $srcdir/ directory. This is + handy if you want to go into $srcdir/ and manually patch or tweak code, + then make a package out of the result. Keep in mind that creating a + patch may be a better solution to allow others to use your PKGBUILD. + +*\--verifysource*:: + For each source file in the source array of PKGBUILD, download the file + if required and perform the integrity checks. No extraction or build is + performed. Dependencies specified in the PKGBUILD will not be handled + unless `--syncdeps` is used. Useful for performing subsequent offline + builds. + +*-f, \--force*:: + makepkg will not build a package if a built package already exists in + the `PKGDEST` (set in linkman:makepkg.conf[5]) directory, which may + default to the current directory. This allows the built package to be + overwritten. + +*-g, \--geninteg*:: + For each source file in the source array of PKGBUILD, download the file + if required and generate integrity checks. The integrity checks generated + are determined by the checks present in the PKGBUILD, falling back to the + value of the INTEGRITY_CHECK array in makepkg.conf(5) if these are absent + This output can be redirected into your PKGBUILD for source validation + using "`makepkg -g >> PKGBUILD`". + +*--skipinteg*:: + 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. + +*--holdver*:: + When using VCS sources (linkman:PKGBUILD[5]) any currently checked out source + will not be updated to the latest revision. + +*-i, \--install*:: + Install or upgrade the package after a successful build using + linkman:pacman[8]. + +*-L, \--log*:: + Enable logging. This will use the *tee* program to send the output of each + of the PKGBUILD functions to both the console and to a text file in the + build directory named `pkgbase-pkgver-pkgrel-arch-.log`. + As mentioned above, the logs will be localized so you may want to set your + locale accordingly if sharing the log output with others. + +*-m, \--nocolor*:: + Disable color in output messages. + +*-o, \--nobuild*:: + Download and extract files, run the prepare() function, but do not build + them. Useful with the '\--noextract' option if you wish to tweak the files + in $srcdir/ before building. + +*-p* :: + Read the package script `buildscript` instead of the `PKGBUILD` default; + see linkman:PKGBUILD[5]. The `buildscript` must be located in the directory + makepkg is called from. + +*-r, \--rmdeps*:: + Upon successful build, remove any dependencies installed by makepkg + during dependency auto-resolution and installation when using `-s`. + +*-R, \--repackage*:: + Repackage contents of the package without rebuilding the package. This + is useful if you forgot, for example, a dependency or install file in your + PKGBUILD and the build itself will not change. + +*-s, \--syncdeps*:: + Install missing dependencies using pacman. When build-time or run-time + dependencies are not found, pacman will try to resolve them. If + successful, the missing packages will be downloaded and installed. + +*-S, \--source*:: + Do not actually build the package, but build a source-only tarball that + does not include sources that can be fetched via a download URL. This is + useful for passing a single tarball to another program such as a chroot, + remote builder, or a tarball upload. Because integrity checks are verified, + all source files of the package need to be present or downloadable. + +*-V, \--version*:: + Display version information. + +*-C, \--cleanbuild*:: + Remove the $srcdir before building the package. + +*\--allsource*:: + Do not actually build the package, but build a source-only tarball that + includes all sources, including those that are normally downloaded via + makepkg. This is useful for passing a single tarball to another program + such as a chroot or remote builder. It will also satisfy requirements of + the GPL when distributing binary packages. + +*\--check*:: + Run the check() function in the PKGBUILD, overriding the setting in + linkman:makepkg.conf[5]. + +*\--noarchive*:: + Do not create the archive at the end of the build process. This can be + useful to test the package() function or if your target distribution does + not use pacman. + +*\--nocheck*:: + Do not run the check() function in the PKGBUILD or handle the checkdepends. + +*\--noprepare*:: + Do not run the prepare() function in the PKGBUILD. + +*\--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* :: + 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. + +*\--needed*:: + (Passed to pacman) Tell pacman not to reinstall a target if it is already + up-to-date. (used with '-i' / '\--install'). + +*\--asdeps*:: + (Passed to pacman) Install packages as non-explicitly installed (used + with '-i' / '\--install'). + +*\--noprogressbar*:: + (Passed to pacman) Prevent pacman from displaying a progress bar; + useful if you are redirecting makepkg output to file. + +*\--packagelist*:: + List the package filenames that would be produced without building. Listed + package filenames include PKGDEST and PKGEXT. + +*\--printsrcinfo*:: + Generate and print the SRCINFO file to stdout. + + +Additional Features +------------------- +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'. See linkman:PKGBUILD[5] for details on how to +set up a development PKGBUILD. + + +Reproducibility +--------------- +makepkg is designed to be compatible with +link:https://reproducible-builds.org/docs/[Reproducible Builds]. If the +**SOURCE_DATE_EPOCH** environment variable is set, it will be exported to +subprocesses, and source and package file modification times and package +metadata will be unified based on the timestamp specified. + +If the **SOURCE_DATE_EPOCH** environment variable is not set, makepkg will use +its own start date for internal use, but will not unify source file timestamps +before building. + + +Environment Variables +--------------------- +**PACMAN**:: + The command that will be used to check for missing dependencies and to + install and remove packages. Pacman's '-Qq', '-Rns', '-S', '-T', and '-U' + operations must be supported by this command. If the variable is not + set or empty, makepkg will fall back to `pacman'. + +**MAKEPKG_CONF=**"/path/to/file":: + Use an alternate config file instead of the +{sysconfdir}/makepkg.conf+ + default. + +**PKGDEST=**"/path/to/directory":: + Directory where the resulting packages will be stored. Overrides the + corresponding value defined in linkman:makepkg.conf[5]. + +**SRCDEST=**"/path/to/directory":: + Directory where the downloaded sources will be stored. Overrides the + corresponding value defined in linkman:makepkg.conf[5]. + +**SRCPKGDEST=**"/path/to/directory":: + Directory where source package files will be stored. Overrides the + corresponding value defined in linkman:makepkg.conf[5]. + +**LOGDEST=**"/path/to/directory":: + Directory where generated log files will be stored. Overrides the + corresponding value defined in linkman:makepkg.conf[5]. + +**PACKAGER=**"John Doe ":: + String to identify the creator of the resulting package. Overrides + the corresponding value defined in linkman:makepkg.conf[5]. + +**BUILDDIR=**"/path/to/directory":: + Directory where the package will be built. Overrides the corresponding + value defined in linkman:makepkg.conf[5]. + +**CARCH=**"(i686|x86_64)":: + Force build for a specific architecture. Useful for cross-compiling. + Overrides the corresponding value defined in linkman:makepkg.conf[5]. + +**PKGEXT=**".pkg.tar.gz", **SRCEXT=**".src.tar.gz":: + Sets the compression used when making compiled or source packages. + Overrides the corresponding value defined in linkman:makepkg.conf[5]. + +**GNUPGHOME=**"/path/to/directory":: + Directory where the gpg keyring for signing the built package is stored. + +**GPGKEY=**"keyid":: + Specify a key to use when signing packages, overriding the GPGKEY setting + in linkman:makepkg.conf[5] + +**SOURCE_DATE_EPOCH=**"":: + Used for link:https://reproducible-builds.org/docs/[Reproducible Builds]. + +Configuration +------------- +See linkman:makepkg.conf[5] for more details on configuring makepkg using the +'makepkg.conf' file. + + +Errors +------ +On exit, makepkg will return one of the following error codes. + +0:: + Normal exit condition. + +1:: + Unknown cause of failure. + +2:: + Error in configuration file. + +3:: + User specified an invalid option + +4:: + Error in user-supplied function in PKGBUILD. + +5:: + Failed to create a viable package. + +6:: + A source or auxiliary file specified in the PKGBUILD is + missing. + +7:: + The PKGDIR is missing. + +8:: + Failed to install dependencies. + +9:: + Failed to remove dependencies. + +10:: + User attempted to run makepkg as root. + +11:: + User lacks permissions to build or install to a given + location. + +12:: + Error parsing PKGBUILD. + +13:: + A package has already been built. + +14:: + The package failed to install. + +15:: + Programs necessary to run makepkg are missing. + +16:: + Specified GPG key does not exist. + +See Also +-------- +linkman:makepkg.conf[5], linkman:PKGBUILD[5], linkman:pacman[8] + +include::footer.asciidoc[] diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt deleted file mode 100644 index 58e9b27a..00000000 --- a/doc/makepkg.8.txt +++ /dev/null @@ -1,349 +0,0 @@ -makepkg(8) -========== - -Name ----- -makepkg - package build utility - - -Synopsis --------- -'makepkg' [options] [ENVVAR=value] [ENVVAR+=value] ... - - -Description ------------ -'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 -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 -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. - - -Options -------- -*-A, \--ignorearch*:: - Ignore a missing or incomplete arch field in the build script. This is - for rebuilding packages from source when the PKGBUILD may be slightly - outdated and not updated with an `arch=('yourarch')` field. - -*-c, \--clean*:: - Clean up leftover work files and directories after a successful build. - -*\--config* :: - Use an alternate configuration file instead of the +{sysconfdir}/makepkg.conf+ - default. - -*-d, \--nodeps*:: - Do not perform any dependency checks. This will let you override and - ignore any dependencies required. There is a good chance this option - will break the build process if all of the dependencies are not - installed. - -*-e, \--noextract*:: - Do not extract source files or run the prepare() function (if present); - use whatever source already exists in the $srcdir/ directory. This is - handy if you want to go into $srcdir/ and manually patch or tweak code, - then make a package out of the result. Keep in mind that creating a - patch may be a better solution to allow others to use your PKGBUILD. - -*\--verifysource*:: - For each source file in the source array of PKGBUILD, download the file - if required and perform the integrity checks. No extraction or build is - performed. Dependencies specified in the PKGBUILD will not be handled - unless `--syncdeps` is used. Useful for performing subsequent offline - builds. - -*-f, \--force*:: - makepkg will not build a package if a built package already exists in - the `PKGDEST` (set in linkman:makepkg.conf[5]) directory, which may - default to the current directory. This allows the built package to be - overwritten. - -*-g, \--geninteg*:: - For each source file in the source array of PKGBUILD, download the file - if required and generate integrity checks. The integrity checks generated - are determined by the checks present in the PKGBUILD, falling back to the - value of the INTEGRITY_CHECK array in makepkg.conf(5) if these are absent - This output can be redirected into your PKGBUILD for source validation - using "`makepkg -g >> PKGBUILD`". - -*--skipinteg*:: - 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. - -*--holdver*:: - When using VCS sources (linkman:PKGBUILD[5]) any currently checked out source - will not be updated to the latest revision. - -*-i, \--install*:: - Install or upgrade the package after a successful build using - linkman:pacman[8]. - -*-L, \--log*:: - Enable logging. This will use the *tee* program to send the output of each - of the PKGBUILD functions to both the console and to a text file in the - build directory named `pkgbase-pkgver-pkgrel-arch-.log`. - As mentioned above, the logs will be localized so you may want to set your - locale accordingly if sharing the log output with others. - -*-m, \--nocolor*:: - Disable color in output messages. - -*-o, \--nobuild*:: - Download and extract files, run the prepare() function, but do not build - them. Useful with the '\--noextract' option if you wish to tweak the files - in $srcdir/ before building. - -*-p* :: - Read the package script `buildscript` instead of the `PKGBUILD` default; - see linkman:PKGBUILD[5]. The `buildscript` must be located in the directory - makepkg is called from. - -*-r, \--rmdeps*:: - Upon successful build, remove any dependencies installed by makepkg - during dependency auto-resolution and installation when using `-s`. - -*-R, \--repackage*:: - Repackage contents of the package without rebuilding the package. This - is useful if you forgot, for example, a dependency or install file in your - PKGBUILD and the build itself will not change. - -*-s, \--syncdeps*:: - Install missing dependencies using pacman. When build-time or run-time - dependencies are not found, pacman will try to resolve them. If - successful, the missing packages will be downloaded and installed. - -*-S, \--source*:: - Do not actually build the package, but build a source-only tarball that - does not include sources that can be fetched via a download URL. This is - useful for passing a single tarball to another program such as a chroot, - remote builder, or a tarball upload. Because integrity checks are verified, - all source files of the package need to be present or downloadable. - -*-V, \--version*:: - Display version information. - -*-C, \--cleanbuild*:: - Remove the $srcdir before building the package. - -*\--allsource*:: - Do not actually build the package, but build a source-only tarball that - includes all sources, including those that are normally downloaded via - makepkg. This is useful for passing a single tarball to another program - such as a chroot or remote builder. It will also satisfy requirements of - the GPL when distributing binary packages. - -*\--check*:: - Run the check() function in the PKGBUILD, overriding the setting in - linkman:makepkg.conf[5]. - -*\--noarchive*:: - Do not create the archive at the end of the build process. This can be - useful to test the package() function or if your target distribution does - not use pacman. - -*\--nocheck*:: - Do not run the check() function in the PKGBUILD or handle the checkdepends. - -*\--noprepare*:: - Do not run the prepare() function in the PKGBUILD. - -*\--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* :: - 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. - -*\--needed*:: - (Passed to pacman) Tell pacman not to reinstall a target if it is already - up-to-date. (used with '-i' / '\--install'). - -*\--asdeps*:: - (Passed to pacman) Install packages as non-explicitly installed (used - with '-i' / '\--install'). - -*\--noprogressbar*:: - (Passed to pacman) Prevent pacman from displaying a progress bar; - useful if you are redirecting makepkg output to file. - -*\--packagelist*:: - List the package filenames that would be produced without building. Listed - package filenames include PKGDEST and PKGEXT. - -*\--printsrcinfo*:: - Generate and print the SRCINFO file to stdout. - - -Additional Features -------------------- -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'. See linkman:PKGBUILD[5] for details on how to -set up a development PKGBUILD. - - -Reproducibility ---------------- -makepkg is designed to be compatible with -link:https://reproducible-builds.org/docs/[Reproducible Builds]. If the -**SOURCE_DATE_EPOCH** environment variable is set, it will be exported to -subprocesses, and source and package file modification times and package -metadata will be unified based on the timestamp specified. - -If the **SOURCE_DATE_EPOCH** environment variable is not set, makepkg will use -its own start date for internal use, but will not unify source file timestamps -before building. - - -Environment Variables ---------------------- -**PACMAN**:: - The command that will be used to check for missing dependencies and to - install and remove packages. Pacman's '-Qq', '-Rns', '-S', '-T', and '-U' - operations must be supported by this command. If the variable is not - set or empty, makepkg will fall back to `pacman'. - -**MAKEPKG_CONF=**"/path/to/file":: - Use an alternate config file instead of the +{sysconfdir}/makepkg.conf+ - default. - -**PKGDEST=**"/path/to/directory":: - Directory where the resulting packages will be stored. Overrides the - corresponding value defined in linkman:makepkg.conf[5]. - -**SRCDEST=**"/path/to/directory":: - Directory where the downloaded sources will be stored. Overrides the - corresponding value defined in linkman:makepkg.conf[5]. - -**SRCPKGDEST=**"/path/to/directory":: - Directory where source package files will be stored. Overrides the - corresponding value defined in linkman:makepkg.conf[5]. - -**LOGDEST=**"/path/to/directory":: - Directory where generated log files will be stored. Overrides the - corresponding value defined in linkman:makepkg.conf[5]. - -**PACKAGER=**"John Doe ":: - String to identify the creator of the resulting package. Overrides - the corresponding value defined in linkman:makepkg.conf[5]. - -**BUILDDIR=**"/path/to/directory":: - Directory where the package will be built. Overrides the corresponding - value defined in linkman:makepkg.conf[5]. - -**CARCH=**"(i686|x86_64)":: - Force build for a specific architecture. Useful for cross-compiling. - Overrides the corresponding value defined in linkman:makepkg.conf[5]. - -**PKGEXT=**".pkg.tar.gz", **SRCEXT=**".src.tar.gz":: - Sets the compression used when making compiled or source packages. - Overrides the corresponding value defined in linkman:makepkg.conf[5]. - -**GNUPGHOME=**"/path/to/directory":: - Directory where the gpg keyring for signing the built package is stored. - -**GPGKEY=**"keyid":: - Specify a key to use when signing packages, overriding the GPGKEY setting - in linkman:makepkg.conf[5] - -**SOURCE_DATE_EPOCH=**"":: - Used for link:https://reproducible-builds.org/docs/[Reproducible Builds]. - -Configuration -------------- -See linkman:makepkg.conf[5] for more details on configuring makepkg using the -'makepkg.conf' file. - - -Errors ------- -On exit, makepkg will return one of the following error codes. - -0:: - Normal exit condition. - -1:: - Unknown cause of failure. - -2:: - Error in configuration file. - -3:: - User specified an invalid option - -4:: - Error in user-supplied function in PKGBUILD. - -5:: - Failed to create a viable package. - -6:: - A source or auxiliary file specified in the PKGBUILD is - missing. - -7:: - The PKGDIR is missing. - -8:: - Failed to install dependencies. - -9:: - Failed to remove dependencies. - -10:: - User attempted to run makepkg as root. - -11:: - User lacks permissions to build or install to a given - location. - -12:: - Error parsing PKGBUILD. - -13:: - A package has already been built. - -14:: - The package failed to install. - -15:: - Programs necessary to run makepkg are missing. - -16:: - Specified GPG key does not exist. - -See Also --------- -linkman:makepkg.conf[5], linkman:PKGBUILD[5], linkman:pacman[8] - -include::footer.txt[] diff --git a/doc/makepkg.conf.5.asciidoc b/doc/makepkg.conf.5.asciidoc new file mode 100644 index 00000000..3b596a91 --- /dev/null +++ b/doc/makepkg.conf.5.asciidoc @@ -0,0 +1,269 @@ +makepkg.conf(5) +=============== + +Name +---- +makepkg.conf - makepkg configuration file + + +Synopsis +-------- +{sysconfdir}/makepkg.conf, $XDG_CONFIG_HOME/pacman/makepkg.conf, ~/.makepkg.conf + + +Description +----------- +Configuration options for makepkg are stored in makepkg.conf. This file is +sourced so you can include any special compiler flags you wish to use. This is +helpful when building for different architectures or with different +optimizations. However, only the variables described below are exported to the +build environment. + +NOTE: This does not guarantee that all package Makefiles will use your exported +variables. Some of them are non-standard. + +The system-wide configuration file is found in {sysconfdir}/makepkg.conf. +Individual options can be overridden (or added to) on a per-user basis in +$XDG_CONFIG_HOME/pacman/makepkg.conf or ~/.makepkg.conf, with the former +taking priority. + +The default file is fairly well commented, so it may be easiest to simply +follow directions given there for customization. + + +Options +------- +**DLAGENTS=(**\'protocol::/path/to/command [options]' ...**)**:: + Sets the download agents used to fetch source files specified with a URL in + the linkman:PKGBUILD[5] file. Options can be specified for each command as + well, and any protocol can have a download agent. Any spaces in option + arguments are required to be escaped to avoid being split. Several + examples are provided in the default makepkg.conf. + + + If present, `%u` will be replaced with the download URL. Otherwise, the + download URL will be placed on the end of the command. If present, `%o` will + be replaced with the local file name, plus a ``.part'' extension, which allows + makepkg to handle resuming file downloads. + +**VCSCLIENTS=(**\'protocol::package' ...**)**:: + Sets the packages required to fetch version controlled source files. When + required, makepkg will check that these packages are installed or are included + in the `depends` or `makedepends` arrays in the PKGBUILD. + +**CARCH=**"carch":: + Specifies your computer architecture; possible values include such things + as ``i686'', ``x86_64'', ``ppc'', etc. This should be automatically set on + installation. + +**CHOST=**"chost":: + A string such as ``i686-pc-linux-gnu''; do not touch this unless you know what + you are doing. This can be commented out by most users if desired. + +**CPPFLAGS=**"cppflags":: + Flags used for the C preprocessor; see CFLAGS for more information. + +**CFLAGS=**"cflags":: + Flags used for the C compiler. This is a key part to the use of makepkg. + Usually several options are specified, and the most common string resembles + something like this: ``-march=i686 -O2 -pipe''. Another useful option may + be `-mcpu` in place of `-march`. Read gcc(1) for more details on the wide + variety of compiler flags available. + +**CXXFLAGS=**"cxxflags":: + Flags used for the C++ compiler; see CFLAGS for more info. + +**LDFLAGS=**"ldflags":: + Flags used for the linker. Several options may be specified with common + usage resembling ``-Wl,--hash-style=gnu''. Read ld(1) for more details on + available linker flags. + +**MAKEFLAGS=**"makeflags":: + This is often used to set the number of jobs used; for example, `-j2`. + Other flags that make accepts can also be passed. + +**DEBUG_CFLAGS=**"debug_cflags":: + Additional compiler flags appended to `CFLAGS` for use in debugging. Usually + this would include: ``-g''. Read gcc(1) for more details on the wide + variety of compiler flags available. + +**DEBUG_CXXFLAGS=**"debug_cxxflags":: + Debug flags used for the C++ compiler; see DEBUG_CFLAGS for more info. + +**BUILDENV=(**!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 add an ``!'' at the front of the + option. If an option is specified multiple times, the final value takes + precedence. Each option works as follows: + + *distcc*;; + Use the distributed C/C++/ObjC compiler to spread compilation among + multiple machines. If this is enabled, `DISTCC_HOSTS` must be specified + as well. + + *color*;; + Colorize output messages, making output easier to read. + + *ccache*;; + Use ccache to cache compilation by default. This allows for faster + compiles if you are continuously recompiling the same packages. It can + 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. + + *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 file name 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`. + +**BUILDDIR=**"/path/to/directory":: + 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 directory. + 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 staticlibs emptydirs !zipman !purge !debug**)**:: + This array contains options that affect 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 + disable an option, simply remove or add an ``!'' at the front of the + option. If an option is specified multiple times, the final value takes + precedence. Each option works as follows: + + *strip*;; + Strip symbols from binaries and libraries. If you frequently use a + debugger on programs or libraries, it may be helpful to disable this + option. + + *docs*;; + Save doc directories. If you wish to delete doc directories, specify + `!docs` in the array. The directories affected are specified by the + `DOC_DIRS` variable. + + *libtool*;; + Leave libtool (.la) files in packages. Specify `!libtool` to remove + them. + + *staticlibs*;; + Leave static library (.a) files in packages. Specify `!staticlibs` to + remove them, if they have a shared counterpart. + + *emptydirs*;; + Leave empty directories in packages. + + *zipman*;; + Compress manual (man and info) pages with gzip. The directories + affected are specified by the `MAN_DIRS` variable. + + *purge*;; + Remove files specified by the `PURGE_TARGETS` variable from the + package. + + *debug*;; + Add the user-specified debug flags as specified in DEBUG_CFLAGS and + DEBUG_CXXFLAGS to their counterpart buildflags. Creates a separate + package containing the debug symbols when used with `strip'. + +**INTEGRITY_CHECK=(**check1 ...**)**:: + File integrity checks to use. Multiple checks may be specified; this + affects both generation and checking. The current valid options are: + `md5`, `sha1`, `sha256`, `sha384`, and `sha512`. + +**STRIP_BINARIES=**"--strip-all":: + Options to be used when stripping binaries. See linkman:strip[1] + for details. + +**STRIP_SHARED=**"--strip-unneeded":: + Options to be used when stripping shared libraries or PIE executables. + See linkman:strip[1] for details. + +**STRIP_STATIC=**"--strip-debug":: + Options to be used when stripping static libraries. See linkman:strip[1] + for details. + +**MAN_DIRS=(**{usr{,/local}{,/share},opt/*}/{man,info} ...**)**:: + If `zipman` is specified in the `OPTIONS` array, this variable will + instruct makepkg where to look to compress manual (man and info) + pages. 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. + +**DOC_DIRS=(**usr/{,share/}{doc,gtk-doc} ...**)**:: + If `!docs` is specified in the `OPTIONS` array, this variable will + instruct makepkg where to look to remove docs. 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 + useful for index files that are added by multiple packages. + +**DBGSRCDIR=**"/usr/src/debug":: + If `strip` and `debug` are specified in the `OPTIONS` array, this variable + will instruct makepkg where to place source files for installed binaries. + The binaries will be modified to link this directory for the debugger + search path. + +**PKGDEST=**"/path/to/directory":: + If this value is not set, packages will, by default, be placed in the + current directory (location of the linkman:PKGBUILD[5]). Many people + like to keep all their packages in one place so this option allows + for this behavior. A common location is ``/home/packages''. + +**SRCDEST=**"/path/to/directory":: + If this value is not set, downloaded source files will only be stored + in the current directory. Many people like to keep all source files in + a central location for easy cleanup, so this path can be set here. + +**SRCPKGDEST=**"/path/to/directory":: + If this value is not set, source package files will be stored in + in the current directory. Many people like to keep all source package files + in a central location for easy cleanup, so this path can be set here. + +**LOGDEST=**"/path/to/directory":: + If this value is not set, log files are written to the current + directory. This centralizes the log location, facilitating cleanup + and compression. + +**PACKAGER=**"John Doe ":: + This value is used when querying a package to see who was the builder. + It is recommended to change this to your name and email address. + +**COMPRESSGZ=**"(gzip -c -f -n)":: +**COMPRESSBZ2=**"(bzip2 -c -f)":: +**COMPRESSXZ=**"(xz -c -z -)":: +**COMPRESSLZO**"(lzop -q)":: +**COMPRESSLRZ=**"(lrzip -q)":: +**COMPRESSZ=**"(compress -c -f)":: + Sets the command and options used when compressing compiled or source + packages in the named format. + +**PKGEXT=**".pkg.tar.gz", **SRCEXT=**".src.tar.gz":: + Sets the compression used when making compiled or source packages. + Valid suffixes are `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, + `.tar.lzo`, `.tar.lrz`, and `.tar.Z`. + Do not touch these unless you know what you are doing. + + +See Also +-------- +linkman:makepkg[8], linkman:pacman[8], linkman:PKGBUILD[5] + +include::footer.asciidoc[] diff --git a/doc/makepkg.conf.5.txt b/doc/makepkg.conf.5.txt deleted file mode 100644 index 27ca3d9d..00000000 --- a/doc/makepkg.conf.5.txt +++ /dev/null @@ -1,269 +0,0 @@ -makepkg.conf(5) -=============== - -Name ----- -makepkg.conf - makepkg configuration file - - -Synopsis --------- -{sysconfdir}/makepkg.conf, $XDG_CONFIG_HOME/pacman/makepkg.conf, ~/.makepkg.conf - - -Description ------------ -Configuration options for makepkg are stored in makepkg.conf. This file is -sourced so you can include any special compiler flags you wish to use. This is -helpful when building for different architectures or with different -optimizations. However, only the variables described below are exported to the -build environment. - -NOTE: This does not guarantee that all package Makefiles will use your exported -variables. Some of them are non-standard. - -The system-wide configuration file is found in {sysconfdir}/makepkg.conf. -Individual options can be overridden (or added to) on a per-user basis in -$XDG_CONFIG_HOME/pacman/makepkg.conf or ~/.makepkg.conf, with the former -taking priority. - -The default file is fairly well commented, so it may be easiest to simply -follow directions given there for customization. - - -Options -------- -**DLAGENTS=(**\'protocol::/path/to/command [options]' ...**)**:: - Sets the download agents used to fetch source files specified with a URL in - the linkman:PKGBUILD[5] file. Options can be specified for each command as - well, and any protocol can have a download agent. Any spaces in option - arguments are required to be escaped to avoid being split. Several - examples are provided in the default makepkg.conf. - + - If present, `%u` will be replaced with the download URL. Otherwise, the - download URL will be placed on the end of the command. If present, `%o` will - be replaced with the local file name, plus a ``.part'' extension, which allows - makepkg to handle resuming file downloads. - -**VCSCLIENTS=(**\'protocol::package' ...**)**:: - Sets the packages required to fetch version controlled source files. When - required, makepkg will check that these packages are installed or are included - in the `depends` or `makedepends` arrays in the PKGBUILD. - -**CARCH=**"carch":: - Specifies your computer architecture; possible values include such things - as ``i686'', ``x86_64'', ``ppc'', etc. This should be automatically set on - installation. - -**CHOST=**"chost":: - A string such as ``i686-pc-linux-gnu''; do not touch this unless you know what - you are doing. This can be commented out by most users if desired. - -**CPPFLAGS=**"cppflags":: - Flags used for the C preprocessor; see CFLAGS for more information. - -**CFLAGS=**"cflags":: - Flags used for the C compiler. This is a key part to the use of makepkg. - Usually several options are specified, and the most common string resembles - something like this: ``-march=i686 -O2 -pipe''. Another useful option may - be `-mcpu` in place of `-march`. Read gcc(1) for more details on the wide - variety of compiler flags available. - -**CXXFLAGS=**"cxxflags":: - Flags used for the C++ compiler; see CFLAGS for more info. - -**LDFLAGS=**"ldflags":: - Flags used for the linker. Several options may be specified with common - usage resembling ``-Wl,--hash-style=gnu''. Read ld(1) for more details on - available linker flags. - -**MAKEFLAGS=**"makeflags":: - This is often used to set the number of jobs used; for example, `-j2`. - Other flags that make accepts can also be passed. - -**DEBUG_CFLAGS=**"debug_cflags":: - Additional compiler flags appended to `CFLAGS` for use in debugging. Usually - this would include: ``-g''. Read gcc(1) for more details on the wide - variety of compiler flags available. - -**DEBUG_CXXFLAGS=**"debug_cxxflags":: - Debug flags used for the C++ compiler; see DEBUG_CFLAGS for more info. - -**BUILDENV=(**!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 add an ``!'' at the front of the - option. If an option is specified multiple times, the final value takes - precedence. Each option works as follows: - - *distcc*;; - Use the distributed C/C++/ObjC compiler to spread compilation among - multiple machines. If this is enabled, `DISTCC_HOSTS` must be specified - as well. - - *color*;; - Colorize output messages, making output easier to read. - - *ccache*;; - Use ccache to cache compilation by default. This allows for faster - compiles if you are continuously recompiling the same packages. It can - 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. - - *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 file name 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`. - -**BUILDDIR=**"/path/to/directory":: - 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 directory. - 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 staticlibs emptydirs !zipman !purge !debug**)**:: - This array contains options that affect 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 - disable an option, simply remove or add an ``!'' at the front of the - option. If an option is specified multiple times, the final value takes - precedence. Each option works as follows: - - *strip*;; - Strip symbols from binaries and libraries. If you frequently use a - debugger on programs or libraries, it may be helpful to disable this - option. - - *docs*;; - Save doc directories. If you wish to delete doc directories, specify - `!docs` in the array. The directories affected are specified by the - `DOC_DIRS` variable. - - *libtool*;; - Leave libtool (.la) files in packages. Specify `!libtool` to remove - them. - - *staticlibs*;; - Leave static library (.a) files in packages. Specify `!staticlibs` to - remove them, if they have a shared counterpart. - - *emptydirs*;; - Leave empty directories in packages. - - *zipman*;; - Compress manual (man and info) pages with gzip. The directories - affected are specified by the `MAN_DIRS` variable. - - *purge*;; - Remove files specified by the `PURGE_TARGETS` variable from the - package. - - *debug*;; - Add the user-specified debug flags as specified in DEBUG_CFLAGS and - DEBUG_CXXFLAGS to their counterpart buildflags. Creates a separate - package containing the debug symbols when used with `strip'. - -**INTEGRITY_CHECK=(**check1 ...**)**:: - File integrity checks to use. Multiple checks may be specified; this - affects both generation and checking. The current valid options are: - `md5`, `sha1`, `sha256`, `sha384`, and `sha512`. - -**STRIP_BINARIES=**"--strip-all":: - Options to be used when stripping binaries. See linkman:strip[1] - for details. - -**STRIP_SHARED=**"--strip-unneeded":: - Options to be used when stripping shared libraries or PIE executables. - See linkman:strip[1] for details. - -**STRIP_STATIC=**"--strip-debug":: - Options to be used when stripping static libraries. See linkman:strip[1] - for details. - -**MAN_DIRS=(**{usr{,/local}{,/share},opt/*}/{man,info} ...**)**:: - If `zipman` is specified in the `OPTIONS` array, this variable will - instruct makepkg where to look to compress manual (man and info) - pages. 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. - -**DOC_DIRS=(**usr/{,share/}{doc,gtk-doc} ...**)**:: - If `!docs` is specified in the `OPTIONS` array, this variable will - instruct makepkg where to look to remove docs. 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 - useful for index files that are added by multiple packages. - -**DBGSRCDIR=**"/usr/src/debug":: - If `strip` and `debug` are specified in the `OPTIONS` array, this variable - will instruct makepkg where to place source files for installed binaries. - The binaries will be modified to link this directory for the debugger - search path. - -**PKGDEST=**"/path/to/directory":: - If this value is not set, packages will, by default, be placed in the - current directory (location of the linkman:PKGBUILD[5]). Many people - like to keep all their packages in one place so this option allows - for this behavior. A common location is ``/home/packages''. - -**SRCDEST=**"/path/to/directory":: - If this value is not set, downloaded source files will only be stored - in the current directory. Many people like to keep all source files in - a central location for easy cleanup, so this path can be set here. - -**SRCPKGDEST=**"/path/to/directory":: - If this value is not set, source package files will be stored in - in the current directory. Many people like to keep all source package files - in a central location for easy cleanup, so this path can be set here. - -**LOGDEST=**"/path/to/directory":: - If this value is not set, log files are written to the current - directory. This centralizes the log location, facilitating cleanup - and compression. - -**PACKAGER=**"John Doe ":: - This value is used when querying a package to see who was the builder. - It is recommended to change this to your name and email address. - -**COMPRESSGZ=**"(gzip -c -f -n)":: -**COMPRESSBZ2=**"(bzip2 -c -f)":: -**COMPRESSXZ=**"(xz -c -z -)":: -**COMPRESSLZO**"(lzop -q)":: -**COMPRESSLRZ=**"(lrzip -q)":: -**COMPRESSZ=**"(compress -c -f)":: - Sets the command and options used when compressing compiled or source - packages in the named format. - -**PKGEXT=**".pkg.tar.gz", **SRCEXT=**".src.tar.gz":: - Sets the compression used when making compiled or source packages. - Valid suffixes are `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, - `.tar.lzo`, `.tar.lrz`, and `.tar.Z`. - Do not touch these unless you know what you are doing. - - -See Also --------- -linkman:makepkg[8], linkman:pacman[8], linkman:PKGBUILD[5] - -include::footer.txt[] diff --git a/doc/pacman-key.8.asciidoc b/doc/pacman-key.8.asciidoc new file mode 100644 index 00000000..f0b5ac08 --- /dev/null +++ b/doc/pacman-key.8.asciidoc @@ -0,0 +1,145 @@ +pacman-key(8) +============= + + +Name +---- +pacman-key - manage pacman's list of trusted keys + + +Synopsis +-------- +'pacman-key' [options] operation [targets] + + +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). + +Invoking pacman-key consists of supplying an operation with any potential +options and targets to operate on. Depending on the operation, a 'target' may +be a valid key identifier, filename, or directory. + + +Operations +---------- +*-a, \--add*:: + Add the key(s) contained in the specified file or files to pacman's + keyring. If a key already exists, update it. + +*-d, \--delete*:: + Remove the key(s) identified by the specified keyid(s) from pacman's + keyring. + +*-e, \--export*:: + Export key(s) identified by the specified keyid(s) to 'stdout'. If no keyid + is specified, all keys will be exported. + +*\--edit-key*:: + Present a menu for key management task on the specified keyid(s). Useful + for adjusting a keys trust level. + +*-f, \--finger*:: + List a fingerprint for each specified keyid, or for all known keys if no + keyids are specified. + +*-h, \--help*:: + Output syntax and command line options. + +*\--import*:: + Imports keys from `pubring.gpg` into the public keyring from the specified + directories. + +*\--import-trustdb*:: + Imports ownertrust values from `trustdb.gpg` into the shared trust database + from the specified directories. + +*\--init*:: + Ensure the keyring is properly initialized and has the required access + permissions. + +*-l, \--list-keys*:: + Lists all or specified keys from the public keyring. + +*\--list-sigs*:: + Same as '\--list-keys', but the signatures are listed too. + +*\--lsign-key*:: + Locally sign the given key. This is primarily used to root the web of trust + in the local private key generated by '\--init'. + +*\--nocolor*:: + Disable colored output from pacman-key. + +*-r, \--recv-keys*:: + Equivalent to '\--recv-keys' in GnuPG. + +*\--refresh-keys*:: + Equivalent to '\--refresh-keys' in GnuPG. + +*\--populate*:: + Reload the default keys from the (optionally provided) keyrings in + +{pkgdatadir}/keyrings+. For more information, see + <> below. + +*-u, \--updatedb*:: + Equivalent to '\--check-trustdb' in GnuPG. This operation can be specified with + other operations. + +*-V, \--version*:: + Displays the program version. + +*-v, \--verify*:: + Verify the file(s) specified by the signature(s). + + +Options +------- +*\--config* :: + Use an alternate configuration file instead of the +{sysconfdir}/pacman.conf+ + default. + +*\--gpgdir* :: + Set an alternate home directory for GnuPG. If unspecified, the value is + read from +{sysconfdir}/pacman.conf+. + +*\--keyserver* :: + Use the specified keyserver if the operation requires one. This will take + precedence over any keyserver option specified in a `gpg.conf` + configuration file. Running '\--init' with this option will set the default + keyserver if one was not already configured. + + +Providing a Keyring for Import[[PK]] +------------------------------------ +A distribution or other repository provided may want to provide a set of +PGP keys used in the signing of its packages and repository databases that can +be readily imported into the pacman keyring. This is achieved by providing a +PGP keyring file `foo.gpg` that contains the keys for the foo keyring in the +directory +{pkgdatadir}/keyrings+. + +Optionally, the file `foo-trusted` can be provided containing a list of trusted +key IDs for that keyring. This is a file in a format compatible with 'gpg +\--export-ownertrust' output. This file will inform the user which keys a user +needs to verify and sign to build a local web of trust, in addition to +assigning provided owner trust values. + +Also optionally, the file `foo-revoked` can be provided containing a list of +revoked key IDs for that keyring. Revoked is defined as "no longer valid for +any signing", so should be used with prudence. A key being marked as revoked +will be disabled in the keyring and no longer treated as valid, so this always +takes priority over it's trusted state in any other keyring. + + +See Also +-------- +linkman:pacman[8], linkman:pacman.conf[5] + +include::footer.asciidoc[] diff --git a/doc/pacman-key.8.txt b/doc/pacman-key.8.txt deleted file mode 100644 index 0b46f919..00000000 --- a/doc/pacman-key.8.txt +++ /dev/null @@ -1,145 +0,0 @@ -pacman-key(8) -============= - - -Name ----- -pacman-key - manage pacman's list of trusted keys - - -Synopsis --------- -'pacman-key' [options] operation [targets] - - -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). - -Invoking pacman-key consists of supplying an operation with any potential -options and targets to operate on. Depending on the operation, a 'target' may -be a valid key identifier, filename, or directory. - - -Operations ----------- -*-a, \--add*:: - Add the key(s) contained in the specified file or files to pacman's - keyring. If a key already exists, update it. - -*-d, \--delete*:: - Remove the key(s) identified by the specified keyid(s) from pacman's - keyring. - -*-e, \--export*:: - Export key(s) identified by the specified keyid(s) to 'stdout'. If no keyid - is specified, all keys will be exported. - -*\--edit-key*:: - Present a menu for key management task on the specified keyid(s). Useful - for adjusting a keys trust level. - -*-f, \--finger*:: - List a fingerprint for each specified keyid, or for all known keys if no - keyids are specified. - -*-h, \--help*:: - Output syntax and command line options. - -*\--import*:: - Imports keys from `pubring.gpg` into the public keyring from the specified - directories. - -*\--import-trustdb*:: - Imports ownertrust values from `trustdb.gpg` into the shared trust database - from the specified directories. - -*\--init*:: - Ensure the keyring is properly initialized and has the required access - permissions. - -*-l, \--list-keys*:: - Lists all or specified keys from the public keyring. - -*\--list-sigs*:: - Same as '\--list-keys', but the signatures are listed too. - -*\--lsign-key*:: - Locally sign the given key. This is primarily used to root the web of trust - in the local private key generated by '\--init'. - -*\--nocolor*:: - Disable colored output from pacman-key. - -*-r, \--recv-keys*:: - Equivalent to '\--recv-keys' in GnuPG. - -*\--refresh-keys*:: - Equivalent to '\--refresh-keys' in GnuPG. - -*\--populate*:: - Reload the default keys from the (optionally provided) keyrings in - +{pkgdatadir}/keyrings+. For more information, see - <> below. - -*-u, \--updatedb*:: - Equivalent to '\--check-trustdb' in GnuPG. This operation can be specified with - other operations. - -*-V, \--version*:: - Displays the program version. - -*-v, \--verify*:: - Verify the file(s) specified by the signature(s). - - -Options -------- -*\--config* :: - Use an alternate configuration file instead of the +{sysconfdir}/pacman.conf+ - default. - -*\--gpgdir* :: - Set an alternate home directory for GnuPG. If unspecified, the value is - read from +{sysconfdir}/pacman.conf+. - -*\--keyserver* :: - Use the specified keyserver if the operation requires one. This will take - precedence over any keyserver option specified in a `gpg.conf` - configuration file. Running '\--init' with this option will set the default - keyserver if one was not already configured. - - -Providing a Keyring for Import[[PK]] ------------------------------------- -A distribution or other repository provided may want to provide a set of -PGP keys used in the signing of its packages and repository databases that can -be readily imported into the pacman keyring. This is achieved by providing a -PGP keyring file `foo.gpg` that contains the keys for the foo keyring in the -directory +{pkgdatadir}/keyrings+. - -Optionally, the file `foo-trusted` can be provided containing a list of trusted -key IDs for that keyring. This is a file in a format compatible with 'gpg -\--export-ownertrust' output. This file will inform the user which keys a user -needs to verify and sign to build a local web of trust, in addition to -assigning provided owner trust values. - -Also optionally, the file `foo-revoked` can be provided containing a list of -revoked key IDs for that keyring. Revoked is defined as "no longer valid for -any signing", so should be used with prudence. A key being marked as revoked -will be disabled in the keyring and no longer treated as valid, so this always -takes priority over it's trusted state in any other keyring. - - -See Also --------- -linkman:pacman[8], linkman:pacman.conf[5] - -include::footer.txt[] diff --git a/doc/pacman.8.asciidoc b/doc/pacman.8.asciidoc new file mode 100644 index 00000000..b6f4dd76 --- /dev/null +++ b/doc/pacman.8.asciidoc @@ -0,0 +1,568 @@ +pacman(8) +========= + +Name +---- +pacman - package manager utility + + +Synopsis +-------- +'pacman' [options] [targets] + + +Description +----------- +Pacman is a package management utility that tracks installed packages on a Linux +system. It features dependency support, package groups, install and uninstall +scripts, and the ability to sync your local machine with a remote repository to +automatically upgrade packages. Pacman packages are a zipped tar format. + +Since version 3.0.0, pacman has been the front-end to linkman:libalpm[3], the +``Arch Linux Package Management'' library. This library allows alternative +front-ends to be written (for instance, a GUI front-end). + +Invoking pacman involves specifying an operation with any potential options and +targets to operate on. A 'target' is usually a package name, file name, URL, or +a search string. Targets can be provided as command line arguments. +Additionally, if stdin is not from a terminal and a single hyphen (-) is passed +as an argument, targets will be read from stdin. + + +Operations +---------- +*-D, \--database*:: + Operate on the package database. This operation allows you to modify + certain attributes of the installed packages in pacman's database. It + also allows you to check the databases for internal consistency. + See <> below. + +*-Q, \--query*:: + Query the package database. This operation allows you to view installed + packages and their files, as well as meta-information about individual + packages (dependencies, conflicts, install date, build date, size). This + can be run against the local package database or can be used on + individual package files. In the first case, if no package names + are provided in the command line, all installed packages will be + queried. Additionally, various filters can be applied on the package + list. See <> below. + +*-R, \--remove*:: + Remove package(s) from the system. Groups can also be specified to be + removed, in which case every package in that group will be removed. + Files belonging to the specified package will be deleted, and the + database will be updated. Most configuration files will be saved + with a '.pacsave' extension unless the '\--nosave' option is used. + See <> below. + +*-S, \--sync*:: + Synchronize packages. Packages are installed directly from the remote + repositories, including all dependencies required to run the packages. For + example, `pacman -S qt` will download and install qt and all the + packages it depends on. If a package name exists in more than one + repository, the repository can be explicitly specified to clarify the + package to install: `pacman -S testing/qt`. You can also specify version + requirements: `pacman -S "bash>=3.2"`. Quotes are needed, otherwise the + shell interprets ">" as redirection to a 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 provide a +prompt allowing you to select which packages to install from a numbered list. +The package selection is specified using a space- and/or comma-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. 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 +<> below. When upgrading, pacman performs version comparison +to determine which packages need upgrading. This behavior operates as follows: + + Alphanumeric: + 1.0a < 1.0b < 1.0beta < 1.0p < 1.0pre < 1.0rc < 1.0 < 1.0.a < 1.0.1 + 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 + installed packages. This operation will check each dependency specified and + return a list of dependencies that are not currently satisfied on the system. + This operation accepts no other options. Example usage: `pacman -T qt + "bash>=3.2"`. + +*-U, \--upgrade*:: + Upgrade or add package(s) to the system and install the required + dependencies from sync repositories. Either a URL or file path can be + specified. This is a ``remove-then-add'' process. See <> below; also see <> for an explanation + on how pacman takes care of configuration files. + +*-F, \--files*:: + Query the files database. This operation allows you to look for packages + owning certain files or display files owned by certain packages. Only + packages that are part of your sync databases are searched. See + <> below. + +*-V, \--version*:: + Display version and exit. + +*-h, \--help*:: + Display syntax for the given operation. If no operation was supplied, + then the general syntax is shown. + + +Options +------- +*-b, \--dbpath* :: + Specify an alternative database location (the default is + +{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. + +*-v, \--verbose*:: + Output paths such as as the Root, Conf File, DB Path, Cache Dirs, etc. + +*\--arch* :: + Specify an alternate architecture. + +*\--cachedir* :: + Specify an alternative package cache location (the default is + +{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, and the root path is not automatically + prepended. + +*\--color* :: + Specify when to enable coloring. Valid options are 'always', 'never', or + 'auto'. 'always' forces colors on; 'never' forces colors off; and 'auto' only + automatically enables colors when outputting onto a tty. + +*\--config* :: + Specify an alternate configuration file. + +*\--debug*:: + Display debug messages. When reporting bugs, this option is recommended + to be used. + +*\--gpgdir* :: + Specify a directory of files used by GnuPG to verify package signatures + (the 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, and the root path is not automatically prepended. + +*\--hookdir* :: + Specify a alternative directory containing hook files (the default is + +{sysconfdir}/pacman.d/hooks+). Multiple hook directories can be specified + with hooks in later directories taking precedence over hooks in earlier + directories. *NOTE*: This is an absolute path, and the root path is not + automatically prepended. + +*\--logfile* :: + Specify an alternate log file. This is an absolute path, regardless of + the installation root setting. + +*\--noconfirm*:: + 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. + +*\--confirm*:: + Cancels the effects of a previous '\--noconfirm'. + +*\--disable-download-timeout*:: + Disable defaults for low speed limit and timeout on downloads. Use this + if you have issues downloading files with proxy and/or security gateway. + +*\--sysroot* :: + Specify an alternative system root. Pacman will chroot and chdir into the + system root prior to running. This allows mounted guest systems to be + properly operated on. Any other paths given will be interpreted as relative + to the system root. Requires root privileges. + + +Transaction Options (apply to '-S', '-R' and '-U') +-------------------------------------------------- +*-d, \--nodeps*:: + Skips dependency version checks. Package names are still checked. 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. Specify this option twice to skip all dependency checks. + +*\--assume-installed* :: + Add a virtual package "package" with version "version" to the transaction + to satisfy dependencies. This allows to disable specific dependency checks + without affecting all dependency checks. To disable all dependency + checking, see the '\--nodeps' option. + +*\--dbonly*:: + Adds/removes the database entry only, leaving 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. + +*\--noscriptlet*:: + If an install scriptlet exists, do not execute it. Do not use this + unless you know what you are doing. + +*-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 URLs with + '-S', file names with '-U', and pkgname-pkgver with '-R'. + +*\--print-format* :: + Specify a printf-like format to control the output of the '\--print' + operation. The possible attributes are: "%n" for pkgname, "%v" for pkgver, + "%l" for location, "%r" for repository, and "%s" for size. Implies '\--print'. + + +Upgrade Options (apply to '-S' and '-U')[[UO]] +---------------------------------------------- +*\--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* :: + 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* :: + 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. + +*\--needed*:: + Do not reinstall the targets that are already up-to-date. + +*\--overwrite* :: + Bypass file conflict checks and overwrite conflicting files. If the + package that is about to be installed contains files that are already + installed and match 'glob', this option will cause all those files to be + overwritten. Using '\--overwrite' will not allow overwriting a directory + with a file or installing packages with conflicting files and directories. + Multiple patterns can be specified by separating them with a comma. May be + specified multiple times. Patterns can be negated, such that files + matching them will not be overwritten, by prefixing them with an + exclamation mark. Subsequent matches will override previous ones. A leading + literal exclamation mark or backslash needs to be escaped. + + +Query Options (apply to '-Q')[[QO]] +----------------------------------- +*-c, \--changelog*:: + View the ChangeLog of a package if it exists. + +*-d, \--deps*:: + Restrict or filter output to packages installed as dependencies. This + option can be combined with '-t' for listing real orphans - packages that + were installed as dependencies but are no longer required by any + installed package. + +*-e, \--explicit*:: + Restrict or filter output to explicitly installed packages. This option + can be combined with '-t' to list explicitly installed packages that + are not required by any other package. + +*-g, \--groups*:: + Display all packages that are members of a named group. If a name is not + specified, list all grouped packages. + +*-i, \--info*:: + Display information on a given package. The '-p' option can be used if + querying a package file instead of the local database. Passing two + '\--info' or '-i' flags will also display the list of backup files and + their modification states. + +*-k, \--check*:: + Check that all files owned by the given package(s) are present on the + system. If packages are not specified or filter flags are not provided, + check all installed packages. Specifying this option twice will perform + more detailed file checking (including permissions, file sizes, and + modification times) for packages that contain the needed mtree file. + +*-l, \--list*:: + List all files owned by a given package. Multiple packages can be + specified on the command line. + +*-m, \--foreign*:: + Restrict or filter output to packages that were not found in the sync + database(s). Typically these are packages that were downloaded manually + and installed with '\--upgrade'. + +*-n, \--native*:: + Restrict or filter output to packages that are found in the sync + database(s). This is the inverse filter of '\--foreign'. + +*-o, \--owns* :: + Search for packages that own the specified file(s). The path can be + relative or absolute, and one or more files can be specified. + +*-p, \--file*:: + Signifies that the package supplied on the command line is a file and + not an entry in the database. The file will be decompressed and queried. + This is useful in combination with '\--info' and '\--list'. + +*-q, \--quiet*:: + Show less information for certain query operations. This is useful when + pacman's output is processed in a script. Search will only show package + names and not version, group, and description information; owns will + only show package names instead of "file is owned by pkg" messages; group + will only show package names and omit group names; list will only show + files and omit package names; check will only show pairs of package names + and missing files; a bare query will only show package names + rather than names and versions. + +*-s, \--search* :: + Search each locally-installed package for names or descriptions that + match `regexp`. When including multiple search terms, only packages + with descriptions matching ALL of those terms are returned. + +*-t, \--unrequired*:: + Restrict or filter output to print only packages neither required nor + optionally required by any currently installed package. Specify this + option twice to include packages which are optionally, but not directly, + required by another package. + +*-u, \--upgrades*:: + Restrict or filter output to packages that are out-of-date on the local + system. Only package versions are used to find outdated packages; + replacements are not checked here. This option works best if the sync + database is refreshed using '-Sy'. + + +Remove Options (apply to '-R')[[RO]] +------------------------------------ +*-c, \--cascade*:: + Remove all target packages, as well as all packages that depend on one + or more target packages. This operation is recursive and must be used + with care, since it can remove many potentially needed packages. + +*-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 + file should be renamed with a '.pacsave' extension. + +*-s, \--recursive*:: + Remove each target specified including all of their dependencies, provided + that (A) they are not required by other packages; and (B) they were not + explicitly installed by the user. This operation is recursive and analogous + to a backwards '\--sync' operation, and it helps keep a clean system without + orphans. If you want to omit condition (B), pass this option twice. + +*-u, \--unneeded*:: + Removes targets that are not required by any other packages. + This is mostly useful when removing a group without using the '-c' option, + to avoid breaking any dependencies. + + +Sync Options (apply to '-S')[[SO]] +---------------------------------- +*-c, \--clean*:: + Remove packages that are no longer installed from the cache as well as + currently unused sync databases to free up disk space. When pacman + downloads packages, it saves them in a cache directory. In addition, + databases are saved for every sync DB you download from and are not + deleted even if they are removed from the configuration file + linkman:pacman.conf[5]. Use one '\--clean' switch to only remove + packages that are no longer installed; use two to remove all files + from the cache. In both cases, you will have a yes or no option to + remove packages and/or unused downloaded databases. ++ +If you use a network shared cache, see the 'CleanMethod' option in +linkman:pacman.conf[5]. + +*-g, \--groups*:: + Display all the members for each package group specified. If no group + names are provided, all groups will be listed; pass the flag twice to + view all groups and their members. + +*-i, \--info*:: + Display information on a given sync database package. Passing two '\--info' + or '-i' flags will also display those packages in all repositories that + depend on this package. + +*-l, \--list*:: + List all packages in the specified repositories. Multiple repositories + can be specified on the command line. + +*-q, \--quiet*:: + Show less information for certain sync operations. This is useful when + pacman's output is processed in a script. Search will only show package + names and not repository, version, group, and description information; list + will only show package names and omit databases and versions; group will + only show package names and omit group names. + +*-s, \--search* :: + This will search each package in the sync databases for names or + descriptions that match `regexp`. When you include multiple search + terms, only packages with descriptions matching ALL of those terms will + be returned. + +*-u, \--sysupgrade*:: + Upgrades all packages that are out-of-date. Each currently-installed + package will be examined and upgraded if a newer package exists. A + report of all packages to upgrade will be presented, and the operation + will not proceed without user confirmation. Dependencies are + automatically resolved at this level and will be installed/upgraded if + necessary. ++ +Pass this option twice to enable package downgrades; in this case, pacman will +select sync packages whose versions do not match with the local versions. This +can be useful when the user switches from a testing repository to a stable one. ++ +Additional targets can also be specified manually, so that '-Su foo' will do a +system upgrade and install/upgrade the "foo" package in the same operation. + +*-w, \--downloadonly*:: + Retrieve all packages from the server, but do not install/upgrade anything. + +*-y, \--refresh*:: + Download a fresh copy of the master package database from the server(s) + defined in linkman:pacman.conf[5]. This should typically be used each time + you use '\--sysupgrade' or '-u'. Passing two '\--refresh' or '-y' flags + will force a refresh of all package databases, even if they appear to be + up-to-date. + + +Database Options (apply to '-D')[[QO]] +-------------------------------------- +*\--asdeps* :: + Mark a package as non-explicitly installed; in other words, set their install + reason to be installed as a dependency. + +*\--asexplicit* :: + Mark a package as explicitly installed; in other words, set their install + reason to be explicitly installed. This is useful it you want to keep a + package installed even when it was initially installed as a dependency + of another package. + +*-k, \--check*:: + Check the local package database is internally consistent. This will + check all required files are present and that installed packages have + the required dependencies, do not conflict and that multiple packages + do not own the same file. Specifying this option twice will perform + a check on the sync databases to ensure all specified dependencies + are available. + +*-q, \--quiet*:: + Suppress messages on successful completion of database operations. + +File Options (apply to '-F')[[FO]] +---------------------------------- +*-y, --refresh*:: + Download fresh package databases from the server. Use twice to force a + refresh even if databases are up to date. + +*-l, \--list*:: + List the files owned by the queried package. + +*-s, \--search*:: + Search package file names for matching strings. + +*-x, --regex*:: + Treat arguments to '--search' as regular expressions. + +*-o, \--owns*:: + Search for packages that own a particular file. + +*-q, \--quiet*:: + Show less information for certain file operations. This is useful when + pacman's output is processed in a script, however, you may want to use + '--machinereadable' instead. + +*--machinereadable*:: + Use a machine readable output format for '--list', '--search' and + '--owns'. The format is 'repository\0pkgname\0pkgver\0path\n' with '\0' + being the NULL character and '\n' a linefeed. + +Handling Config Files[[HCF]] +---------------------------- +Pacman uses the same logic as 'rpm' to determine action against files that are +designated to be backed up. During an upgrade, three MD5 hashes are used for +each backup file to determine the required action: one for the original file +installed, one for the new file that is about to be installed, and one for the +actual file existing on the file system. After comparing these three hashes, the +follow scenarios can result: + +original=X, current=X, new=X:: + All three files are the same, so overwrites are not an issue. Install the + new file. + +original=X, current=X, new=Y:: + The current file is the same as the original, but the new one differs. + Since the user did not ever modify the file, and the new one may contain + improvements or bug fixes, install the new file. + +original=X, current=Y, new=X:: + Both package versions contain the exact same file, but the one on the + file system has been modified. Leave the current file in place. + +original=X, current=Y, new=Y:: + The new file is identical to the current file. Install the new file. + +original=X, current=Y, new=Z:: + All three files are different, so install the new file with a '.pacnew' + extension and warn the user. The user must then manually merge any + necessary changes into the original file. + +original=NULL, current=Y, new=Z:: + The package was not previously installed, and the file already exists on the + file system. Install the new file with a '.pacnew' extension and warn the + user. The user must then manually merge any 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 +'pacman.conf' file. + + +See Also +-------- +linkman:alpm-hooks[5], linkman:libalpm[3], linkman:makepkg[8], +linkman:pacman.conf[5] + +include::footer.asciidoc[] diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt deleted file mode 100644 index ebe16e61..00000000 --- a/doc/pacman.8.txt +++ /dev/null @@ -1,568 +0,0 @@ -pacman(8) -========= - -Name ----- -pacman - package manager utility - - -Synopsis --------- -'pacman' [options] [targets] - - -Description ------------ -Pacman is a package management utility that tracks installed packages on a Linux -system. It features dependency support, package groups, install and uninstall -scripts, and the ability to sync your local machine with a remote repository to -automatically upgrade packages. Pacman packages are a zipped tar format. - -Since version 3.0.0, pacman has been the front-end to linkman:libalpm[3], the -``Arch Linux Package Management'' library. This library allows alternative -front-ends to be written (for instance, a GUI front-end). - -Invoking pacman involves specifying an operation with any potential options and -targets to operate on. A 'target' is usually a package name, file name, URL, or -a search string. Targets can be provided as command line arguments. -Additionally, if stdin is not from a terminal and a single hyphen (-) is passed -as an argument, targets will be read from stdin. - - -Operations ----------- -*-D, \--database*:: - Operate on the package database. This operation allows you to modify - certain attributes of the installed packages in pacman's database. It - also allows you to check the databases for internal consistency. - See <> below. - -*-Q, \--query*:: - Query the package database. This operation allows you to view installed - packages and their files, as well as meta-information about individual - packages (dependencies, conflicts, install date, build date, size). This - can be run against the local package database or can be used on - individual package files. In the first case, if no package names - are provided in the command line, all installed packages will be - queried. Additionally, various filters can be applied on the package - list. See <> below. - -*-R, \--remove*:: - Remove package(s) from the system. Groups can also be specified to be - removed, in which case every package in that group will be removed. - Files belonging to the specified package will be deleted, and the - database will be updated. Most configuration files will be saved - with a '.pacsave' extension unless the '\--nosave' option is used. - See <> below. - -*-S, \--sync*:: - Synchronize packages. Packages are installed directly from the remote - repositories, including all dependencies required to run the packages. For - example, `pacman -S qt` will download and install qt and all the - packages it depends on. If a package name exists in more than one - repository, the repository can be explicitly specified to clarify the - package to install: `pacman -S testing/qt`. You can also specify version - requirements: `pacman -S "bash>=3.2"`. Quotes are needed, otherwise the - shell interprets ">" as redirection to a 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 provide a -prompt allowing you to select which packages to install from a numbered list. -The package selection is specified using a space- and/or comma-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. 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 -<> below. When upgrading, pacman performs version comparison -to determine which packages need upgrading. This behavior operates as follows: - - Alphanumeric: - 1.0a < 1.0b < 1.0beta < 1.0p < 1.0pre < 1.0rc < 1.0 < 1.0.a < 1.0.1 - 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 - installed packages. This operation will check each dependency specified and - return a list of dependencies that are not currently satisfied on the system. - This operation accepts no other options. Example usage: `pacman -T qt - "bash>=3.2"`. - -*-U, \--upgrade*:: - Upgrade or add package(s) to the system and install the required - dependencies from sync repositories. Either a URL or file path can be - specified. This is a ``remove-then-add'' process. See <> below; also see <> for an explanation - on how pacman takes care of configuration files. - -*-F, \--files*:: - Query the files database. This operation allows you to look for packages - owning certain files or display files owned by certain packages. Only - packages that are part of your sync databases are searched. See - <> below. - -*-V, \--version*:: - Display version and exit. - -*-h, \--help*:: - Display syntax for the given operation. If no operation was supplied, - then the general syntax is shown. - - -Options -------- -*-b, \--dbpath* :: - Specify an alternative database location (the default is - +{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. - -*-v, \--verbose*:: - Output paths such as as the Root, Conf File, DB Path, Cache Dirs, etc. - -*\--arch* :: - Specify an alternate architecture. - -*\--cachedir* :: - Specify an alternative package cache location (the default is - +{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, and the root path is not automatically - prepended. - -*\--color* :: - Specify when to enable coloring. Valid options are 'always', 'never', or - 'auto'. 'always' forces colors on; 'never' forces colors off; and 'auto' only - automatically enables colors when outputting onto a tty. - -*\--config* :: - Specify an alternate configuration file. - -*\--debug*:: - Display debug messages. When reporting bugs, this option is recommended - to be used. - -*\--gpgdir* :: - Specify a directory of files used by GnuPG to verify package signatures - (the 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, and the root path is not automatically prepended. - -*\--hookdir* :: - Specify a alternative directory containing hook files (the default is - +{sysconfdir}/pacman.d/hooks+). Multiple hook directories can be specified - with hooks in later directories taking precedence over hooks in earlier - directories. *NOTE*: This is an absolute path, and the root path is not - automatically prepended. - -*\--logfile* :: - Specify an alternate log file. This is an absolute path, regardless of - the installation root setting. - -*\--noconfirm*:: - 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. - -*\--confirm*:: - Cancels the effects of a previous '\--noconfirm'. - -*\--disable-download-timeout*:: - Disable defaults for low speed limit and timeout on downloads. Use this - if you have issues downloading files with proxy and/or security gateway. - -*\--sysroot* :: - Specify an alternative system root. Pacman will chroot and chdir into the - system root prior to running. This allows mounted guest systems to be - properly operated on. Any other paths given will be interpreted as relative - to the system root. Requires root privileges. - - -Transaction Options (apply to '-S', '-R' and '-U') --------------------------------------------------- -*-d, \--nodeps*:: - Skips dependency version checks. Package names are still checked. 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. Specify this option twice to skip all dependency checks. - -*\--assume-installed* :: - Add a virtual package "package" with version "version" to the transaction - to satisfy dependencies. This allows to disable specific dependency checks - without affecting all dependency checks. To disable all dependency - checking, see the '\--nodeps' option. - -*\--dbonly*:: - Adds/removes the database entry only, leaving 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. - -*\--noscriptlet*:: - If an install scriptlet exists, do not execute it. Do not use this - unless you know what you are doing. - -*-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 URLs with - '-S', file names with '-U', and pkgname-pkgver with '-R'. - -*\--print-format* :: - Specify a printf-like format to control the output of the '\--print' - operation. The possible attributes are: "%n" for pkgname, "%v" for pkgver, - "%l" for location, "%r" for repository, and "%s" for size. Implies '\--print'. - - -Upgrade Options (apply to '-S' and '-U')[[UO]] ----------------------------------------------- -*\--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* :: - 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* :: - 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. - -*\--needed*:: - Do not reinstall the targets that are already up-to-date. - -*\--overwrite* :: - Bypass file conflict checks and overwrite conflicting files. If the - package that is about to be installed contains files that are already - installed and match 'glob', this option will cause all those files to be - overwritten. Using '\--overwrite' will not allow overwriting a directory - with a file or installing packages with conflicting files and directories. - Multiple patterns can be specified by separating them with a comma. May be - specified multiple times. Patterns can be negated, such that files - matching them will not be overwritten, by prefixing them with an - exclamation mark. Subsequent matches will override previous ones. A leading - literal exclamation mark or backslash needs to be escaped. - - -Query Options (apply to '-Q')[[QO]] ------------------------------------ -*-c, \--changelog*:: - View the ChangeLog of a package if it exists. - -*-d, \--deps*:: - Restrict or filter output to packages installed as dependencies. This - option can be combined with '-t' for listing real orphans - packages that - were installed as dependencies but are no longer required by any - installed package. - -*-e, \--explicit*:: - Restrict or filter output to explicitly installed packages. This option - can be combined with '-t' to list explicitly installed packages that - are not required by any other package. - -*-g, \--groups*:: - Display all packages that are members of a named group. If a name is not - specified, list all grouped packages. - -*-i, \--info*:: - Display information on a given package. The '-p' option can be used if - querying a package file instead of the local database. Passing two - '\--info' or '-i' flags will also display the list of backup files and - their modification states. - -*-k, \--check*:: - Check that all files owned by the given package(s) are present on the - system. If packages are not specified or filter flags are not provided, - check all installed packages. Specifying this option twice will perform - more detailed file checking (including permissions, file sizes, and - modification times) for packages that contain the needed mtree file. - -*-l, \--list*:: - List all files owned by a given package. Multiple packages can be - specified on the command line. - -*-m, \--foreign*:: - Restrict or filter output to packages that were not found in the sync - database(s). Typically these are packages that were downloaded manually - and installed with '\--upgrade'. - -*-n, \--native*:: - Restrict or filter output to packages that are found in the sync - database(s). This is the inverse filter of '\--foreign'. - -*-o, \--owns* :: - Search for packages that own the specified file(s). The path can be - relative or absolute, and one or more files can be specified. - -*-p, \--file*:: - Signifies that the package supplied on the command line is a file and - not an entry in the database. The file will be decompressed and queried. - This is useful in combination with '\--info' and '\--list'. - -*-q, \--quiet*:: - Show less information for certain query operations. This is useful when - pacman's output is processed in a script. Search will only show package - names and not version, group, and description information; owns will - only show package names instead of "file is owned by pkg" messages; group - will only show package names and omit group names; list will only show - files and omit package names; check will only show pairs of package names - and missing files; a bare query will only show package names - rather than names and versions. - -*-s, \--search* :: - Search each locally-installed package for names or descriptions that - match `regexp`. When including multiple search terms, only packages - with descriptions matching ALL of those terms are returned. - -*-t, \--unrequired*:: - Restrict or filter output to print only packages neither required nor - optionally required by any currently installed package. Specify this - option twice to include packages which are optionally, but not directly, - required by another package. - -*-u, \--upgrades*:: - Restrict or filter output to packages that are out-of-date on the local - system. Only package versions are used to find outdated packages; - replacements are not checked here. This option works best if the sync - database is refreshed using '-Sy'. - - -Remove Options (apply to '-R')[[RO]] ------------------------------------- -*-c, \--cascade*:: - Remove all target packages, as well as all packages that depend on one - or more target packages. This operation is recursive and must be used - with care, since it can remove many potentially needed packages. - -*-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 - file should be renamed with a '.pacsave' extension. - -*-s, \--recursive*:: - Remove each target specified including all of their dependencies, provided - that (A) they are not required by other packages; and (B) they were not - explicitly installed by the user. This operation is recursive and analogous - to a backwards '\--sync' operation, and it helps keep a clean system without - orphans. If you want to omit condition (B), pass this option twice. - -*-u, \--unneeded*:: - Removes targets that are not required by any other packages. - This is mostly useful when removing a group without using the '-c' option, - to avoid breaking any dependencies. - - -Sync Options (apply to '-S')[[SO]] ----------------------------------- -*-c, \--clean*:: - Remove packages that are no longer installed from the cache as well as - currently unused sync databases to free up disk space. When pacman - downloads packages, it saves them in a cache directory. In addition, - databases are saved for every sync DB you download from and are not - deleted even if they are removed from the configuration file - linkman:pacman.conf[5]. Use one '\--clean' switch to only remove - packages that are no longer installed; use two to remove all files - from the cache. In both cases, you will have a yes or no option to - remove packages and/or unused downloaded databases. -+ -If you use a network shared cache, see the 'CleanMethod' option in -linkman:pacman.conf[5]. - -*-g, \--groups*:: - Display all the members for each package group specified. If no group - names are provided, all groups will be listed; pass the flag twice to - view all groups and their members. - -*-i, \--info*:: - Display information on a given sync database package. Passing two '\--info' - or '-i' flags will also display those packages in all repositories that - depend on this package. - -*-l, \--list*:: - List all packages in the specified repositories. Multiple repositories - can be specified on the command line. - -*-q, \--quiet*:: - Show less information for certain sync operations. This is useful when - pacman's output is processed in a script. Search will only show package - names and not repository, version, group, and description information; list - will only show package names and omit databases and versions; group will - only show package names and omit group names. - -*-s, \--search* :: - This will search each package in the sync databases for names or - descriptions that match `regexp`. When you include multiple search - terms, only packages with descriptions matching ALL of those terms will - be returned. - -*-u, \--sysupgrade*:: - Upgrades all packages that are out-of-date. Each currently-installed - package will be examined and upgraded if a newer package exists. A - report of all packages to upgrade will be presented, and the operation - will not proceed without user confirmation. Dependencies are - automatically resolved at this level and will be installed/upgraded if - necessary. -+ -Pass this option twice to enable package downgrades; in this case, pacman will -select sync packages whose versions do not match with the local versions. This -can be useful when the user switches from a testing repository to a stable one. -+ -Additional targets can also be specified manually, so that '-Su foo' will do a -system upgrade and install/upgrade the "foo" package in the same operation. - -*-w, \--downloadonly*:: - Retrieve all packages from the server, but do not install/upgrade anything. - -*-y, \--refresh*:: - Download a fresh copy of the master package database from the server(s) - defined in linkman:pacman.conf[5]. This should typically be used each time - you use '\--sysupgrade' or '-u'. Passing two '\--refresh' or '-y' flags - will force a refresh of all package databases, even if they appear to be - up-to-date. - - -Database Options (apply to '-D')[[QO]] --------------------------------------- -*\--asdeps* :: - Mark a package as non-explicitly installed; in other words, set their install - reason to be installed as a dependency. - -*\--asexplicit* :: - Mark a package as explicitly installed; in other words, set their install - reason to be explicitly installed. This is useful it you want to keep a - package installed even when it was initially installed as a dependency - of another package. - -*-k, \--check*:: - Check the local package database is internally consistent. This will - check all required files are present and that installed packages have - the required dependencies, do not conflict and that multiple packages - do not own the same file. Specifying this option twice will perform - a check on the sync databases to ensure all specified dependencies - are available. - -*-q, \--quiet*:: - Suppress messages on successful completion of database operations. - -File Options (apply to '-F')[[FO]] ----------------------------------- -*-y, --refresh*:: - Download fresh package databases from the server. Use twice to force a - refresh even if databases are up to date. - -*-l, \--list*:: - List the files owned by the queried package. - -*-s, \--search*:: - Search package file names for matching strings. - -*-x, --regex*:: - Treat arguments to '--search' as regular expressions. - -*-o, \--owns*:: - Search for packages that own a particular file. - -*-q, \--quiet*:: - Show less information for certain file operations. This is useful when - pacman's output is processed in a script, however, you may want to use - '--machinereadable' instead. - -*--machinereadable*:: - Use a machine readable output format for '--list', '--search' and - '--owns'. The format is 'repository\0pkgname\0pkgver\0path\n' with '\0' - being the NULL character and '\n' a linefeed. - -Handling Config Files[[HCF]] ----------------------------- -Pacman uses the same logic as 'rpm' to determine action against files that are -designated to be backed up. During an upgrade, three MD5 hashes are used for -each backup file to determine the required action: one for the original file -installed, one for the new file that is about to be installed, and one for the -actual file existing on the file system. After comparing these three hashes, the -follow scenarios can result: - -original=X, current=X, new=X:: - All three files are the same, so overwrites are not an issue. Install the - new file. - -original=X, current=X, new=Y:: - The current file is the same as the original, but the new one differs. - Since the user did not ever modify the file, and the new one may contain - improvements or bug fixes, install the new file. - -original=X, current=Y, new=X:: - Both package versions contain the exact same file, but the one on the - file system has been modified. Leave the current file in place. - -original=X, current=Y, new=Y:: - The new file is identical to the current file. Install the new file. - -original=X, current=Y, new=Z:: - All three files are different, so install the new file with a '.pacnew' - extension and warn the user. The user must then manually merge any - necessary changes into the original file. - -original=NULL, current=Y, new=Z:: - The package was not previously installed, and the file already exists on the - file system. Install the new file with a '.pacnew' extension and warn the - user. The user must then manually merge any 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 -'pacman.conf' file. - - -See Also --------- -linkman:alpm-hooks[5], linkman:libalpm[3], linkman:makepkg[8], -linkman:pacman.conf[5] - -include::footer.txt[] diff --git a/doc/pacman.conf.5.asciidoc b/doc/pacman.conf.5.asciidoc new file mode 100644 index 00000000..e5fffecf --- /dev/null +++ b/doc/pacman.conf.5.asciidoc @@ -0,0 +1,371 @@ +pacman.conf(5) +============== + +Name +---- +pacman.conf - pacman package manager configuration file + + +Synopsis +-------- +{sysconfdir}/pacman.conf + + +Description +----------- +Pacman, using linkman:libalpm[3], will attempt to read pacman.conf each time it +is invoked. This configuration file is divided into sections or repositories. +Each section defines a package repository that pacman can use when searching +for packages in '\--sync' mode. The exception to this is the options section, +which defines global options. + + +Example +------- + +-------- +# +# pacman.conf +# +[options] +NoUpgrade = etc/passwd etc/group etc/shadow +NoUpgrade = etc/fstab + +[core] +Include = /etc/pacman.d/core + +[custom] +Server = file:///home/pkgs +-------- + +NOTE: Each directive must be in CamelCase. If the case isn't respected, the +directive won't be recognized. For example. noupgrade or NOUPGRADE will not +work. + + +Options +------- +*RootDir =* /path/to/root/dir:: + Set the default root directory for pacman to install to. This option is + used if you want to install a package on a temporary mounted partition + which is "owned" by another system, or for a chroot install. + *NOTE*: If database path or log file are not specified on either the + command line or in linkman:pacman.conf[5], their default location will + be inside this root path. + +*DBPath =* /path/to/db/dir:: + Overrides the default location of the toplevel database directory. The + 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. The + 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 + path, the root path is not automatically prepended. + +*HookDir =* /path/to/hook/dir:: + Add directories to search for alpm hooks in addition to the system hook + directory (+{datarootdir}/libalpm/hooks/+). The default is + +{sysconfdir}/pacman.d/hooks+. Multiple directories can be specified with + hooks in later directories taking precedence over hooks in earlier + directories. *NOTE*: this is an absolute path, the root path is not + automatically prepended. For more information on the alpm hooks, see + linkman:alpm-hooks[5]. + +*GPGDir =* /path/to/gpg/dir:: + Overrides the default location of the directory containing configuration + files for GnuPG. The 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/log/file:: + Overrides the default location of the pacman log file. The default + is +{localstatedir}/log/pacman.log+. This is an absolute path and the root directory + is not prepended. + +*HoldPkg =* package ...:: + If a user tries to '\--remove' a package that's listed in `HoldPkg`, + pacman will ask for confirmation before proceeding. Shell-style glob + patterns are allowed. + +*IgnorePkg =* package ...:: + Instructs pacman to ignore any upgrades for this package when performing + a '\--sysupgrade'. Shell-style glob patterns are allowed. + +*IgnoreGroup =* group ...:: + Instructs pacman to ignore any upgrades for all packages in this + group when performing a '\--sysupgrade'. Shell-style glob patterns are + allowed. + +*Include =* /path/to/config/file:: + Include another configuration file. This file can include repositories or + general configuration options. Wildcards in the specified paths will get + expanded based on linkman:glob[7] rules. + +*Architecture =* auto | i686 | x86_64 | ...:: + If set, pacman will only allow installation of packages of the given + architecture (e.g. 'i686', 'x86_64', etc). The special value 'auto' will + use the system architecture, provided via ``uname -m''. If unset, no + architecture checks are made. *NOTE*: Packages with the special + architecture 'any' can always be installed, as they are meant to be + architecture independent. + +*XferCommand =* /path/to/command %u:: + If set, an external program will be used to download all remote files. + All instances of `%u` will be replaced with the download URL. If present, + instances of `%o` will be replaced with the local filename, plus a + ``.part'' extension, which allows programs like wget to do file resumes + properly. + + + This option is useful for users who experience problems with built-in + HTTP/FTP support, or need the more advanced proxy support that comes with + utilities like wget. + +*NoUpgrade =* file ...:: + All files listed with a `NoUpgrade` directive will never be touched during + a package install/upgrade, and the new files will be installed with a + '.pacnew' extension. + These files refer to files in the package archive, so do not include the + leading slash (the RootDir) when specifying them. Shell-style glob patterns + are allowed. It is possible to invert matches by prepending a file with + an exclamation mark. Inverted files will result in previously blacklisted + files being whitelisted again. Subsequent matches will override previous + ones. A leading literal exclamation mark or backslash needs to be escaped. + +*NoExtract =* file ...:: + All files listed with a `NoExtract` directive will never be extracted from + a package into the filesystem. This can be useful when you don't want part + of a package to be installed. For example, if your httpd root uses an + 'index.php', then you would not want the 'index.html' file to be extracted + from the 'apache' package. + These files refer to files in the package archive, so do not include the + leading slash (the RootDir) when specifying them. Shell-style glob patterns + are allowed. It is possible to invert matches by prepending a file with + an exclamation mark. Inverted files will result in previously blacklisted + files being whitelisted again. Subsequent matches will override previous + ones. A leading literal exclamation mark or backslash needs to be escaped. + +*CleanMethod =* KeepInstalled &| KeepCurrent:: + If set to `KeepInstalled` (the default), the '-Sc' operation will clean + packages that are no longer installed (not present in the local database). + If set to `KeepCurrent`, '-Sc' will clean outdated packages (not present in + any sync database). + The second behavior is useful when the package cache is shared among + multiple machines, where the local databases are usually different, but the + sync databases in use could be the same. If both values are specified, + 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 + <> below. + +*LocalFileSigLevel =* ...:: + Set the signature verification level for installing packages using the "-U" + operation on a local file. Uses the value from SigLevel as the default. + +*RemoteFileSigLevel =* ...:: + Set the signature verification level for installing packages using the "-U" + operation on a remote file URL. Uses the value from SigLevel as the default. + +*UseSyslog*:: + Log action messages through syslog(). This will insert log entries into + +{localstatedir}/log/messages+ or equivalent. + +*Color*:: + Automatically enable colors only when pacman's output is on a tty. + +*UseDelta* [= ratio]:: + Download delta files instead of complete packages if possible. Requires + the `xdelta3` program to be installed. If a ratio is specified (e.g., + `0.5`), then it is used as a cutoff for determining whether to use deltas. + Allowed values are between `0.0` and `2.0`; sensible values are between + `0.2` and `0.9`. Using a value above `1.0` is not recommended. The + default is `0.7` if left unspecified. + +*TotalDownload*:: + When downloading, display the amount downloaded, download rate, ETA, + and completed percentage of the entire download list rather + than the percent of each individual download target. The progress + bar is still based solely on the current file download. + This option won't work if XferCommand is used. + +*CheckSpace*:: + 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. + +*DisableDownloadTimeout*:: + Disable defaults for low speed limit and timeout on downloads. Use this + if you have issues downloading files with proxy and/or security gateway. + + +Repository Sections +------------------- +Each repository section defines a section name and at least one location where +the packages can be found. The section name is defined by the string within +square brackets (the two above are 'core' and 'custom'). Repository names +must be unique and the name 'local' is reserved for the database of installed +packages. Locations are defined with the 'Server' directive and follow a URL +naming structure. If you want to use a local directory, you can specify the +full path with a ``file://'' prefix, as shown above. + +A common way to define DB locations utilizes the 'Include' directive. For each +repository defined in the configuration file, a single 'Include' directive can +contain a file that lists the servers for that repository. + +-------- +[core] +# 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 <> below. + +*Usage =* ...:: + Set the usage level for this repository. This option takes a list of tokens + which must be at least one of the following: + *Sync*;; + Enables refreshes for this repository. + *Search*;; + Enables searching for this repository. + *Install*;; + Enables installation of packages from this repository during a '\--sync' + operation. + *Upgrade*;; + Allows this repository to be a valid source of packages when performing + a '\--sysupgrade'. + *All*;; + Enables all of the above features for the repository. This is the default + if not specified. ++ +Note that an enabled repository can be operated on explicitly, regardless of the Usage +level set. + + +Package and Database Signature Checking[[SC]] +--------------------------------------------- +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: + +-------- +SigLevel = Optional TrustedOnly +-------- + + +Using Your Own Repository +------------------------- +If you have numerous custom packages of your own, it is often easier to generate +your own custom local repository than install them all with the '\--upgrade' +option. All you need to do is generate a compressed package database in the +directory with these packages so pacman can find it when run with '\--refresh'. + + repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz + +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.{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]. + + +See Also +-------- +linkman:pacman[8], linkman:libalpm[3] + +include::footer.asciidoc[] diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt deleted file mode 100644 index db8fe740..00000000 --- a/doc/pacman.conf.5.txt +++ /dev/null @@ -1,371 +0,0 @@ -pacman.conf(5) -============== - -Name ----- -pacman.conf - pacman package manager configuration file - - -Synopsis --------- -{sysconfdir}/pacman.conf - - -Description ------------ -Pacman, using linkman:libalpm[3], will attempt to read pacman.conf each time it -is invoked. This configuration file is divided into sections or repositories. -Each section defines a package repository that pacman can use when searching -for packages in '\--sync' mode. The exception to this is the options section, -which defines global options. - - -Example -------- - --------- -# -# pacman.conf -# -[options] -NoUpgrade = etc/passwd etc/group etc/shadow -NoUpgrade = etc/fstab - -[core] -Include = /etc/pacman.d/core - -[custom] -Server = file:///home/pkgs --------- - -NOTE: Each directive must be in CamelCase. If the case isn't respected, the -directive won't be recognized. For example. noupgrade or NOUPGRADE will not -work. - - -Options -------- -*RootDir =* /path/to/root/dir:: - Set the default root directory for pacman to install to. This option is - used if you want to install a package on a temporary mounted partition - which is "owned" by another system, or for a chroot install. - *NOTE*: If database path or log file are not specified on either the - command line or in linkman:pacman.conf[5], their default location will - be inside this root path. - -*DBPath =* /path/to/db/dir:: - Overrides the default location of the toplevel database directory. The - 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. The - 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 - path, the root path is not automatically prepended. - -*HookDir =* /path/to/hook/dir:: - Add directories to search for alpm hooks in addition to the system hook - directory (+{datarootdir}/libalpm/hooks/+). The default is - +{sysconfdir}/pacman.d/hooks+. Multiple directories can be specified with - hooks in later directories taking precedence over hooks in earlier - directories. *NOTE*: this is an absolute path, the root path is not - automatically prepended. For more information on the alpm hooks, see - linkman:alpm-hooks[5]. - -*GPGDir =* /path/to/gpg/dir:: - Overrides the default location of the directory containing configuration - files for GnuPG. The 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/log/file:: - Overrides the default location of the pacman log file. The default - is +{localstatedir}/log/pacman.log+. This is an absolute path and the root directory - is not prepended. - -*HoldPkg =* package ...:: - If a user tries to '\--remove' a package that's listed in `HoldPkg`, - pacman will ask for confirmation before proceeding. Shell-style glob - patterns are allowed. - -*IgnorePkg =* package ...:: - Instructs pacman to ignore any upgrades for this package when performing - a '\--sysupgrade'. Shell-style glob patterns are allowed. - -*IgnoreGroup =* group ...:: - Instructs pacman to ignore any upgrades for all packages in this - group when performing a '\--sysupgrade'. Shell-style glob patterns are - allowed. - -*Include =* /path/to/config/file:: - Include another configuration file. This file can include repositories or - general configuration options. Wildcards in the specified paths will get - expanded based on linkman:glob[7] rules. - -*Architecture =* auto | i686 | x86_64 | ...:: - If set, pacman will only allow installation of packages of the given - architecture (e.g. 'i686', 'x86_64', etc). The special value 'auto' will - use the system architecture, provided via ``uname -m''. If unset, no - architecture checks are made. *NOTE*: Packages with the special - architecture 'any' can always be installed, as they are meant to be - architecture independent. - -*XferCommand =* /path/to/command %u:: - If set, an external program will be used to download all remote files. - All instances of `%u` will be replaced with the download URL. If present, - instances of `%o` will be replaced with the local filename, plus a - ``.part'' extension, which allows programs like wget to do file resumes - properly. - + - This option is useful for users who experience problems with built-in - HTTP/FTP support, or need the more advanced proxy support that comes with - utilities like wget. - -*NoUpgrade =* file ...:: - All files listed with a `NoUpgrade` directive will never be touched during - a package install/upgrade, and the new files will be installed with a - '.pacnew' extension. - These files refer to files in the package archive, so do not include the - leading slash (the RootDir) when specifying them. Shell-style glob patterns - are allowed. It is possible to invert matches by prepending a file with - an exclamation mark. Inverted files will result in previously blacklisted - files being whitelisted again. Subsequent matches will override previous - ones. A leading literal exclamation mark or backslash needs to be escaped. - -*NoExtract =* file ...:: - All files listed with a `NoExtract` directive will never be extracted from - a package into the filesystem. This can be useful when you don't want part - of a package to be installed. For example, if your httpd root uses an - 'index.php', then you would not want the 'index.html' file to be extracted - from the 'apache' package. - These files refer to files in the package archive, so do not include the - leading slash (the RootDir) when specifying them. Shell-style glob patterns - are allowed. It is possible to invert matches by prepending a file with - an exclamation mark. Inverted files will result in previously blacklisted - files being whitelisted again. Subsequent matches will override previous - ones. A leading literal exclamation mark or backslash needs to be escaped. - -*CleanMethod =* KeepInstalled &| KeepCurrent:: - If set to `KeepInstalled` (the default), the '-Sc' operation will clean - packages that are no longer installed (not present in the local database). - If set to `KeepCurrent`, '-Sc' will clean outdated packages (not present in - any sync database). - The second behavior is useful when the package cache is shared among - multiple machines, where the local databases are usually different, but the - sync databases in use could be the same. If both values are specified, - 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 - <> below. - -*LocalFileSigLevel =* ...:: - Set the signature verification level for installing packages using the "-U" - operation on a local file. Uses the value from SigLevel as the default. - -*RemoteFileSigLevel =* ...:: - Set the signature verification level for installing packages using the "-U" - operation on a remote file URL. Uses the value from SigLevel as the default. - -*UseSyslog*:: - Log action messages through syslog(). This will insert log entries into - +{localstatedir}/log/messages+ or equivalent. - -*Color*:: - Automatically enable colors only when pacman's output is on a tty. - -*UseDelta* [= ratio]:: - Download delta files instead of complete packages if possible. Requires - the `xdelta3` program to be installed. If a ratio is specified (e.g., - `0.5`), then it is used as a cutoff for determining whether to use deltas. - Allowed values are between `0.0` and `2.0`; sensible values are between - `0.2` and `0.9`. Using a value above `1.0` is not recommended. The - default is `0.7` if left unspecified. - -*TotalDownload*:: - When downloading, display the amount downloaded, download rate, ETA, - and completed percentage of the entire download list rather - than the percent of each individual download target. The progress - bar is still based solely on the current file download. - This option won't work if XferCommand is used. - -*CheckSpace*:: - 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. - -*DisableDownloadTimeout*:: - Disable defaults for low speed limit and timeout on downloads. Use this - if you have issues downloading files with proxy and/or security gateway. - - -Repository Sections -------------------- -Each repository section defines a section name and at least one location where -the packages can be found. The section name is defined by the string within -square brackets (the two above are 'core' and 'custom'). Repository names -must be unique and the name 'local' is reserved for the database of installed -packages. Locations are defined with the 'Server' directive and follow a URL -naming structure. If you want to use a local directory, you can specify the -full path with a ``file://'' prefix, as shown above. - -A common way to define DB locations utilizes the 'Include' directive. For each -repository defined in the configuration file, a single 'Include' directive can -contain a file that lists the servers for that repository. - --------- -[core] -# 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 <> below. - -*Usage =* ...:: - Set the usage level for this repository. This option takes a list of tokens - which must be at least one of the following: - *Sync*;; - Enables refreshes for this repository. - *Search*;; - Enables searching for this repository. - *Install*;; - Enables installation of packages from this repository during a '\--sync' - operation. - *Upgrade*;; - Allows this repository to be a valid source of packages when performing - a '\--sysupgrade'. - *All*;; - Enables all of the above features for the repository. This is the default - if not specified. -+ -Note that an enabled repository can be operated on explicitly, regardless of the Usage -level set. - - -Package and Database Signature Checking[[SC]] ---------------------------------------------- -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: - --------- -SigLevel = Optional TrustedOnly --------- - - -Using Your Own Repository -------------------------- -If you have numerous custom packages of your own, it is often easier to generate -your own custom local repository than install them all with the '\--upgrade' -option. All you need to do is generate a compressed package database in the -directory with these packages so pacman can find it when run with '\--refresh'. - - repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz - -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.{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]. - - -See Also --------- -linkman:pacman[8], linkman:libalpm[3] - -include::footer.txt[] diff --git a/doc/pkgdelta.8.asciidoc b/doc/pkgdelta.8.asciidoc new file mode 100644 index 00000000..412e607e --- /dev/null +++ b/doc/pkgdelta.8.asciidoc @@ -0,0 +1,53 @@ +pkgdelta(8) +========= + +Name +---- +pkgdelta - package delta generation utility + + +Synopsis +-------- +'pkgdelta' [options] + + +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 +------- +*--max-delta-size *:: + Only create delta files if the delta is smaller than ratio * package_size. + Possible values: 0.0 to 2.0. + Recommended values: 0.2 to 0.9. + Default value: 0.7 + +*--min-pkg-size *:: + Minimal size of the package file in bytes to be considered for delta creation. + Default value: 1048576 bytes = 1 MiB. This may be any absolute size in bytes or + a human-readable value such as `4MiB` or `3.5MB`. + +*-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.asciidoc[] diff --git a/doc/pkgdelta.8.txt b/doc/pkgdelta.8.txt deleted file mode 100644 index 6d93a67a..00000000 --- a/doc/pkgdelta.8.txt +++ /dev/null @@ -1,53 +0,0 @@ -pkgdelta(8) -========= - -Name ----- -pkgdelta - package delta generation utility - - -Synopsis --------- -'pkgdelta' [options] - - -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 -------- -*--max-delta-size *:: - Only create delta files if the delta is smaller than ratio * package_size. - Possible values: 0.0 to 2.0. - Recommended values: 0.2 to 0.9. - Default value: 0.7 - -*--min-pkg-size *:: - Minimal size of the package file in bytes to be considered for delta creation. - Default value: 1048576 bytes = 1 MiB. This may be any absolute size in bytes or - a human-readable value such as `4MiB` or `3.5MB`. - -*-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.asciidoc b/doc/repo-add.8.asciidoc new file mode 100644 index 00000000..945fff75 --- /dev/null +++ b/doc/repo-add.8.asciidoc @@ -0,0 +1,94 @@ +repo-add(8) +========== + +Name +---- +repo-add - package database maintenance utility + + +Synopsis +-------- +'repo-add' [options] [ ...] + +'repo-remove' [options] [ ...] + + +Description +----------- +'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 or package +delta file. Multiple packages and/or deltas to add can be specified on the +command line. + +If a matching ``.sig'' file is found alongside a package file, the signature +will automatically be embedded into the database. + +'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'' 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. + + +Common Options +-------------- +*-q, \--quiet*:: + Force this program to keep quiet and run silently 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* :: + 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. + +*\--nocolor*:: + Remove color from 'repo-add' and 'repo-remove' output. + + +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. + +*-n, \--new*:: + Only add packages that are not already in the database. Warnings will be + printed upon detection of existing packages, but they will not be re-added. + +*-R, \--remove*:: + Remove old package files from the disk when updating their entry in the + database. + + +Example +------- +'repo-add' foo.db.tar.xz [ ...] + +This creates two separate databases; a smaller database ``foo.db.tar.xz'' used by +pacman and a large database containing package file lists ``foo.files.tar.xz'' for +use by other utilities. While pacman can use the large database (if renamed with a +db.tar* extension), there is currently no additional benefit for the larger download. + + +See Also +-------- +linkman:makepkg[8], linkman:pacman[8], linkman:pkgdelta[8] + +include::footer.asciidoc[] diff --git a/doc/repo-add.8.txt b/doc/repo-add.8.txt deleted file mode 100644 index 4c6d8d5a..00000000 --- a/doc/repo-add.8.txt +++ /dev/null @@ -1,94 +0,0 @@ -repo-add(8) -========== - -Name ----- -repo-add - package database maintenance utility - - -Synopsis --------- -'repo-add' [options] [ ...] - -'repo-remove' [options] [ ...] - - -Description ------------ -'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 or package -delta file. Multiple packages and/or deltas to add can be specified on the -command line. - -If a matching ``.sig'' file is found alongside a package file, the signature -will automatically be embedded into the database. - -'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'' 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. - - -Common Options --------------- -*-q, \--quiet*:: - Force this program to keep quiet and run silently 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* :: - 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. - -*\--nocolor*:: - Remove color from 'repo-add' and 'repo-remove' output. - - -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. - -*-n, \--new*:: - Only add packages that are not already in the database. Warnings will be - printed upon detection of existing packages, but they will not be re-added. - -*-R, \--remove*:: - Remove old package files from the disk when updating their entry in the - database. - - -Example -------- -'repo-add' foo.db.tar.xz [ ...] - -This creates two separate databases; a smaller database ``foo.db.tar.xz'' used by -pacman and a large database containing package file lists ``foo.files.tar.xz'' for -use by other utilities. While pacman can use the large database (if renamed with a -db.tar* extension), there is currently no additional benefit for the larger download. - - -See Also --------- -linkman:makepkg[8], linkman:pacman[8], linkman:pkgdelta[8] - -include::footer.txt[] diff --git a/doc/submitting-patches.asciidoc b/doc/submitting-patches.asciidoc new file mode 100644 index 00000000..73c7487d --- /dev/null +++ b/doc/submitting-patches.asciidoc @@ -0,0 +1,101 @@ +Pacman - Submitting Patches +=========================== + +This document is here mainly to make the job of those who review patches +easier and is more of a guideline and not a strict set of rules. However, +please try to follow as much as you can. + +NOTE: Some of this is paraphrased from the kernel documentation's +"SubmittingPatches" file. + + +Getting the most recent source +------------------------------ +Patches need to be submitted in GIT format and are best if they are against the +latest version of the code. There are several helpful tutorials for getting +started with GIT if you have not worked with it before. + +* https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html +* https://wiki.archlinux.org/index.php/Super_Quick_Git_Guide + +The pacman code can be fetched using the following command: + + git clone git://projects.archlinux.org/pacman.git + + +Creating your patch +------------------- + +-- +* Use `git commit -s` for creating a commit of your changes. + +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 + +Please use your real name and email address. Feel free to "scramble" the +address if you're afraid of spam. + +* Describe your patch. + +It helps if you describe the overview and goals of the patch in the git commit +log. This allows others to see what you intended so as to compare it to what +was actually done, and allows better feedback. + +* Use `git format-patch` to create patches. + +Your commit message will be shown above the patch by default when you will use +`git format-patch`, including the signoff line. Sets of multiple patches that +need extra explanation beyond the commit messages may include additional notes +in a cover letter. Individual patches may include additional notes between the +"---" following the commit message and the beginning of the diff. + +-- + +Submitting your patch +--------------------- + +-- +* Send the patch to the pacman-dev mailing list + +The mailing list is the primary queue for review and acceptance. Here you +will get feedback, and let the reviewers know the details of your patch. + +* No MIME, no links, no compression, no attachments. Just plain text. + +Patches should be contained in the actual body of the email. There are many +reasons for this. First, it makes them easier to read with any mail reader, +it allows easier review "at a glance", and most importantly, it allows people +to comment on exact lines of the patch in reply emails. + +`git send-email` allows you to send Git-formatted patches in plain text easily +and is the preferred method for submission to the mailing list. Mail clients, +including Gmail's web interface, have a tendency to break patches by wrapping +lines and/or adjusting whitespace and should be avoided. + +-- + +After you submit +---------------- + +-- +* Don't get discouraged + +Any feedback you get, positive or negative, has nothing to do with you. If a +patch is rejected, try taking the suggestions into account and re-submitting. +We welcome most submissions here, and some may take a bit longer to get +looked over than others. If you think your patch got lost in the shuffle, +send another email to the list in reply to the original asking if anyone has +looked at it yet. + +* Respond to feedback + +When you do get feedback, it usually merits a response, whether this be a +resubmission of the patch with corrections or a follow-up email asking for +clarifications. When neither of these occurs, don't expect your patch to get +further review. The all-volunteer staff don't have time to fix up patches that +aren't their own. When resubmitting patches, update the subject line to reflect +the version number ('[PATCHv2]'), and send it as a reply to the original thread. + +-- diff --git a/doc/submitting-patches.txt b/doc/submitting-patches.txt deleted file mode 100644 index 73c7487d..00000000 --- a/doc/submitting-patches.txt +++ /dev/null @@ -1,101 +0,0 @@ -Pacman - Submitting Patches -=========================== - -This document is here mainly to make the job of those who review patches -easier and is more of a guideline and not a strict set of rules. However, -please try to follow as much as you can. - -NOTE: Some of this is paraphrased from the kernel documentation's -"SubmittingPatches" file. - - -Getting the most recent source ------------------------------- -Patches need to be submitted in GIT format and are best if they are against the -latest version of the code. There are several helpful tutorials for getting -started with GIT if you have not worked with it before. - -* https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html -* https://wiki.archlinux.org/index.php/Super_Quick_Git_Guide - -The pacman code can be fetched using the following command: - - git clone git://projects.archlinux.org/pacman.git - - -Creating your patch -------------------- - --- -* Use `git commit -s` for creating a commit of your changes. - -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 - -Please use your real name and email address. Feel free to "scramble" the -address if you're afraid of spam. - -* Describe your patch. - -It helps if you describe the overview and goals of the patch in the git commit -log. This allows others to see what you intended so as to compare it to what -was actually done, and allows better feedback. - -* Use `git format-patch` to create patches. - -Your commit message will be shown above the patch by default when you will use -`git format-patch`, including the signoff line. Sets of multiple patches that -need extra explanation beyond the commit messages may include additional notes -in a cover letter. Individual patches may include additional notes between the -"---" following the commit message and the beginning of the diff. - --- - -Submitting your patch ---------------------- - --- -* Send the patch to the pacman-dev mailing list - -The mailing list is the primary queue for review and acceptance. Here you -will get feedback, and let the reviewers know the details of your patch. - -* No MIME, no links, no compression, no attachments. Just plain text. - -Patches should be contained in the actual body of the email. There are many -reasons for this. First, it makes them easier to read with any mail reader, -it allows easier review "at a glance", and most importantly, it allows people -to comment on exact lines of the patch in reply emails. - -`git send-email` allows you to send Git-formatted patches in plain text easily -and is the preferred method for submission to the mailing list. Mail clients, -including Gmail's web interface, have a tendency to break patches by wrapping -lines and/or adjusting whitespace and should be avoided. - --- - -After you submit ----------------- - --- -* Don't get discouraged - -Any feedback you get, positive or negative, has nothing to do with you. If a -patch is rejected, try taking the suggestions into account and re-submitting. -We welcome most submissions here, and some may take a bit longer to get -looked over than others. If you think your patch got lost in the shuffle, -send another email to the list in reply to the original asking if anyone has -looked at it yet. - -* Respond to feedback - -When you do get feedback, it usually merits a response, whether this be a -resubmission of the patch with corrections or a follow-up email asking for -clarifications. When neither of these occurs, don't expect your patch to get -further review. The all-volunteer staff don't have time to fix up patches that -aren't their own. When resubmitting patches, update the subject line to reflect -the version number ('[PATCHv2]'), and send it as a reply to the original thread. - --- diff --git a/doc/translation-help.asciidoc b/doc/translation-help.asciidoc new file mode 100644 index 00000000..67117bcc --- /dev/null +++ b/doc/translation-help.asciidoc @@ -0,0 +1,153 @@ +Pacman - Translating +==================== + +This document is here to guide you in helping translate pacman messages, +libalpm messages, and the manual pages for the entire pacman package. + +We are currently using http://www.transifex.com/[Transifex] as the translation +platform for pacman and libalpm. You will need to sign up for an account there +and then register with a translation team on the +http://www.transifex.com/projects/p/archlinux-pacman/[pacman project page]. + +NOTE: This may be old information due to our switch to Transifex, but the +gettext website is a very useful guide to read before embarking on translation +work, as it describes many of the commands in more detail than I will here: +https://www.gnu.org/software/gettext/manual/html_node/gettext.html[]. + + +Translating Messages +-------------------- + +Overview +~~~~~~~~ + +There are two separate message catalogs in pacman: one for the back-end +(libalpm) and one for the front-end (pacman and scripts). These correspond to +the `lib/libalpm/po` and `po` directories in the pacman source, respectively. + +Translation message files are a specially formatted text file containing the +original message and the corresponding translation. These po files can then +either be hand-edited, or modified with a tool such as poedit, gtranslator or +kbabel. Using a translation tool tends to make the job easier. + +Please read up on Transifex usage using the +http://docs.transifex.com/[Transifex Help] if you are not familiar. + +Transifex provides a command-line client to help with translations. Here is +an example set of commands if you have a source code checkout and are 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/.po + poedit lib/libalpm/po/.po + tx push -t -l + +Or to just push one of the two available resources: + + tx push -r archlinux-pacman.pacman-pot -t -l + tx push -r archlinux-pacman.libalpm-pot -t -l + +See the <> section for additional hints on translating. + +Pre-release Updates +~~~~~~~~~~~~~~~~~~~ + +A week or two before each release, the codebase will go into a string freeze +and an email will be sent to the mailto:pacman-dev@archlinux.org[pacman-dev] +mailing list asking for translations. This email will have a prefix of +*[translation]* for anyone looking to set up an email filter. + +At this time, the latest `.po` language files will be made available at the +Transifex project page. Each language will have two files available (back-end +and front-end). Translators interested in helping are encouraged to use the +features of Transifex to let others know they are currently translating their +language. + +Once a translator has completed the translation (*OR* realizes they do not have +time to finish), please upload your progress back to the Transifex site. + +NOTE: Please upload your translations as soon as possible- this will give other +speakers of your language time to review your translations and update them as +necessary. + +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 + +Next, you will need to run `./autogen.sh` and `./configure` in the base +directory to generate the correct Makefiles. At this point, all necessary +make targets will be generated and we can begin updating the translation +files. + +We need to first update the main message catalog file. Navigate into either the +`lib/libalpm/po` or `po` directory depending on which translation you wish to +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 + +Next, update your specific language's translation file: + + make -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 +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 + +Adding a New Language +~~~~~~~~~~~~~~~~~~~~~ + +Making a new language is not too hard, but be sure to follow all the steps. +You will have to do the following steps in both the `lib/libalpm/po/` and `po/` +directories, substituting where appropriate. First, edit the `LINGUAS` file and +add your new language code at the bottom. Next, run the following command, +substituting 'libalpm.pot' or 'pacman.pot' for potfile depending on which +directory you are currently working in: + + msginit -l -o .po -i + +You can then also add your language code to the end of the `LINGUAS` file +located in each po directory. + +Look at the current message files for more guidance if necessary. Once you +create the new language file, you may need to slightly modify the headers; +try to make them look similar to the other .po file headers. In addition, for +all new translations we would strongly recommend using UTF-8 encoding. + +Notes[[Notes]] +~~~~~~~~~~~~~~ + +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" + +If you want to test the translation (for example, the front-end one): + + rm *.gmo stamp-po + make + cp .gmo /usr/share/locale//LC_MESSAGES/pacman.mo + + +Translating Manpages +-------------------- +There are currently no efforts underway to include translated manual pages in +the pacman codebase. However, this is not to say translations are unwelcome. If +someone has experience with i18n man pages and how to best include them with our +source, please contact the pacman-dev mailing list at +mailto:pacman-dev@archlinux.org[]. diff --git a/doc/translation-help.txt b/doc/translation-help.txt deleted file mode 100644 index 67117bcc..00000000 --- a/doc/translation-help.txt +++ /dev/null @@ -1,153 +0,0 @@ -Pacman - Translating -==================== - -This document is here to guide you in helping translate pacman messages, -libalpm messages, and the manual pages for the entire pacman package. - -We are currently using http://www.transifex.com/[Transifex] as the translation -platform for pacman and libalpm. You will need to sign up for an account there -and then register with a translation team on the -http://www.transifex.com/projects/p/archlinux-pacman/[pacman project page]. - -NOTE: This may be old information due to our switch to Transifex, but the -gettext website is a very useful guide to read before embarking on translation -work, as it describes many of the commands in more detail than I will here: -https://www.gnu.org/software/gettext/manual/html_node/gettext.html[]. - - -Translating Messages --------------------- - -Overview -~~~~~~~~ - -There are two separate message catalogs in pacman: one for the back-end -(libalpm) and one for the front-end (pacman and scripts). These correspond to -the `lib/libalpm/po` and `po` directories in the pacman source, respectively. - -Translation message files are a specially formatted text file containing the -original message and the corresponding translation. These po files can then -either be hand-edited, or modified with a tool such as poedit, gtranslator or -kbabel. Using a translation tool tends to make the job easier. - -Please read up on Transifex usage using the -http://docs.transifex.com/[Transifex Help] if you are not familiar. - -Transifex provides a command-line client to help with translations. Here is -an example set of commands if you have a source code checkout and are 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/.po - poedit lib/libalpm/po/.po - tx push -t -l - -Or to just push one of the two available resources: - - tx push -r archlinux-pacman.pacman-pot -t -l - tx push -r archlinux-pacman.libalpm-pot -t -l - -See the <> section for additional hints on translating. - -Pre-release Updates -~~~~~~~~~~~~~~~~~~~ - -A week or two before each release, the codebase will go into a string freeze -and an email will be sent to the mailto:pacman-dev@archlinux.org[pacman-dev] -mailing list asking for translations. This email will have a prefix of -*[translation]* for anyone looking to set up an email filter. - -At this time, the latest `.po` language files will be made available at the -Transifex project page. Each language will have two files available (back-end -and front-end). Translators interested in helping are encouraged to use the -features of Transifex to let others know they are currently translating their -language. - -Once a translator has completed the translation (*OR* realizes they do not have -time to finish), please upload your progress back to the Transifex site. - -NOTE: Please upload your translations as soon as possible- this will give other -speakers of your language time to review your translations and update them as -necessary. - -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 - -Next, you will need to run `./autogen.sh` and `./configure` in the base -directory to generate the correct Makefiles. At this point, all necessary -make targets will be generated and we can begin updating the translation -files. - -We need to first update the main message catalog file. Navigate into either the -`lib/libalpm/po` or `po` directory depending on which translation you wish to -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 - -Next, update your specific language's translation file: - - make -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 -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 - -Adding a New Language -~~~~~~~~~~~~~~~~~~~~~ - -Making a new language is not too hard, but be sure to follow all the steps. -You will have to do the following steps in both the `lib/libalpm/po/` and `po/` -directories, substituting where appropriate. First, edit the `LINGUAS` file and -add your new language code at the bottom. Next, run the following command, -substituting 'libalpm.pot' or 'pacman.pot' for potfile depending on which -directory you are currently working in: - - msginit -l -o .po -i - -You can then also add your language code to the end of the `LINGUAS` file -located in each po directory. - -Look at the current message files for more guidance if necessary. Once you -create the new language file, you may need to slightly modify the headers; -try to make them look similar to the other .po file headers. In addition, for -all new translations we would strongly recommend using UTF-8 encoding. - -Notes[[Notes]] -~~~~~~~~~~~~~~ - -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" - -If you want to test the translation (for example, the front-end one): - - rm *.gmo stamp-po - make - cp .gmo /usr/share/locale//LC_MESSAGES/pacman.mo - - -Translating Manpages --------------------- -There are currently no efforts underway to include translated manual pages in -the pacman codebase. However, this is not to say translations are unwelcome. If -someone has experience with i18n man pages and how to best include them with our -source, please contact the pacman-dev mailing list at -mailto:pacman-dev@archlinux.org[]. diff --git a/doc/vercmp.8.asciidoc b/doc/vercmp.8.asciidoc new file mode 100644 index 00000000..88021674 --- /dev/null +++ b/doc/vercmp.8.asciidoc @@ -0,0 +1,72 @@ +vercmp(8) +========= + +Name +---- +vercmp - version comparison utility + + +Synopsis +-------- +'vercmp' [-h] [--help] + + +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 comparison operates as follows: + + Alphanumeric: + 1.0a < 1.0b < 1.0beta < 1.0p < 1.0pre < 1.0rc < 1.0 < 1.0.a < 1.0.1 + 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`. + +Keep in mind that the 'pkgrel' is only compared if it is available on both +versions given to this tool. For example, comparing `1.5-1` and `1.5` will +yield 0; comparing `1.5-1` and `1.5-2` will yield < 0 as expected. This is +mainly for supporting versioned dependencies that do not include the 'pkgrel'. + + +Options +------- +*-h, \--help*:: + + Display summary of the available return codes. Must be the first option + specified. + + +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 + + +See Also +-------- +linkman:pacman[8], linkman:makepkg[8], linkman:libalpm[3] + +include::footer.asciidoc[] diff --git a/doc/vercmp.8.txt b/doc/vercmp.8.txt deleted file mode 100644 index f8328a6b..00000000 --- a/doc/vercmp.8.txt +++ /dev/null @@ -1,72 +0,0 @@ -vercmp(8) -========= - -Name ----- -vercmp - version comparison utility - - -Synopsis --------- -'vercmp' [-h] [--help] - - -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 comparison operates as follows: - - Alphanumeric: - 1.0a < 1.0b < 1.0beta < 1.0p < 1.0pre < 1.0rc < 1.0 < 1.0.a < 1.0.1 - 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`. - -Keep in mind that the 'pkgrel' is only compared if it is available on both -versions given to this tool. For example, comparing `1.5-1` and `1.5` will -yield 0; comparing `1.5-1` and `1.5-2` will yield < 0 as expected. This is -mainly for supporting versioned dependencies that do not include the 'pkgrel'. - - -Options -------- -*-h, \--help*:: - - Display summary of the available return codes. Must be the first option - specified. - - -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 - - -See Also --------- -linkman:pacman[8], linkman:makepkg[8], linkman:libalpm[3] - -include::footer.txt[] -- cgit v1.2.3-70-g09d2