Date: Thursday, February 8, 2007 @ 22:44:55 Author: dan Path: /home/cvs-pacman/pacman-lib/doc Added: makepkg.conf.5 (1.1) Modified: PKGBUILD.5 (1.3 -> 1.4) libalpm.3 (1.3 -> 1.4) makepkg.8 (1.4 -> 1.5) pacman.8 (1.4 -> 1.5) pacman.conf.5 (1.1 -> 1.2) Another round of manpage updates. ----------------+ PKGBUILD.5 | 53 +++++++++++-------- libalpm.3 | 37 ++++++++++++- makepkg.8 | 15 ++--- makepkg.conf.5 | 146 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ pacman.8 | 6 +- pacman.conf.5 | 22 ++++---- 6 files changed, 234 insertions(+), 45 deletions(-) Index: pacman-lib/doc/PKGBUILD.5 diff -u pacman-lib/doc/PKGBUILD.5:1.3 pacman-lib/doc/PKGBUILD.5:1.4 --- pacman-lib/doc/PKGBUILD.5:1.3 Thu Feb 8 00:24:18 2007 +++ pacman-lib/doc/PKGBUILD.5 Thu Feb 8 22:44:54 2007 @@ -14,7 +14,7 @@ \fBNOTE:\fR 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\fR script included with pacman/makepkg. +the \fBabs\fR script included with \fBpacman\fP. .SS Quick \*(PB Explanation For an example of a \*(PB, see the \fBEXAMPLE\fR section. @@ -41,9 +41,9 @@ when removing or upgrading packages. See \fBHANDLING CONFIG FILES\fR in the \fIpacman\fR manpage for more information on this. -The \fIsource()\fR array tells makepkg which files to download or extract before -compiling begins. The \fImd5sums()\fR array provides md5sums for each of these -files. These are used to validate the integrity of the source files. +The \fIsource()\fR array tells \fBmakepkg\fP which files to download or extract +before compiling begins. The \fImd5sums()\fR array provides md5sums for each of +these files. These are used to validate the integrity of the source files. The \fIbuild\fR function is what actually does the work of putting the package together. Sometimes this is as simple as a configure, make, make install (to @@ -74,8 +74,8 @@ .B pkgdesc This should be a brief description of the package and its functionality. -." Not entirely applicable, and we can do this better anyway. pacman does -." actuall support localized descriptions, though, but i don't think makepkg does. +." Not entirely applicable, and we can do this better anyway. pacman does +." actuall support localized descriptions, though, but I don't think makepkg does. ." .TP ." .B pkgdesc_localized \fI(array)\fR ." Array of the localized package descriptions. The format is the following: @@ -100,9 +100,9 @@ .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 \*(PB, and will be -copied into the package by makepkg. It does not need to be included in the +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\fR array. (eg, install=pkgname.install) .TP @@ -121,16 +121,20 @@ .TP .B md5sums \fI(array)\fR If this field is present, it should contain an MD5 hash for every source file -specified in the \fIsource\fR array (in the same order). \fImakepkg\fR will use +specified in the \fIsource\fR array (in the same order). \fBmakepkg\fR will use this to verify source file integrity during subsequent builds. To easily -generate md5sums, first build using the \*(PB then run -\fBmakepkg -g >>\*(PB\fR. Then you can edit the \*(PB and move the -\fImd5sums\fR line from the bottom to an appropriate location. -\fBNOTE:\fR makepkg supports multiple integrity algorithms and their -corresponding arrays (i.e. sha1sums for the SHA1 algorithm), however official +generate md5sums, first build using the \*(PB then run "makepkg -g >> \*(PB". +Then edit the \*(PB and move the \fImd5sums\fR 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. +These are alternative integrity checks that \fBmakepkg\fP supports, as noted in +\fBmd5sums\fP above. + +.TP .B groups \fI(array)\fR This is an array of symbolic names that represent groups of packages, allowing you to install multiple packages by requesting a single target. For example, @@ -144,9 +148,9 @@ .B backup \fI(array)\fR A space-delimited array of filenames (without a preceding slash). The \fIbackup\fR line will be propagated to the package meta-info file for -pacman. This will designate all files listed there to be backed up if this -package is ever removed from a system. See \fBHANDLING CONFIG FILES\fR in -the \fIpacman\fR manpage for more information. +\fBpacman\fP. This will designate all files listed there to be backed up if +this package is ever removed from a system. See \fBHANDLING CONFIG FILES\fR in +the \fBpacman\fR manpage for more information. .TP .B depends \fI(array)\fR @@ -184,15 +188,18 @@ .TP .B options \fI(array)\fR -This array allows you to override some of makepkg's default behaviour +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\fR array. -See \fBmakepkg (8)\fR for details on the options array. +See +.BR makepkg (8) +for details on the options array. .SS 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. +\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: Index: pacman-lib/doc/libalpm.3 diff -u pacman-lib/doc/libalpm.3:1.3 pacman-lib/doc/libalpm.3:1.4 --- pacman-lib/doc/libalpm.3:1.3 Wed Feb 7 17:29:21 2007 +++ pacman-lib/doc/libalpm.3 Thu Feb 8 22:44:54 2007 @@ -1,9 +1,18 @@ -.TH libalpm 3 "07 Jan 2007" "libalpm @PM_VERSION@" "" +." 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 library + 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 @@ -15,7 +24,29 @@ alpm_trans Transaction Functions .fi -.SH AUTHOR +.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 +<pacman-dev@archlinux.org>. + +.SH SEE ALSO +.BR pacman (8), +.BR makepkg (8), +.BR pacman.conf (5) + +See the Arch Linux website at <http://www.archlinux.org> for more current +information on the distribution and the \fBpacman\fP family of tools. + +.SH AUTHORS .nf Judd Vinet <jvinet@zeroflux.org> +Aurelien Foret <aurelien@archlinux.org> +Aaron Griffin <aaron@archlinux.org> +Dan McGee <dan@archlinux.org> +See the 'AUTHORS' file for additional contributors. .fi Index: pacman-lib/doc/makepkg.8 diff -u pacman-lib/doc/makepkg.8:1.4 pacman-lib/doc/makepkg.8:1.5 --- pacman-lib/doc/makepkg.8:1.4 Thu Feb 8 00:24:18 2007 +++ pacman-lib/doc/makepkg.8 Thu Feb 8 22:44:54 2007 @@ -115,15 +115,14 @@ useful if you are redirecting makepkg output to file. .SH CONFIGURATION -Configuration options 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. +See +.BR makepkg.conf (5) +for more details on configuring \fBmakepkg\fP using the \fBmakepkg.conf\fP file. -\fBNOTE:\fP This does not guarantee that all package Makefiles will use your -exported variables. Some of them are non-standard... - -The file is fairly well commented, so follow directions given there for -customization. +.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 +<pacman-dev@archlinux.org>. .SH SEE ALSO .BR makepkg.conf (5), Index: pacman-lib/doc/makepkg.conf.5 diff -u /dev/null pacman-lib/doc/makepkg.conf.5:1.1 --- /dev/null Thu Feb 8 22:44:55 2007 +++ pacman-lib/doc/makepkg.conf.5 Thu Feb 8 22:44:54 2007 @@ -0,0 +1,146 @@ +." 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) +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: +.RS +.TP +fakeroot +Allow building packages as a non-root user. This is \fIhighly\fP recommended. +.TP +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 +color +Colorize output messages, making output easier to read. +.TP +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 passing the \fB-B\fP or \fB--noccache\fP flag to +\fBmakepkg\fP. +.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 +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 +docs +Save doc and info directories. If you wish to delete doc and info directories, +specify "!docs" in the array. +.TP +libtool +Leave libtool (.la) files in packages. Specify "!libtool" to remove them. +.TP +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 <john@doe.com>\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 <http://www.archlinux.org> for more current +information on the distribution and the \fBpacman\fP family of tools, and +<http://wiki.archlinux.org/index.php/Arch_Packaging_Standards> for +recommendations on packaging standards. + +.SH AUTHORS +.nf +Judd Vinet <jvinet@zeroflux.org> +Aurelien Foret <aurelien@archlinux.org> +Aaron Griffin <aaron@archlinux.org> +Dan McGee <dan@archlinux.org> +See the 'AUTHORS' file for additional contributors. +.fi Index: pacman-lib/doc/pacman.8 diff -u pacman-lib/doc/pacman.8:1.4 pacman-lib/doc/pacman.8:1.5 --- pacman-lib/doc/pacman.8:1.4 Thu Feb 8 00:24:18 2007 +++ pacman-lib/doc/pacman.8 Thu Feb 8 22:44:54 2007 @@ -2,6 +2,7 @@ .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 @@ -131,7 +132,8 @@ matche \fIregexp\fP. .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. +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 @@ -233,7 +235,7 @@ .SH CONFIGURATION See .BR pacman.conf (5) -for more details on configuring pacman using the \fBpacman.conf\fP file. +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 Index: pacman-lib/doc/pacman.conf.5 diff -u pacman-lib/doc/pacman.conf.5:1.1 pacman-lib/doc/pacman.conf.5:1.2 --- pacman-lib/doc/pacman.conf.5:1.1 Thu Feb 8 00:24:18 2007 +++ pacman-lib/doc/pacman.conf.5 Thu Feb 8 22:44:54 2007 @@ -2,17 +2,17 @@ .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 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. +\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 @@ -34,11 +34,11 @@ .SH OPTIONS .TP -.B DBPath = path/to/db/dir +.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 = path/to/cache/dir +.B CacheDir = \fIpath/to/cache/dir\fP Overrides the default location of the package cache directory. The default is \fIvar/cache/pacman\fP. .TP @@ -102,7 +102,11 @@ 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. +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