From 91f175270142aa8b03e4efc108a07ddf71f7080d Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Sun, 1 Jul 2007 10:14:08 -0400 Subject: [PATCH 01/14] Remove old 'static' manpages in anticipation of the asciidoc switch Signed-off-by: Dan McGee --- doc/PKGBUILD.5 | 288 ------------------------------------------- doc/libalpm.3 | 53 -------- doc/makepkg.8 | 146 ---------------------- doc/makepkg.conf.5 | 152 ----------------------- doc/pacman.8 | 297 --------------------------------------------- doc/pacman.conf.5 | 143 ---------------------- 6 files changed, 1079 deletions(-) delete mode 100644 doc/PKGBUILD.5 delete mode 100644 doc/libalpm.3 delete mode 100644 doc/makepkg.8 delete mode 100644 doc/makepkg.conf.5 delete mode 100644 doc/pacman.8 delete mode 100644 doc/pacman.conf.5 diff --git a/doc/PKGBUILD.5 b/doc/PKGBUILD.5 deleted file mode 100644 index 747b9f15..00000000 --- a/doc/PKGBUILD.5 +++ /dev/null @@ -1,288 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.TH \*(PB 5 "Feb 07, 2007" "\*(PB version \*(VR" "\*(DS Files" -.SH NAME -\*(PB \- \*(DS package build description file - -.SH DESCRIPTION -This manual page is meant to describe general rules about \fB\*(PB\fPs. Once -a \fB\*(PB\fP is written, the actual package is built using \fBmakepkg\fP and -installed with \fBpacman\fP. - -\fBNOTE:\fP If you have a local copy of the Arch Build System (ABS) tree -on your computer, you can copy the \*(PB.proto file to your new package -build directory and edit it from there. To acquire/sync the ABS tree, use -the \fBabs\fP script included with \fBpacman\fP. - -.SH OPTIONS AND DIRECTIVES -.TP -.B pkgname -The name of the package. This has be a unix-friendly name as it will be -used in the package filename. - -.TP -.B pkgver -The version of the software as released from the author (e.g. 2.7.1). - -.TP -.B pkgrel -This is the release number specific to the \*(DSs release. This allows package -maintainers to make updates to the package's configure flags, for example. - -.TP -.B pkgdesc -This should be a brief description of the package and its functionality. Try to -keep the description to one line of text. - -.TP -.B url -This field contains a URL that is associated with the software being packaged. -This is typically the project's website. - -.TP -.B license (array) -This field specifies the license(s) that apply to the package. Commonly-used -licenses are found in \fI/usr/share/licenses/common\fP. If you see the -package's license there, simply reference it in the license field (e.g. -\fBlicense=("GPL")\fP). If the package provides a license not found in -\fI/usr/share/licenses/common\fP, then you should include the license in the -package itself and set \fBlicense=("custom")\fP or -\fBlicense=("custom:LicenseName")\fP. The license should be placed in -\fI$startdir/pkg/usr/share/licenses/$pkgname\fP when building the package. If -multiple licenses are applicable for a package, list all of them: -\fBlicenses=('GPL' 'FDL')\fP. - -.TP -.B install -Specifies a special install script that is to be included in the package. This -file should reside in the same directory as the \fB\*(PB\fP, and will be copied -into the package by \fBmakepkg\fP. It does not need to be included in the -\fIsource\fP array (e.g. \fBinstall=pkgname.install\fP). - -.TP -.B source \fI(array)\fP -An array of source files required to build the package. Source files must -either reside in the same directory as the \fB\*(PB file\fP, or be a -fully-qualified URL that makepkg will use to download the file. In order to -make the PKGBUILD as useful as possible, use the \fB$pkgname\fP and -\fB$pkgver\fP variables if possible when specifying the download location. - -.TP -.B noextract \fI(array)\fP -An array of filenames corresponding to those from the \fBsource\fP array. Files -listed here will not be extracted with the rest of the source files. This is -useful for packages which use compressed data which is downloaded but not -necessary to uncompress. - -.TP -.B md5sums \fI(array)\fP -This array contains an MD5 hash for every source file specified in the -\fBsource\fP array (in the same order). \fBmakepkg\fP will use this to verify -source file integrity during subsequent builds. To easily generate md5sums, run -"makepkg -g >> \*(PB". If desired, move the \fBmd5sums\fP line to an -appropriate location. NOTE: \fBmakepkg\fP supports multiple integrity -algorithms and their corresponding arrays (i.e. sha1sums for the SHA1 -algorithm); however, official packages use only md5sums for the time being. - -.TP -.B sha1sums, etc. -Alternative integrity checks that \fBmakepkg\fP supports, as noted in -\fBmd5sums\fP above. - -.TP -.B groups \fI(array)\fP -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. - -.TP -.B arch \fI(array)\fP -Defines on which architectures the given package is available (e.g. -\fBarch=('i686' 'x86_64')\fP). - -.TP -.B backup \fI(array)\fP -A space-delimited array of filenames, \fIwithout\fP 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 \fBHANDLING CONFIG -FILES\fP in the \fBpacman\fP manpage for more information. - -.TP -.B depends \fI(array)\fP -An array of packages that this package depends on to run. Packages 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 -\fB'name<>version'\fP, where <> is one of three comparisons: \fI>=\fP (greater -than or equal to), \fI<=\fP (less than or equal to), or \fI=\fP (equal to). - -.TP -.B makedepends \fI(array)\fP -An array of packages that this package depends on to build, but are not needed -at runtime. Packages in this list follow the same format as \fBdepends\fP. - -.TP -.B conflicts \fI(array)\fP -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 -\fIdepends\fP, except you cannot specify versions. - -.TP -.B provides \fI(array)\fP -An array of "virtual provisions" that 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'. - -.TP -.B replaces \fI(array)\fP -An array of packages that this package should replace, and 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. - -.TP -.B options \fI(array)\fP -This array allows you to override some of \fBmakepkg\fP's default behavior when -building packages. To set an option, just include the option name in the -\fBoptions\fP 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 \fBmakepkg.conf\fP. NOTE: 'force' is a special option -only used in \fB\*(PB\fPs, do not use it unless you know what you are doing. -.RS -.TP -.B 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. -.TP -.B docs -Save doc and info directories. If you wish to delete doc and info directories, -specify "!docs" in the array. -.TP -.B libtool -Leave libtool (.la) files in packages. Specify "!libtool" to remove them. -.TP -.B emptydirs -Leave empty directories in packages. -.TP -.B ccache -Allow the use of \fBccache\fP during build. More useful in its negative form -"!ccache" with select packages that have problems building with \fBccache\fP. -.TP -.B distcc -Allow the use of \fBdistcc\fP during build. More useful in its negative form -"!distcc" with select packages that have problems building with \fBdistcc\fP. -.TP -.B makeflags -Allow the use of user-specific makeflags during build as specified in -\fBmakepkg.conf\fP. More useful in its negative form "!makeflags" with select -packages that have problems building with custom makeflags such as "-j2" (or -higher). -.TP -.B force -Force the package to be upgraded by a \fBpacman\fP system upgrade operation, -even if the version number would normally not trigger such an upgrade. This is -useful when the version numbering scheme of a package changes (or is -alphanumeric). -.RE - -.SH INSTALL/UPGRADE/REMOVE SCRIPTING -\fBPacman\fP 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 do the opposite right before it is -removed. - -The exact time the script is run varies with each operation: - -.TP -.B pre_install -script is run right before files are extracted. - -.TP -.B post_install -script is run right after files are extracted. - -.TP -.B pre_upgrade -script is run right before files are extracted. - -.TP -.B post_upgrade -script is run after files are extracted. - -.TP -.B pre_remove -script is run right before files are removed. - -.TP -.B post_remove -script is run right after files are removed. - -.P -To use this feature, create a file such as 'pkgname.install' and put it in -the same directory as the \fB\*(PB\fP script. Then use the \fBinstall\fP -directive: - -.RS -.nf -install=pkgname.install -.fi -.RE - -The install script does not need to be specified in the \fBsource\fP array. -A template install file is available in the ABS tree (/var/abs/install.proto). - -.SH EXAMPLE -The following is an example \fB\*(PB\fP for the 'modutils' package. For more -examples, look through the ABS tree. - -.nf -# Maintainer: John Doe -# Contributor: Bill Smith -pkgname=modutils -pkgver=2.4.25 -pkgrel=1 -pkgdesc="Utilities for inserting modules in the linux kernel" -url="http://www.kernel.org" -makedepends=('bash' 'mawk') -depends=('glibc' 'zlib') -backup=(etc/modules.conf) -source=(ftp://ftp.kernel.org/pub/linux/utils/kernel/$pkgname/v2.4/$pkgname-$pkgver.tar.bz2 - modules.conf) -arch=('i686') -license=('GPL' 'custom') # dual licensed -md5sums=('2c0cca3ef6330a187c6ef4fe41ecaa4d' - '35175bee593a7cc7d6205584a94d8625') -options=(!libtool) - -build() { - cd $startdir/src/$pkgname-$pkgver - ./configure --prefix=/usr --enable-insmod-static - make || return 1 - make prefix=$startdir/pkg/usr install - mv $startdir/pkg/usr/sbin $startdir/pkg - mkdir -p $startdir/pkg/etc - cp ../modules.conf $startdir/pkg/etc -} -.fi - -.SH SEE ALSO -.BR makepkg (8), -.BR pacman (8), -.BR makepkg.conf (5) - -See the Arch Linux website at for more current -information on the distribution and the \fBpacman\fP family of tools, and - for -recommendations on packaging standards. - -.SH AUTHORS -.nf -Judd Vinet -Aurelien Foret -Aaron Griffin -Dan McGee -.fi - -See the 'AUTHORS' file for additional contributors. diff --git a/doc/libalpm.3 b/doc/libalpm.3 deleted file mode 100644 index e78e9eca..00000000 --- a/doc/libalpm.3 +++ /dev/null @@ -1,53 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.ds LV 1.0.0 -.TH libalpm 3 "Feb 08, 2007" "libalpm version \*(LV" "\*(DS Utilities" -.SH NAME - libalpm \- Arch Linux Package Management (ALPM) library - -.SH 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. - -.nf -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 -.fi - -.SH CONFIGURATION -See -.BR pacman.conf (5) -for more details on configuring \fBlibalpm\fP using the \fBpacman.conf\fP file. - -.SH 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 -. - -.SH SEE ALSO -.BR pacman (8), -.BR makepkg (8), -.BR pacman.conf (5) - -See the Arch Linux website at for more current -information on the distribution and the \fBpacman\fP family of tools. - -.SH AUTHORS -.nf -Judd Vinet -Aurelien Foret -Aaron Griffin -Dan McGee -.fi - -See the 'AUTHORS' file for additional contributors. diff --git a/doc/makepkg.8 b/doc/makepkg.8 deleted file mode 100644 index 9135be21..00000000 --- a/doc/makepkg.8 +++ /dev/null @@ -1,146 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.TH makepkg 8 "Feb 07, 2007" "makepkg version \*(VR" "\*(DS Utilities" -.SH NAME -makepkg \- package build utility - -.SH SYNOPSIS -.B makepkg -[\fIoptions\fR] - -.SH DESCRIPTION -\fBmakepkg\fP is a script to automate the building of packages. All it needs is -a build-capable Linux platform and a custom build script for each package you -wish to build (known as a \fB\*(PB\fP). See -.BR \*(PB (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 -\fBpacman\fP to use. - -\fBmakeworld\fP can be used to rebuild an entire package group or the entire -build tree. See \fBmakeworld --help\fP for syntax. - -.SH OPTIONS -.TP -.B \-b, --builddeps -Build missing dependencies from source. When \fBmakepkg\fP finds missing -build-time or run-time dependencies, it will look for the dependencies' -\fB\*(PB\fP files under \fIABSROOT\fP (set in \fBmakepkg.conf\fP). If it finds -them it will call \fBmakepkg\fP to build and install the missing dependencies. -The child calls will be made with the \fB-b\fP and \fB-i\fP options. -.TP -.B \-c, --clean -Clean up leftover work files and directories after a successful build. -.TP -.B \-C, --cleancache -Removes all cached source files from the directory specified in \fISRCDEST\fP -in \fBmakepkg.conf\fP. -.TP -.B \-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. -.TP -.B \-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 \fB\*(PB\fP. -.TP -.B \-f, --force -\fBmakepkg\fP will not build a package if a built package already exists in the -\fIPKGDEST\fP (set in \fBmakepkg.conf\fP) directory, which may default to the -current directory. This allows the built package to be overwritten. -.TP -.B \-g, --geninteg -For each source file in the source array of \fB\*(PB\fP, download the file if -required and generate integrity checks. The integrity checks generated are -determined by the value of the \fIINTEGRITY_CHECK\fP array in makepkg.conf. -This output can be redirected into your \fB\*(PB\fP for source validation -(makepkg -g >> \*(PB). -.TP -.B \-h, --help -Output syntax and command line options. -.TP -.B \-i, --install -Install or upgrade the package after a successful build using \fBpacman\fP. -.TP -.B \-L, --log -Log the package build progress to a file. This file is stored in the build -directory with a name similar to that of the built package. -.TP -.B \-m, --nocolor -Disable color in output messages. -.TP -.B \-o, --nobuild -Download and extract files only, but do not build them. Useful with the -\fB--noextract\fP option if you wish to tweak the files in src/ before -building. -.TP -.B \-p \fIbuildscript\fP -Read the package script \fIbuildscript\fP instead of the default, \fI\*(PB\fP. -.TP -.B \-r, --rmdeps -Upon successful build, remove any dependencies installed by \fBmakepkg\fP -during dependency auto-resolution (using \fB-b\fP or \fB-s\fP). -.TP -.B \-R, --repackage -Repackage contents of pkg/ without rebuilding the package. This is useful if -you forgot a depend or install file in your \fB\*(PB\fP and the build itself -will not change. -.TP -.B \-s, --syncdeps -Install missing dependencies using \fBpacman\fP. When missing build-time or -run-time dependencies are found, \fBpacman\fP will try to resolve them. If -successful, the missing packages will be downloaded and installed. -.TP -.B \--asroot -This option allows you to run \fBmakepkg\fP as root. You should not normally -run \fBmakepkg\fP as root unless you know what you are doing. For any -operations that require \fBpacman\fP, \fBsudo\fP is normally used; this switch -will call \fBpacman\fP directly. -.TP -.B \--noconfirm -(Passed to \fBpacman\fP) Prevent \fBpacman\fP from waiting for user input -before proceeding with operations. -.TP -.B \--noprogressbar -(Passed to \fBpacman\fP) Prevent \fBpacman\fP from displaying a progress bar; -useful if you are redirecting makepkg output to file. - -.SH CONFIGURATION -See -.BR makepkg.conf (5) -for more details on configuring \fBmakepkg\fP using the \fBmakepkg.conf\fP file. - -.SH 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 -. - -.SH SEE ALSO -.BR makepkg.conf (5), -.BR \*(PB (5), -.BR pacman (8) - -See the Arch Linux website at for more current -information on the distribution and the \fBpacman\fP family of tools, and - for -recommendations on packaging standards. - -.SH AUTHORS -.nf -Judd Vinet -Aurelien Foret -Aaron Griffin -Dan McGee -.fi - -See the 'AUTHORS' file for additional contributors. diff --git a/doc/makepkg.conf.5 b/doc/makepkg.conf.5 deleted file mode 100644 index 08be3fc8..00000000 --- a/doc/makepkg.conf.5 +++ /dev/null @@ -1,152 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.TH \*(PB 5 "Feb 08, 2007" "makepkg.conf version \*(VR" "\*(DS Files" -.SH NAME -makepkg.conf \- makepkg configuration file - -.SH DESCRIPTION -Configuration options for \fBmakekpg\fP are stored in \fBmakepkg.conf\fP. This -file is sourced, so you can include any special compiler flags you wish to use. -This is helpful for building for different architectures, or with different -optimizations. - -\fBNOTE:\fP This does not guarantee that all package Makefiles will use your -exported variables. Some of them are non-standard... - -The default file is fairly well commented, so it may be easiest to simply -follow directions given there for customization. - -.SH OPTIONS -.TP -.B FTPAGENT="\fI/path/to/command\fP [\fIoptions\fP]" -Sets the download agent used to fetch source files specified with a URL in the -\fB\*(PB\fP file. Flags can be specified as well; the download URL is then -placed on the end of the command. -.TP -.B CARCH="\fIcarch\fP" -Specifies your computer architecture; possible values include such things as -"i686", "x86_64", "ppc", etc. This should be automatically set on installation. -.TP -.B CHOST="\fIchost\fP" -A string such as "i686-pc-linux-gnu", do not touch unless you know what you are -doing. -.TP -.B CFLAGS="\fIcflags\fP" -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 -.BR gcc (1) -for more details on the wide variety of compiler flags available. -.TP -.B CXXFLAGS="\fIcxxflags\fP" -Flags used for the C++ compiler; see \fBCFLAGS\fP for more info. -.TP -.B MAKEFLAGS="\fImakeflags\fP" -This is often used to set the number of jobs used, for example, "-j2". Other -flags that make accepts can also be passed. -.TP -.B BUILDENV=(fakeroot !distcc color !ccache !xdelta) -This array contains options that affect the build environment, the defaults -are shown here. All options should always be left in the array; to enable or -disable an option simply remove or place an "!" at the front of the option. -Each works as follows: -.RS -.TP -.B fakeroot -Allow building packages as a non-root user. This is \fIhighly\fP recommended. -.TP -.B distcc -Use the distributed C/C++/ObjC compiler to spread compilation among multiple -machines. If this is enabled, \fBDISTCC_HOSTS\fP must be specified as well. -.TP -.B color -Colorize output messages, making output easier to read. -.TP -.B 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 \fB!ccache\fP in the \fB\*(PB\fP options array. -.TP -.B xdelta -Generate delta patch from previous to current package. This is mainly useful -for large package upgrades that have only minor changes between versions where -a binary diff will be a much smaller download. This is only useful if using -the xdelta download script for pacman. -.RE -.TP -.B DISTCC_HOSTS="\fIhost1 ...\fP" -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 -\fBMAKEFLAGS\fP. -.TP -.B OPTIONS=(strip !docs libtool emptydirs) -This array contains four options that affect the default packaging. All four -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 place an "!" at the front of the option. -Each works as follows: -.RS -.TP -.B 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. -.TP -.B docs -Save doc and info directories. If you wish to delete doc and info directories, -specify "!docs" in the array. -.TP -.B libtool -Leave libtool (.la) files in packages. Specify "!libtool" to remove them. -.TP -.B emptydirs -Leave empty directories in packages. -.RE -.TP -.B INTEGRITY_CHECK=(\fIcheck1 ...\fP) -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. -.TP -.B DOC_DIRS=(usr/{,share/}{info,doc} ...) -If "!docs" is specified in the \fBOPTIONS\fP 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. -.TP -.B PKGDEST=\fI/path/to/folder\fP -If this value is not set, packages will by default be placed in the current -directory (location of the \fB\*(PB\fP). Many people like to keep all their -packages in one place so this option allows this behavior. A common location is -"/home/packages". -.TP -.B SRCDEST=\fI/path/to/folder\fP -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. -.TP -.B PACKAGER="\fIJohn Doe \fP" -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. - -.SH SEE ALSO -.BR makepkg (8), -.BR pacman (8), -.BR \*(PB (5) - -See the Arch Linux website at for more current -information on the distribution and the \fBpacman\fP family of tools, and - for -recommendations on packaging standards. - -.SH AUTHORS -.nf -Judd Vinet -Aurelien Foret -Aaron Griffin -Dan McGee -.fi - -See the 'AUTHORS' file for additional contributors. diff --git a/doc/pacman.8 b/doc/pacman.8 deleted file mode 100644 index 4825f4a7..00000000 --- a/doc/pacman.8 +++ /dev/null @@ -1,297 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.ds LV 1.0.0 -.TH pacman 8 "Feb 07, 2007" "pacman version \*(VR" "\*(DS Utilities" -.SH NAME -pacman \- package manager utility - -.SH SYNOPSIS -.B pacman -<\fIoperation\fR> [\fIoptions\fR] [\fIpackages\fR] - -.SH DESCRIPTION -\fBpacman\fP is a \fIpackage management\fP utility that tracks installed -packages on a Linux system. It features dependency support, package groups, -install and uninstall hooks, and the ability to sync your local machine with a -remote ftp server to automatically upgrade packages. \fBpacman\fP packages are -a zipped tar format. - -Since version 3.0.0, \fBpacman\fP has been the frontend to \fBlibalpm\fP, the -"Arch Linux Package Management" library. This library allows alternative front -ends to be written (for instance, a GUI front end). - -.SH OPERATIONS -.TP -.B \-A, --add (deprecated) -Add a package to the system. Either a URL or file path can be specified. The -package will be uncompressed into the installation root and the database will -be updated. The package will not be installed if another version is already -installed. NOTE: please use \fB--upgrade\fP in place of this option. -.TP -.B \-F, --freshen -This is like \fB--upgrade\fP except it will only upgrade packages already -installed on the system. -.TP -.B \-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 .tar.gz -packages. See \fBQUERY OPTIONS\fP below. -.TP -.B \-R, --remove -Remove a package from the system. Files belonging to the specified package -will be deleted, and the database will be updated. Most configuration files -will be saved with a \fI.pacsave\fP extension unless the \fB--nosave\fP option -is used. See \fBREMOVE OPTIONS\fP below. -.TP -.B \-S, --sync -Synchronize packages. Packages are installed directly from the ftp servers, -including all dependencies required to run the packages. For example, -\fBpacman -S qt\fP will download and install \fBqt\fP and all the packages it -depends on. You can also use \fBpacman -Su\fP to upgrade all packages that are -out of date. See \fBSYNC OPTIONS\fP below. -.TP -.B \-U, --upgrade -Upgrade or add a package to the system. Either a URL or file path can be -specified. This is a "remove-then-add" process. See \fBHANDLING CONFIG -FILES\fP for an explanation on how pacman takes care of config files. -.TP -.B \-V, --version -Display version and exit. -.TP -.B \-h, --help -Display syntax for the given operation. If no operation was supplied then the -general syntax is shown. - -.SH OPTIONS -.TP -.B \--ask \fInumber\fP -Pre-specify answers to questions. It is doubtful whether this option even -works, so I would not recommend using it. TODO: document this more, as I have -no idea how it works or when you would use it, or if we should just dump it. -.TP -.B \-b, --dbpath \fIpath\fP -Specify an alternative database location (default is "/var/lib/pacman/"). This -should not be used unless you know what you are doing. -.TP -.B \-d, --nodeps -Skips all dependency checks. Normally, pacman will always check a package's -dependency fields to ensure that all dependencies are installed and there are -no package conflicts in the system. -.TP -.B \-f, --force -Bypass file conflict checks and overwrite conflicting files. If the package -that is about to be installed contains files that are already installed, this -option will cause all those files to be overwritten. This option should be -used with care, ideally not at all. -.TP -.B \-r, --root \fIpath\fP -Specify an alternative installation root (default is "/"). This should -\fInot\fP be used as a way to install software into /usr/local instead of /usr. -This option is used if you want to install a package on a temporary mounted -partition which is "owned" by another system. By using this option you not only -specify where the software should be installed, but you also specify which -package database and cache location to use. -.TP -.B \-v, --verbose -Output more status messages, such as the Root and DBPath. -.TP -.B \--cachedir \fIdir\fP -Specify an alternative package cache location (default is -"/var/cache/pacman/pkg/"). This should not be used unless you know what you are -doing. -.TP -.B \--config \fIfilepath\fP -Specify an alternate configuration file. -.TP -.B \--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. -.TP -.B \--noprogressbar -Do not show a progress bar when downloading files. This can be useful for -scripts that call pacman and capture the output. -.TP -.B \--noscriptlet -If an install scriptlet exists, do not execute it. Do not use this unless you -know what you are doing. - -.SH QUERY OPTIONS -.TP -.B \-c, --changelog -View the ChangeLog of a package. Not every package will provide one but it -will be shown if available. -.TP -.B \-e, --orphans -List all packages that were pulled in by a previously installed package but no -longer required by any installed package. -.TP -.B \-g, --groups -Display all packages that are members of a named group. If not name is -specified, list all grouped packages. -.TP -.B \-i, --info -Display information on a given package. The \fB-p\fP option can be used if -querying a package file instead of the local database. -.TP -.B \-l, --list -List all files owned by a given package. Multiple packages can be specified on -the command line. -.TP -.B \-m, --foreign -List all packages that were not found in the sync database(s). Typically these -are packages that were downloaded manually and installed with \fB--upgrade\fP. -.TP -.B \-o, --owns \fIfile\fP -Search for the package that owns \fIfile\fP. -.TP -.B \-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 \fB--info\fP and \fB--list\fP. -.TP -.B \-s, --search \fIregexp\fP -This will search each locally-installed package for names or descriptions that -matche \fIregexp\fP. -.TP -.B \-t, --test -Test the consistancy of the local pacman database, and alert you of any -problems found while searching. Returns 0 on success, >0 otherwise. -.TP -.B \-u, --upgrades -Lists all packages that are out of date on the local system. This option works -best if the sync database is refreshed using \fB-Sy\fP. - -.SH REMOVE OPTIONS -.TP -.B \-c, --cascade -Remove all target packages, as well as all packages that depend on one or more -target packages. This operation is recursive. -.TP -.B \-k, --keep -Removes the database entry only. Leaves all files in place. -.TP -.B \-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. -.TP -.B \-s, --recursive -Remove each target specified including all dependencies, provided that (A) they -are not required by other packages; and (B) they were not explicitly installed -by the user. This option is analogous to a backwards \fB--sync\fP operation. - -.SH SYNC OPTIONS -.TP -.B \-c, --clean -Remove old packages from the cache to free up disk space. When \fBpacman\fP -downloads packages, it saves them in \fI/var/cache/pacman/pkg\fP. Use one -\fB--clean\fP switch to remove \fIold\fP packages; use two to remove \fIall\fP -packages from the cache. -.TP -.B \-e, --dependsonly -Install all dependencies of a package, but not the specified package itself. -This is pretty useless and we're not sure why it even exists. -.TP -.B \-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. -.TP -.B \-i, --info -Display dependency and other information for a given package. This will search -through all repositories for a matching package. -.TP -.B \-l, --list -List all packages in the specified repositories. Multiple repositories can be -specified on the command line. -.TP -.B \-p, --print-uris -Print out URIs for each package that will be installed, including any -dependencies yet to be installed. These can be piped to a file and downloaded -at a later time, using a program like wget. -.TP -.B \-s, --search \fIregexp\fP -This will search each package in the sync databases for names or descriptions -that match \fIregexp\fP. -.TP -.B \-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. -.TP -.B \-w, --downloadonly -Retrieve all packages from the server, but do not install/upgrade anything. -.TP -.B \-y, --refresh -Download a fresh copy of the master package list from the server(s) defined in -\fBpacman.conf\fP. This should typically be used each time you use -\fB--sysupgrade\fP or \fB-u\fP. Passing two \fB--refresh\fP or \fB-y\fP flags -will force a refresh of all package lists even if they are thought to be -up to date. -.TP -.B \--ignore \fIpackage\fP -Directs \fBpacman\fP to ignore upgrades of \fIpackage\fP even if there is one -available. - -.SH HANDLING CONFIG FILES -pacman uses the same logic as rpm to determine action against files that are -designated to be backed up. During an upgrade, 3 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's about to be installed, and one for the -actual file existing on the filesystem. After comparing these 3 hashes, the -follow scenarios can result: -.TP -original=\fBX\fP, current=\fBX\fP, new=\fBX\fP -All three files are the same, so overwrites are not an issue Install the new -file. -.TP -original=\fBX\fP, current=\fBX\fP, new=\fBY\fP -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 bugfixes, install the new file. -.TP -original=\fBX\fP, current=\fBY\fP, new=\fBX\fP -Both package versions contain the exact same file, but the one on the -filesystem has been modified. Leave the current file in place. -.TP -original=\fBX\fP, current=\fBY\fP, new=\fBY\fP -The new file is identical to the current file. Install the new file. -.TP -original=\fBX\fP, current=\fBY\fP, new=\fBZ\fP -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. - -.SH CONFIGURATION -See -.BR pacman.conf (5) -for more details on configuring \fBpacman\fP using the \fBpacman.conf\fP file. - -.SH 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 -. - -.SH SEE ALSO -.BR pacman.conf (5), -.BR makepkg (8), -.BR libalpm (3) - -See the Arch Linux website at for more current -information on the distribution and the \fBpacman\fP family of tools. - -.SH AUTHORS -.nf -Judd Vinet -Aurelien Foret -Aaron Griffin -Dan McGee -.fi - -See the 'AUTHORS' file for additional contributors. diff --git a/doc/pacman.conf.5 b/doc/pacman.conf.5 deleted file mode 100644 index f7304aa5..00000000 --- a/doc/pacman.conf.5 +++ /dev/null @@ -1,143 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.ds LV 1.0.0 -.TH \*(PB 5 "Feb 07, 2007" "pacman.conf version \*(VR" "\*(DS Files" -.SH NAME -pacman.conf \- pacman package manager configuration file - -.SH DESCRIPTION -\fBpacman\fP, using \fBlibalpm\fP, will attempt to read \fBpacman.conf\fP each -time it is invoked. This configuration file is divided into sections or -\fIrepositories\fP. Each section defines a package repository that \fBpacman\fP -can use when searching for packages in \fB--sync\fP mode. The exception to this -is the \fIoptions\fP section, which defines global options. - -.SH EXAMPLE -.RS -.nf -# -# pacman.conf -# -[options] -NoUpgrade = etc/passwd etc/group etc/shadow -NoUpgrade = etc/fstab - -[current] -Include = /etc/pacman.d/current - -[custom] -Server = file:///home/pkgs -.fi -.RE - -.SH OPTIONS -.TP -.B DBPath = \fIpath/to/db/dir\fP -Overrides the default location of the toplevel database directory. The default -is \fIvar/lib/pacman\fP. -.TP -.B CacheDir = \fIpath/to/cache/dir\fP -Overrides the default location of the package cache directory. The default is -\fIvar/cache/pacman\fP. -.TP -.B HoldPkg = \fIpackage\fP ... -If a user tries to \fB--remove\fP a package that's listed in \fBHoldPkg\fI, -\fBpacman\fP will ask for confirmation before proceeding. -.TP -.B IgnorePkg = \fIpackage\fP ... -Instructs \fBpacman\fP to ignore any upgrades for this package when performing a -\fB--sysupgrade\fP. -.TP -.B Include = \fIpath\fP -Include another config file. This file can include repositories or general -configuration options. -.TP -.B XferCommand = \fI/path/to/command %u\fP -If set, an external program will be used to download all remote files. All -instances of \fB%u\fP will be replaced with the download URL. If present, -instances of \fB%o\fP 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. -.TP -.B NoPassiveFtp -Disables passive ftp connections when downloading packages. (aka Active Mode) -.TP -.B NoUpgrade = \fIfile\fP ... -All files listed with a \fBNoUpgrade\fP directive will never be touched during -a package install/upgrade. Do \fInot\fP include the leading slash when -specifying files. -.TP -.B NoExtract = \fIfile\fP ... -All files listed with a \fBNoExtract\fP 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 -\fBapache\fP package. -.TP -.B UseSyslog -Log action messages through \fBsyslog()\fP. This will insert log entries into -\fI/var/log/messages\fP or equivalent. -.TP -.B LogFile = \fI/path/to/file\fP -Log actions directly to a file. Default is \fI/var/log/pacman.log\fP. -.TP -.B ShowSize -Display the size of individual packages for \fB--sync\fP and \fB--query\fP -modes. - -.SH 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 'current' and 'custom'). Locations are -defined with the \fBServer\fP 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. - -The order of repositories in the file 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. - -.SH 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 -\fB--upgrade\fP option. All you need to do is generate a compressed package -database in the directory with these packages so \fBpacman\fP can find it when -run with \fB--refresh\fP. - -.RS -.nf -repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz -.fi -.RE - -The above command will generate a compressed database named -\fI/home/pkgs/custom.db.tar.gz\fP. Note that the database must be of the form -\fI{treename}.db.tar.gz\fP, where {treename} is the name of the section defined -in the configuration file. That's it! Now configure your \fIcustom\fP 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 \fBpacman\fP's --refresh option. - -For more information on the \fBrepo-add\fP command, use \fB repo-add --help\fP. - -.SH SEE ALSO -.BR pacman (8), -.BR libalpm (3) - -See the Arch Linux website at for more current -information on the distribution and the \fBpacman\fP family of tools. - -.SH AUTHORS -.nf -Judd Vinet -Aurelien Foret -Aaron Griffin -Dan McGee -.fi - -See the 'AUTHORS' file for additional contributors. From 168b795f9eb12c08d70d05f2ee313165004564e3 Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Sun, 1 Jul 2007 17:55:44 -0400 Subject: [PATCH 02/14] Start addition of asciidoc stuff Add some asciidoc generation stuff to the doc/ Makefile.am so we can get some manpages up and working. Add necessary stuff to gitignore, and check in the asciidoc.conf file along with the footer for all of the manpages. Signed-off-by: Dan McGee --- doc/.gitignore | 8 ++++++- doc/Makefile.am | 17 ++++++++++--- doc/asciidoc.conf | 61 +++++++++++++++++++++++++++++++++++++++++++++++ doc/footer.txt | 8 +++++++ 4 files changed, 90 insertions(+), 4 deletions(-) create mode 100644 doc/asciidoc.conf create mode 100644 doc/footer.txt diff --git a/doc/.gitignore b/doc/.gitignore index b6ab6ec3..c7de9a64 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,4 +1,10 @@ Makefile Makefile.in -*.html +PKGBUILD.5 +libalpm.3 +makepkg.8 +makepkg.conf.5 +pacman.8 +pacman.conf.5 +*.xml man3 diff --git a/doc/Makefile.am b/doc/Makefile.am index 14caa0da..fd6fff45 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -10,7 +10,18 @@ if HAS_DOXYGEN man_MANS += $(wildcard man3/*.3) endif -EXTRA_DIST = $(man_MANS) Doxyfile +EXTRA_DIST = \ + pacman.8.txt \ + makepkg.8.txt \ + PKGBUILD.5.txt \ + makepkg.conf.5.txt \ + pacman.conf.5.txt \ + libalpm.3.txt \ + footer.txt \ + Doxyfile + +# Files that should be removed, but which Automake does not know. +MOSTLYCLEANFILES = $(man_MANS) man3/*.3 *.xml if HAS_DOXYGEN all: doxygen.in @@ -19,7 +30,7 @@ doxygen.in: doxygen $(srcdir)/Doxyfile endif -clean-local: - $(RM) man3/*.3 +$(man_MANS): + a2x -d manpage -f manpage --asciidoc-opts="-f asciidoc.conf" $@.txt # vim:set ts=2 sw=2 noet: diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf new file mode 100644 index 00000000..cb75ad75 --- /dev/null +++ b/doc/asciidoc.conf @@ -0,0 +1,61 @@ +# +# Inspired by/borrowed from the GIT source tree at Documentation/asciidoc.conf +# + +## manlink: macro +# +# Usage: manlink:command[manpage-section] +# +# Note, {0} is the manpage section, while {target} is the command. +# +# Show man link as: (
); if section is defined, else just show +# the command. + +[attributes] +plus=+ +caret=^ +startsb=[ +endsb=] +tilde=~ + +ifdef::backend-docbook[] +[manlink-inlinemacro] +{0%{target}} +{0#} +{0#{target}{0}} +{0#} +endif::backend-docbook[] + +ifdef::backend-docbook[] +# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. +[listingblock] +{title} + +| + +{title#} +endif::backend-docbook[] + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + +{mantitle} +{manvolnum} +Pacman +{pacman_version} +Pacman Manual + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] + +ifdef::backend-xhtml11[] +[manlink-inlinemacro] +{target}{0?({0})} +endif::backend-xhtml11[] diff --git a/doc/footer.txt b/doc/footer.txt new file mode 100644 index 00000000..e67a6e7b --- /dev/null +++ b/doc/footer.txt @@ -0,0 +1,8 @@ +Authors +------- +* Judd Vinet +* Aurelien Foret +* Aaron Griffin +* Dan McGee + +See the 'AUTHORS' file for additional contributors. From 2f7d2485f5c23223dad2b827d5c384837c878c5a Mon Sep 17 00:00:00 2001 From: Andrew Fyfe Date: Sun, 1 Jul 2007 17:58:46 -0400 Subject: [PATCH 03/14] Add two asciidoc manpages to the doc/ dir Add the pacman.8 and pacman.conf.5 asciidoc manpages to the GIT tree, with the rest to follow. Signed-off-by: Dan McGee --- doc/pacman.8.txt | 302 ++++++++++++++++++++++++++++++++++++++++++ doc/pacman.conf.5.txt | 135 +++++++++++++++++++ 2 files changed, 437 insertions(+) create mode 100644 doc/pacman.8.txt create mode 100644 doc/pacman.conf.5.txt diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt new file mode 100644 index 00000000..79c58d7d --- /dev/null +++ b/doc/pacman.8.txt @@ -0,0 +1,302 @@ +PACMAN(8) +========= + +NAME +---- +pacman - package manager utility + + +SYNOPSIS +-------- +'pacman' [options] [packages] + + +DESCRIPTION +----------- +Pacman is a package management utility that tracks installed packages on a Linux +system. It features dependency support, package groups, install and uninstall +hooks, and the ability to sync your local machine with a remote ftp server to +automatically upgrade packages. Pacman packages are a zipped tar format. + +Since version 3.0.0, pacman has been the frontend to manlink:libalpm[3], the +"Arch Linux Package Management" library. This library allows alternative front +ends to be written (for instance, a GUI front end). + + +OPERATIONS +---------- +-A, --add (deprecated):: + Add a package to the system. Either a URL or file path can be specified. + The package will be uncompressed into the installation root and the + database will be updated. The package will not be installed if another + version is already installed. *NOTE*: please use `--upgrade` in place of + this option. + +-F, --freshen:: + This is like `--upgrade` except it will only upgrade packages already + installed on the system. + +-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 `.tar.gz` packages. See <> below. + +-R, --remove:: + Remove a package from the system. 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 ftp + servers, 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. You can also use `pacman -Su` to upgrade all + packages that are out of date. See <> below. + +-U, --upgrade:: + Upgrade or add a package to the system. Either a URL or file path can be + specified. This is a "remove-then-add" process. See + <> for an explanation on how + pacman takes care of config files. + +-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 +------- +--ask :: + Pre-specify answers to questions. It is doubtful whether this option + even works, so I would not recommend using it. *TODO*: document this + more, as I have no idea how it works or when you would use it, or if we + should just dump it. + +-b, --dbpath :: + Specify an alternative database location (default is `/var/lib/pacman`). + This should not be used unless you know what you are doing. + +-d, --nodeps:: + Skips all dependency checks. Normally, pacman will always check a + package's dependency fields to ensure that all dependencies are + installed and there are no package conflicts in the system. + +-f, --force:: + Bypass file conflict checks and overwrite conflicting files. If the + package that is about to be installed contains files that are already + installed, this option will cause all those files to be overwritten. + This option should be used with care, ideally not at all. + +-r, --root :: + Specify an alternative installation root (default is `/`). This should + not be used as a way to install software into `/usr/local` instead of + `/usr`. This option is used if you want to install a package on a + temporary mounted partition which is "owned" by another system. By using + this option you not only specify where the software should be installed, + but you also specify which package database and cache location to use. + +-v, --verbose:: + Output more status messages, such as the Root and DBPath. + +--cachedir :: + Specify an alternative package cache location (default is + `/var/cache/pacman/pkg`). This should not be used unless you know what + you are doing. + +--config :: + Specify an alternate configuration file. + +--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. + +--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. + + +Query Options[[QO]] +------------------- +-c, --changelog:: + View the ChangeLog of a package. Not every package will provide one but + it will be shown if available. + +-e, --orphans:: + List all packages that were pulled in by a previously installed package + but no longer required by any installed package. + +-g, --groups:: + Display all packages that are members of a named group. If not name is + 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. + +-l, --list:: + List all files owned by a given package. Multiple packages can be + specified on the command line. + +-m, --foreign:: + List all packages that were not found in the sync database(s). Typically + these are packages that were downloaded manually and installed with + `--upgrade`. + +-o, --owns :: + Search for the package that owns file. + +-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`. + +-s, --search :: + This will search each locally-installed package for names or + descriptions that matche regexp. + +-u, --upgrades:: + Lists all packages that are out of date on the local system. This option + works best if the sync database is refreshed using `-Sy`. + + +Remove Options[[RO]] +-------------------- +-c, --cascade:: + Remove all target packages, as well as all packages that depend on one + or more target packages. This operation is recursive. + +-k, --keep:: + Removes the database entry only. Leaves all files in place. + +-n, --nosave:: + Instructs pacman to ignore file backup designations. Normally, when a + file is removed from the system the database is checked to see if the + file should be renamed with a .pacsave extension. + +-s, --recursive:: + Remove each target specified including all dependencies, provided that + (A) they are not required by other packages; and (B) they were not + explicitly installed by the user. This option is analogous to a + backwards `--sync` operation. + + +Sync Options[[SO]] +------------------ +-c, --clean:: + Remove old packages from the cache to free up disk space. When pacman + downloads packages, it saves them in `/var/cache/pacman/pkg`. Use one + `--clean` switch to remove old packages; use two to remove all packages + from the cache. + +-e, --dependsonly:: + Install all dependencies of a package, but not the specified package + itself. This is pretty useless and we're not sure why it even exists. + +-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 dependency and other information for a given package. This will + search through all repositories for a matching package. + +-l, --list:: + List all packages in the specified repositories. Multiple repositories + can be specified on the command line. + +-p, --print-uris:: + Print out URIs for each package that will be installed, including any + dependencies yet to be installed. These can be piped to a file and + downloaded at a later time, using a program like wget. + +-s, --search :: + This will search each package in the sync databases for names or + descriptions that match regexp. + +-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. + +-w, --downloadonly:: + Retrieve all packages from the server, but do not install/upgrade + anything. + +-y, --refresh:: + Download a fresh copy of the master package list from the server(s) + defined in pacman.conf. 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 lists even if they are thought to be up to date. + +--ignore :: + Directs pacman to ignore upgrades of package even if there is one + available. + + +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, 3 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's about to be installed, and one for the +actual file existing on the filesystem. After comparing these 3 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 bugfixes, install the new file. + +original=X, current=Y, new=X:: + Both package versions contain the exact same file, but the one on the + filesystem 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. + + +Configuration +------------- +See manlink:pacman.conf[5] for more details on configuring pacman using the +`pacman.conf` file. + + +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 +pacman-dev@archlinux.org. + + +See Also +-------- +manlink:pacman.conf[5], manlink:makepkg[8], manlink:libalpm[3] + +See the Arch Linux website at http://www.archlinux.org for more current +information on the distribution and the pacman family of tools. + + +include::footer.txt[] diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt new file mode 100644 index 00000000..89ca47f0 --- /dev/null +++ b/doc/pacman.conf.5.txt @@ -0,0 +1,135 @@ +pacman.conf(5) +============== + +NAME +---- +pacman.conf - pacman package manager configuration file + + +DESCRIPTION +----------- +Pacman, using manlink: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 + +[current] +Include = /etc/pacman.d/current + +[custom] +Server = file:///home/pkgs +-------- + + +OPTIONS +------- +DBPath = path/to/db/dir:: + Overrides the default location of the toplevel database directory. + The default is `var/lib/pacman`. + +CacheDir = path/to/cache/dir:: + Overrides the default location of the package cache directory. The + default is `var/cache/pacman`. + +HoldPkg = package ...:: + If a user tries to `--remove` a package that's listed in `HoldPkg`, + pacman will ask for confirmation before proceeding. + +IgnorePkg = package ...:: + Instructs pacman to ignore any upgrades for this package when performing + a `--sysupgrade`. + +Include = path:: + Include another config file. This file can include repositories or + general configuration options. + +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. + +NoPassiveFtp:: + Disables passive ftp connections when downloading packages. (aka Active Mode) + +NoUpgrade = file ...:: + All files listed with a `NoUpgrade` directive will never be touched during + a package install/upgrade. Do not include the leading slash when specifying + files. + +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. + +UseSyslog:: + Log action messages through syslog(). This will insert log entries into + `/var/log/messages` or equivalent. + +LogFile = /path/to/file:: + Log actions directly to a file. Default is `/var/log/pacman.log`. + +ShowSize:: + Display the size of individual packages for `--sync` and `--query` modes. + + +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 'current' and 'custom'). 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. + +The order of repositories in the file matters; repositories listed first will +take precedence over those listed later in the file when packages in two +repositories have identical names, regardless of version number. + +Using Your Own Repository +------------------------- +If you have numerous custom packages of your own, it is often easier to generate +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.gz`, where `{treename}` is the name of the section defined in +the configuration file. That's it! Now configure your custom section in the +configuration file as shown in the config example above. Pacman will now use your +package repository. If you add new packages to the repository, remember to +re-generate the database and use pacman's `--refresh` option. + +For more information on the repo-add command, use `repo-add --help`. + + +See Also +-------- +manlink:pacman[8], manlink:libalpm[3] + +See the Arch Linux website at http://www.archlinux.org for more current +information on the distribution and the pacman family of tools. + + +include::footer.txt[] From 493e5fb7828793a8b834d5ecfd2e83050fcd920c Mon Sep 17 00:00:00 2001 From: Andrew Fyfe Date: Mon, 2 Jul 2007 21:30:39 +0100 Subject: [PATCH 04/14] Move common stuff into footer.txt and some formating tweaks. Signed-off-by: Andrew Fyfe --- doc/footer.txt | 13 +++++ doc/pacman.8.txt | 109 +++++++++++++++++++----------------------- doc/pacman.conf.5.txt | 36 +++++++------- 3 files changed, 78 insertions(+), 80 deletions(-) diff --git a/doc/footer.txt b/doc/footer.txt index e67a6e7b..5f62a647 100644 --- a/doc/footer.txt +++ b/doc/footer.txt @@ -1,3 +1,16 @@ +See the Arch Linux website at for more current +information on the distribution and the pacman family of tools, and + for +recommendations on packaging standards. + + +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 +. + + Authors ------- * Judd Vinet diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt index 79c58d7d..dbdb146c 100644 --- a/doc/pacman.8.txt +++ b/doc/pacman.8.txt @@ -1,17 +1,17 @@ PACMAN(8) ========= -NAME +Name ---- pacman - package manager utility -SYNOPSIS +Synopsis -------- 'pacman' [options] [packages] -DESCRIPTION +Description ----------- Pacman is a package management utility that tracks installed packages on a Linux system. It features dependency support, package groups, install and uninstall @@ -23,77 +23,77 @@ Since version 3.0.0, pacman has been the frontend to manlink:libalpm[3], the ends to be written (for instance, a GUI front end). -OPERATIONS +Operations ---------- --A, --add (deprecated):: +*-A, --add* (deprecated):: Add a package to the system. Either a URL or file path can be specified. The package will be uncompressed into the installation root and the database will be updated. The package will not be installed if another version is already installed. *NOTE*: please use `--upgrade` in place of this option. --F, --freshen:: +*-F, --freshen*:: This is like `--upgrade` except it will only upgrade packages already installed on the system. --Q, --query:: +*-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 `.tar.gz` packages. See <> below. --R, --remove:: +*-R, --remove*:: Remove a package from the system. 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:: +*-S, --sync*:: Synchronize packages. Packages are installed directly from the ftp servers, 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. You can also use `pacman -Su` to upgrade all packages that are out of date. See <> below. --U, --upgrade:: +*-U, --upgrade*:: Upgrade or add a package to the system. Either a URL or file path can be specified. This is a "remove-then-add" process. See <> for an explanation on how pacman takes care of config files. --V, --version:: +*-V, --version*:: Display version and exit. --h, --help:: +*-h, --help*:: Display syntax for the given operation. If no operation was supplied then the general syntax is shown. -OPTIONS +Options ------- ---ask :: +*--ask* <'number'>:: Pre-specify answers to questions. It is doubtful whether this option even works, so I would not recommend using it. *TODO*: document this more, as I have no idea how it works or when you would use it, or if we should just dump it. --b, --dbpath :: +*-b, --dbpath* <'path'>:: Specify an alternative database location (default is `/var/lib/pacman`). This should not be used unless you know what you are doing. --d, --nodeps:: +*-d, --nodeps*:: Skips all dependency checks. Normally, pacman will always check a package's dependency fields to ensure that all dependencies are installed and there are no package conflicts in the system. --f, --force:: +*-f, --force*:: Bypass file conflict checks and overwrite conflicting files. If the package that is about to be installed contains files that are already installed, this option will cause all those files to be overwritten. This option should be used with care, ideally not at all. --r, --root :: +*-r, --root* <'path'>:: Specify an alternative installation root (default is `/`). This should not be used as a way to install software into `/usr/local` instead of `/usr`. This option is used if you want to install a package on a @@ -101,89 +101,89 @@ OPTIONS this option you not only specify where the software should be installed, but you also specify which package database and cache location to use. --v, --verbose:: +*-v, --verbose*:: Output more status messages, such as the Root and DBPath. ---cachedir :: +*--cachedir* <'dir'>:: Specify an alternative package cache location (default is `/var/cache/pacman/pkg`). This should not be used unless you know what you are doing. ---config :: +*--config* <'file'>:: Specify an alternate configuration file. ---noconfirm:: +*--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. ---noprogressbar:: +*--noprogressbar*:: Do not show a progress bar when downloading files. This can be useful for scripts that call pacman and capture the output. ---noscriptlet:: +*--noscriptlet*:: If an install scriptlet exists, do not execute it. Do not use this unless you know what you are doing. Query Options[[QO]] ------------------- --c, --changelog:: +*-c, --changelog*:: View the ChangeLog of a package. Not every package will provide one but it will be shown if available. --e, --orphans:: +*-e, --orphans*:: List all packages that were pulled in by a previously installed package but no longer required by any installed package. --g, --groups:: +*-g, --groups*:: Display all packages that are members of a named group. If not name is specified, list all grouped packages. --i, --info:: +*-i, --info*:: Display information on a given package. The `-p` option can be used if querying a package file instead of the local database. --l, --list:: +*-l, --list*:: List all files owned by a given package. Multiple packages can be specified on the command line. --m, --foreign:: +*-m, --foreign*:: List all packages that were not found in the sync database(s). Typically these are packages that were downloaded manually and installed with `--upgrade`. --o, --owns :: +*-o, --owns* <'file'>:: Search for the package that owns file. --p, --file:: +*-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`. --s, --search :: +*-s, --search* <'regexp'>:: This will search each locally-installed package for names or descriptions that matche regexp. --u, --upgrades:: +*-u, --upgrades*:: Lists all packages that are out of date on the local system. This option works best if the sync database is refreshed using `-Sy`. Remove Options[[RO]] -------------------- --c, --cascade:: +*-c, --cascade*:: Remove all target packages, as well as all packages that depend on one or more target packages. This operation is recursive. --k, --keep:: +*-k, --keep*:: Removes the database entry only. Leaves all files in place. --n, --nosave:: +*-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:: +*-s, --recursive*:: Remove each target specified including all dependencies, provided that (A) they are not required by other packages; and (B) they were not explicitly installed by the user. This option is analogous to a @@ -192,39 +192,39 @@ Remove Options[[RO]] Sync Options[[SO]] ------------------ --c, --clean:: +*-c, --clean*:: Remove old packages from the cache to free up disk space. When pacman downloads packages, it saves them in `/var/cache/pacman/pkg`. Use one `--clean` switch to remove old packages; use two to remove all packages from the cache. --e, --dependsonly:: +*-e, --dependsonly*:: Install all dependencies of a package, but not the specified package itself. This is pretty useless and we're not sure why it even exists. --g, --groups:: +*-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:: +*-i, --info*:: Display dependency and other information for a given package. This will search through all repositories for a matching package. --l, --list:: +*-l, --list*:: List all packages in the specified repositories. Multiple repositories can be specified on the command line. --p, --print-uris:: +*-p, --print-uris*:: Print out URIs for each package that will be installed, including any dependencies yet to be installed. These can be piped to a file and downloaded at a later time, using a program like wget. --s, --search :: +*-s, --search* <'regexp'>:: This will search each package in the sync databases for names or descriptions that match regexp. --u, --sysupgrade:: +*-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 @@ -232,17 +232,17 @@ Sync Options[[SO]] automatically resolved at this level and will be installed/upgraded if necessary. --w, --downloadonly:: +*-w, --downloadonly*:: Retrieve all packages from the server, but do not install/upgrade anything. --y, --refresh:: +*-y, --refresh*:: Download a fresh copy of the master package list from the server(s) defined in pacman.conf. 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 lists even if they are thought to be up to date. ---ignore :: +*--ignore* <'package'>:: Directs pacman to ignore upgrades of package even if there is one available. @@ -284,19 +284,8 @@ See manlink:pacman.conf[5] for more details on configuring pacman using the `pacman.conf` file. -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 -pacman-dev@archlinux.org. - - See Also -------- manlink:pacman.conf[5], manlink:makepkg[8], manlink:libalpm[3] -See the Arch Linux website at http://www.archlinux.org for more current -information on the distribution and the pacman family of tools. - - include::footer.txt[] diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt index 89ca47f0..295c9b28 100644 --- a/doc/pacman.conf.5.txt +++ b/doc/pacman.conf.5.txt @@ -1,12 +1,12 @@ pacman.conf(5) ============== -NAME +Name ---- pacman.conf - pacman package manager configuration file -DESCRIPTION +Description ----------- Pacman, using manlink:libalpm[3], will attempt to read `pacman.conf` each time it is invoked. This configuration file is divided into sections or @@ -15,7 +15,7 @@ when searching for packages in `--sync` mode. The exception to this is the options section, which defines global options. -EXAMPLE +Example ------- -------- # @@ -33,29 +33,29 @@ Server = file:///home/pkgs -------- -OPTIONS +Options ------- -DBPath = path/to/db/dir:: +*DBPath =* 'path/to/db/dir':: Overrides the default location of the toplevel database directory. The default is `var/lib/pacman`. -CacheDir = path/to/cache/dir:: +*CacheDir =* 'path/to/cache/dir':: Overrides the default location of the package cache directory. The default is `var/cache/pacman`. -HoldPkg = package ...:: +*HoldPkg =* 'package' ...:: If a user tries to `--remove` a package that's listed in `HoldPkg`, pacman will ask for confirmation before proceeding. -IgnorePkg = package ...:: +*IgnorePkg =* 'package' ...:: Instructs pacman to ignore any upgrades for this package when performing a `--sysupgrade`. -Include = path:: +*Include =* 'path':: Include another config file. This file can include repositories or general configuration options. -XferCommand = /path/to/command %u:: +*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 @@ -65,29 +65,29 @@ XferCommand = /path/to/command %u:: http/ftp support, or need the more advanced proxy support that comes with utilities like wget. -NoPassiveFtp:: +*NoPassiveFtp*:: Disables passive ftp connections when downloading packages. (aka Active Mode) -NoUpgrade = file ...:: +*NoUpgrade =* 'file' ...:: All files listed with a `NoUpgrade` directive will never be touched during a package install/upgrade. Do not include the leading slash when specifying files. -NoExtract = file ...:: +*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. -UseSyslog:: +*UseSyslog*:: Log action messages through syslog(). This will insert log entries into `/var/log/messages` or equivalent. -LogFile = /path/to/file:: +*LogFile =* '/path/to/file':: Log actions directly to a file. Default is `/var/log/pacman.log`. -ShowSize:: +*ShowSize*:: Display the size of individual packages for `--sync` and `--query` modes. @@ -128,8 +128,4 @@ See Also -------- manlink:pacman[8], manlink:libalpm[3] -See the Arch Linux website at http://www.archlinux.org for more current -information on the distribution and the pacman family of tools. - - include::footer.txt[] From be0a472cb798f0bfd4a75d1cfe165b4005a8ca90 Mon Sep 17 00:00:00 2001 From: Andrew Fyfe Date: Tue, 3 Jul 2007 00:22:01 +0100 Subject: [PATCH 05/14] Convert the remaining man pages to asciidoc. Signed-off-by: Andrew Fyfe --- doc/PKGBUILD.5.txt | 256 +++++++++++++++++++++++++++++++++++++++++ doc/libalpm.3.txt | 36 ++++++ doc/makepkg.8.txt | 124 ++++++++++++++++++++ doc/makepkg.conf.5.txt | 136 ++++++++++++++++++++++ doc/pacman.8.txt | 2 +- 5 files changed, 553 insertions(+), 1 deletion(-) create mode 100644 doc/PKGBUILD.5.txt create mode 100644 doc/libalpm.3.txt create mode 100644 doc/makepkg.8.txt create mode 100644 doc/makepkg.conf.5.txt diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt new file mode 100644 index 00000000..642f8884 --- /dev/null +++ b/doc/PKGBUILD.5.txt @@ -0,0 +1,256 @@ +PKGBUILD(5) +=========== + +Name +---- +PKGBUILD - Arch Linux package build description file + + +Description +----------- +This manual page is meant to describe general rules about PKGBUILDs. Once a +PKGBUILD is written, the actual package is built using makepkg and installed +with pacman. + +*NOTE:* If you have a local copy of the Arch Build System (ABS) tree on your +computer, you can copy the PKGBUILD.proto file to your new package build +directory and edit it from there. To acquire/sync the ABS tree, use the abs +script included with pacman. + + +Options and Directives +---------------------- +*pkgname*:: + The name of the package. This has be a unix-friendly name as it will be + used in the package filename. + +*pkgver*:: + The version of the software as released from the author (e.g. 2.7.1). + +*pkgrel*:: + This is the release number specific to the Arch Linuxs release. This + allows package maintainers to make updates to the package's configure + flags, for example. + + +*pkgdesc*:: + This should be a brief description of the package and its functionality. + Try to keep the description to one line of text. + +*url*:: + This field contains a URL that is associated with the software being + packaged. This is typically the project's website. + +*license (array)*:: + This field specifies the license(s) that apply to the package. + Commonly-used licenses are found in /usr/share/licenses/common. If you + see the package's license there, simply reference it in the license + field (e.g. license=("GPL")). If the package provides a license not + found in /usr/share/licenses/common, then you should include the license + in the package itself and set license=("custom") or + license=("custom:LicenseName"). The license should be placed in + $startdir/pkg/usr/share/licenses/$pkgname when building the package. If + multiple licenses are applicable for a package, list all of them: + licenses=('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). + +*source (array)*:: + An array of source files required to build the package. Source files + must either reside in the same directory as the PKGBUILD file, or be a + fully-qualified URL that makepkg will use to download the file. In order + to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver + variables if possible when specifying the download location. + +*noextract (array)*:: + An array of filenames corresponding to those from the source array. Files + listed here will not be extracted with the rest of the source files. This + is useful for packages which use compressed data which is downloaded but + not necessary to uncompress. + +*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. *NOTE:* makepkg supports multiple integrity + algorithms and their corresponding arrays (i.e. sha1sums for the SHA1 + algorithm); however, official packages use only md5sums for the time + being. + +*sha1sums, etc.*:: + Alternative integrity checks that makepkg supports, as noted in md5sums + above. + +*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')). + +*backup (array)*:: + A space-delimited array of filenames, without preceding slashes, that + should be backed up if the package is removed or upgraded. This is + commonly used for packages placing configuration files in /etc. See + Handling Config Files in manlink:pacman[8] for more information. + +*depends (array)*:: + An array of packages that this package depends on to run. Packages 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 three comparisons: >= (greater + than or equal to), <= (less than or equal to), or = (equal to). + +*makedepends (array)*:: + An array of packages that this package depends on to build, but are not + needed at runtime. Packages in this list follow the same format as + depends. + +*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, except you cannot specify versions. + +*provides (array)*:: + An array of "virtual provisions" that 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'. + +*replaces (array)*:: + An array of packages that this package should replace, and 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. + +*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 manlink:makepkg.conf[5]. + *NOTE:* 'force' is a special option only used in manlink:PKGBUILD[5]s, + do not use it unless you know what you are doing. + + *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 and info directories. If you wish to delete doc and + info directories, specify "!docs" in the array. + + *libtool*:: + Leave libtool (.la) files in packages. Specify "!libtool" to + remove them. + + *emptydirs*:: + Leave empty directories in packages. + + *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. + + *makeflags*:: + Allow the use of user-specific makeflags during build as specified + in manlink:makepkg.conf[5]. More useful in its negative form + "!makeflags" with select packages that have problems building with + custom makeflags such as "-j2" (or higher). + + *force*:: + Force the package to be upgraded by a pacman system upgrade + operation, even if the version number would normally not trigger + such an upgrade. This is useful when the version numbering scheme + of a package changes (or is alphanumeric). + + +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 do the opposite right before it is removed. + +The exact time the script is run varies with each operation: + +*pre_install*:: + script is run right before files are extracted. + +*post_install*:: + script is run right after files are extracted. + +*pre_upgrade*:: + script is run right before files are extracted. + +*post_upgrade*:: + script is run after files are extracted. + +*pre_remove*:: + script is run right before files are removed. + +*post_remove*:: + script is run right after files are removed. + +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 the ABS tree (/var/abs/install.proto). + + +Example +------- +The following is an example PKGBUILD for the 'modutils' package. For more +examples, look through the ABS tree. + +----- +# Maintainer: John Doe +# Contributor: Bill Smith +pkgname=modutils +pkgver=2.4.25 +pkgrel=1 +pkgdesc="Utilities for inserting modules in the linux kernel" +url="http://www.kernel.org" +makedepends=('bash' 'mawk') +depends=('glibc' 'zlib') +backup=(etc/modules.conf) +source=(ftp://ftp.kernel.org/pub/linux/utils/kernel/$pkgname/v2.4/$pkgname-$pkgver.tar.bz2 + modules.conf) +arch=('i686') +license=('GPL' 'custom') # dual licensed +md5sums=('2c0cca3ef6330a187c6ef4fe41ecaa4d' + '35175bee593a7cc7d6205584a94d8625') +options=(!libtool) + +build() { + cd $startdir/src/$pkgname-$pkgver + ./configure --prefix=/usr --enable-insmod-static + make || return 1 + make prefix=$startdir/pkg/usr install + mv $startdir/pkg/usr/sbin $startdir/pkg + mkdir -p $startdir/pkg/etc + cp ../modules.conf $startdir/pkg/etc +} +----- + + +See Also +-------- +manlink:makepkg[8], manlink:pacman[8], manlink:makepkg.conf[5] + +include::footer.txt[] diff --git a/doc/libalpm.3.txt b/doc/libalpm.3.txt new file mode 100644 index 00000000..c9951311 --- /dev/null +++ b/doc/libalpm.3.txt @@ -0,0 +1,36 @@ +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 manlink:pacman.conf[5] for more details on configuring libalpm using the +pacman.conf file. + + +See Also +-------- +manlink:pacman[8], manlink:makepkg[8], manlink:pacman.conf[5] + +include::footer.txt[] diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt new file mode 100644 index 00000000..636d409f --- /dev/null +++ b/doc/makepkg.8.txt @@ -0,0 +1,124 @@ +makepkg(8) +========== + +Name +---- +makepkg - package build utility + + +Synopsis +-------- +makepkg [options] + + +Description +----------- +makepkg is a script to automate the building of packages. All it needs is a +build-capable Linux platform and a custom build script for each package you +wish to build (known as a PKGBUILD). See manlink: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. + +makeworld can be used to rebuild an entire package group or the entire build tree. +See `makeworld --help` for syntax. + +Options +------- +*-b, --builddeps*:: + Build missing dependencies from source. When makepkg finds missing + build-time or run-time dependencies, it will look for the dependencies' + PKGBUILD files under ABSROOT (set in makepkg.conf). If it finds them it + will call makepkg to build and install the missing dependencies. The + child calls will be made with the `-b` and `-i` options. + +*-c, --clean*:: + Clean up leftover work files and directories after a successful build. + +*-C, --cleancache*:: + Removes all cached source files from the directory specified in SRCDEST + in manlink:makepkg.conf[5]. + +*-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; 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. + +*-f, --force*:: + makepkg will not build a package if a built package already exists in + the PKGDEST (set in manlink: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 value of the INTEGRITY_CHECK array in + manlink:makepkg.conf[5]. This output can be redirected into your + PKGBUILD for source validation (`makepkg -g >> PKGBUILD`). + +*-h, --help*:: + Output syntax and command line options. + +*-i, --install*:: + Install or upgrade the package after a successful build using pacman. + +*-m, --nocolor*:: + 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. + +*-p* <'buildscript'>:: + Read the package script buildscript instead of the default, + manlink:PKGBUILD[5]. + +*-r, --rmdeps*:: + Upon successful build, remove any dependencies installed by makepkg + during dependency auto-resolution (using `-b` or `-s`). + +*-R, --repackage*:: + Repackage contents of pkg/ without rebuilding the package. This is + useful if you forgot a depend or install file in your PKGBUILD and the + build itself will not change. + +*-s, --syncdeps*:: + Install missing dependencies using pacman. When missing build-time or + run-time dependencies are found, pacman will try to resolve them. If + successful, the missing packages will be downloaded and installed. + +*--noconfirm*:: + (Passed to pacman) Prevent pacman from waiting for user input before + proceeding with operations. + +*--noprogressbar*:: + (Passed to pacman) Prevent pacman from displaying a progress bar; + useful if you are redirecting makepkg output to file. + + +Configuration +------------- +See manlink:makepkg.conf[5] for more details on configuring makepkg using the +makepkg.conf file. + + +See Also +-------- +manlink:makepkg.conf[5], manlink:PKGBUILD[5], manlink:pacman[8] + +include::footer.txt[] diff --git a/doc/makepkg.conf.5.txt b/doc/makepkg.conf.5.txt new file mode 100644 index 00000000..fd867f6b --- /dev/null +++ b/doc/makepkg.conf.5.txt @@ -0,0 +1,136 @@ +makepkg.conf(5) +=============== + +Name +---- +makepkg.conf - makepkg configuration file + + +Description +----------- +Configuration options for makekpg are stored in makepkg.conf. This file is +sourced, so you can include any special compiler flags you wish to use. This is +helpful for building for different architectures, or with different +optimizations. + +*NOTE:* This does not guarantee that all package Makefiles will use your +exported variables. Some of them are non-standard... + +The default file is fairly well commented, so it may be easiest to simply follow +directions given there for customization. + + +Options +------- +*FTPAGENT="*'/path/to/command [options]'*"*:: + Sets the download agent used to fetch source files specified with a URL + in the manlink:PKGBUILD[5] file. Flags can be specified as well; the + download URL is then placed on the end of the command. + +*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 unless you know what + you are doing. + +*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. + +*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. + +*BUILDENV=(*'fakeroot !distcc color !ccache'*)*:: + This array contains four options that affect the build environment, the + defaults are shown here. All options should always be left in the array; + to enable or disable an option simply remove or place an "!" at the + front of the option. Each works as follows: + + *fakeroot*:: + Allow building packages as a non-root user. This is highly + recommended. + + *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. + +*DISTCC_HOSTS="*'host1' ...*"*:: + If using DistCC, this is used to specify a space-delimited list of hosts + running in the DistCC cluster. In addition, you will want to modify your + MAKEFLAGS. + +*OPTIONS=(*'strip !docs libtool emptydirs'*)*:: + This array contains four options that affect the default packaging. All + four 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 place an "!" at the front + of the option. Each 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 and info directories. If you wish to delete doc and info + directories, specify "!docs" in the array. + + *libtool*:: + Leave libtool (.la) files in packages. Specify "!libtool" to + remove them. + + *emptydirs*:: + Leave empty directories in packages. + +*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. + +*DOC_DIRS=(*'usr/{,share/}{info,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. + +*PKGDEST=*'/path/to/folder':: + If this value is not set, packages will by default be placed in the + current directory (location of the manlink:PKGBUILD[5]). Many people + like to keep all their packages in one place so this option allows + this behavior. A common location is "/home/packages". + +*SRCDEST=*'/path/to/folder':: + 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. + +*PACKAGER="*'John Doe '*"*:: + 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. + + +See Also +-------- +manlink:makepkg[8], manlink:pacman[8], manlink:PKGBUILD[5] + +include::footer.txt[] diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt index dbdb146c..891be7dd 100644 --- a/doc/pacman.8.txt +++ b/doc/pacman.8.txt @@ -1,4 +1,4 @@ -PACMAN(8) +pacman(8) ========= Name From fe9a0de32edaf1db58e46a3fd3f1c05ad0b0e6c2 Mon Sep 17 00:00:00 2001 From: Andrew Fyfe Date: Fri, 6 Jul 2007 06:56:11 +0100 Subject: [PATCH 06/14] doc/Makefile.am: Set pacman version and date when man pages are generated. Signed-off-by: Andrew Fyfe --- doc/Makefile.am | 7 ++++++- doc/asciidoc.conf | 3 +++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index fd6fff45..8c51a95a 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -23,6 +23,11 @@ EXTRA_DIST = \ # Files that should be removed, but which Automake does not know. MOSTLYCLEANFILES = $(man_MANS) man3/*.3 *.xml +ASCIIDOC_OPTS = \ + -f asciidoc.conf \ + -apacman_version="$(PACKAGE_VERSION)" \ + -apacman_date="`date +%Y-%m-%d`" + if HAS_DOXYGEN all: doxygen.in @@ -31,6 +36,6 @@ doxygen.in: endif $(man_MANS): - a2x -d manpage -f manpage --asciidoc-opts="-f asciidoc.conf" $@.txt + a2x -d manpage -f manpage --asciidoc-opts="$(ASCIIDOC_OPTS)" $@.txt # vim:set ts=2 sw=2 noet: diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf index cb75ad75..6b0747d6 100644 --- a/doc/asciidoc.conf +++ b/doc/asciidoc.conf @@ -41,6 +41,9 @@ ifdef::backend-docbook[] [header] template::[header-declarations] + +{pacman_date} + {mantitle} {manvolnum} From 499b750c2fbbedde27ad25d241f0c95566e5a0b7 Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Fri, 6 Jul 2007 09:59:46 -0400 Subject: [PATCH 07/14] Make manpage generation depend on footer.txt If footer.txt is updated, we need to regenerate the manpages, this little fix should do this. Signed-off-by: Dan McGee --- doc/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index 8c51a95a..ab73b8d7 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -35,7 +35,7 @@ doxygen.in: doxygen $(srcdir)/Doxyfile endif -$(man_MANS): +$(man_MANS): footer.txt a2x -d manpage -f manpage --asciidoc-opts="$(ASCIIDOC_OPTS)" $@.txt # vim:set ts=2 sw=2 noet: From ab87657b937f3de392b1796e7f93c4008cc21f01 Mon Sep 17 00:00:00 2001 From: Andrew Fyfe Date: Fri, 6 Jul 2007 16:07:53 +0100 Subject: [PATCH 08/14] Add Synopsis section to man 5 pages. Signed-off-by: Andrew Fyfe --- doc/Makefile.am | 5 +++-- doc/PKGBUILD.5.txt | 5 +++++ doc/makepkg.conf.5.txt | 5 +++++ doc/pacman.conf.5.txt | 5 +++++ 4 files changed, 18 insertions(+), 2 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index ab73b8d7..a65f1cf7 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -25,8 +25,9 @@ MOSTLYCLEANFILES = $(man_MANS) man3/*.3 *.xml ASCIIDOC_OPTS = \ -f asciidoc.conf \ - -apacman_version="$(PACKAGE_VERSION)" \ - -apacman_date="`date +%Y-%m-%d`" + -a pacman_version="$(PACKAGE_VERSION)" \ + -a pacman_date="`date +%Y-%m-%d`" \ + -a sysconfdir=$(sysconfdir) if HAS_DOXYGEN all: doxygen.in diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index 642f8884..3fa2f66b 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -6,6 +6,11 @@ Name PKGBUILD - Arch Linux package build description file +Synopsis +-------- +PKGBUILD + + Description ----------- This manual page is meant to describe general rules about PKGBUILDs. Once a diff --git a/doc/makepkg.conf.5.txt b/doc/makepkg.conf.5.txt index fd867f6b..d8a02726 100644 --- a/doc/makepkg.conf.5.txt +++ b/doc/makepkg.conf.5.txt @@ -6,6 +6,11 @@ Name makepkg.conf - makepkg configuration file +Synopsis +-------- +{sysconfdir}/makepkg.conf, ~/.makepkg.conf + + Description ----------- Configuration options for makekpg are stored in makepkg.conf. This file is diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt index 295c9b28..180b19c7 100644 --- a/doc/pacman.conf.5.txt +++ b/doc/pacman.conf.5.txt @@ -6,6 +6,11 @@ Name pacman.conf - pacman package manager configuration file +Synopsis +-------- +{sysconfdir}/pacman.conf + + Description ----------- Pacman, using manlink:libalpm[3], will attempt to read `pacman.conf` each From f1fac6abfb676b081ee2d474ab3e15f6d07d0416 Mon Sep 17 00:00:00 2001 From: Andrew Fyfe Date: Fri, 6 Jul 2007 16:30:53 +0100 Subject: [PATCH 09/14] Update PKGBUILD example. Signed-off-by: Andrew Fyfe --- doc/Makefile.am | 3 +++ doc/PKGBUILD-example.txt | 32 ++++++++++++++++++++++++++++++++ doc/PKGBUILD.5.txt | 32 +++----------------------------- 3 files changed, 38 insertions(+), 29 deletions(-) create mode 100644 doc/PKGBUILD-example.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index a65f1cf7..308f338b 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -14,6 +14,7 @@ EXTRA_DIST = \ pacman.8.txt \ makepkg.8.txt \ PKGBUILD.5.txt \ + PKGBUILD-example.txt \ makepkg.conf.5.txt \ pacman.conf.5.txt \ libalpm.3.txt \ @@ -39,4 +40,6 @@ endif $(man_MANS): footer.txt a2x -d manpage -f manpage --asciidoc-opts="$(ASCIIDOC_OPTS)" $@.txt +PKGBUILD.5: PKGBUILD-example.txt + # vim:set ts=2 sw=2 noet: diff --git a/doc/PKGBUILD-example.txt b/doc/PKGBUILD-example.txt new file mode 100644 index 00000000..50b652bd --- /dev/null +++ b/doc/PKGBUILD-example.txt @@ -0,0 +1,32 @@ +# $Id: PKGBUILD,v 1.16 2006/06/20 07:03:04 tpowa Exp $ +# Maintainer: judd +pkgname=module-init-tools +pkgver=3.2.2 +pkgrel=3 +pkgdesc="Utilities for inserting and removing modules from the Linux kernel" +arch=(i686 x86_64) +url="http://www.kernel.org" +license=('GPL') +depends=('glibc') +conflicts=('modutils') +replaces=('modutils') +backup=('etc/modprobe.conf' 'etc/modules.conf' 'etc/modprobe.devfs') +source=(http://www.kernel.org/pub/linux/utils/kernel/module-init-tools/module-init-tools-$pkgver.tar.bz2 \ + makefile.patch modprobe.conf) +md5sums=('a1ad0a09d3231673f70d631f3f5040e9' '47e14fda7a46668290d11d0444d81826'\ + '6db59d41e04941a790f80c1a4432faef') + +build() { + cd "$srcdir"/$pkgname-$pkgver + + patch -Np1 -i ../makefile.patch || return 1 + sed -i 's|/usr/bin/install|/bin/install|g' install-with-care + + ./configure --prefix=/usr --exec-prefix=/ + make || return 1 + + INSTALL=/bin/install make DESTDIR="$pkgdir" install + install -D -m644 ../modprobe.conf "$pkgdir"/etc/modprobe.conf +} + +# vim:set ts=2 sw=2 et: diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index 3fa2f66b..fbb7886c 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -54,7 +54,7 @@ Options and Directives found in /usr/share/licenses/common, then you should include the license in the package itself and set license=("custom") or license=("custom:LicenseName"). The license should be placed in - $startdir/pkg/usr/share/licenses/$pkgname when building the package. If + $pkgdir/usr/share/licenses/$pkgname when building the package. If multiple licenses are applicable for a package, list all of them: licenses=('GPL' 'FDL'). @@ -220,37 +220,11 @@ install file is available in the ABS tree (/var/abs/install.proto). Example ------- -The following is an example PKGBUILD for the 'modutils' package. For more +The following is an example PKGBUILD for the 'module-init-tools' package. For more examples, look through the ABS tree. ----- -# Maintainer: John Doe -# Contributor: Bill Smith -pkgname=modutils -pkgver=2.4.25 -pkgrel=1 -pkgdesc="Utilities for inserting modules in the linux kernel" -url="http://www.kernel.org" -makedepends=('bash' 'mawk') -depends=('glibc' 'zlib') -backup=(etc/modules.conf) -source=(ftp://ftp.kernel.org/pub/linux/utils/kernel/$pkgname/v2.4/$pkgname-$pkgver.tar.bz2 - modules.conf) -arch=('i686') -license=('GPL' 'custom') # dual licensed -md5sums=('2c0cca3ef6330a187c6ef4fe41ecaa4d' - '35175bee593a7cc7d6205584a94d8625') -options=(!libtool) - -build() { - cd $startdir/src/$pkgname-$pkgver - ./configure --prefix=/usr --enable-insmod-static - make || return 1 - make prefix=$startdir/pkg/usr install - mv $startdir/pkg/usr/sbin $startdir/pkg - mkdir -p $startdir/pkg/etc - cp ../modules.conf $startdir/pkg/etc -} +include::PKGBUILD-example.txt[] ----- From e412ac19f549afa26b58dbd2a2090ed95ca9cb95 Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Fri, 6 Jul 2007 16:54:18 -0400 Subject: [PATCH 10/14] Asciidoc updates- make it pretty, fix build, etc. * Fix up the target so we rebuild the manpages when we edit the corresponding text file. * Add vim modelines to all of the asciidoc files ensureing the right syntax highlighting is used and we have expandtabs turned off. * Start making a few small changes to PKGBUILD.5 to make it pretty in both HTML and manpage format output. * Fix the manlink macro to include the manpage section in the link. Signed-off-by: Dan McGee --- doc/Makefile.am | 15 ++++++++++++--- doc/PKGBUILD.5.txt | 25 ++++++++++++++----------- doc/asciidoc.conf | 2 +- doc/footer.txt | 3 +++ doc/libalpm.3.txt | 3 +++ doc/makepkg.8.txt | 3 +++ doc/makepkg.conf.5.txt | 3 +++ doc/pacman.8.txt | 3 +++ doc/pacman.conf.5.txt | 3 +++ 9 files changed, 45 insertions(+), 15 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index 308f338b..89f2a639 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -man_MANS = \ +ASCIIDOC_MANS = \ pacman.8 \ makepkg.8 \ PKGBUILD.5 \ @@ -6,6 +6,8 @@ man_MANS = \ pacman.conf.5 \ libalpm.3 +man_MANS = $(ASCIIDOC_MANS) + if HAS_DOXYGEN man_MANS += $(wildcard man3/*.3) endif @@ -37,9 +39,16 @@ doxygen.in: doxygen $(srcdir)/Doxyfile endif -$(man_MANS): footer.txt +$(ASCIIDOC_MANS): a2x -d manpage -f manpage --asciidoc-opts="$(ASCIIDOC_OPTS)" $@.txt -PKGBUILD.5: PKGBUILD-example.txt +# These rules are due to the includes and files of the asciidoc text +$(ASCIIDOC_MANS): footer.txt +pacman.8: pacman.8.txt +makepkg.8: makepkg.8.txt +PKGBUILD.5: PKGBUILD.5.txt PKGBUILD-example.txt +makepkg.conf.5: makepkg.conf.5.txt +pacman.conf.5: pacman.conf.5.txt +libalpm.3: libalpm.3.txt # vim:set ts=2 sw=2 noet: diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index fbb7886c..f9f50d17 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -1,3 +1,6 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// PKGBUILD(5) =========== @@ -30,7 +33,7 @@ Options and Directives used in the package filename. *pkgver*:: - The version of the software as released from the author (e.g. 2.7.1). + The version of the software as released from the author (e.g. `2.7.1`). *pkgrel*:: This is the release number specific to the Arch Linuxs release. This @@ -48,21 +51,21 @@ Options and Directives *license (array)*:: This field specifies the license(s) that apply to the package. - Commonly-used licenses are found in /usr/share/licenses/common. If you + Commonly-used licenses are found in `/usr/share/licenses/common`. If you see the package's license there, simply reference it in the license - field (e.g. license=("GPL")). If the package provides a license not - found in /usr/share/licenses/common, then you should include the license - 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 + field (e.g. `$$license=('GPL')$$`). If the package provides a license not + found in `/usr/share/licenses/common`, then you should include the license + in the package itself and set `$$license=('custom')$$` or + `$$license=('custom:LicenseName')$$`. The license should be placed in + `$pkgdir/usr/share/licenses/$pkgname` when building the package. If multiple licenses are applicable for a package, list all of them: - licenses=('GPL' 'FDL'). + `$$license=('GPL' 'FDL')$$`. *install*:: Specifies a special install script that is to be included in the package. This file should reside in the same directory as the PKGBUILD, and will be copied into the package by makepkg. It does not need to be included - in the source array (e.g. install=pkgname.install). + in the source array (e.g. `$$install=pkgname.install$$`). *source (array)*:: An array of source files required to build the package. Source files @@ -94,11 +97,11 @@ Options and Directives *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. + 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')). + `$$arch=('i686' 'x86_64')). *backup (array)*:: A space-delimited array of filenames, without preceding slashes, that diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf index 6b0747d6..92e01179 100644 --- a/doc/asciidoc.conf +++ b/doc/asciidoc.conf @@ -60,5 +60,5 @@ endif::doctype-manpage[] ifdef::backend-xhtml11[] [manlink-inlinemacro] -{target}{0?({0})} +{target}{0?({0})} endif::backend-xhtml11[] diff --git a/doc/footer.txt b/doc/footer.txt index 5f62a647..d1ee9d1e 100644 --- a/doc/footer.txt +++ b/doc/footer.txt @@ -1,3 +1,6 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// See the Arch Linux website at for more current information on the distribution and the pacman family of tools, and for diff --git a/doc/libalpm.3.txt b/doc/libalpm.3.txt index c9951311..27281fad 100644 --- a/doc/libalpm.3.txt +++ b/doc/libalpm.3.txt @@ -1,3 +1,6 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// libalpm(3) ========== diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt index 636d409f..622423c9 100644 --- a/doc/makepkg.8.txt +++ b/doc/makepkg.8.txt @@ -1,3 +1,6 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// makepkg(8) ========== diff --git a/doc/makepkg.conf.5.txt b/doc/makepkg.conf.5.txt index d8a02726..72b57c3e 100644 --- a/doc/makepkg.conf.5.txt +++ b/doc/makepkg.conf.5.txt @@ -1,3 +1,6 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// makepkg.conf(5) =============== diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt index 891be7dd..c0a16971 100644 --- a/doc/pacman.8.txt +++ b/doc/pacman.8.txt @@ -1,3 +1,6 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// pacman(8) ========= diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt index 180b19c7..ec04fcb2 100644 --- a/doc/pacman.conf.5.txt +++ b/doc/pacman.conf.5.txt @@ -1,3 +1,6 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// pacman.conf(5) ============== From cd5b38a4b0e8cfe634b31fc730bddbc373eb17ce Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Mon, 9 Jul 2007 14:22:01 -0400 Subject: [PATCH 11/14] Add a manpage for repo-add We still need some work here- we should have a repo-remove manpage link to this one, and we should not have to struggle with asciidoc formatting to get it to work like any other multiple-command manpage works. Signed-off-by: Dan McGee --- doc/.gitignore | 1 + doc/Makefile.am | 3 +++ doc/repo-add.8.txt | 51 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 55 insertions(+) create mode 100644 doc/repo-add.8.txt diff --git a/doc/.gitignore b/doc/.gitignore index c7de9a64..6fee5088 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -6,5 +6,6 @@ makepkg.8 makepkg.conf.5 pacman.8 pacman.conf.5 +repo-add.8 *.xml man3 diff --git a/doc/Makefile.am b/doc/Makefile.am index 89f2a639..f790f585 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,7 @@ ASCIIDOC_MANS = \ pacman.8 \ makepkg.8 \ + repo-add.8 \ PKGBUILD.5 \ makepkg.conf.5 \ pacman.conf.5 \ @@ -15,6 +16,7 @@ endif EXTRA_DIST = \ pacman.8.txt \ makepkg.8.txt \ + repo-add.8.txt \ PKGBUILD.5.txt \ PKGBUILD-example.txt \ makepkg.conf.5.txt \ @@ -46,6 +48,7 @@ $(ASCIIDOC_MANS): $(ASCIIDOC_MANS): footer.txt pacman.8: pacman.8.txt makepkg.8: makepkg.8.txt +repo-add.8: repo-add.8.txt PKGBUILD.5: PKGBUILD.5.txt PKGBUILD-example.txt makepkg.conf.5: makepkg.conf.5.txt pacman.conf.5: pacman.conf.5.txt diff --git a/doc/repo-add.8.txt b/doc/repo-add.8.txt new file mode 100644 index 00000000..27e0e93f --- /dev/null +++ b/doc/repo-add.8.txt @@ -0,0 +1,51 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +repo-add(8) +========== + +Name +---- +//// +* If we use this below line, the manpage name comes out all weird. We also +* can't use two separate lines, which is quite annoying. * +repo-add, repo-remove - package database maintenance utilities +//// +repo-add - package database maintenance utility + + +Synopsis +-------- +repo-add [--force] ... + +repo-remove ... + + +Description +----------- +repo-add and repo-remove are two scripts to help build a package database for +packages built with manlink:makepkg[8] and installed with manlink:pacman[8]. + +repo-add will update a package database by reading a built package file. +Multiple packages to add can be specified on the command line. + +repo-remove will update a package database by removing the package name +specified on the command line. Multiple packages to remove can be specified +on the command line. + + +Options +------- +*--force* (repo-add only):: + Add a force entry to the sync database, which tells pacman to skip version + number comparison and update the package regardless. This flag can be + specified in the middle of the command line, with any packages listed + before the flag being added as normal entries, and any specified after + being marked as force upgrades. + + +See Also +-------- +manlink:makepkg[8], manlink:pacman[8] + +include::footer.txt[] From d2613b97fa8173920ef7440cf291ca24a05b5b7c Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Mon, 9 Jul 2007 14:38:02 -0400 Subject: [PATCH 12/14] Add asciidoc checking to configure.ac, make manpage generation optional Include manpages when we ship a package tarball, and allow them to be generated by the end user if they want by using the --enable-asciidoc option to ./configure. This will allow us to maintain manpages in an easier to modify format while still keeping the make dependencies to a minimum. Signed-off-by: Dan McGee --- configure.ac | 27 +++++++++++++++++++++++++-- doc/Makefile.am | 29 ++++++++++++++++------------- 2 files changed, 41 insertions(+), 15 deletions(-) diff --git a/configure.ac b/configure.ac index 9a439346..17c85ad6 100644 --- a/configure.ac +++ b/configure.ac @@ -53,6 +53,11 @@ AC_ARG_ENABLE(doxygen, AC_HELP_STRING([--disable-doxygen], [do not build API docs via Doxygen]), [wantdoxygen=$enableval], [wantdoxygen=yes]) +# Help line for asciidoc +AC_ARG_ENABLE(asciidoc, + AC_HELP_STRING([--enable-asciidoc], [build your own manpages with Asciidoc]), + [wantasciidoc=$enableval], [wantasciidoc=no]) + # Help line for debug AC_ARG_ENABLE(debug, AC_HELP_STRING([--enable-debug], [enable debugging support]), @@ -177,7 +182,7 @@ AC_SUBST(CARCHFLAGS) AC_SUBST(ARCHSWITCH) AC_SUBST(CHOST) -# Check for doxygen support +# Check for doxygen support and status AC_MSG_CHECKING([for doxygen]) if test "x$wantdoxygen" = "xyes" ; then AC_CHECK_PROGS([DOXYGEN], [doxygen]) @@ -192,7 +197,24 @@ else AC_MSG_RESULT([no, disabled by configure]) usedoxygen=no fi -AM_CONDITIONAL(HAS_DOXYGEN, test "x$usedoxygen" = "xyes") +AM_CONDITIONAL(USE_DOXYGEN, test "x$usedoxygen" = "xyes") + +# Check for asciidoc support and status +AC_MSG_CHECKING([for asciidoc]) +if test "x$wantasciidoc" = "xyes" ; then + AC_CHECK_PROGS([ASCIIDOC], [asciidoc]) + if test $ASCIIDOC ; then + AC_MSG_RESULT([yes]) + useasciidoc=yes + else + AC_MSG_RESULT([no, asciidoc missing]) + useasciidoc=no + fi +else + AC_MSG_RESULT([no, disabled by configure]) + useasciidoc=no +fi +AM_CONDITIONAL(USE_ASCIIDOC, test "x$useasciidoc" = "xyes") # Enable or disable debug code AC_MSG_CHECKING(for debug mode request) @@ -276,6 +298,7 @@ $PACKAGE_STRING: Compilation options: Doxygen support : ${usedoxygen} + Asciidoc support : ${useasciidoc} debug support : ${debug} include abs : ${includeabs} " diff --git a/doc/Makefile.am b/doc/Makefile.am index f790f585..ad251287 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -7,12 +7,12 @@ ASCIIDOC_MANS = \ pacman.conf.5 \ libalpm.3 -man_MANS = $(ASCIIDOC_MANS) - -if HAS_DOXYGEN -man_MANS += $(wildcard man3/*.3) +if USE_DOXYGEN +DOXYGEN_MANS = $(wildcard man3/*.3) endif +man_MANS = $(ASCIIDOC_MANS) $(DOXYGEN_MANS) + EXTRA_DIST = \ pacman.8.txt \ makepkg.8.txt \ @@ -23,24 +23,26 @@ EXTRA_DIST = \ pacman.conf.5.txt \ libalpm.3.txt \ footer.txt \ - Doxyfile + Doxyfile \ + $(ASCIIDOC_MANS) # Files that should be removed, but which Automake does not know. -MOSTLYCLEANFILES = $(man_MANS) man3/*.3 *.xml +MOSTLYCLEANFILES = $(DOXYGEN_MANS) *.xml -ASCIIDOC_OPTS = \ - -f asciidoc.conf \ - -a pacman_version="$(PACKAGE_VERSION)" \ - -a pacman_date="`date +%Y-%m-%d`" \ - -a sysconfdir=$(sysconfdir) - -if HAS_DOXYGEN +if USE_DOXYGEN all: doxygen.in doxygen.in: doxygen $(srcdir)/Doxyfile endif +if USE_ASCIIDOC +ASCIIDOC_OPTS = \ + -f asciidoc.conf \ + -a pacman_version="$(PACKAGE_VERSION)" \ + -a pacman_date="`date +%Y-%m-%d`" \ + -a sysconfdir=$(sysconfdir) + $(ASCIIDOC_MANS): a2x -d manpage -f manpage --asciidoc-opts="$(ASCIIDOC_OPTS)" $@.txt @@ -53,5 +55,6 @@ PKGBUILD.5: PKGBUILD.5.txt PKGBUILD-example.txt makepkg.conf.5: makepkg.conf.5.txt pacman.conf.5: pacman.conf.5.txt libalpm.3: libalpm.3.txt +endif # vim:set ts=2 sw=2 noet: From c9189f54cd9e57a4d66124d14467848db9fcc8f1 Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Mon, 16 Jul 2007 12:57:02 -0400 Subject: [PATCH 13/14] Man page revision time Spruce up the asciidoc formatting, fix a few issues that we had. Formatting now looks pretty good in both the manpage output and the XHTML output. Also added some options that we have changed since 3.0, and a few wording updates, etc. Signed-off-by: Dan McGee --- doc/PKGBUILD.5.txt | 55 +++++++-------- doc/libalpm.3.txt | 18 ++--- doc/makepkg.8.txt | 66 +++++++++++------- doc/makepkg.conf.5.txt | 146 +++++++++++++++++++++------------------ doc/pacman.8.txt | 152 +++++++++++++++++++++-------------------- doc/pacman.conf.5.txt | 78 +++++++++++---------- 6 files changed, 278 insertions(+), 237 deletions(-) diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index f9f50d17..be3f1169 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -20,7 +20,7 @@ This manual page is meant to describe general rules about PKGBUILDs. Once a PKGBUILD is written, the actual package is built using makepkg and installed with pacman. -*NOTE:* If you have a local copy of the Arch Build System (ABS) tree on your +NOTE: If you have a local copy of the Arch Build System (ABS) tree on your computer, you can copy the PKGBUILD.proto file to your new package build directory and edit it from there. To acquire/sync the ABS tree, use the abs script included with pacman. @@ -33,14 +33,13 @@ Options and Directives used in the package filename. *pkgver*:: - The version of the software as released from the author (e.g. `2.7.1`). + The version of the software as released from the author (e.g. \'2.7.1'). *pkgrel*:: This is the release number specific to the Arch Linuxs release. This allows package maintainers to make updates to the package's configure flags, for example. - *pkgdesc*:: This should be a brief description of the package and its functionality. Try to keep the description to one line of text. @@ -51,13 +50,13 @@ Options and Directives *license (array)*:: This field specifies the license(s) that apply to the package. - Commonly-used licenses are found in `/usr/share/licenses/common`. If you + Commonly-used licenses are found in '/usr/share/licenses/common'. If you see the package's license there, simply reference it in the license field (e.g. `$$license=('GPL')$$`). If the package provides a license not - found in `/usr/share/licenses/common`, then you should include the license + found in '/usr/share/licenses/common', then you should include the license 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 + '$pkgdir/usr/share/licenses/$pkgname' when building the package. If multiple licenses are applicable for a package, list all of them: `$$license=('GPL' 'FDL')$$`. @@ -84,7 +83,7 @@ Options and Directives 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 + ``makepkg -g >> PKGBUILD''. If desired, move the md5sums line to an appropriate location. *NOTE:* makepkg supports multiple integrity algorithms and their corresponding arrays (i.e. sha1sums for the SHA1 algorithm); however, official packages use only md5sums for the time @@ -97,11 +96,11 @@ Options and Directives *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. + 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')). + `$$arch=('i686' 'x86_64')$$`). *backup (array)*:: A space-delimited array of filenames, without preceding slashes, that @@ -127,7 +126,7 @@ Options and Directives same format as depends, except you cannot specify versions. *provides (array)*:: - An array of "virtual provisions" that this package provides. This allows + An array of ``virtual provisions'' that 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'. @@ -136,50 +135,52 @@ Options and Directives An array of packages that this package should replace, and 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. + as expected even though the package has moved. Sysupgrade is currently + the only pacman operation that utilizes this field, a normal sync will + not use its value. *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 + 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 manlink:makepkg.conf[5]. - *NOTE:* 'force' is a special option only used in manlink:PKGBUILD[5]s, + *NOTE:* 'force' is a special option only used in a manlink:PKGBUILD[5], do not use it unless you know what you are doing. - *strip*:: + *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*:: + *docs*;; Save doc and info directories. If you wish to delete doc and - info directories, specify "!docs" in the array. + info directories, specify `!docs` in the array. - *libtool*:: - Leave libtool (.la) files in packages. Specify "!libtool" to + *libtool*;; + Leave libtool (.la) files in packages. Specify `!libtool` to remove them. - *emptydirs*:: + *emptydirs*;; Leave empty directories in packages. - *ccache*:: + *ccache*;; Allow the use of ccache during build. More useful in its negative - form "!ccache" with select packages that have problems building + form `!ccache` with select packages that have problems building with ccache. - *distcc*:: + *distcc*;; Allow the use of distcc during build. More useful in its negative - form "!distcc" with select packages that have problems building + form `!distcc` with select packages that have problems building with distcc. - *makeflags*:: + *makeflags*;; Allow the use of user-specific makeflags during build as specified in manlink: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). + `!makeflags` with select packages that have problems building with + custom makeflags such as `-j2` (or higher). - *force*:: + *force*;; Force the package to be upgraded by a pacman system upgrade operation, even if the version number would normally not trigger such an upgrade. This is useful when the version numbering scheme diff --git a/doc/libalpm.3.txt b/doc/libalpm.3.txt index 27281fad..d8fb58e8 100644 --- a/doc/libalpm.3.txt +++ b/doc/libalpm.3.txt @@ -16,20 +16,20 @@ 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 +*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 manlink:pacman.conf[5] for more details on configuring libalpm using the -pacman.conf file. +'pacman.conf' file. See Also diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt index 622423c9..02d29f32 100644 --- a/doc/makepkg.8.txt +++ b/doc/makepkg.8.txt @@ -25,91 +25,107 @@ 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. +customizations, generate meta-info, and package the whole thing up for pacman +to use. -makeworld can be used to rebuild an entire package group or the entire build tree. -See `makeworld --help` for syntax. +makeworld can be used to rebuild an entire package group or the entire build +tree. See `makeworld \--help` for syntax. Options ------- -*-b, --builddeps*:: +*-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. + +*-b, \--builddeps*:: Build missing dependencies from source. When makepkg finds missing build-time or run-time dependencies, it will look for the dependencies' PKGBUILD files under ABSROOT (set in makepkg.conf). If it finds them it will call makepkg to build and install the missing dependencies. The child calls will be made with the `-b` and `-i` options. -*-c, --clean*:: +*-c, \--clean*:: Clean up leftover work files and directories after a successful build. -*-C, --cleancache*:: +*-C, \--cleancache*:: Removes all cached source files from the directory specified in SRCDEST in manlink:makepkg.conf[5]. -*-d, --nodeps*:: +*-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*:: +*-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. -*-f, --force*:: +*-f, \--force*:: makepkg will not build a package if a built package already exists in the PKGDEST (set in manlink:makepkg.conf[5]) directory, which may default to the current directory. This allows the built package to be overwritten. -*-g, --geninteg*:: +*-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 value of the INTEGRITY_CHECK array in manlink:makepkg.conf[5]. This output can be redirected into your PKGBUILD for source validation (`makepkg -g >> PKGBUILD`). -*-h, --help*:: +*-h, \--help*:: Output syntax and command line options. -*-i, --install*:: - Install or upgrade the package after a successful build using pacman. +*-i, \--install*:: + Install or upgrade the package after a successful build using + manlink:pacman[8]. -*-m, --nocolor*:: +*-m, \--nocolor*:: Disable color in output messages. -*-o, --nobuild*:: +*-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 + `\--noextract` option if you wish to tweak the files in src/ before building. -*-p* <'buildscript'>:: - Read the package script buildscript instead of the default, +*-p* <`buildscript`>:: + Read the package script `buildscript` instead of the default, see manlink:PKGBUILD[5]. -*-r, --rmdeps*:: +*-r, \--rmdeps*:: Upon successful build, remove any dependencies installed by makepkg during dependency auto-resolution (using `-b` or `-s`). -*-R, --repackage*:: +*-R, \--repackage*:: Repackage contents of pkg/ without rebuilding the package. This is useful if you forgot a depend or install file in your PKGBUILD and the build itself will not change. -*-s, --syncdeps*:: +*-s, \--syncdeps*:: Install missing dependencies using pacman. When missing build-time or run-time dependencies are found, pacman will try to resolve them. If successful, the missing packages will be downloaded and installed. -*--noconfirm*:: +*\--asroot*:: + Allow makepkg to run as root. This is for security purposes as it is + normally dangerous to do so. This will also disable use of fakeroot and + sudo. + +*\--source*:: + Do not actually build the package, but build a source-only tarball. This + is useful for passing a single tarball to another program such as a + chroot, remote builder, or an AUR upload. + +*\--noconfirm*:: (Passed to pacman) Prevent pacman from waiting for user input before proceeding with operations. -*--noprogressbar*:: +*\--noprogressbar*:: (Passed to pacman) Prevent pacman from displaying a progress bar; useful if you are redirecting makepkg output to file. @@ -117,7 +133,7 @@ Options Configuration ------------- See manlink:makepkg.conf[5] for more details on configuring makepkg using the -makepkg.conf file. +'makepkg.conf' file. See Also diff --git a/doc/makepkg.conf.5.txt b/doc/makepkg.conf.5.txt index 72b57c3e..17e4bd87 100644 --- a/doc/makepkg.conf.5.txt +++ b/doc/makepkg.conf.5.txt @@ -19,123 +19,133 @@ Description Configuration options for makekpg are stored in makepkg.conf. This file is sourced, so you can include any special compiler flags you wish to use. This is helpful for building for different architectures, or with different -optimizations. +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... +NOTE: This does not guarantee that all package Makefiles will use your exported +variables. Some of them are non-standard. -The default file is fairly well commented, so it may be easiest to simply follow -directions given there for customization. +The default file is fairly well commented, so it may be easiest to simply +follow directions given there for customization. Options ------- -*FTPAGENT="*'/path/to/command [options]'*"*:: - Sets the download agent used to fetch source files specified with a URL - in the manlink:PKGBUILD[5] file. Flags can be specified as well; the - download URL is then placed on the end of the command. +**DLAGENTS=(**\'protocol::/path/to/command [options]' ...**)**:: + Sets the download agents used to fetch source files specified with a URL in + the manlink:PKGBUILD[5] file. Options can be specified for each command as + well; the download URL is placed on the end of the command. This is more + flexible than the former `FTPAGENT` variable, as any protocol can have a + download agent. Several examples are provided in the default makepkg.conf. -*CARCH="*'carch'*"*:: - Specifies your computer architecture; possible values include such - things as "i686", "x86_64", "ppc", etc. This should be automatically - set on installation. +**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 unless you know what - you are doing. +**CHOST=**"chost":: + 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. -*CFLAGS="*'cflags'*"*:: +**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. + 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'*"*:: +**CXXFLAGS=**"cxxflags":: Flags used for the C++ compiler; see CFLAGS for more info. -*MAKEFLAGS="*'makeflags'*"*:: - This is often used to set the number of jobs used, for example, "-j2". +**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. -*BUILDENV=(*'fakeroot !distcc color !ccache'*)*:: - This array contains four options that affect the build environment, the - defaults are shown here. All options should always be left in the array; - to enable or disable an option simply remove or place an "!" at the - front of the option. Each works as follows: +**BUILDENV=(**fakeroot !distcc color !ccache !xdelta**)**:: + This array contains options that affect the build environment, the defaults + are shown here. All options should always be left in the array; to enable + or disable an option simply remove or place an ``!'' at the front of the + option. Each works as follows: - *fakeroot*:: - Allow building packages as a non-root user. This is highly - recommended. + *fakeroot*;; + Allow building packages as a non-root user. This is highly recommended. - *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. + *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*:: + *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. + *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. -*DISTCC_HOSTS="*'host1' ...*"*:: + *xdelta*;; + Generate an xdelta binary patch from previous to current package. The + previous package must be available in the makepkg cache directory for + this to occur. + +**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. + `MAKEFLAGS`. -*OPTIONS=(*'strip !docs libtool emptydirs'*)*:: - This array contains four options that affect the default packaging. All - four 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 place an "!" at the front - of the option. Each works as follows: +**OPTIONS=(**strip !docs libtool emptydirs**)**:: + This array contains options that affect the default packaging. All four 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 place an ``!'' at the front of the + option. Each 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. + *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*:: + *docs*;; Save doc and info directories. If you wish to delete doc and info - directories, specify "!docs" in the array. + directories, specify `!docs' in the array. - *libtool*:: - Leave libtool (.la) files in packages. Specify "!libtool" to - remove them. + *libtool*;; + Leave libtool (.la) files in packages. Specify `!libtool' to remove + them. - *emptydirs*:: + *emptydirs*;; Leave empty directories in packages. -*INTEGRITY_CHECK=(*'check1' ...*)*:: +**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. + `md5`, `sha1`, `sha256`, `sha384`, and `sha512`. -*DOC_DIRS=(*'usr/{,share/}{info,doc}' ...*)*:: +**DOC_DIRS=(**usr/{,share/}{info,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. + array. *NOTE:* Do not add the leading slash to the directory name. -*PKGDEST=*'/path/to/folder':: +**PKGDEST=**"/path/to/folder":: If this value is not set, packages will by default be placed in the current directory (location of the manlink:PKGBUILD[5]). Many people like to keep all their packages in one place so this option allows - this behavior. A common location is "/home/packages". + this behavior. A common location is ``/home/packages''. -*SRCDEST=*'/path/to/folder':: +**SRCDEST=**"/path/to/folder":: 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. -*PACKAGER="*'John Doe '*"*:: +**PACKAGER=**"John Doe ":: 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. +*BUILDSCRIPT*, *PKGEXT*, *SRCEXT*, *DB_COMPRESSION*, *DB_CHECKSUMS*:: + Do not touch these unless you know what you are doing. + See Also -------- diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt index c0a16971..26bb0537 100644 --- a/doc/pacman.8.txt +++ b/doc/pacman.8.txt @@ -28,206 +28,212 @@ ends to be written (for instance, a GUI front end). Operations ---------- -*-A, --add* (deprecated):: +*-A, \--add* (deprecated):: Add a package to the system. Either a URL or file path can be specified. The package will be uncompressed into the installation root and the database will be updated. The package will not be installed if another - version is already installed. *NOTE*: please use `--upgrade` in place of + version is already installed. *NOTE*: please use '\--upgrade' in place of this option. -*-F, --freshen*:: - This is like `--upgrade` except it will only upgrade packages already +*-F, \--freshen*:: + This is like '\--upgrade' except it will only upgrade packages already installed on the system. -*-Q, --query*:: +*-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 `.tar.gz` packages. See <> below. + individual '.tar.gz' packages. See <> below. -*-R, --remove*:: +*-R, \--remove*:: Remove a package from the system. 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. + '\--nosave' option is used. See <> below. -*-S, --sync*:: +*-S, \--sync*:: Synchronize packages. Packages are installed directly from the ftp servers, 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. You can also use `pacman -Su` to upgrade all packages that are out of date. See <> below. -*-U, --upgrade*:: +*-U, \--upgrade*:: Upgrade or add a package to the system. Either a URL or file path can be - specified. This is a "remove-then-add" process. See - <> for an explanation on how - pacman takes care of config files. + specified. This is a "remove-then-add" process. See <> for an explanation on how pacman takes care of config files. -*-V, --version*:: +*-V, \--version*:: Display version and exit. -*-h, --help*:: +*-h, \--help*:: Display syntax for the given operation. If no operation was supplied then the general syntax is shown. Options ------- -*--ask* <'number'>:: +*\--asdeps*:: + Install packages non-explicitly; in other works, 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. + +*\--ask* <'number'>:: Pre-specify answers to questions. It is doubtful whether this option even works, so I would not recommend using it. *TODO*: document this more, as I have no idea how it works or when you would use it, or if we should just dump it. -*-b, --dbpath* <'path'>:: - Specify an alternative database location (default is `/var/lib/pacman`). +*-b, \--dbpath* <'path'>:: + Specify an alternative database location (default is ``/var/lib/pacman''). This should not be used unless you know what you are doing. -*-d, --nodeps*:: +*-d, \--nodeps*:: Skips all dependency checks. Normally, pacman will always check a package's dependency fields to ensure that all dependencies are installed and there are no package conflicts in the system. -*-f, --force*:: +*-f, \--force*:: Bypass file conflict checks and overwrite conflicting files. If the package that is about to be installed contains files that are already installed, this option will cause all those files to be overwritten. This option should be used with care, ideally not at all. -*-r, --root* <'path'>:: - Specify an alternative installation root (default is `/`). This should - not be used as a way to install software into `/usr/local` instead of - `/usr`. This option is used if you want to install a package on a - temporary mounted partition which is "owned" by another system. By using - this option you not only specify where the software should be installed, - but you also specify which package database and cache location to use. +*-r, \--root* <'path'>:: + Specify an alternative installation root (default is ``/''). This should + not be used as a way to install software into ``/usr/local'' instead of + ``/usr''. This option is used if you want to install a package on a + temporary mounted partition which is "owned" by another system. *-v, --verbose*:: - Output more status messages, such as the Root and DBPath. + Output more status messages, such as the Root, DBPath, CacheDir, etc. -*--cachedir* <'dir'>:: +*\--cachedir* <'dir'>:: Specify an alternative package cache location (default is - `/var/cache/pacman/pkg`). This should not be used unless you know what - you are doing. + ``/var/cache/pacman/pkg''). Multiple cache directories can be specified, + and they are tried in the order they are passed to pacman. -*--config* <'file'>:: +*\--config* <'file'>:: Specify an alternate configuration file. -*--noconfirm*:: +*\--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. -*--noprogressbar*:: +*\--noprogressbar*:: Do not show a progress bar when downloading files. This can be useful for scripts that call pacman and capture the output. -*--noscriptlet*:: +*\--noscriptlet*:: If an install scriptlet exists, do not execute it. Do not use this unless you know what you are doing. Query Options[[QO]] ------------------- -*-c, --changelog*:: +*-c, \--changelog*:: View the ChangeLog of a package. Not every package will provide one but it will be shown if available. -*-e, --orphans*:: +*-e, \--orphans*:: List all packages that were pulled in by a previously installed package but no longer required by any installed package. -*-g, --groups*:: +*-g, \--groups*:: Display all packages that are members of a named group. If not name is specified, list all grouped packages. -*-i, --info*:: - Display information on a given package. The `-p` option can be used if +*-i, \--info*:: + Display information on a given package. The '-p' option can be used if querying a package file instead of the local database. -*-l, --list*:: +*-l, \--list*:: List all files owned by a given package. Multiple packages can be specified on the command line. -*-m, --foreign*:: +*-m, \--foreign*:: List all packages that were not found in the sync database(s). Typically these are packages that were downloaded manually and installed with - `--upgrade`. + '\--upgrade'. -*-o, --owns* <'file'>:: +*-o, \--owns* <'file'>:: Search for the package that owns file. -*-p, --file*:: +*-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`. + This is useful in combination with '\--info' and '\--list'. -*-s, --search* <'regexp'>:: +*-s, \--search* <'regexp'>:: This will search each locally-installed package for names or - descriptions that matche regexp. + descriptions that match `regexp`. -*-u, --upgrades*:: +*-t, \--test*:: + Run some brief checks looking at the consistency of the local database. + +*-u, \--upgrades*:: Lists all packages that are out of date on the local system. This option - works best if the sync database is refreshed using `-Sy`. + works best if the sync database is refreshed using '-Sy'. Remove Options[[RO]] -------------------- -*-c, --cascade*:: +*-c, \--cascade*:: Remove all target packages, as well as all packages that depend on one or more target packages. This operation is recursive. -*-k, --keep*:: +*-k, \--keep*:: Removes the database entry only. Leaves all files in place. -*-n, --nosave*:: +*-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. + file should be renamed with a ``.pacsave'' extension. -*-s, --recursive*:: +*-s, \--recursive*:: Remove each target specified including all dependencies, provided that (A) they are not required by other packages; and (B) they were not explicitly installed by the user. This option is analogous to a - backwards `--sync` operation. + backwards '\--sync' operation. Sync Options[[SO]] ------------------ -*-c, --clean*:: +*-c, \--clean*:: Remove old packages from the cache to free up disk space. When pacman - downloads packages, it saves them in `/var/cache/pacman/pkg`. Use one - `--clean` switch to remove old packages; use two to remove all packages + downloads packages, it saves them in ``/var/cache/pacman/pkg''. Use one + '\--clean' switch to remove old packages; use two to remove all packages from the cache. -*-e, --dependsonly*:: +*-e, \--dependsonly*:: Install all dependencies of a package, but not the specified package itself. This is pretty useless and we're not sure why it even exists. -*-g, --groups*:: +*-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*:: +*-i, \--info*:: Display dependency and other information for a given package. This will search through all repositories for a matching package. -*-l, --list*:: +*-l, \--list*:: List all packages in the specified repositories. Multiple repositories can be specified on the command line. -*-p, --print-uris*:: +*-p, \--print-uris*:: Print out URIs for each package that will be installed, including any dependencies yet to be installed. These can be piped to a file and downloaded at a later time, using a program like wget. -*-s, --search* <'regexp'>:: +*-s, \--search* <'regexp'>:: This will search each package in the sync databases for names or - descriptions that match regexp. + descriptions that match `regexp`. -*-u, --sysupgrade*:: +*-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 @@ -235,17 +241,17 @@ Sync Options[[SO]] automatically resolved at this level and will be installed/upgraded if necessary. -*-w, --downloadonly*:: +*-w, \--downloadonly*:: Retrieve all packages from the server, but do not install/upgrade anything. -*-y, --refresh*:: +*-y, \--refresh*:: Download a fresh copy of the master package list from the server(s) defined in pacman.conf. This should typically be used each time you use - `--sysupgrade` or `-u`. Passing two `--refresh` or `-y` flags will force + '\--sysupgrade' or '-u'. Passing two '\--refresh' or '-y' flags will force a refresh of all package lists even if they are thought to be up to date. -*--ignore* <'package'>:: +*\--ignore* <'package'>:: Directs pacman to ignore upgrades of package even if there is one available. @@ -276,7 +282,7 @@ 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` + 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. @@ -284,7 +290,7 @@ original=X, current=Y, new=Z:: Configuration ------------- See manlink:pacman.conf[5] for more details on configuring pacman using the -`pacman.conf` file. +'pacman.conf' file. See Also diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt index ec04fcb2..d422a4b9 100644 --- a/doc/pacman.conf.5.txt +++ b/doc/pacman.conf.5.txt @@ -16,11 +16,11 @@ Synopsis Description ----------- -Pacman, using manlink: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. +Pacman, using manlink: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 @@ -43,32 +43,42 @@ Server = file:///home/pkgs Options ------- -*DBPath =* 'path/to/db/dir':: +*RootDir =* path/to/root:: + Set the default root directory for pacman to install to. + +*DBPath =* path/to/db/dir:: Overrides the default location of the toplevel database directory. - The default is `var/lib/pacman`. + The default is ``/var/lib/pacman/''. -*CacheDir =* 'path/to/cache/dir':: - Overrides the default location of the package cache directory. The - default is `var/cache/pacman`. +*CacheDir =* path/to/cache/dir:: + Overrides the default location of the package cache directory. The default + is ``/var/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. -*HoldPkg =* 'package' ...:: - If a user tries to `--remove` a package that's listed in `HoldPkg`, +*LogFile =* '/path/to/file':: + Log actions directly to a file. Default is ``/var/log/pacman.log''. + +*HoldPkg =* package ...:: + If a user tries to '\--remove' a package that's listed in `HoldPkg`, pacman will ask for confirmation before proceeding. -*IgnorePkg =* 'package' ...:: +*IgnorePkg =* package ...:: Instructs pacman to ignore any upgrades for this package when performing - a `--sysupgrade`. + a '\--sysupgrade'. -*Include =* 'path':: +*Include =* path:: Include another config file. This file can include repositories or general configuration options. -*XferCommand =* '/path/to/command %u':: +*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 + ``.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. @@ -76,27 +86,24 @@ Options *NoPassiveFtp*:: Disables passive ftp connections when downloading packages. (aka Active Mode) -*NoUpgrade =* 'file' ...:: +*NoUpgrade =* file ...:: All files listed with a `NoUpgrade` directive will never be touched during a package install/upgrade. Do not include the leading slash when specifying files. -*NoExtract =* 'file' ...:: +*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. + 'index.php', then you would not want the 'index.html' file to be extracted + from the 'apache' package. *UseSyslog*:: Log action messages through syslog(). This will insert log entries into - `/var/log/messages` or equivalent. - -*LogFile =* '/path/to/file':: - Log actions directly to a file. Default is `/var/log/pacman.log`. + ``/var/log/messages'' or equivalent. *ShowSize*:: - Display the size of individual packages for `--sync` and `--query` modes. + Display the size of individual packages for '\--sync' and '\--query' modes. Repository Sections @@ -104,32 +111,33 @@ 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 'current' and 'custom'). 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://` +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. The order of repositories in the file matters; repositories listed first will -take precedence over those listed later in the file when packages in two +take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number. Using Your Own Repository ------------------------- If you have numerous custom packages of your own, it is often easier to generate -your own custom local repository than install them all with the `--upgrade` +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`. +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.gz`, where `{treename}` is the name of the section defined in +'/home/pkgs/custom.db.tar.gz'. Note that the database must be of the form +'{treename}.db.tar.gz', where '{treename}' is the name of the section defined in the configuration file. That's it! Now configure your custom section in the configuration file as shown in the config example above. Pacman will now use your package repository. If you add new packages to the repository, remember to -re-generate the database and use pacman's `--refresh` option. +re-generate the database and use pacman's '\--refresh' option. -For more information on the repo-add command, use `repo-add --help`. +For more information on the repo-add command, see ``repo-add \--help'' or +manlink:repo-add[8]. See Also From f131ee9c56b99429374dfcce583872ad9259ed96 Mon Sep 17 00:00:00 2001 From: Chantry Xavier Date: Thu, 16 Aug 2007 13:41:57 +0200 Subject: [PATCH 14/14] Update manpage with new query options. Dan: did a bit more updating and clarifying. Signed-off-by: Chantry Xavier Signed-off-by: Dan McGee --- doc/pacman.8.txt | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt index 26bb0537..5e5d2f55 100644 --- a/doc/pacman.8.txt +++ b/doc/pacman.8.txt @@ -137,9 +137,17 @@ Query Options[[QO]] View the ChangeLog of a package. Not every package will provide one but it will be shown if available. -*-e, \--orphans*:: - List all packages that were pulled in by a previously installed package - but no longer required by any installed package. +*-d, \--deps*:: + List all 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. ('-Qdt' + is equivalent to the pacman 3.0.X '-Qe' option.) + +*-e, \--explicit*:: + List all packages explicitly installed. This option can be combined with + '-t' to list top-level packages- those packages that were explicitly + installed but are not required by any other package. ('-Qet' is equivalent + to the pacman 2.9.X '-Qe' option.) *-g, \--groups*:: Display all packages that are members of a named group. If not name is @@ -154,12 +162,13 @@ Query Options[[QO]] specified on the command line. *-m, \--foreign*:: - List all packages that were not found in the sync database(s). Typically - these are packages that were downloaded manually and installed with - '\--upgrade'. + 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'. *-o, \--owns* <'file'>:: - Search for the package that owns file. + Search for the package that owns file. The path can be relative or + absolute. *-p, \--file*:: Signifies that the package supplied on the command line is a file and @@ -170,13 +179,17 @@ Query Options[[QO]] This will search each locally-installed package for names or descriptions that match `regexp`. -*-t, \--test*:: - Run some brief checks looking at the consistency of the local database. +*-t, \--orphans*:: + Restrict or filter output to packages not required by any currently + installed package. *-u, \--upgrades*:: Lists all packages that are out of date on the local system. This option works best if the sync database is refreshed using '-Sy'. +*\--test*:: + Run some brief checks looking at the consistency of the local database. + Remove Options[[RO]] --------------------