1 files changed, 251 insertions, 0 deletions
diff --git a/doc/makepkg.8.in b/doc/makepkg.8.in
new file mode 100644
index 00000000..e21fec1c
--- /dev/null
+++ b/doc/makepkg.8.in
@@ -0,0 +1,251 @@
+.TH makepkg 8 "July 18, 2002" "makepkg #VERSION#" ""
+.SH NAME
+makepkg \- package build utility
+.SH SYNOPSIS
+\fBmakepkg\fP
+.SH DESCRIPTION
+\fBmakepkg\fP will build packages for you.  All it needs is
+a build-capable linux platform, wget, and some build scripts.  The advantage
+to a script-based build is that you only really do the work once.  Once you
+have the build script for a package, you just need to run makepkg and it
+will do the rest: download source files, check dependencies, 
+configure the buildtime 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.
+.SH BUILD PROCESS (or How To Build Your Own Packages)
+Start in an isolated directory (ie, it's not used for anything other
+than building this package).  The build script should be called PKGBUILD
+and it should bear resemblance to the example below.
+
+\fBNOTE:\fP 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\fP script included with pacman/makepkg.
+
+.TP
+.TP
+.SH PKGBUILD Example:
+.RS
+.nf
+pkgname=modutils
+pkgver=2.4.13
+pkgrel=1
+pkgdesc="Utilities for inserting and removing modules from the linux kernel"
+backup=(etc/modules.conf)
+depends=('glibc>=2.2.5' 'bash' 'zlib')
+source=(ftp://ftp.server.com/$pkgname-$pkgver.tar.gz modules.conf)
+
+build() {
+  cd $startdir/src/$pkgname-$pkgver
+  ./configure --prefix=/usr
+  make || return 1
+  make prefix=$startdir/pkg/usr install
+  # copy our custom modules.conf into the package root
+  mkdir -p $startdir/pkg/etc
+  cp ../modules.conf $startdir/pkg/etc
+}
+.fi
+.RE
+
+As you can see, the setup is fairly simple.  The first three lines define
+the package name and version info.  They also define the final package name
+which will be of the form \fI$pkgname-$pkgver-$pkgrel.pkg.tar.gz\fP.  The fourth
+line provides a brief description of the package.  These four lines should
+be present in every PKGBUILD script.
+
+The line with \fIbackup=\fP specifies files that should be treated specially
+when removing or upgrading packages.  See \fBHANDLING CONFIG FILES\fP in
+the \fIpacman\fP manpage for more information on this.
+
+The sixth line lists the dependencies for this package.  In order to build/run
+the package, all dependencies must be satisifed first.  makepkg will check this
+before attempting to build the package.
+
+Once your PKGBUILD is created, you can run \fImakepkg\fP from the build directory.
+makepkg will then 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\fP array.
+
+The sources are then extracted into a directory called ./src and
+the \fIbuild\fP function is called.  This is where all package configuration,
+building, and installing should be done.  Any customization will likely take
+place here.
+
+After a package is built, the \fIbuild\fP function must install the package
+files into a special package root, which can be referenced by \fB$startdir/pkg\fP
+in the \fIbuild\fP function.  The typical way to do this is one of the following:
+.RS
+.nf
+
+make DESTDIR=$startdir/pkg install
+
+or
+
+make prefix=$startdir/pkg/usr install
+
+.fi
+.RE
+Notice that the "/usr" portion should be present with "prefix", but not "DESTDIR".
+
+Once the package is successfully installed into the package root, \fImakepkg\fP
+will remove some directories (as per Arch Linux package guidelines; if you use
+this elsewhere, feel free to change it) like /usr/doc and /usr/info.  It will
+then strip debugging info from libraries and binaries and generate a meta-info
+file.  Finally, it will compress everything into a .pkg.tar.gz file and leave it
+in the directory you ran \fBmakepkg\fP from.
+
+At this point you should have a package file in the current directory, named
+something like name-version-release.pkg.tar.gz.  Done!
+
+.SH 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 post_install
+script is run right after files are installed.
+
+.TP
+.B post_upgrade
+script is run after all files have been upgraded.
+
+.TP
+.B pre_remove
+script is run right before files are removed.
+
+.RE
+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\fP directive:
+.RS
+.nf
+install=pkgname.install
+.fi
+.RE
+
+The install script does not need to be specified in the \fIsource\fP array.
+
+.TP
+.TP
+.SH Install scripts must follow this format:
+.RS
+.nf
+# arg 1:  the new package version
+post_install() {
+  #
+  #  do post-install stuff here
+  #
+  /bin/true
+}
+
+# arg 1:  the new package version
+# arg 2:  the old package version
+post_upgrade() {
+  #
+  #  do post-upgrade stuff here
+  #
+  /bin/true
+}
+
+# arg 1:  the old package version
+pre_remove() {
+  #
+  #  do pre-remove stuff here
+  #
+  /bin/true
+}
+
+op=$1
+shift
+
+$op $*
+.fi
+.RE
+
+This template is also available in your ABS tree (/usr/abs/install.proto).
+
+.SH PKGBUILD 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 Arch Linux packages.
+
+.TP
+.B pkgdesc
+This should be a brief description of the package and its functionality.
+
+.TP
+.B backup
+A space-delimited array of filenames (without a preceding slash). The
+\fIbackup\fP 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\fP in
+the \fIpacman\fP manpage for more information.
+
+.TP
+.B install
+Specified 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\fP array.  (eg, install=modutils.install)
+
+.TP
+.B depends
+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\fP, where <> is one of these three comparisons: \fB>=\fP
+(greater than equal to), \fB<=\fP (less than or equal to), or \fB=\fP (equal to).
+See the PKGBUILD example above for an example of the \fIdepends\fP directive.
+
+.TP
+.B conflicts
+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\fP except you cannot specify versions here, only package names.
+
+.TP
+.B source
+The \fIsource\fP 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.  Then if the source file
+does not already exist in /var/cache/pacman/src, the file is downloaded
+by wget.
+
+.SH MAKEPKG OPTIONS
+.TP
+.B "\-c, \-\-clean"
+Clean up leftover work files/directories after a successful build.
+.TP
+.B "\-i, \-\-install"
+Install/Upgrade the package after a successful build.
+
+.SH CONFIGURATION
+Configuration options are stored in \fI/etc/makepkg.conf\fP.  This file is parsed
+as a bash script, so you can export 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 flaky...
+.SH SEE ALSO
+\fBpacman\fP is the package manager that uses packages built by makepkg.
+
+See the Arch Linux Documentation for package-building guidelines if you wish
+to contribute packages to the Arch Linux project.
+.SH AUTHOR
+.nf
+Judd Vinet <jvinet@zeroflux.org>
+.fi