Ensure better text editor automatic filetype detection

Since we no longer use vim-specific modelines, use the .asciidoc file
extension which is, well, reserved for asciidoc formatted files. This
should presumably work everywhere without needing editor-specific
workarounds and configuration.

Also add a shebang to makepkg.conf to indicate it contains bash content.

Signed-off-by: Eli Schwartz <eschwartz@archlinux.org>
Signed-off-by: Allan McRae <allan@archlinux.org>

1 files changed, 525 insertions, 0 deletions

diff --git a/doc/PKGBUILD.5.asciidoc b/doc/PKGBUILD.5.asciidoc
new file mode 100644
index 00000000..9634bd15
--- /dev/null
+++ b/doc/PKGBUILD.5.asciidoc
@@ -0,0 +1,525 @@
+PKGBUILD(5)
+===========
+
+Name
+----
+PKGBUILD - Arch Linux package build description file
+
+
+Synopsis
+--------
+PKGBUILD
+
+
+Description
+-----------
+This manual page describes general rules about PKGBUILDs. Once a
+PKGBUILD is written, the actual package is built using makepkg and installed
+with pacman.
+
+NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'
+along with other example files such as a ChangeLog and an install
+script. You can copy the provided PKGBUILD.proto file to a new package build
+directory and make customizations to suit your needs.
+
+
+Options and Directives
+----------------------
+The following is a list of standard options and directives available for use
+in a PKGBUILD. These are all understood and interpreted by makepkg, and most
+of them will be directly transferred to the built package. The mandatory
+fields for a minimally functional PKGBUILD are *pkgname*, *pkgver*, *pkgrel*
+and *arch*.
+
+If you need to create any custom variables for use in your build process, it is
+recommended to prefix their name with an '_' (underscore).
+This will prevent any possible name clashes with internal makepkg variables.
+For example, to store the base kernel version in a variable, use something
+similar to `$_basekernver`.
+
+*pkgname (array)*::
+	Either the name of the package or an array of names for split packages.
+	Valid characters for members of this array are alphanumerics, and any of
+	the following characters: ```@ . _ + -`''. Additionally, names are not
+	allowed to start with hyphens or dots.
+
+*pkgver*::
+	The version of the software as released from the author (e.g., '2.7.1').
+	The variable is not allowed to contain colons, forward slashes, hyphens
+	or whitespace.
++
+The `pkgver` variable can be automatically updated by providing a `pkgver()`
+function in the PKGBUILD that outputs the new package version.
+This is run after downloading and extracting the sources and running the
+`prepare()` function (if present), so it can use those files in determining the
+new `pkgver`.  This is most useful when used with sources from version control
+systems (see below).
+
+*pkgrel*::
+	This is the release number specific to the Arch Linux release. This
+	allows package maintainers to make updates to the package's configure
+	flags, for example. This is typically set to '1' for each new upstream
+	software release and incremented for intermediate PKGBUILD updates. The
+	variable is not allowed to contain hyphens.
+
+*epoch*::
+	Used to force the package to be seen as newer than any previous versions
+	with a lower epoch, even if the version number would normally not trigger
+	such an upgrade. This value is required to be a positive integer; the
+	default value if left unspecified is '0'. This is useful when the version
+	numbering scheme of a package changes (or is alphanumeric), breaking normal
+	version comparison logic. See linkman:pacman[8] for more information on
+	version comparisons.
+
+*pkgdesc*::
+	This should be a brief description of the package and its functionality.
+	Try to keep the description to one line of text and to not use the package's
+	name.
+
+*url*::
+	This field contains a URL that is associated with the software being
+	packaged. This is typically the project's web site.
+
+*license (array)*::
+	This field specifies the license(s) that apply to the package.
+	Commonly used licenses can be 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
+	available in '/usr/share/licenses/common', then you should include it
+	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, 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`).
+
+*changelog*::
+	Specifies a changelog file that is to be included in the package.
+	The changelog file should end in a single newline.
+	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., `changelog=$pkgname.changelog`).
+
+*source (array)*::
+	An array of source files required to build the package. Source files
+	must either reside in the same directory as the PKGBUILD, or be a
+	fully-qualified URL that makepkg can use to download the file.
+	To simplify the maintenance of PKGBUILDs, use the `$pkgname` and `$pkgver`
+	variables when specifying the download location, if possible.
+	Compressed files will be extracted automatically unless found in the
+	noextract array described below.
++
+Additional architecture-specific sources can be added by appending an
+underscore and the architecture name e.g., 'source_x86_64=()'. There must be a
+corresponding integrity array with checksums, e.g. 'md5sums_x86_64=()'.
++
+It is also possible to change the name of the downloaded file, which is helpful
+with weird URLs and for handling multiple source files with the same
+name. The syntax is: `source=('filename::url')`.
++
+makepkg also supports building developmental versions of packages using sources
+downloaded from version control systems (VCS). For more information, see
+<<VCS,Using VCS Sources>> below.
++
+Files in the source array with extensions `.sig`, `.sign` or, `.asc` are
+recognized by makepkg as PGP signatures and will be automatically used to verify
+the integrity of the corresponding source file.
+
+*validpgpkeys (array)*::
+	An array of PGP fingerprints. If this array is non-empty, makepkg will
+	only accept signatures from the keys listed here and will ignore the
+	trust values from the keyring. If the source file was signed with a
+	subkey, makepkg will still use the primary key for comparison.
++
+Only full fingerprints are accepted. They must be uppercase and must not
+contain whitespace characters.
+
+*noextract (array)*::
+	An array of file names 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 that use compressed data directly.
+
+*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. If 'SKIP' is put in the array
+	in place of a normal hash, the integrity check for that source file will
+	be skipped. To easily generate md5sums, run ``makepkg -g >> PKGBUILD''.
+	If desired, move the md5sums line to an appropriate location.
+
+*sha1sums, sha256sums, sha384sums, sha512sums (arrays)*::
+	Alternative integrity checks that makepkg supports; these all behave
+	similar to the md5sums option described above. To enable use and generation
+	of these checksums, be sure to set up the `INTEGRITY_CHECK` option in
+	linkman:makepkg.conf[5].
+
+*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')`). Packages that contain no architecture specific
+	files should use `arch=('any')`. Valid characters for members of this array
+	are alphanumerics and ```_`''.
+
+*backup (array)*::
+	An array of file names, 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 linkman:pacman[8] for more information.
+
+*depends (array)*::
+	An array of packages this package depends on to run. Entries 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 five comparisons: `>=` (greater
+	than or equal to), `<=` (less than or equal to), `=` (equal to), `>`
+	(greater than), or `<` (less than).
++
+If the dependency name appears to be a library (ends with .so), makepkg will
+try to find a binary that depends on the library in the built package and
+append the version needed by the binary. Appending the version yourself
+disables automatic detection.
++
+Additional architecture-specific depends can be added by appending an
+underscore and the architecture name e.g., 'depends_x86_64=()'.
+
+*makedepends (array)*::
+	An array of packages this package depends on to build but are not
+	needed at runtime. Packages in this list follow the same format as
+	depends.
++
+Additional architecture-specific makedepends can be added by appending an
+underscore and the architecture name e.g., 'makedepends_x86_64=()'.
+
+*checkdepends (array)*::
+	An array of packages this package depends on to run its test suite
+	but are not needed at runtime. Packages in this list follow the same
+	format as depends. These dependencies are only considered when the
+	check() function is present and is to be run by makepkg.
++
+Additional architecture-specific checkdepends can be added by appending an
+underscore and the architecture name e.g., 'checkdepends_x86_64=()'.
+
+*optdepends (array)*::
+	An array of packages (and accompanying reasons) that are not essential for
+	base functionality, but may be necessary to make full use of the contents
+	of this package. optdepends are currently for informational purposes only
+	and are not utilized by pacman during dependency resolution. The format
+	for specifying optdepends is:
+
+	optdepends=('python: for library bindings')
++
+Additional architecture-specific optdepends can be added by appending an
+underscore and the architecture name e.g., 'optdepends_x86_64=()'.
+
+*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. Versioned conflicts are supported using the
+	operators as described in `depends`.
++
+Additional architecture-specific conflicts can be added by appending an
+underscore and the architecture name e.g., 'conflicts_x86_64=()'.
+
+*provides (array)*::
+	An array of ``virtual provisions'' 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'.
++
+Versioned provisions are also possible, in the 'name=version' format. For
+example, dcron can provide 'cron=2.0' to satisfy the 'cron>=2.0' dependency of
+other packages. Provisions involving the `>` and `<` operators are invalid as
+only specific versions of a package may be provided.
++
+If the provision name appears to be a library (ends with .so), makepkg will
+try to find the library in the built package and append the correct
+version. Appending the version yourself disables automatic detection.
++
+Additional architecture-specific provides can be added by appending an
+underscore and the architecture name e.g., 'provides_x86_64=()'.
+
+*replaces (array)*::
+	An array of packages this package should replace. This 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. Versioned replaces are
+	supported using the operators as described in `depends`.
++
+Sysupgrade is currently the only pacman operation that utilizes this field.
+A normal sync or upgrade will not use its value.
++
+Additional architecture-specific replaces can be added by appending an
+underscore and the architecture name e.g., 'replaces_x86_64=()'.
+
+*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 linkman:makepkg.conf[5].
+	*NOTE:* 'force' is a now-removed option in favor of the top level 'epoch'
+	variable.
+
+	*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 directories. If you wish to delete doc directories,
+		specify `!docs` in the array.
+
+	*libtool*;;
+		Leave libtool (.la) files in packages. Specify `!libtool` to
+		remove them.
+
+	*staticlibs*;;
+		Leave static library (.a) files in packages. Specify `!staticlibs` to
+		remove them (if they have a shared counterpart).
+
+	*emptydirs*;;
+		Leave empty directories in packages.
+
+	*zipman*;;
+		Compress man and info pages with gzip.
+
+	*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.
+
+	*buildflags*;;
+		Allow the use of user-specific buildflags (CPPFLAGS, CFLAGS, CXXFLAGS,
+		LDFLAGS) during build as specified in linkman:makepkg.conf[5]. More
+		useful in its negative form `!buildflags` with select packages that
+		have problems building with custom buildflags.
+
+	*makeflags*;;
+		Allow the use of user-specific makeflags during build as specified
+		in linkman: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).
+
+	*debug*;;
+		Add the user-specified debug flags (DEBUG_CFLAGS, DEBUG_CXXFLAGS) to
+		their counterpart buildflags as specified in linkman:makepkg.conf[5].
+		When used in combination with the `strip' option, a separate package
+		containing the debug symbols is created.
+
+
+Packaging Functions
+-------------------
+In addition to the above directives, PKGBUILDs require a set of functions that
+provide instructions to build and install the package. As a minimum, the
+PKGBUILD must contain a `package()` function which installs all the package's
+files into the packaging directory, with optional `prepare()`, `build()`, and
+`check()` functions being used to create those files from source.
+
+*package() Function*::
+	The `package()` function is used to install files into the directory that
+	will become the root directory of the built package and is run after all
+	the optional functions listed below. The packaging stage is run using
+	fakeroot to ensure correct file permissions in the resulting package.
+	All other functions will be run as the user calling makepkg.
+
+*prepare() Function*::
+	An optional `prepare()` function can be specified in which operations to
+	prepare the sources for building, such as patching, are performed. This
+	function is run after the source extraction and before the `build()`
+	function. The `prepare()` function is skipped when source extraction
+	is skipped.
+
+*build() Function*::
+	The optional `build()` function is use to compile and/or adjust the source
+	files in preparation to be installed by the `package()` function. This is
+	directly sourced and executed by makepkg, so anything that Bash or the
+	system has available is available for use here. Be sure any exotic
+	commands used are covered by the `makedepends` array.
++
+If you create any variables of your own in the `build()` function, it is
+recommended to use the Bash `local` keyword to scope the variable to inside
+the `build()` function.
+
+*check() Function*::
+	An optional `check()` function can be specified in which a package's
+	test-suite may be run. This function is run between the `build()` and
+	`package()` functions. Be sure any exotic commands used are covered by the
+	`checkdepends` array.
+
+All of the above variables such as `$pkgname` and `$pkgver` are available for
+use in the packaging functions. In addition, makepkg defines the following
+variables:
+
+*srcdir*::
+	This contains the directory where makepkg extracts, or copies, all source
+	files.
++
+All of the packaging functions defined above are run starting inside `$srcdir`
+
+*pkgdir*::
+	This contains the directory where makepkg bundles the installed package.
+	This directory will become the root directory of your built package. This
+	variable should only be used in the `package()` function.
+
+*startdir*::
+	This contains the absolute path to the directory where the PKGBUILD is
+	located, which is usually the output of `$(pwd)` when makepkg is started.
+	Use of this variable is deprecated and strongly discouraged.
+
+
+Package Splitting
+-----------------
+makepkg supports building multiple packages from a single PKGBUILD. This is
+achieved by assigning an array of package names to the `pkgname` directive.
+Each split package uses a corresponding packaging function with name
+`package_foo()`, where `foo` is the name of the split package.
+
+All options and directives for the split packages default to the global values
+given in the PKGBUILD. Nevertheless, the following ones can be overridden within
+each split package's packaging function:
+`pkgdesc`, `arch`, `url`, `license`, `groups`, `depends`, `optdepends`,
+`provides`, `conflicts`, `replaces`, `backup`, `options`, `install`, and
+`changelog`.
+
+Note that makepkg does not consider split package `depends` when checking
+if dependencies are installed before package building and with `--syncdeps`.
+All packages required to make the package are required to be specified in
+the global `depends` and `makedepends` arrays.
+
+An optional global directive is available when building a split package:
+
+*pkgbase*::
+	The name used to refer to the group of packages in the output of makepkg
+	and in the naming of source-only tarballs. If not specified, the first
+	element in the `pkgname` array is used. Valid characters for this
+	variable are alphanumerics, and any of the following characters:
+	```@ . _ + -`''. Additionally, the variable is not allowed to start with
+	hyphens or dots.
+
+
+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 perform an opposite action upon removal.
+
+The exact time the script is run varies with each operation, and should be
+self-explanatory. Note that during an upgrade operation, none of the install
+or remove functions will be called.
+
+Scripts are passed either one or two ``full version strings'', where a full
+version string is either 'pkgver-pkgrel' or 'epoch:pkgver-pkgrel', if epoch is
+non-zero.
+
+*pre_install*::
+	Run right before files are extracted. One argument is passed:
+	new package full version string.
+
+*post_install*::
+	Run right after files are extracted. One argument is passed:
+	new package full version string.
+
+*pre_upgrade*::
+	Run right before files are extracted. Two arguments are passed in this
+	order: new package full version string, old package full version string.
+
+*post_upgrade*::
+	Run after files are extracted. Two arguments are passed in this order:
+	new package full version string, old package full version string.
+
+*pre_remove*::
+	Run right before files are removed. One argument is passed:
+	old package full version string.
+
+*post_remove*::
+	Run right after files are removed. One argument is passed:
+	old package full version string.
+
+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 '{pkgdatadir}' as 'proto.install' for
+reference with all of the available functions defined.
+
+
+Using VCS Sources[[VCS]]
+------------------------
+Building a developmental version of a package using sources from a version
+control system (VCS) is enabled by specifying the source in the form
+`source=('directory::url#fragment?query')`. Currently makepkg supports the
+Bazaar, Git, Subversion, and Mercurial version control systems. For other
+version control systems, manual cloning of upstream repositories must be done
+in the `prepare()` function.
+
+The source URL is divided into four components:
+
+*directory*::
+	(optional) Specifies an alternate directory name for makepkg to download
+	the VCS source into.
+
+*url*::
+	The URL to the VCS repository. This must include the VCS in the URL protocol
+	for makepkg to recognize this as a VCS source. If the protocol does not
+	include the VCS name, it can be added by prefixing the URL with `vcs+`. For
+	example, using a Git repository over HTTPS would have a source URL in the
+	form:
+	`git+https://...`.
+
+*fragment*::
+	(optional) Allows specifying a revision number or branch for makepkg to checkout
+	from the VCS. For example, to checkout a given revision, the source line would
+	have the format `source=(url#revision=123)`. The available fragments depends on
+	the VCS being used:
+
+	*bzr*;;
+		revision (see `'bzr help revisionspec'` for details)
+
+	*git*;;
+		branch, commit, tag
+
+	*hg*;;
+		branch, revision, tag
+
+	*svn*;;
+		revision
+
+*query*::
+	(optional) Allows specifying whether a VCS checkout should be checked for
+	PGP-signed revisions. The source line should have the format
+	`source=(url#fragment?signed)` or `source=(url?signed#fragment)`. Currently
+	only supported by Git.
+
+Example
+-------
+The following is an example PKGBUILD for the 'patch' package. For more
+examples, look through the build files of your distribution's packages. For
+those using Arch Linux, consult the Arch Build System (ABS) tree.
+
+[source,sh]
+-------------------------------
+include::PKGBUILD-example.txt[]
+-------------------------------
+
+
+See Also
+--------
+linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5]
+
+include::footer.asciidoc[]