Swapped out PKGBUILD.8 for PKGBUILD.5 from Dan McGee - original PKGBUILD.8 had too many Frugal specific changes.

1 files changed, 286 insertions, 0 deletions

diff --git a/doc/PKGBUILD.5 b/doc/PKGBUILD.5
new file mode 100644
index 00000000..e7cc55d9
--- /dev/null
+++ b/doc/PKGBUILD.5
@@ -0,0 +1,286 @@
+." 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 PKGBUILD 5 "Feb 06, 2007" "PKGBUILD version \*(VR" "\*(DS Files"
+.SH NAME
+PKGBUILD \- \*(DS package build description file
+.SH DESCRIPTION
+This manual page is meant to describe general rules about PKGBUILDs. Once
+a PKGBUILD is written, the actual package is built using \fBmakepkg\fR and 
+installed with \fBpacman\fR.
+
+\fBNOTE:\fR 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 \fBabs\fR script included with pacman/makepkg.
+
+.SS Quick PKGBUILD Explanation
+For an example of a PKGBUILD, see the \fBEXAMPLE\fR section.
+
+\fIpkgname\fR defines the package name. It should not contain any uppercase
+letters. \fIpkgversion\fR defines the actual package version as given by the
+developers of the package. No dashes are allowed. \fIpkgrel\fR allows for
+\*(DS-specific changes to the package or corrections to a PKGBUILD
+without an upstream version change. The value should be an integer.
+\fIpkgdesc\fR is a short one-line description for the package, usually taken
+from the project's homepage or manpage. It is preferable to keep the length to
+one line for displaying during searches. These four variables are required in
+every PKGBUILD. \fIurl\fR is also highly recommended so users can find more
+information on the package if needed.
+
+\fIdepends\fR and \fImakedepends\fR are bash arrays which define the
+dependencies of the package. Packages listed in \fImakedepends\fR are required
+only for building the package, and not for runtime. \fIdepends\fR is used to
+list runtime depends. To build the package using \fBmakepkg\fR, ALL dependencies
+must be satisfied. For \fBpacman\fR to install the package, all runtime depends
+must be satisfied.
+
+The \fIbackup\fR array specifies files that should be treated specially
+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 \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
+$startdir/pkg). However, some customizations are often needed during the build
+process.
+
+Once your PKGBUILD is created, you can run \fBmakepkg\fR from the build
+directory. \fBmakepkg\fR will check dependencies and look for the source files
+required to build.  If some are missing it will attempt to download them,
+provided there is a fully-qualified URL in the \fIsource()\fR 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.
+
+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, just create a file (eg, pkgname.install) and put it in
+the same directory as the PKGBUILD script.  Then use the \fIinstall\fR
+directive:
+
+install=pkgname.install
+
+The install script does not need to be specified in the \fIsource\fR array.
+A template install file is  available in your ABS tree (/var/abs/install.proto).
+
+.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
+This is the version of the software as released from the author (eg, 2.7.1).
+
+.TP
+.B pkgrel
+This is the release number specific to \*(DS's 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.
+
+." Is this applicable below?
+.TP
+.B pkgdesc_localized \fI(array)\fR
+Array of the localized package descriptions. The format is the following:
+pkgdesc_localized=('xx_YY foo' 'xx_YY bar')
+
+.TP
+.B url
+This field contains an optional URL that is associated with the piece of 
+software being packaged. This is typically the project's website.
+
+.TP
+.B license \fI(array)\fR
+This field specifies the license(s) that apply to the package. Commonly-used
+licenses are typically found in \fI/usr/share/licenses/common\fR. If you
+see the package's license there, simply reference it in the license field
+(eg, \fBlicense="GPL"\fR). If the package provides a license not found in
+\fI/usr/share/licenses/common\fR, then you should include the license in
+the package itself and set \fBlicense="custom"\fR or 
+\fBlicense="custom:LicenseName"\fR. The license itself should be placed in a
+directory called \fI$startdir/pkg/usr/share/licenses/$pkgname\fR. If multiple
+licenses are applied, use the array form: \fBlicenses=('GPL' 'FDL')\fR
+
+.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 PKGBUILD, and will be
+copied into the package by makepkg. It does not need to be included in the
+\fIsource\fR array. (eg, install=pkgname.install)
+
+." Is this applicable below?
+.TP
+.B up2date
+This directive should contain a command that prints the current upstream stable
+version of the project.
+
+.TP
+.B source \fI(array)\fR
+The \fIsource\fR line is an array of source files required to build the
+package. Source files must reside in the same directory as the PKGBUILD
+file, unless they have a fully-qualified URL. 
+
+.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
+this to verify source file integrity during subsequent builds. To easily
+generate md5sums, first build using the PKGBUILD then run
+\fBmakepkg -g >>PKGBUILD\fR. Then you can edit the PKGBUILD and move the
+\fImd5sums\fR line from the bottom to an appropriate location.
+
+." Is this applicable below?
+.TP
+.B signatures \fI(array)\fR
+If this field is present, it should contain an array of gpg signatures required
+to validate the source files. Where there is no signature available just leave
+it empty, like:
+
+signatures=(${source[0]}.asc '')
+
+.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,
+one could install all KDE packages by installing the 'kde' group.
+
+.TP
+.B archs \fI(array)\fR
+This array defines on which architectures the given package is available.
+
+.TP
+.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.
+
+.TP
+.B depends \fI(array)\fR 
+An array of packages that this package depends on to build and run. Packages
+in this list should be surrounded with single quotes and contain at least the
+package name. They can also include a version requirement of the form
+\fBname<>version\fR, where <> is one of these three comparisons:
+\fB>=\fR (greater than equal to), \fB<=\fR (less than or equal to), or 
+\fB=\fR (equal to).
+
+.TP
+.B makedepends \fI(array)\fR
+An array of packages that this package depends on to build, but not at runtime.
+Packages in this list should follow the same format as \fIdepends\fR.
+
+.TP
+.B conflicts \fI(array)\fR 
+An array of packages that will conflict with this package (ie, they cannot both
+be installed at the same time). This directive follows the same format as
+\fIdepends\fR except you cannot specify versions.
+
+.TP
+.B provides \fI(array)\fR 
+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 kernel26beyond package can each provide 'kernel26' which allows packages
+to simply depend on 'kernel26' rather than "kernel26 OR kernel26beyond".
+
+.TP
+.B replaces \fI(array)\fR 
+This is an array of packages that this package should replace, and can be used
+to handle renamed/combined packages. For example, if the j2re package gets
+renamed to jre, then subsequent 'pacman -Syu' calls will not pick up the
+upgrade, due to the differing package names. \fIreplaces\fR handles this.
+
+.TP
+.B options \fI(array)\fR
+This array allows you to override some of makepkg's default behaviour
+when building packages. To set an option, just include the option name
+in the \fBoptions\fR array.
+.RS
+.TP
+.B nostrip
+don't strip binaries/libraries.
+.TP
+.B keepdocs
+keep /usr/share/doc and /usr/share/info directories.
+.TP
+.B force
+force the package to be upgraded by --sysupgrade, even if it's an older version.
+.RE
+
+.SH EXAMPLE
+The following is an example PKGBUILD for the 'modutils' package. For more
+examples, look through the ABS tree.
+
+.nf
+# Maintainer: John Doe <johndoe@archlinux.org>
+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)
+md5sums=('2c0cca3ef6330a187c6ef4fe41ecaa4d' \\
+         '35175bee593a7cc7d6205584a94d8625')
+
+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)
+
+See the Arch Linux website at <http://www.archlinux.org> for more current
+information on the distribution, and 
+<http://wiki.archlinux.org/index.php/Arch_Packaging_Standards> for
+recommendations on packaging standards.
+.SH AUTHORS
+Judd Vinet <jvinet@zeroflux.org>
+and the Frugalware developers <frugalware-devel@frugalware.org>