[Frugalware-darcs] pacman: doc: new manpage FrugalBuild
VMiklos
vmiklos at frugalware.org
Sat Jun 17 17:33:26 CEST 2006
[doc: new manpage FrugalBuild
VMiklos <vmiklos at frugalware.org>**20060613224711
move out the FrugalBuild notes from makepkg's manpage to a separate
FrugalBuild manpage
] {
addfile ./doc/FrugalBuild.8
hunk ./doc/FrugalBuild.8 1
+.TH makepkg 8 "Jane 13, 2006" "Frugalware Developer Manual" ""
+.SH NAME
+FrugalBuild \- Frugalware package builder descriptor
+.SH DESCRIPTION
+This manual page is meant to describe general rules about FrugalBuilds. If
+you're interested in the package builder \fBmakepkg\fP itself, then see its
+manual page, not this one.
+
+.TP
+.TP
+.SH FrugalBuild Example:
+.RS
+.nf
+# Last Modified: Sun, 19 Jun 2005 15:24:32 +0000
+# Compiling Time: 0.17 SBU
+# Maintainer: Name <email at addr.ess>
+
+pkgname=dvdauthor
+pkgver=0.6.11
+pkgrel=3
+pkgdesc="Will generate a DVD movie from a valid mpeg2 stream"
+depends=('imagemagick' 'libdvdread')
+Finclude sourceforge
+groups=('xapps')
+archs=('i686' 'x86_64')
+sha1sums=('a99ea7ef6e50646b77ad47a015127925053d34ea')
+
+# optimization OK
+.fi
+.RE
+
+As you can see, the setup is fairly simple. The first line tracks the time of
+the last update, this is automatically updated after a successful build.
+
+The next line defines its build time. Of course, it depends on your hardware,
+so we use SBUs instead of minutes as a unit.
+
+SBU is the Static Binutils Unit, which means the time "repoman merge binutils"
+takes on your machine. By default makepkg will print out how many seconds the
+build took. After you built binutils, you should update your /etc/makepkg.conf:
+
+SBU="257"
+
+The line above means compiling binutils on your machine took 257 seconds.
+Starting from this point, makepkg will print out SBUs instead of seconds after
+successful builds, and this SBU value will be equal on anyone's machine.
+
+If you wish to maintain the package, write your name or nick and e-mail
+address to the third line. If you don't plan to maintain the package just wrote
+the FrugalBuild, then write Contributor instead of Maintainer, and then someone
+can take it and will add his/her line later. Other lines like "Modified by" are
+not allowed. Use the darcs patch comments to mention others if you wish.
+
+pkgname defines the package name. It should not contain any uppercase letters.
+The package version defines the upstream version, while the package release
+tracks the Frugalware-specific changes. pkgrel should be an integer, pkgrels
+like 5wanda1 are reserved for security updates. There the rule is the
+following: If the original package's pkgrel was 4, then increment it once when
+you add a security patch, but then use 5wanda1, 5wanda2 and so on. This way
+the user can easily upgrade to pkgrel=5 which is in -current.
+
+pkgdesc is a short one-line description for the package. Usually taken from
+the project's homepage or manpage. Try to keep the lenght under 80 chars.
+
+depends() is a bash array which defines the dependencies of the package.
+depends() means the other package is required for building and using the
+current one. If the dependency is runtime-only, then use rodepends(), if
+buildtime-only then use makedepends().
+
+The next line is a special Finclude commands which allows you to inherit
+any directive from a FrugalBuild scheme. They can be found in the FST,
+under /source/include. The "util" scheme always included, since its
+provided functions are used by almost every FrugalBuild. Look at the
+/source/include/sourceforge.sh, it provides the url, up2date and source()
+directives, so we don't have to specify them here. After the Finclude you
+can overwrite the inherited directives, for example define a custom up2date
+if the inherited one is not sutable for you.
+
+The groups() array's first element can't be omitted, and it should be a
+valid "first group". This means it should be in a foo or bar-extra format,
+where foo is a dir under /source or bar is a dir under /extra/source in the
+FST.
+
+The archs() array defines for which architectures the given package is
+available. If it's not available, it means that gensync will skip it when
+generating package databases. If you are not able to provide a binary package
+for a given arch, don't include that in archs()! For example, no matter if
+the package could be compiled in x86_64, if you haven't compiled it yourself,
+don't include it. If you're sure it won't be available on a given arch (for
+example it's written in x86 asm), then use !arch, for example !x86_64.
+
+The sha1sums() array can be generated with the makepkg -g command. Its purpose
+is to prevent compiling from wrong sources, especially when the build is
+automatic. Where it is available you can use signatures(), its goal is that
+you don't have to update it manually every time.
+
+The last line will be added automatically to the end of the FrugalBuild if the
+build() function used your $CFLAGS or $CXXFLAGS. This is handy if you want to
+cross-compile on a faster machine for a slower architecture. Until the package
+doesn't use our $CFLAGS we can't cross-compile it, so please try to avoid
+creating "unoptimized" packages. If the package doesn't contain any
+architecture-dependent file, then you can add this line manually as makepkg
+will not detect this.
+
+Finally we define a build() function that will build the package. If you don't
+want to do anything special, probably you don't have to specify anything, as
+the default build() (inherited from util.sh) will fit your needs. Even if you
+define a custom build(), probably you can re-use parts of the default build().
+For the list of special functions provided by util.sh and others refer to
+the /source/include dir. Again, util.sh is included automatically, but you
+have to Finclude the others before using them!
+
+Once the package is successfully installed into the package root, \fImakepkg\fP
+will prepare some documentation. It will
+then strip debugging info from libraries and binaries and generate a meta-info
+file. Finally, it will compress everything into a .fpm 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-arch.fpm. 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 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.
+
+.RE
+To use this feature, just create a file (eg, pkgname.install) and put it in
+the same directory as the FrugalBuild 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.
+If you omit the install directive then makepkg will check for the
+$pkgname.install install and will use it if it's present.
+
+You can find a scriptlet skeleton in the /docs/tech/skel/ directory, use it
+when creating new packages.
+
+.SH FrugalBuild 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 Frugalware Linux packages.
+
+.TP
+.B pkgdesc
+This should be a brief description of the package and its functionality.
+
+.TP
+.B pkgdesc_localized
+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
+Sets the license type (eg, "GPL", "BSD", "NON-FREE"). (\fBNote\fP: This
+option is still in development and may change in the future)
+
+.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 FrugalBuild, 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 up2date
+This directive should contain a command that prints the current upstream stable
+version of the project. This way we can check for newer version without visiting
+manually the project's website (see above).
+
+.TP
+.B source \fI(array)\fP
+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 FrugalBuild
+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.
+
+.TP
+.B md5sums \fI(array)\fP
+If this field is present, it should contain an MD5 hash for every source file
+specified in the \fIsource\fP array (in the same order). makepkg will use
+this to verify source file integrity during subsequent builds. To easily
+generate md5sums, first build using the FrugalBuild then run
+\fBmakepkg -G >>FrugalBuild\fP. Then you can edit the FrugalBuild and move the
+\fImd5sums\fP line from the bottom to an appropriate location.
+
+.TP
+.B sha1sums \fI(array)\fP
+If this field is present, it should contain an SHA1 hash for every source file
+specified in the \fIsource\fP array (in the same order). makepkg will use
+this to verify source file integrity during subsequent builds. To easily
+generate sha1sums, first build using the FrugalBuild then run
+\fBmakepkg -g >>FrugalBuild\fP. Then you can edit the FrugalBuild and move the
+\fIsha1sums\fP line from the bottom to an appropriate location.
+
+.TP
+.B signatures \fI(array)\fP
+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)\fP
+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)\fP
+This array defines on which architectures the given package is avalibable.
+If it's not available, that will mean that gensync will skip it when generating
+package databases.
+
+.TP
+.B backup \fI(array)\fP
+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 depends \fI(array)\fP
+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 FrugalBuild example above for an example of the \fIdepends\fP directive.
+
+.TP
+.B makedepends \fI(array)\fP
+An array of packages that this package depends on to build (ie, not required
+to run). Packages in this list should follow the same format as \fIdepends\fP.
+
+.TP
+.B rodepends \fI(array)\fP
+An array of packages that this package depends on to run (ie, not required to
+build). Generally \fIrodepends\fP should be avoided in favour of \fIdepends\fP
+except where this will create circular dependency chains. (For example building
+logrotate doesn't requires to have dcron installed.) Packages in this list
+should follow the same format as \fIdepends\fP.
+
+.TP
+.B conflicts \fI(array)\fP
+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 provides \fI(array)\fP
+An array of "virtual provisions" that this package provides. This allows a package
+to provide dependency names other than it's own package name. For example, the
+kernel-scsi and kernel-ide packages can each provide 'kernel' which allows packages
+to simply depend on 'kernel' rather than "kernel-scsi OR kernel-ide OR ..."
+
+.TP
+.B replaces \fI(array)\fP
+This is an array of packages that this package should replace, and can be used to handle
+renamed/combined packages. For example, if the kernel package gets renamed
+to kernel-ide, then subsequent 'pacman -Syu' calls will not pick up the upgrade, due
+to the differing package names. \fIreplaces\fP handles this.
+
+.TP
+.B options \fI(array)\fP
+This is an array of various boolean options. The possible values are:
+.nf
+nodocs Don't add any documentation automatically (ie. when there'll be
+ a separate documentation subpackage).
+nostrip Don't strip binaries/libraries.
+force This is used to force the package to be upgraded by --sysupgrade,
+ even if its an older version.
+nobuild If this directive set, gensync will ignore this package, so users
+ must build these packages on their machines, they will not be able
+ to install them with pacman -S. Useful for closed-source, but
+ freeware programs.
+nofakeroot Don't drop privileges after chrooting. Required by some broken
+ packages.
+scriptlet Don't skip executing scriptlets even if we're in chroot.
+.fi
+
+.SH What is the process of chrooted build ?
+
+First, what is chroot? We currently use fakeroot to prevent build() from
+modifying the host system, and we use a prefix or DESTDIR directive to install
+everything to a directory and not under to the host system. This is good, but
+not enough.
+
+This system lacks of the ability to control the list of installed packages
+during the build on the system of a packager, the given compiled package maybe
+linked itself to an extra installed library. This way we can't really control
+the list of real dependencies. For example if libquicktime is installed from
+source on my system, then mplayer or any other program can link itself to that,
+and so that depends() will be incorrect. Or if I have the closed source binary
+NVidia drivers installed, some programs link tho NVidia's libraries.
+
+Of course there is a sollution to avoid this, to use a real chroot instead of a
+simple fakeroot. What is this means? The followings:
+
+When starting the build, a core chroot system is installed under /var/chroot.
+(Of course you can change this value under /etc/makepkg.conf.) The core system
+contains ~60 packages which are must installed to build any package in
+a chrooted environment. These packages (for example gcc, kernel-headers, make)
+should not be mentioned in makedepends(). 'pacman -Sg core chroot-core
+devel-core' should show you the actial list. (We try to change this list rarely
+of course.)
+
+When you start building with makepkg -R, pacman will install these packages to
+/var/chroot if necessary. This will produce a fully "clean" Frugalware system,
+that consits of base packages only. This /var/chroot is fully separated from
+the host system so that this will solve the problems mentioned above.
+(Linking to a library installed from source, etc.)
+
+Here comes the fun part. The packages listed in depends() and makedepends() are
+installed to this clean (/var/chroot) system. From this point, this chroot is
+capable to build the specified package in it without any unnecessary package
+installed, fully separated from the host system.
+
+After this the chroot should be cleaned up which means the removal of the
+installed depends() and makedepends(). This ensures us not to build from
+scratch the core chroot.
+
+This way we can prevent lots of dependency problems and it is even possible to
+build packages for a different Frugalware version. This is quite efficent when
+building security updates or fixing critical bugs in the -stable tree.
+
+If the build is failed, the working directory will not be deleted, you can find
+it under /var/chroot/var/tmp/fst. Later if you want to clean your chroot
+(delete the working directory and remove unnecessary packages) you can use 'makepkg -CR'.
+
+To activate building in a chroot, you should run makepkg as root at least with
+the -R option.
+
+.SH Package splitting
+
+Package splitting means moving out a list of specifed files to subpackages (like
+libmysql out of mysql) and then defining the properties of subpackages. The
+\fBsubpkgs()\fP array is to define the pkgnames of the subpackages. From now all
+the directives has their subfoo equivalent:
+.nf
+pkgname -> subpkgs()
+pkgdesc -> subdescs()
+pkgdesc_localized -> subdescs_localized()
+license() -> sublicense()
+replaces() -> subreplaces()
+groups() -> subgroups()
+depends() -> subdepends()
+rodepends() -> subrodepends()
+removes() -> subremoves()
+conflicts() -> subconflicts()
+provides() -> subprovides()
+backup() -> subbackup()
+install -> subinstall()
+options -> suboptions()
+archs -> subarchs()
+.fi
+
+Also note that bash does not support two-dimensional arrays, so when defining the
+array of arrays, then quotes are the major separators and spaces are the minor ones.
+
+Simple example:
+.nf
+Add the followings to your bottom of your FrugalBuild
+subpkgs=('foo' 'bar')
+subdescs=('desc of foo' 'desc of bar')
+subdepends=('foodep1 foodep2' 'bardep1 bardep2')
+subgroups=('apps' 'apps')
+subarchs=('i686 x86_64' 'i686 x86_64')
+.fi
+
+You may define conflicts, replaces and other directives for your subpackages, but
+the requirement is only to define these 5 ones.
+
+The second part is to move some files to the - just defined - subpackages. You
+should use the Fsplit command for this at the end of your build() function. You
+can read more about Fsplit in the fwmakepkg documentation, but here is a short
+example:
+.nf
+
+Fsplit subpkgname usr/share/
+
+.fi
+This will move the /usr/share dir of the package to the "subpkgname" subpackage.
+
+NOTE: never use a trailing slash when defining file patterns, especially if you
+use wildcards in it!
+
+Special case: subpkgs in other repos.
+
+The situation is the following: you have a package which is in the frugalware
+repo, but you want its subpackage to be in extra. It's a but tricky, but still
+possible.
+
+The trick is to create a fake FrugalBuild in the other repo. You could place
+it whereever you want, but to use repoman you need to place it under
+$fst/extra/source/subpkgs/pkgname, where pkgname is the name of the original
+main package.
+
+How to create that fake FrugalBuild?
+
+Copy the original one, but remove everything except the subfoo directives,
+pkgver and pkgrel. The next step is to clarify which subpackage have to be
+in which repo. This is done by removing the architectures from the subarchs()
+array.
+
+Example:
+.nf
+
+The old main:
+
+subpkgs=('foo' 'bar')
+subarchs=('i686 x86_64' 'i686 x86_64')
+
+The new main:
+subpkgs=('foo' 'bar')
+subarchs=('i686 x86_64' '')
+
+The new fake:
+subpkgs=('foo' 'bar')
+subarchs=('' 'i686 x86_64')
+
+.fi
+This means that bar is expected to be uploaded to extra, while foo is still in
+the frugalware repo. If you move all the subpackages to extra, then of course
+you can remove the whole subarchs() array from the main FrugalBuild.
+
+.SH "SEE ALSO"
+.BR makepkg (8),
+.BR pacman (8)
+.SH AUTHOR
+.nf
+Judd Vinet <jvinet at zeroflux.org>
+and the Frugalware developers <frugalware-devel at frugalware.org>
+.fi
hunk ./doc/Makefile.am 1
-all: makepkg.8 pacman.8 po4a
+all: makepkg.8 FrugalBuild.8 pacman.8 po4a
hunk ./doc/Makefile.am 12
+if HAS_MAN2HTML
+FrugalBuild.8:
+ man2html FrugalBuild.8 > html/FrugalBuild.8.html
+endif
+
hunk ./doc/Makefile.am 26
-man_MANS = pacman.8 makepkg.8 libalpm.3
+man_MANS = pacman.8 makepkg.8 FrugalBuild.8 libalpm.3
hunk ./doc/hu/Makefile.am 4
-man_MANS = pacman.8 makepkg.8
+man_MANS = pacman.8 makepkg.8 FrugalBuild.8
hunk ./doc/hu/Makefile.am 8
-EXTRA_DIST = pacman.8 makepkg.8
+EXTRA_DIST = pacman.8 makepkg.8 FrugalBuild.8
hunk ./doc/makepkg.8 18
-.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 FrugalBuild
-and it should bear resemblance to the example below.
-
-\fBNOTE:\fP If you have a local copy of the Frugalware Source Tree (FST)
-on your computer, you can copy the source/apps/cabextract/FrugalBuild
-file to your new package
-build directory and edit it from there. To acquire/sync the FST, use
-the \fBrepoman upd\fP command provided by the pacman-tools package.
-
-.TP
-.TP
-.SH FrugalBuild Example:
-.RS
-.nf
-pkgname=modutils
-pkgver=2.4.25
-pkgrel=1
-pkgdesc="Utilities for inserting and removing modules from the linux kernel"
-url="http://www.kernel.org"
-backup=(etc/modules.conf)
-makedepends=('bash' 'mawk')
-depends=('glibc' 'zlib')
-archs=('i686')
-up2date="lynx -dump http://www.kernel.org/pub/linux/utils/kernel/modutils/v2.4/|grep LATEST |sed -n 's/.*S-\([0-9\.]*\) .*/\1/; 1 p'"
-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
-.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-$arch.fpm\fP. The fourth
-line provides a brief description of the package. These four lines should
-be present in every FrugalBuild 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.
-
-Lines 7 and 8 list the dependencies for this package. The \fIdepends\fP array
-specifies the run-time dependencies and \fImakedepends\fP specifies the build-time
-dependencies. In order to run the package, \fIdepends\fP must be satisfied. To
-build the package, \fBall\fP dependencies must be satisifed first. makepkg
-will check this before attempting to build the package.
-
-The \fIsource\fP array tells makepkg which files to download/extract before compiling
-begins. The \fImd5sums\fP array provides md5sums for each of these files. These
-are used to validate the integrity of the source files.
-
-Once your FrugalBuild 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".
-"DESTDIR" is the favorable option to use, but not all Makefiles support it. Use
-"prefix" only when "DESTDIR" is unavailable.
-
-Once the package is successfully installed into the package root, \fImakepkg\fP
-will prepare some documentation. It will
-then strip debugging info from libraries and binaries and generate a meta-info
-file. Finally, it will compress everything into a .fpm 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-arch.fpm. 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 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.
-
-.RE
-To use this feature, just create a file (eg, pkgname.install) and put it in
-the same directory as the FrugalBuild 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
-pre_install() {
- #
- # do pre-install stuff here
- #
- /bin/true
-}
-
-# 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
-pre_upgrade() {
- #
- # do pre-upgrade 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
-}
-
-# arg 1: the old package version
-post_remove() {
- #
- # do post-remove stuff here
- #
- /bin/true
-}
-
-op=$1
-shift
-$op $*
-.fi
-.RE
-
-.SH FrugalBuild 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 Frugalware Linux packages.
-
-.TP
-.B pkgdesc
-This should be a brief description of the package and its functionality.
-
-.TP
-.B pkgdesc_localized
-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
-Sets the license type (eg, "GPL", "BSD", "NON-FREE"). (\fBNote\fP: This
-option is still in development and may change in the future)
-
-.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 FrugalBuild, 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 up2date
-This directive should contain a command that prints the current upstream stable
-version of the project. This way we can check for newer version without visiting
-manually the project's website (see above).
hunk ./doc/makepkg.8 19
-.TP
-.B source \fI(array)\fP
-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 FrugalBuild
-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.
-
-.TP
-.B md5sums \fI(array)\fP
-If this field is present, it should contain an MD5 hash for every source file
-specified in the \fIsource\fP array (in the same order). makepkg will use
-this to verify source file integrity during subsequent builds. To easily
-generate md5sums, first build using the FrugalBuild then run
-\fBmakepkg -G >>FrugalBuild\fP. Then you can edit the FrugalBuild and move the
-\fImd5sums\fP line from the bottom to an appropriate location.
-
-.TP
-.B sha1sums \fI(array)\fP
-If this field is present, it should contain an SHA1 hash for every source file
-specified in the \fIsource\fP array (in the same order). makepkg will use
-this to verify source file integrity during subsequent builds. To easily
-generate sha1sums, first build using the FrugalBuild then run
-\fBmakepkg -g >>FrugalBuild\fP. Then you can edit the FrugalBuild and move the
-\fIsha1sums\fP line from the bottom to an appropriate location.
-
-.TP
-.B signatures \fI(array)\fP
-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)\fP
-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)\fP
-This array defines on which architectures the given package is avalibable.
-If it's not available, that will mean that gensync will skip it when generating
-package databases.
-
-.TP
-.B backup \fI(array)\fP
-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 depends \fI(array)\fP
-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 FrugalBuild example above for an example of the \fIdepends\fP directive.
-
-.TP
-.B makedepends \fI(array)\fP
-An array of packages that this package depends on to build (ie, not required
-to run). Packages in this list should follow the same format as \fIdepends\fP.
-
-.TP
-.B rodepends \fI(array)\fP
-An array of packages that this package depends on to run (ie, not required to
-build). Generally \fIrodepends\fP should be avoided in favour of \fIdepends\fP
-except where this will create circular dependency chains. (For example building
-logrotate doesn't requires to have dcron installed.) Packages in this list
-should follow the same format as \fIdepends\fP.
-
-.TP
-.B conflicts \fI(array)\fP
-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 provides \fI(array)\fP
-An array of "virtual provisions" that this package provides. This allows a package
-to provide dependency names other than it's own package name. For example, the
-kernel-scsi and kernel-ide packages can each provide 'kernel' which allows packages
-to simply depend on 'kernel' rather than "kernel-scsi OR kernel-ide OR ..."
-
-.TP
-.B replaces \fI(array)\fP
-This is an array of packages that this package should replace, and can be used to handle
-renamed/combined packages. For example, if the kernel package gets renamed
-to kernel-ide, then subsequent 'pacman -Syu' calls will not pick up the upgrade, due
-to the differing package names. \fIreplaces\fP handles this.
-
-.TP
-.B options \fI(array)\fP
-This is an array of various boolean options. The possible values are:
-.nf
-nodocs Don't add any documentation automatically (ie. when there'll be
- a separate documentation subpackage).
-nostrip Don't strip binaries/libraries.
-force This is used to force the package to be upgraded by --sysupgrade,
- even if its an older version.
-nobuild If this directive set, gensync will ignore this package, so users
- must build these packages on their machines, they will not be able
- to install them with pacman -S. Useful for closed-source, but
- freeware programs.
-nofakeroot Don't drop privileges after chrooting. Required by some broken
- packages.
-scriptlet Don't skip executing scriptlets even if we're in chroot.
-.fi
-
-.SH What is the process of chrooted build ?
-
-First, what is chroot? We currently use fakeroot to prevent build() from
-modifying the host system, and we use a prefix or DESTDIR directive to install
-everything to a directory and not under to the host system. This is good, but
-not enough.
-
-This system lacks of the ability to control the list of installed packages
-during the build on the system of a packager, the given compiled package maybe
-linked itself to an extra installed library. This way we can't really control
-the list of real dependencies. For example if libquicktime is installed from
-source on my system, then mplayer or any other program can link itself to that,
-and so that depends() will be incorrect. Or if I have the closed source binary
-NVidia drivers installed, some programs link tho NVidia's libraries.
-
-Of course there is a sollution to avoid this, to use a real chroot instead of a
-simple fakeroot. What is this means? The followings:
-
-When starting the build, a core chroot system is installed under /var/chroot.
-(Of course you can change this value under /etc/makepkg.conf.) The core system
-contains ~60 packages which are must installed to build any package in
-a chrooted environment. These packages (for example gcc, kernel-headers, make)
-should not be mentioned in makedepends(). 'pacman -Sg core chroot-core
-devel-core' should show you the actial list. (We try to change this list rarely
-of course.)
-
-When you start building with makepkg -R, pacman will install these packages to
-/var/chroot if necessary. This will produce a fully "clean" Frugalware system,
-that consits of base packages only. This /var/chroot is fully separated from
-the host system so that this will solve the problems mentioned above.
-(Linking to a library installed from source, etc.)
-
-Here comes the fun part. The packages listed in depends() and makedepends() are
-installed to this clean (/var/chroot) system. From this point, this chroot is
-capable to build the specified package in it without any unnecessary package
-installed, fully separated from the host system.
-
-After this the chroot should be cleaned up which means the removal of the
-installed depends() and makedepends(). This ensures us not to build from
-scratch the core chroot.
-
-This way we can prevent lots of dependency problems and it is even possible to
-build packages for a different Frugalware version. This is quite efficent when
-building security updates or fixing critical bugs in the -stable tree.
-
-If the build is failed, the working directory will not be deleted, you can find
-it under /var/chroot/var/tmp/fst. Later if you want to clean your chroot
-(delete the working directory and remove unnecessary packages) you can use 'makepkg -CR'.
-
-To activate building in a chroot, you should run makepkg as root at least with
-the -R option.
-
-.SH Package splitting
-
-Package splitting means moving out a list of specifed files to subpackages (like
-libmysql out of mysql) and then defining the properties of subpackages. The
-\fBsubpkgs()\fP array is to define the pkgnames of the subpackages. From now all
-the directives has their subfoo equivalent:
-.nf
-pkgname -> subpkgs()
-pkgdesc -> subdescs()
-pkgdesc_localized -> subdescs_localized()
-license() -> sublicense()
-replaces() -> subreplaces()
-groups() -> subgroups()
-depends() -> subdepends()
-rodepends() -> subrodepends()
-removes() -> subremoves()
-conflicts() -> subconflicts()
-provides() -> subprovides()
-backup() -> subbackup()
-install -> subinstall()
-options -> suboptions()
-archs -> subarchs()
-.fi
-
-Also note that bash does not support two-dimensional arrays, so when defining the
-array of arrays, then quotes are the major separators and spaces are the minor ones.
-
-Simple example:
-.nf
-Add the followings to your bottom of your FrugalBuild
-subpkgs=('foo' 'bar')
-subdescs=('desc of foo' 'desc of bar')
-subdepends=('foodep1 foodep2' 'bardep1 bardep2')
-subgroups=('apps' 'apps')
-subarchs=('i686 x86_64' 'i686 x86_64')
-.fi
-
-You may define conflicts, replaces and other directives for your subpackages, but
-the requirement is only to define these 5 ones.
-
-The second part is to move some files to the - just defined - subpackages. You
-should use the Fsplit command for this at the end of your build() function. You
-can read more about Fsplit in the fwmakepkg documentation, but here is a short
-example:
-.nf
-
-Fsplit subpkgname usr/share/
-
-.fi
-This will move the /usr/share dir of the package to the "subpkgname" subpackage.
-
-NOTE: never use a trailing slash when defining file patterns, especially if you
-use wildcards in it!
-
-Special case: subpkgs in other repos.
-
-The situation is the following: you have a package which is in the frugalware
-repo, but you want its subpackage to be in extra. It's a but tricky, but still
-possible.
-
-The trick is to create a fake FrugalBuild in the other repo. You could place
-it whereever you want, but to use repoman you need to place it under
-$fst/extra/source/subpkgs/pkgname, where pkgname is the name of the original
-main package.
-
-How to create that fake FrugalBuild?
-
-Copy the original one, but remove everything except the subfoo directives,
-pkgver and pkgrel. The next step is to clarify which subpackage have to be
-in which repo. This is done by removing the architectures from the subarchs()
-array.
-
-Example:
-.nf
-
-The old main:
-
-subpkgs=('foo' 'bar')
-subarchs=('i686 x86_64' 'i686 x86_64')
-
-The new main:
-subpkgs=('foo' 'bar')
-subarchs=('i686 x86_64' '')
-
-The new fake:
-subpkgs=('foo' 'bar')
-subarchs=('' 'i686 x86_64')
-
-.fi
-This means that bar is expected to be uploaded to extra, while foo is still in
-the frugalware repo. If you move all the subpackages to extra, then of course
-you can remove the whole subarchs() array from the main FrugalBuild.
-
-.SH MAKEPKG OPTIONS
+.SH OPTIONS
hunk ./doc/makepkg.8 149
-.SH SEE ALSO
-\fBpacman\fP is the package manager that uses packages built by makepkg.
-
-See the Frugalware Linux Documentation for package-building guidelines if you
-wish to contribute packages to the Frugalware Linux project.
+.SH "SEE ALSO"
+.BR FrugalBuild (8),
+.BR pacman (8)
hunk ./doc/po4a.cfg 8
+ opt:"-o groff_code=verbatim -o translate_joined=CW,CE -o no_wrap=CW:CE"
+[type: man] FrugalBuild.8 \
+ $lang:$lang/FrugalBuild.8 add_$lang:addendum.8.$lang \
}
More information about the Frugalware-darcs
mailing list