diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 18 | ||||
| -rw-r--r-- | doc/PKGBUILD.5.txt | 130 | ||||
| -rw-r--r-- | doc/makepkg.8.txt | 41 | ||||
| -rw-r--r-- | doc/makepkg.conf.5.txt | 7 | ||||
| -rw-r--r-- | doc/pacman-key.8.txt | 74 | ||||
| -rw-r--r-- | doc/pacman.8.txt | 10 | ||||
| -rw-r--r-- | doc/pacman.conf.5.txt | 33 | ||||
| -rw-r--r-- | doc/pkgdelta.8.txt | 3 |
8 files changed, 163 insertions, 153 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index dd37124f..bcb05b74 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -93,8 +93,12 @@ endif html: $(HTML_DOCS) -website: html - bsdtar czf website.tar.gz $(HTML_DOCS) \ +website: website.tar.gz + +.PHONY: html website + +website.tar.gz: html + $(AM_V_GEN)bsdtar czf $@ $(HTML_DOCS) \ asciidoc-override.css \ -C /etc/asciidoc/stylesheets/ \ asciidoc.css \ @@ -122,15 +126,15 @@ A2X_OPTS = \ # These rules are due to the includes and files of the asciidoc text $(ASCIIDOC_MANS): asciidoc.conf footer.txt Makefile.am - a2x $(A2X_OPTS) --asciidoc-opts="$(ASCIIDOC_OPTS) --out-file=./$@.xml" $(srcdir)/$@.txt + $(AM_V_GEN)a2x $(A2X_OPTS) --asciidoc-opts="$(ASCIIDOC_OPTS) --out-file=./$@.xml" $(srcdir)/$@.txt %.html: %.txt - asciidoc $(ASCIIDOC_OPTS) $*.txt - dos2unix $@ + $(AM_V_GEN)asciidoc $(ASCIIDOC_OPTS) -o - $*.txt | \ + sed -e 's/\r$$//' > $@ HACKING.html: ../HACKING - asciidoc $(ASCIIDOC_OPTS) -o $@ ../HACKING - dos2unix $@ + $(AM_V_GEN)asciidoc $(ASCIIDOC_OPTS) -o - ../HACKING | \ + sed -e 's/\r$$//' > $@ # Customizations for certain HTML docs $(HTML_MANPAGES): asciidoc.conf footer.txt Makefile.am diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index ffbb69bd..47f9e884 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -47,6 +47,11 @@ similar to `$_basekernver`. *pkgver*:: The version of the software as released from the author (e.g., '2.7.1'). The variable is not allowed to contain colons or hyphens. ++ +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 so 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 @@ -109,6 +114,10 @@ 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 +<<VCS,Using VCS Sources>> 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. @@ -121,9 +130,10 @@ of the corresponding source file. *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. To easily generate md5sums, run - `makepkg -g >> PKGBUILD`. If desired, move the md5sums line to an - appropriate location. + 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 @@ -253,10 +263,10 @@ A normal sync or upgrade will not use its value. with distcc. *buildflags*;; - Allow the use of user-specific buildflags (CFLAGS, CXXFLAGS, LDFLAGS) - during build as specified in linkman:makepkg.conf[5]. More useful in - its negative form `!buildflags` with select packages that have problems - building with custom buildflags. + 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 @@ -295,6 +305,15 @@ 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. +prepare() Function +------------------ +An optional prepare() function can be specified in which operations that are +to be run in order to prepare the sources for building (such as patching) are +performed. This function is run after the source extraction and before the +build() function and is skipped when source extraction is skipped. The +function is run in `bash -e` mode, meaning any command that exits with a +non-zero status will cause the function to exit. + check() Function ---------------- An optional check() function can be specified in which a packages test-suite @@ -323,9 +342,9 @@ Each split package uses a corresponding packaging function with name 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: -`pkgver`, `pkgrel`, `epoch`, `pkgdesc`, `arch`, `license`, `groups`, `depends`, -`optdepends`, `provides`, `conflicts`, `replaces`, `backup`, `options`, -`install` and `changelog`. +`pkgver`, `pkgrel`, `epoch`, `pkgdesc`, `arch`, `url`, `license`, `groups`, +`depends`, `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, +`options`, `install` and `changelog`. An optional global directive is available when building a split package: @@ -382,69 +401,40 @@ 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=('folder::url#fragment')`. Currently makepkg supports the `git`, `hg` and +`svn` protocols. -Development Directives ----------------------- -makepkg supports building development versions of packages without having to -manually update the pkgver in the PKGBUILD. This was formerly done using the -separate utility 'versionpkg'. In order to utilize this functionality, your -PKGBUILD must use correct variable names depending on the SCM being fetched -from (e.g., 'makepkg-git', 'mplayer-svn'). - -*CVS*:: - The generated pkgver will be the date the package is built. - - *_cvsroot*;; - The root of the CVS repository. - - *_cvsmod*;; - The CVS module to fetch. - -*SVN*:: - The generated pkgver will be the latest SVN revision number. - - *_svntrunk*;; - The trunk of the SVN repository. - - *_svnmod*;; - The SVN module to fetch. +The source URL is divided into three components: -*Git*:: - The generated pkgver will be the date the package is built. - - *_gitroot*;; - The URL (all protocols supported) to the GIT repository. - - *_gitname*;; - GIT tag or branch to use. - -*Mercurial*:: - The generated pkgver will be the hg tip revision number. - - *_hgroot*;; - The URL of the mercurial repository. - - *_hgrepo*;; - The repository to follow. - -*Darcs*:: - The generated pkgver will be the date the package is built. - - *_darcstrunk*;; - URL to the repository trunk. - - *_darcsmod*;; - Darcs module to use. - -*Bazaar*:: - The generated pkgver will be the latest Bazaar revision number (revno). - - *_bzrtrunk*;; - URL to the bazaar repository. - - *_bzrmod*;; - Bazaar module to use. +*folder*:: + (optional) Specifies an alternate folder name for makepkg to download the VCS + source into. +*url*:: + The url to the VCS repo. This must include the 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 `http` would have a source URL in the form + `git+http://...`. + +*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: + + *git*;; + branch, commit, tag + + *hg*;; + branch, revision, tag + + *svn*;; + revision Example ------- diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt index f693a5a8..9d19e38e 100644 --- a/doc/makepkg.8.txt +++ b/doc/makepkg.8.txt @@ -59,11 +59,11 @@ Options installed. *-e, \--noextract*:: - Do not extract source files; use whatever source already exists in the - src/ directory. This is handy if you want to go into src/ 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. + 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. *-f, \--force*:: makepkg will not build a package if a built package already exists in @@ -71,11 +71,6 @@ Options default to the current directory. This allows the built package to be overwritten. -*--forcever*:: - This is a hidden option that should *not* be used unless you really know - what you are doing. makepkg uses this internally when calling itself to - set the new development pkgver of the package. - *-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 @@ -96,10 +91,9 @@ Options *-h, \--help*:: Output syntax and command line options. -*\--holdver*:: - Useful when building development versions of packages. Prevents makepkg - from automatically bumping the pkgver to the latest revision number in - the package's development tree. +*--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 @@ -116,9 +110,9 @@ Options Disable color in output messages. *-o, \--nobuild*:: - Download and extract files only, but do not build them. Useful with the - '\--noextract' option if you wish to tweak the files in src/ before - building. + 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* <buildscript>:: Read the package script `buildscript` instead of the `PKGBUILD` default; @@ -152,8 +146,9 @@ Options such as a chroot or remote builder. It will also satisfy requirements of the GPL when distributing binary packages. -*\--pkg <list>*:: - Only build listed packages from a split package. +*\--pkg* <list>:: + Only build listed packages from a split package. Multiple packages should + be comma separated in the list. This option can be specified multiple times. *\--check*:: Run the check() function in the PKGBUILD, overriding the setting in @@ -178,6 +173,10 @@ Options (Passed to pacman) Prevent pacman from waiting for user input before proceeding with operations. +*\--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. @@ -207,6 +206,10 @@ Environment Variables Folder where the downloaded sources will be stored. Overrides the corresponding value defined in linkman:makepkg.conf[5]. +**PACKAGER=**"John Doe <john@doe.com>":: + String to identify the creator of the resulting package. Overrides + the corresponding value defined in linkman:makepkg.conf[5]. + **BUILDDIR=**"/path/to/folder":: Folder where the package will be built. Overrides the corresponding value defined in linkman:makepkg.conf[5]. diff --git a/doc/makepkg.conf.5.txt b/doc/makepkg.conf.5.txt index ada5e750..3dbaea1e 100644 --- a/doc/makepkg.conf.5.txt +++ b/doc/makepkg.conf.5.txt @@ -55,6 +55,9 @@ Options A string such as ``i686-pc-linux-gnu'', do not touch 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 info. + **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 @@ -217,6 +220,10 @@ Options This value is used when querying a package to see who was the builder. It is recommended you change this to your name and email address. +**COMPRESSGZ=**"(gzip -c -f -n)", **COMPRESSBZ2=**"(bzip2 -c -f)", **COMPRESSXZ=**"(xz -c -z -)", **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. The current valid suffixes are `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, and diff --git a/doc/pacman-key.8.txt b/doc/pacman-key.8.txt index 3631ec8c..8126edb7 100644 --- a/doc/pacman-key.8.txt +++ b/doc/pacman-key.8.txt @@ -12,7 +12,7 @@ pacman-key - manage pacman's list of trusted keys Synopsis -------- -'pacman-key' [options] +'pacman-key' [options] operation [targets] Description @@ -26,45 +26,40 @@ More complex keyring management can be achieved using GnuPG directly combined wi 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. -Options -------- -*-a, \--add* [file(s)]:: +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. -*\--config* <file>:: - Use an alternate config file instead of the +{sysconfdir}/pacman.conf+ - default. - -*-d, \--delete* <keyid(s)>:: +*-d, \--delete*:: Remove the key(s) identified by the specified keyid(s) from pacman's keyring. -*-e, \--export* [keyid(s)]:: +*-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* <keyid(s)>:: +*\--edit-key*:: Present a menu for key management task on the specified keyid(s). Useful for adjusting a keys trust level. -*-f, \--finger* [keyid(s)]:: +*-f, \--finger*:: List a fingerprint for each specified keyid, or for all known keys if no keyids are specified. -*\--gpgdir* <dir>:: - Set an alternate home directory for GnuPG. If unspecified, the value is - read from +{sysconfdir}/pacman.conf+. - *-h, \--help*:: Output syntax and command line options. -*\--import* <dir(s)>:: +*\--import*:: Imports keys from `pubring.gpg` into the public keyring from the specified directories. -*\--import-trustdb* <dir(s)> :: +*\--import-trustdb*:: Imports ownertrust values from `trustdb.gpg` into the shared trust database from the specified directories. @@ -72,42 +67,53 @@ Options Ensure the keyring is properly initialized and has the required access permissions. -*\--keyserver* <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. - -*-l, \--list-keys* [keyid(s)]:: +*-l, \--list-keys*:: Lists all or specified keys from the public keyring. -*\--list-sigs* [keyid(s)]:: +*\--list-sigs*:: Same as '\--list-keys', but the signatures are listed too. -*\--lsign-key* <keyid>:: +*\--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'. -*-r, \--recv-keys* <keyid(s)>:: +*-r, \--recv-keys*:: Equivalent to '\--recv-keys' in GnuPG. -*\--refresh-keys* [keyid(s)]:: +*\--refresh-keys*:: Equivalent to '\--refresh-keys' in GnuPG. -*\--populate* [keyring(s)]:: +*\--populate*:: Reload the default keys from the (optionally provided) keyrings in +{pkgdatadir}/keyrings+. For more information, see <<SC,Providing a Keyring for Import>> below. *-u, \--updatedb*:: - Equivalent to '\--check-trustdb' in GnuPG. - -*-v, \--verify* <signature>:: - Verify the given signature file. + 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* <file>:: + Use an alternate config file instead of the +{sysconfdir}/pacman.conf+ + default. + +*\--gpgdir* <dir>:: + Set an alternate home directory for GnuPG. If unspecified, the value is + read from +{sysconfdir}/pacman.conf+. + +*\--keyserver* <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 ------------------------------ diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt index 32d64d70..24c22431 100644 --- a/doc/pacman.8.txt +++ b/doc/pacman.8.txt @@ -70,10 +70,10 @@ Operations 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 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 (`^`). +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 @@ -201,7 +201,7 @@ Transaction Options (apply to '-S', '-R' and '-U') Upgrade Options (apply to '-S' and '-U')[[UO]] -------------------------------------------- -*-f, \--force*:: +*\--force*:: Bypass file conflict checks and overwrite conflicting files. If the package that is about to be installed contains files that are already installed, this option will cause all those files to be overwritten. diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt index e793e78b..a9c5db36 100644 --- a/doc/pacman.conf.5.txt +++ b/doc/pacman.conf.5.txt @@ -86,24 +86,17 @@ Options *HoldPkg =* package ...:: If a user tries to '\--remove' a package that's listed in `HoldPkg`, - pacman will ask for confirmation before proceeding. + 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'. - -*SyncFirst =* package ...:: - Instructs pacman to check for newer version of these packages before any - sync operation. The user will have the choice to either cancel the current - operation and upgrade these packages first or go on with the current - operation. This option is typically used with the 'pacman' package. - *NOTE*: when a `SyncFirst` transaction takes place, no command line flags - (e.g. '\--force') are honored. If this is not ideal, disabling `SyncFirst` - and performing a manual sync of the involved packages may be required. + 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'. + group when performing a '\--sysupgrade'. Shell-style glob patterns are + allowed. *Include =* path:: Include another config file. This file can include repositories or @@ -134,7 +127,8 @@ Options 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. + leading slash (the RootDir) when specifying them. Shell-style glob patterns + are allowed. *NoExtract =* file ...:: All files listed with a `NoExtract` directive will never be extracted from @@ -143,7 +137,8 @@ Options '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. + leading slash (the RootDir) when specifying them. Shell-style glob patterns + are allowed. *CleanMethod =* KeepInstalled &| KeepCurrent:: If set to `KeepInstalled` (the default), the '-Sc' operation will clean @@ -164,9 +159,13 @@ Options Log action messages through syslog(). This will insert log entries into +{localstatedir}/log/messages+ or equivalent. -*UseDelta*:: - Download delta files instead of complete packages if possible. Requires - the xdelta3 program to be installed. +*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, diff --git a/doc/pkgdelta.8.txt b/doc/pkgdelta.8.txt index 5913dba6..587320a6 100644 --- a/doc/pkgdelta.8.txt +++ b/doc/pkgdelta.8.txt @@ -35,7 +35,8 @@ Options *--min-pkg-size <size>*:: Minimal size of the package file in bytes to be considered for delta creation. - Default value: 1048576 bytes = 1MiB + Default value: 1048576 bytes = 1MiB. This may be any absolute size in bytes, or + a human readable value such as `4 MiB` or `3.5MB`. *-q, \--quiet*:: Be quiet. Do not output anything but warnings and errors. |