summaryrefslogtreecommitdiff
path: root/doc/PKGBUILD.5.txt
diff options
context:
space:
mode:
authorDan McGee <dan@archlinux.org>2007-09-16 21:10:44 -0500
committerDan McGee <dan@archlinux.org>2007-09-16 21:10:44 -0500
commit708488f6fe8bf5e06ae724243381b40586301633 (patch)
tree83042c703173107def709f65d65697e233225441 /doc/PKGBUILD.5.txt
parentb0aa51059233849b0a7ef8d6a851750776ce6645 (diff)
parentf131ee9c56b99429374dfcce583872ad9259ed96 (diff)
downloadpacman-708488f6fe8bf5e06ae724243381b40586301633.tar.xz
Merge branch 'asciidoc' into working
We're getting close to release, so might as well do this now so people can actually update some of our documentation.
Diffstat (limited to 'doc/PKGBUILD.5.txt')
-rw-r--r--doc/PKGBUILD.5.txt239
1 files changed, 239 insertions, 0 deletions
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
new file mode 100644
index 00000000..be3f1169
--- /dev/null
+++ b/doc/PKGBUILD.5.txt
@@ -0,0 +1,239 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+PKGBUILD(5)
+===========
+
+Name
+----
+PKGBUILD - Arch Linux package build description file
+
+
+Synopsis
+--------
+PKGBUILD
+
+
+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
+ '$pkgdir/usr/share/licenses/$pkgname' when building the package. If
+ multiple licenses are applicable for a package, list all of them:
+ `$$license=('GPL' 'FDL')$$`.
+
+*install*::
+ Specifies a special install script that is to be included in the package.
+ This file should reside in the same directory as the PKGBUILD, and will
+ be copied into the package by makepkg. It does not need to be included
+ in the source array (e.g. `$$install=pkgname.install$$`).
+
+*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. 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
+ 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 a manlink:PKGBUILD[5],
+ 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 'module-init-tools' package. For more
+examples, look through the ABS tree.
+
+-----
+include::PKGBUILD-example.txt[]
+-----
+
+
+See Also
+--------
+manlink:makepkg[8], manlink:pacman[8], manlink:makepkg.conf[5]
+
+include::footer.txt[]