diff options
| -rw-r--r-- | doc/Makefile.am | 21 | ||||
| -rw-r--r-- | doc/PKGBUILD.8 | 460 | ||||
| -rw-r--r-- | doc/addendum.8.hu | 3 | ||||
| -rw-r--r-- | doc/libalpm.3 | 25 | ||||
| -rw-r--r-- | doc/makepkg.8 | 156 | ||||
| -rw-r--r-- | doc/pacman.8 | 359 | ||||
| -rw-r--r-- | doc/po4a.cfg | 11 |
7 files changed, 1028 insertions, 7 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index f6378bf8..8f7d90da 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,22 +1,29 @@ -all: makepkg.8 pacman.8 +all: po4a makepkg.8 PKGBUILD.8 pacman.8 + +SUBDIRS = hu + +po4a: +if HAS_PO4A + @$(NORMAL_INSTALL) + po4a -k 0 po4a.cfg +endif if HAS_MAN2HTML makepkg.8: - sed -e 's,#PACMAN_VERSION#,$(PACMAN_VERSION),g' < makepkg.8.in > makepkg.8 man2html makepkg.8 > html/makepkg.8.html -endif -if HAS_MAN2HTML +PKGBUILD.8: + man2html PKGBUILD.8 > html/PKGBUILD.8.html + pacman.8: - sed -e 's,#PACMAN_VERSION#,$(PACMAN_VERSION),g' < pacman.8.in > pacman.8 man2html pacman.8 > html/pacman.8.html endif clean: - rm -rf *.8 rm -rf html/* + rm -rf hu/*.8 -man_MANS = pacman.8 makepkg.8 libalpm.3 +man_MANS = pacman.8 makepkg.8 PKGBUILD.8 libalpm.3 if HAS_DOXYGEN man_MANS += man3/*.3 diff --git a/doc/PKGBUILD.8 b/doc/PKGBUILD.8 new file mode 100644 index 00000000..61fc7208 --- /dev/null +++ b/doc/PKGBUILD.8 @@ -0,0 +1,460 @@ +.TH FrugalBuild 8 "June 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@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 foo-extra format, where foo +or foo-extra is a dir under /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. + +The scriptlet messages are parsed, a simple example tells you everything: +.nf +post_upgrade() +{ + echo "START this will be good" + echo "DONE 0" + echo "START this will fail" + echo "DONE 1" + echo "old message" +} +.fi + +.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. + +NOTE: if you create several subpackages, maintaining those packages will +require more and more time. Thus, unnecessary splits aren't welcome. +Especially, if you split out a library, then don't move the headers to the +package just to speed up building with a few seconds! + +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! + +.SH "SEE ALSO" +.BR makepkg (8), +.BR pacman (8) +.SH AUTHOR +.nf +Judd Vinet <jvinet@zeroflux.org> +and the Frugalware developers <frugalware-devel@frugalware.org> +.fi diff --git a/doc/addendum.8.hu b/doc/addendum.8.hu new file mode 100644 index 00000000..3b5ba0b9 --- /dev/null +++ b/doc/addendum.8.hu @@ -0,0 +1,3 @@ +PO4A-HEADER:mode=after;position=SZERZŐ;beginboundary=.SH +.SH FORDÍTÁS +Dvornik László <dvornik@gnome.hu>. diff --git a/doc/libalpm.3 b/doc/libalpm.3 new file mode 100644 index 00000000..52e4af0b --- /dev/null +++ b/doc/libalpm.3 @@ -0,0 +1,25 @@ +.TH libalpm 3 "29 Jan 2006" "Frugalware Developer Manual" "" +.SH NAME +libalpm \- Arch Linux package management library +.SH SYNOPSIS +For ease of access, the libalpm manual has been split up into several sections. + +.nf +alpm_databases Database Functions +alpm_dep Dependency Functions +alpm_groups Group Functions +alpm_interface Interface Functions +alpm_list List Functions +alpm_log Logging Functions +alpm_misc Miscellaneous Functions +alpm_options Library Options +alpm_packages Package Functions +alpm_sync Sync Functions +alpm_trans Transaction Functions +.fi + +.SH AUTHOR +.nf +Judd Vinet <jvinet@zeroflux.org> +and the Frugalware developers <frugalware-devel@frugalware.org> +.fi diff --git a/doc/makepkg.8 b/doc/makepkg.8 new file mode 100644 index 00000000..418d5dca --- /dev/null +++ b/doc/makepkg.8 @@ -0,0 +1,156 @@ +.TH makepkg 8 "January 30, 2006" "Frugalware Developer Manual" "" +.SH NAME +makepkg \- package build utility +.SH SYNOPSIS +\fBmakepkg [options]\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 and validate 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. See \fBmakeworld --help\fP for syntax. + +.SH OPTIONS +.TP +.B "\-b, \-\-builddeps" +Build missing dependencies from source. When makepkg finds missing build-time or +run-time dependencies, it will look for the dependencies' FrugalBuild files under +$fst_root (set in your /etc/repoman.conf). If it finds them it will +run another copy of makepkg to build and install the missing dependencies. +The child makepkg calls will be made with the \fB-b\fP and \fB-i\fP options. +.TP +.B "\-B, \-\-noccache" +Do not use ccache during build. +.TP +.B "\-c, \-\-clean" +Clean up leftover work files/directories after a successful build. +.TP +.B "\-C, \-\-cleancache" +Used with --chroot cleans up the chroot which means removing unnecessary +packages from it. If used twice, then it removes all source files from +the cache directory and cleans up the full compiler cache to free up diskspace. +.TP +.B "\-d, \-\-nodeps" +Do not perform any dependency checks. This will let you override/ignore any +dependencies required. There's a good chance this option will break the build +process if all of the dependencies aren't installed. +.TP +.B "\-D <pkgname>" +Clean up only one package's compiler cache. (Uses ccache -C.) +.TP +.B "\-e, \-\-noextract" +Do not extract source files. Instead, use whatever already exists in the +src/ directory. This is handy if you want to go into src and manually +patch/tweak code, then make a package out of the result. +.TP +.B "\-f, \-\-force" +\fBmakepkg\fP will not build a package if a \fIpkgname-pkgver-pkgrel-arch.fpm\fP +file already exists in the build directory. You can override this behaviour with +the \fB--force\fP switch. +.TP +.B "\-G, \-\-genmd5" +Download all source files (if required) and use \fImd5sum\fP to generate md5 hashes +for each of them. You can then redirect the output into your FrugalBuild for source +validation (makepkg -G >>FrugalBuild). +.TP +.B "\-g, \-\-gensha1" +Download all source files (if required) and use \fIsha1sum\fP to generate sha1 hashes +for each of them. You can then redirect the output into your FrugalBuild for source +validation (makepkg -g >>FrugalBuild). +.TP +.B "\-h, \-\-help" +Output syntax and commandline options. +.TP +.B "\-i, \-\-install" +Install/Upgrade the package after a successful build. +.TP +.B "\-j <jobs>" +Sets MAKEFLAGS="-j<jobs>" before building the package. This is useful for overriding +the MAKEFLAGS setting in /etc/makepkg.conf. +.TP +.B "\-L, \-\-nolastmod" +Disable updating the Last modified line. +.TP +.B "\-k, \-\-logging" +Logging package build process +.TP +.B "\-l <pkgname>" +Download the package's buildscript before starting the build. This is useful +if you do not want to do a full 'repoman upd' nor want to download manually the +buildscript. +.TP +.B "\-m, \-\-nocolor" +Disable color in output messages +.TP +.B "\-n, \-\-nostrip" +Do not strip binaries and libraries. +.TP +.B "\-o, \-\-nobuild" +Download and extract files only, do not build. +.TP +.B "\-p <buildscript>" +Read the package script \fI<buildscript>\fP instead of the default (\fIFrugalBuild\fP). +.TP +.B "\-r, \-\-rmdeps" +Upon successful build, remove any dependencies installed by makepkg/pacman during +dependency auto-resolution (using \fB-b\fP or \fB-s\fP). +.TP +.B "\-R, \-\-chroot" +Build the package in a chroot environment. +.TP +.B "\-s, \-\-syncdeps" +Install missing dependencies using pacman. When makepkg finds missing build-time +or run-time dependencies, it will run pacman to try and resolve them. If successful, +pacman will download the missing packages from a package repository and +install them for you. +.TP +.B "\-t <tree>" +When building in a chroot (using -R) you may want to build packages for a +version other than the host one. Using this option, it's possible to build +packages for "stable" while the host system is "current" and vica versa. +.TP +.B "\-u, \-\-noup2date" +Do not check for newer version before starting build. Normally makepkg will +prevent you from building obsolete source by mistake. If you know what you are +doing, you can disable this feature with this switch. +.B "\-S, \-\-sudosync" +Install missing dependencies using pacman and sudo. This is the same as \fB-s\fP +except that makepkg will call pacman with sudo. This means you don't have to +build as root to use dependency auto-resolution. +.TP +.TP +.B "\-w <destdir>" +Write the resulting package file to the directory \fI<destdir>\fP instead of the +current working directory. +.TP +.B "\-\-noconfirm" +When calling pacman to resolve dependencies or conflicts, makepkg can pass +the \fI--noconfirm\fP option to it so it does not wait for any user +input before proceeding with operations. +.TP +.B "\-\-noprogressbar" +When calling pacman, makepkg can pass the \fI--noprogressbar\fP option to it. +This is useful if one is directing makepkg's output to a non-terminal (ie, a file). + +.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" +.BR FrugalBuild (8), +.BR pacman (8) +.SH AUTHOR +.nf +Judd Vinet <jvinet@zeroflux.org> +and the Frugalware developers <frugalware-devel@frugalware.org> +.fi diff --git a/doc/pacman.8 b/doc/pacman.8 new file mode 100644 index 00000000..704f9d1b --- /dev/null +++ b/doc/pacman.8 @@ -0,0 +1,359 @@ +.TH pacman 8 "January 21, 2006" "Frugalware User Manual" "" +.SH NAME +pacman \- package manager utility +.SH SYNOPSIS +\fBpacman <operation> [options] <package> [package] ...\fP +.SH DESCRIPTION +\fBpacman\fP is a \fIpackage management\fP utility that tracks installed +packages on a linux system. It has simple dependency support and the ability +to connect to a remote ftp server and automatically upgrade packages on +the local system. pacman package are \fIbzipped tar\fP format. +.SH OPERATIONS +.TP +.B "\-A, \-\-add" +Add a package to the system. Package will be uncompressed +into the installation root and the database will be updated. +.TP +.B "\-F, \-\-freshen" +This is like --upgrade except that, unlike --upgrade, this will only +upgrade packages that are already installed on your system. +.TP +.B "\-Q, \-\-query" +Query the package database. This operation allows you to +view installed packages and their files, as well as meta-info +about individual packages (dependencies, conflicts, install date, +build date, size). This can be run against the local package +database or can be used on individual .fpm packages. See +\fBQUERY OPTIONS\fP below. +.TP +.B "\-c, \-\-changelog" +View the changelog of a package. +.TP +.B "\-R, \-\-remove" +Remove a package from the system. Files belonging to the +specified package will be deleted, and the database will +be updated. Most configuration files will be saved with a +\fI.pacsave\fP extension unless the \fB--nosave\fP option was +used. +.TP +.B "\-S, \-\-sync" +Synchronize packages. With this function you can install packages +directly from the ftp servers, complete with all dependencies required +to run the packages. For example, \fBpacman -S qt\fP will download +qt and all the packages it depends on and install them. You could also use +\fBpacman -Su\fP to upgrade all packages that are out of date (see below). +.TP +.B "\-U, \-\-upgrade" +Upgrade a package. This is essentially a "remove-then-add" +process. See \fBHANDLING CONFIG FILES\fP for an explanation +on how pacman takes care of config files. +.TP +.B "\-V, \-\-version" +Display version and exit. +.TP +.B "\-h, \-\-help" +Display syntax for the given operation. If no operation was +supplied then the general syntax is shown. +.SH OPTIONS +.TP +.B "\-d, \-\-nodeps" +Skips all dependency checks. Normally, pacman will always check +a package's dependency fields to ensure that all dependencies are +installed and there are no package conflicts in the system. This +switch disables these checks. +.TP +.B "\-f, \-\-force" +Bypass file conflict checks, overwriting conflicting files. If the +package that is about to be installed contains files that are already +installed, this option will cause all those files to be overwritten. +This option should be used with care, ideally not at all. +.TP +.B "\-r, \-\-root <path>" +Specify alternative installation root (default is "/"). This +should \fInot\fP be used as a way to install software into +e.g. /usr/local instead of /usr. Instead this should be used +if you want to install a package on a temporary mounted partition, +which is "owned" by another system. By using this option you not only +specify where the software should be installed, but you also +specify which package database to use. +.TP +.B "\-v, \-\-verbose" +Output more status and error messages. +.TP +.B "\-\-config <path>" +Specify an alternate configuration file. +.TP +.B "\-\-noconfirm" +Bypass any and all "Are you sure?" messages. It's not a good idea to do this +unless you want to run pacman from a script. +.TP +.B "\-\-ask <number>" +Finetune the --noconfirm switch by not answering "yes" to all libalpm +questions, but you are able to specify yes/no for all type of libalpm +questions. The types are the followings: +.nf +The given package is in IgnorePkg. (1) +Replace package foo with bar? (2) +foo conflicts with bar. Remove bar? (4) +Do you want to delete the corrupted package? (8) +Local version is newer. (16) +Local version is up to date. (32) +.fi +Select for what types do you want to answer yes, sum up the values and use the +result as a parameter to this option. +.TP +.B "\-\-noprogressbar" +Do not show a progress bar when downloading files. This can be useful for +scripts that call pacman and capture the output. +.SH SYNC OPTIONS +.TP +.B "\-c, \-\-clean" +Remove old packages from the cache. When pacman downloads packages, +it saves them in \fI/var/cache/pacman/pkg\fP. If you need to free up +diskspace, you can remove these packages by using the --clean option. +Using one --clean (or -c) switch will only remove \fIold\fP packages. +Use it twice to remove \fIall\fP packages from the cache. +.TP +.B "\-e, \-\-dependsonly" +Don't install the packages itself, only their dependencies. This can be +handy if you want to install the packages themselves with different +options or from source. +.TP +.B "\-g, \-\-groups" +Display all the members for each package group specified. If no group +names are provided, all groups will be listed. +.TP +.B "\-i, \-\-info" +Display dependency information for a given package. This will search +through all repositories for a matching package and display the +dependencies, conflicts, etc. +.TP +.B "\-l, \-\-list" +List all files in the specified repositories. Multiple repositories can +be specified on the command line. +.TP +.B "\-p, \-\-print-uris" +Print out URIs for each package that will be installed, including any +dependencies that have yet to be installed. These can be piped to a +file and downloaded at a later time, using a program like wget. +.TP +.B "\-s, \-\-search <regexp>" +This will search each package in the package list for names or descriptions +that contains <regexp>. +.TP +.B "\-u, \-\-sysupgrade" +Upgrades all packages that are out of date. pacman will examine every +package installed on the system, and if a newer package exists on the +server it will upgrade. pacman will present a report of all packages +it wants to upgrade and will not proceed without user confirmation. +Dependencies are automatically resolved at this level and will be +installed/upgraded if necessary. +.TP +.B "\-w, \-\-downloadonly" +Retrieve all packages from the server, but do not install/upgrade anything. +.TP +.B "\-y, \-\-refresh" +Download a fresh copy of the master package list from the ftp server +defined in \fI/etc/pacman.conf\fP. This should typically be used each +time you use \fB--sysupgrade\fP. +.TP +.B "\-\-ignore <pkg>" +This option functions exactly the same as the \fBIgnorePkg\fP configuration +directive. Sometimes it can be handy to skip some package updates without +having to edit \fIpacman.conf\fP each time. +.SH REMOVE OPTIONS +.TP +.B "\-c, \-\-cascade" +Remove all target packages, as well as all packages that depend on one +or more target packages. This operation is recursive. +.TP +.B "\-k, \-\-keep" +Removes the database entry only. Leaves all files in place. +.TP +.B "\-n, \-\-nosave" +Instructs pacman to ignore file backup designations. Normally, when +a file is about to be \fIremoved\fP from the system the database is first +checked to see if the file should be renamed to a .pacsave extension. If +\fB--nosave\fP is used, these designations are ignored and the files are +removed. +.TP +.B "\-s, \-\-recursive" +For each target specified, remove it and all its dependencies, provided +that (A) they are not required by other packages; and (B) they were not +explicitly installed by the user. +This option is analagous to a backwards --sync operation. +.SH QUERY OPTIONS +.TP +.B "\-e, \-\-orphans" +List all packages that were installed as a dependency (ie, not +installed explicitly) and are not required by any other +packages. +.TP +.B "\-g, \-\-groups" +Display all groups that a specified package is part of. If no package +names are provided, all groups and members will be listed. +.TP +.B "\-i, \-\-info" +Display information on a given package. If it is used with the \fB-p\fP +option then the .PKGINFO file will be printed. +.TP +.B "\-l, \-\-list" +List all files owned by <package>. Multiple packages can be specified on +the command line. +.TP +.B "\-m, \-\-foreign" +List all packages that were not found in the sync database(s). Typically these +are packages that were downloaded manually and installed with --add. +.TP +.B "\-o, \-\-owns <file>" +Search for the package that owns <file>. +.TP +.B "\-p, \-\-file" +Tells pacman that the package supplied on the command line is a +file, not an entry in the database. Pacman will decompress the +file and query it. This is useful with \fB--info\fP and \fB--list\fP. +.TP +.B "\-s, \-\-search <regexp>" +This will search each locally-installed package for names or descriptions +that contains <regexp>. +.SH HANDLING CONFIG FILES +pacman uses the same logic as rpm to determine action against files +that are designated to be backed up. During an upgrade, it uses 3 +md5 hashes for each backup file to determine the required action: +one for the original file installed, one for the new file that's about +to be installed, and one for the actual file existing on the filesystem. +After comparing these 3 hashes, the follow scenarios can result: +.TP +original=\fBX\fP, current=\fBX\fP, new=\fBX\fP +All three files are the same, so we win either way. Install the new file. +.TP +original=\fBX\fP, current=\fBX\fP, new=\fBY\fP +The current file is un-altered from the original but the new one is +different. Since the user did not ever modify the file, and the new +one may contain improvements/bugfixes, we install the new file. +.TP +original=\fBX\fP, current=\fBY\fP, new=\fBX\fP +Both package versions contain the exact same file, but the one +on the filesystem has been modified since. In this case, we leave +the current file in place. +.TP +original=\fBX\fP, current=\fBY\fP, new=\fBY\fP +The new one is identical to the current one. Win win. Install the new file. +.TP +original=\fBX\fP, current=\fBY\fP, new=\fBZ\fP +All three files are different, so we install the new file with a .pacnew +extension and warn the user, so she can manually move the file into place +after making any necessary customizations. +.SH CONFIGURATION +pacman will attempt to read \fI/etc/pacman.conf\fP each time it is invoked. This +configuration file is divided into sections or \fIrepositories\fP. Each section +defines a package repository that pacman can use when searching for packages in +--sync mode. The exception to this is the \fIoptions\fP section, which defines +global options. +.TP +.SH Example: +.RS +.nf +[options] +NoUpgrade = etc/passwd etc/group etc/shadow +NoUpgrade = etc/fstab + +Include = /etc/pacman.d/current + +[custom] +Server = file:///home/pkgs + +.fi +.RE +.SH CONFIG: OPTIONS +.TP +.B "DBPath = path/to/db/dir" +Overrides the default location of the toplevel database directory. The default is +\fIvar/lib/pacman\fP. +.TP +.B "CacheDir = path/to/cache/dir" +Overrides the default location of the package cache directory. The default is +\fIvar/cache/pacman\fP. +.TP +.B "HoldPkg = <package> [package] ..." +If a user tries to \fB--remove\fP a package that's listed in HoldPkg, pacman +will ask for confirmation before proceeding. +.TP +.B "IgnorePkg = <package> [package] ..." +Instructs pacman to ignore any upgrades for this package when performing a +\fB--sysupgrade\fP. +.TP +.B "UpgradeDelay = <number>" +Upgrade only the packages that are at least <number> days old when +performing a \fB--sysupgrade\fP. +.TP +.B "Include = <path>" +Include another config file. This config file can include repositories or +general configuration options. +.TP +.B "ProxyServer = <host|ip>[:port]" +If set, pacman will use this proxy server for all ftp/http transfers. +.TP +.B "XferCommand = /path/to/command %u" +If set, pacman will use this external program to download all remote files. +All instances of \fB%u\fP will be replaced with the URL to be downloaded. If +present, instances of \fB%o\fP will be replaced with the local filename, plus a +".part" extension, which allows programs like wget to do file resumes properly. + +This option is useful for users who experience problems with pacman's built-in http/ftp +support, or need the more advanced proxy support that comes with utilities like +wget. +.TP +.B "NoPassiveFtp" +Disables passive ftp connections when downloading packages. (aka Active Mode) +.TP +.B "NoUpgrade = <file> [file] ..." +All files listed with a \fBNoUpgrade\fP directive will never be touched during a package +install/upgrade. \fINote:\fP do not include the leading slash when specifying files. +.TP +.B "NoExtract = <file> [file] ..." +All files listed with a \fBNoExtract\fP directive will never be extracted from +a package into the filesystem. This can be useful when you don't want part of +a package to be installed. For example, if your httpd root uses an index.php, +then you would not want the index.html file to be extracted from the apache +package. +.TP +.B "UseSyslog" +Log action messages through syslog(). This will insert pacman log entries into your +/var/log/messages or equivalent. +.TP +.B "LogFile = /path/to/file" +Log actions directly to a file, usually /var/log/pacman.log. + +.SH CONFIG: REPOSITORIES +Each repository section defines a section name and at least one location where the packages +can be found. The section name is defined by the string within square brackets (eg, the two +above are 'current' and 'custom'). Locations are defined with the \fIServer\fP directive and +follow a URL naming structure. Currently only ftp is supported for remote servers. If you +want to use a local directory, you can specify the full path with a 'file://' prefix, as +shown above. +.SH USING YOUR OWN REPOSITORY +Let's say you have a bunch of custom packages in \fI/home/pkgs\fP and their respective FrugalBuild +files are all in \fI/var/fst/local\fP. All you need to do is generate a compressed package database +in the \fI/home/pkgs\fP directory so pacman can find it when run with --refresh. + +.RS +.nf +# gensync /var/fst/local /home/pkgs/custom.fdb +.fi +.RE + +The above command will read all FrugalBuild files in /var/fst/local and generate a compressed +database called /home/pkgs/custom.fdb. Note that the database must be of the form +\fI{treename}.fdb\fP, where {treename} is the name of the section defined in the +configuration file. +That's it! Now configure your \fIcustom\fP section in the configuration file as shown in the +config example above. Pacman will now use your package repository. If you add new packages to +the repository, remember to re-generate the database and use pacman's --refresh option. +.SH SEE ALSO +\fBmakepkg\fP is the package-building tool that comes with pacman. +.SH AUTHOR +.nf +Judd Vinet <jvinet@zeroflux.org> +and the Frugalware developers <frugalware-devel@frugalware.org> +.fi diff --git a/doc/po4a.cfg b/doc/po4a.cfg new file mode 100644 index 00000000..171d8275 --- /dev/null +++ b/doc/po4a.cfg @@ -0,0 +1,11 @@ +[po4a_langs] hu +[po4a_paths] po/pacman.pot $lang:po/$lang.po +[type: man] pacman.8 \ + $lang:$lang/pacman.8 add_$lang:addendum.8.$lang \ + opt:"-o groff_code=verbatim -o translate_joined=CW,CE -o no_wrap=CW:CE" +[type: man] makepkg.8 \ + $lang:$lang/makepkg.8 add_$lang:addendum.8.$lang \ + opt:"-o groff_code=verbatim -o translate_joined=CW,CE -o no_wrap=CW:CE" +[type: man] PKGBUILD.8 \ + $lang:$lang/PKGBUILD.8 add_$lang:addendum.8.$lang \ + opt:"-o groff_code=verbatim -o translate_joined=CW,CE -o no_wrap=CW:CE" |