From 62a783a6bd7649ccd162e32278098080bf450c7b Mon Sep 17 00:00:00 2001 From: Judd Vinet Date: Fri, 9 Aug 2002 18:03:48 +0000 Subject: Imported from pacman-2.0.tar.gz --- doc/makepkg.8.in | 251 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 doc/makepkg.8.in (limited to 'doc/makepkg.8.in') 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 +.fi -- cgit v1.2.3-24-g4f1b