diff options
| author | Dan McGee <dan@archlinux.org> | 2007-09-16 21:10:44 -0500 |
|---|---|---|
| committer | Dan McGee <dan@archlinux.org> | 2007-09-16 21:10:44 -0500 |
| commit | 708488f6fe8bf5e06ae724243381b40586301633 (patch) | |
| tree | 83042c703173107def709f65d65697e233225441 | |
| parent | b0aa51059233849b0a7ef8d6a851750776ce6645 (diff) | |
| parent | f131ee9c56b99429374dfcce583872ad9259ed96 (diff) | |
Merge branch 'asciidoc' into working
We're getting close to release, so might as well do this now so people can
actually update some of our documentation.
| -rw-r--r-- | configure.ac | 27 | ||||
| -rw-r--r-- | doc/.gitignore | 9 | ||||
| -rw-r--r-- | doc/Makefile.am | 49 | ||||
| -rw-r--r-- | doc/PKGBUILD-example.txt | 32 | ||||
| -rw-r--r-- | doc/PKGBUILD.5 | 288 | ||||
| -rw-r--r-- | doc/PKGBUILD.5.txt | 239 | ||||
| -rw-r--r-- | doc/asciidoc.conf | 64 | ||||
| -rw-r--r-- | doc/footer.txt | 24 | ||||
| -rw-r--r-- | doc/libalpm.3 | 53 | ||||
| -rw-r--r-- | doc/libalpm.3.txt | 39 | ||||
| -rw-r--r-- | doc/makepkg.8 | 146 | ||||
| -rw-r--r-- | doc/makepkg.8.txt | 143 | ||||
| -rw-r--r-- | doc/makepkg.conf.5 | 152 | ||||
| -rw-r--r-- | doc/makepkg.conf.5.txt | 154 | ||||
| -rw-r--r-- | doc/pacman.8 | 293 | ||||
| -rw-r--r-- | doc/pacman.8.txt | 313 | ||||
| -rw-r--r-- | doc/pacman.conf.5 | 143 | ||||
| -rw-r--r-- | doc/pacman.conf.5.txt | 147 | ||||
| -rw-r--r-- | doc/repo-add.8.txt | 51 |
19 files changed, 1281 insertions, 1085 deletions
diff --git a/configure.ac b/configure.ac index 7852cca0..96d8f167 100644 --- a/configure.ac +++ b/configure.ac @@ -103,6 +103,11 @@ AC_ARG_ENABLE(doxygen, AC_HELP_STRING([--disable-doxygen], [do not build API docs via Doxygen]), [wantdoxygen=$enableval], [wantdoxygen=yes]) +# Help line for asciidoc +AC_ARG_ENABLE(asciidoc, + AC_HELP_STRING([--enable-asciidoc], [build your own manpages with Asciidoc]), + [wantasciidoc=$enableval], [wantasciidoc=no]) + # Help line for debug AC_ARG_ENABLE(debug, AC_HELP_STRING([--enable-debug], [enable debugging support]), @@ -225,7 +230,7 @@ AC_SUBST(CARCH) AC_SUBST(CARCHFLAGS) AC_SUBST(CHOST) -# Check for doxygen support +# Check for doxygen support and status AC_MSG_CHECKING([for doxygen]) if test "x$wantdoxygen" = "xyes" ; then AC_CHECK_PROGS([DOXYGEN], [doxygen]) @@ -240,7 +245,24 @@ else AC_MSG_RESULT([no, disabled by configure]) usedoxygen=no fi -AM_CONDITIONAL(HAS_DOXYGEN, test "x$usedoxygen" = "xyes") +AM_CONDITIONAL(USE_DOXYGEN, test "x$usedoxygen" = "xyes") + +# Check for asciidoc support and status +AC_MSG_CHECKING([for asciidoc]) +if test "x$wantasciidoc" = "xyes" ; then + AC_CHECK_PROGS([ASCIIDOC], [asciidoc]) + if test $ASCIIDOC ; then + AC_MSG_RESULT([yes]) + useasciidoc=yes + else + AC_MSG_RESULT([no, asciidoc missing]) + useasciidoc=no + fi +else + AC_MSG_RESULT([no, disabled by configure]) + useasciidoc=no +fi +AM_CONDITIONAL(USE_ASCIIDOC, test "x$useasciidoc" = "xyes") # Enable or disable debug code AC_MSG_CHECKING(for debug mode request) @@ -324,6 +346,7 @@ pacman_display_version: Compilation options: Doxygen support : ${usedoxygen} + Asciidoc support : ${useasciidoc} debug support : ${debug} include abs : ${includeabs} " diff --git a/doc/.gitignore b/doc/.gitignore index fcbfb09d..e10f61a4 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,2 +1,9 @@ -*.html +PKGBUILD.5 +libalpm.3 +makepkg.8 +makepkg.conf.5 +pacman.8 +pacman.conf.5 +repo-add.8 +*.xml man3 diff --git a/doc/Makefile.am b/doc/Makefile.am index 14caa0da..ad251287 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,25 +1,60 @@ -man_MANS = \ +ASCIIDOC_MANS = \ pacman.8 \ makepkg.8 \ + repo-add.8 \ PKGBUILD.5 \ makepkg.conf.5 \ pacman.conf.5 \ libalpm.3 -if HAS_DOXYGEN -man_MANS += $(wildcard man3/*.3) +if USE_DOXYGEN +DOXYGEN_MANS = $(wildcard man3/*.3) endif -EXTRA_DIST = $(man_MANS) Doxyfile +man_MANS = $(ASCIIDOC_MANS) $(DOXYGEN_MANS) -if HAS_DOXYGEN +EXTRA_DIST = \ + pacman.8.txt \ + makepkg.8.txt \ + repo-add.8.txt \ + PKGBUILD.5.txt \ + PKGBUILD-example.txt \ + makepkg.conf.5.txt \ + pacman.conf.5.txt \ + libalpm.3.txt \ + footer.txt \ + Doxyfile \ + $(ASCIIDOC_MANS) + +# Files that should be removed, but which Automake does not know. +MOSTLYCLEANFILES = $(DOXYGEN_MANS) *.xml + +if USE_DOXYGEN all: doxygen.in doxygen.in: doxygen $(srcdir)/Doxyfile endif -clean-local: - $(RM) man3/*.3 +if USE_ASCIIDOC +ASCIIDOC_OPTS = \ + -f asciidoc.conf \ + -a pacman_version="$(PACKAGE_VERSION)" \ + -a pacman_date="`date +%Y-%m-%d`" \ + -a sysconfdir=$(sysconfdir) + +$(ASCIIDOC_MANS): + a2x -d manpage -f manpage --asciidoc-opts="$(ASCIIDOC_OPTS)" $@.txt + +# These rules are due to the includes and files of the asciidoc text +$(ASCIIDOC_MANS): footer.txt +pacman.8: pacman.8.txt +makepkg.8: makepkg.8.txt +repo-add.8: repo-add.8.txt +PKGBUILD.5: PKGBUILD.5.txt PKGBUILD-example.txt +makepkg.conf.5: makepkg.conf.5.txt +pacman.conf.5: pacman.conf.5.txt +libalpm.3: libalpm.3.txt +endif # vim:set ts=2 sw=2 noet: diff --git a/doc/PKGBUILD-example.txt b/doc/PKGBUILD-example.txt new file mode 100644 index 00000000..50b652bd --- /dev/null +++ b/doc/PKGBUILD-example.txt @@ -0,0 +1,32 @@ +# $Id: PKGBUILD,v 1.16 2006/06/20 07:03:04 tpowa Exp $ +# Maintainer: judd <jvinet@zeroflux.org> +pkgname=module-init-tools +pkgver=3.2.2 +pkgrel=3 +pkgdesc="Utilities for inserting and removing modules from the Linux kernel" +arch=(i686 x86_64) +url="http://www.kernel.org" +license=('GPL') +depends=('glibc') +conflicts=('modutils') +replaces=('modutils') +backup=('etc/modprobe.conf' 'etc/modules.conf' 'etc/modprobe.devfs') +source=(http://www.kernel.org/pub/linux/utils/kernel/module-init-tools/module-init-tools-$pkgver.tar.bz2 \ + makefile.patch modprobe.conf) +md5sums=('a1ad0a09d3231673f70d631f3f5040e9' '47e14fda7a46668290d11d0444d81826'\ + '6db59d41e04941a790f80c1a4432faef') + +build() { + cd "$srcdir"/$pkgname-$pkgver + + patch -Np1 -i ../makefile.patch || return 1 + sed -i 's|/usr/bin/install|/bin/install|g' install-with-care + + ./configure --prefix=/usr --exec-prefix=/ + make || return 1 + + INSTALL=/bin/install make DESTDIR="$pkgdir" install + install -D -m644 ../modprobe.conf "$pkgdir"/etc/modprobe.conf +} + +# vim:set ts=2 sw=2 et: diff --git a/doc/PKGBUILD.5 b/doc/PKGBUILD.5 deleted file mode 100644 index 747b9f15..00000000 --- a/doc/PKGBUILD.5 +++ /dev/null @@ -1,288 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.TH \*(PB 5 "Feb 07, 2007" "\*(PB version \*(VR" "\*(DS Files" -.SH NAME -\*(PB \- \*(DS package build description file - -.SH DESCRIPTION -This manual page is meant to describe general rules about \fB\*(PB\fPs. Once -a \fB\*(PB\fP is written, the actual package is built using \fBmakepkg\fP and -installed with \fBpacman\fP. - -\fBNOTE:\fP If you have a local copy of the Arch Build System (ABS) tree -on your computer, you can copy the \*(PB.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 \fBpacman\fP. - -.SH OPTIONS AND 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 -The version of the software as released from the author (e.g. 2.7.1). - -.TP -.B pkgrel -This is the release number specific to the \*(DSs release. This allows package -maintainers to make updates to the package's configure flags, for example. - -.TP -.B pkgdesc -This should be a brief description of the package and its functionality. Try to -keep the description to one line of text. - -.TP -.B url -This field contains a URL that is associated with the software being packaged. -This is typically the project's website. - -.TP -.B license (array) -This field specifies the license(s) that apply to the package. Commonly-used -licenses are found in \fI/usr/share/licenses/common\fP. If you see the -package's license there, simply reference it in the license field (e.g. -\fBlicense=("GPL")\fP). If the package provides a license not found in -\fI/usr/share/licenses/common\fP, then you should include the license in the -package itself and set \fBlicense=("custom")\fP or -\fBlicense=("custom:LicenseName")\fP. The license should be placed in -\fI$startdir/pkg/usr/share/licenses/$pkgname\fP when building the package. If -multiple licenses are applicable for a package, list all of them: -\fBlicenses=('GPL' 'FDL')\fP. - -.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 \fB\*(PB\fP, and will be copied -into the package by \fBmakepkg\fP. It does not need to be included in the -\fIsource\fP array (e.g. \fBinstall=pkgname.install\fP). - -.TP -.B source \fI(array)\fP -An array of source files required to build the package. Source files must -either reside in the same directory as the \fB\*(PB file\fP, or be a -fully-qualified URL that makepkg will use to download the file. In order to -make the PKGBUILD as useful as possible, use the \fB$pkgname\fP and -\fB$pkgver\fP variables if possible when specifying the download location. - -.TP -.B noextract \fI(array)\fP -An array of filenames corresponding to those from the \fBsource\fP array. Files -listed here will not be extracted with the rest of the source files. This is -useful for packages which use compressed data which is downloaded but not -necessary to uncompress. - -.TP -.B md5sums \fI(array)\fP -This array contains an MD5 hash for every source file specified in the -\fBsource\fP array (in the same order). \fBmakepkg\fP will use this to verify -source file integrity during subsequent builds. To easily generate md5sums, run -"makepkg -g >> \*(PB". If desired, move the \fBmd5sums\fP line to an -appropriate location. NOTE: \fBmakepkg\fP supports multiple integrity -algorithms and their corresponding arrays (i.e. sha1sums for the SHA1 -algorithm); however, official packages use only md5sums for the time being. - -.TP -.B sha1sums, etc. -Alternative integrity checks that \fBmakepkg\fP supports, as noted in -\fBmd5sums\fP above. - -.TP -.B groups \fI(array)\fP -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 arch \fI(array)\fP -Defines on which architectures the given package is available (e.g. -\fBarch=('i686' 'x86_64')\fP). - -.TP -.B backup \fI(array)\fP -A space-delimited array of filenames, \fIwithout\fP preceding slashes, that -should be backed up if the package is removed or upgraded. This is commonly -used for packages placing configuration files in /etc. See \fBHANDLING CONFIG -FILES\fP in the \fBpacman\fP manpage for more information. - -.TP -.B depends \fI(array)\fP -An array of packages that this package depends on to run. Packages in this list -should be surrounded with single quotes and contain at least the package name. -Entries can also include a version requirement of the form -\fB'name<>version'\fP, where <> is one of three comparisons: \fI>=\fP (greater -than or equal to), \fI<=\fP (less than or equal to), or \fI=\fP (equal to). - -.TP -.B makedepends \fI(array)\fP -An array of packages that this package depends on to build, but are not needed -at runtime. Packages in this list follow the same format as \fBdepends\fP. - -.TP -.B conflicts \fI(array)\fP -An array of packages that will conflict with this package (i.e. they cannot -both be installed at the same time). This directive follows the same format as -\fIdepends\fP, except you cannot specify versions. - -.TP -.B provides \fI(array)\fP -An array of "virtual provisions" that this package provides. This allows a -package to provide dependencies other than its own package name. For example, -the dcron package can provide 'cron', which allows packages to depend on 'cron' -rather than 'dcron OR fcron'. - -.TP -.B replaces \fI(array)\fP -An array of packages that this package should replace, and can be used to -handle renamed/combined packages. For example, if the 'j2re' package is renamed -to 'jre', this directive allows future upgrades to continue as expected even -though the package has moved. - -.TP -.B options \fI(array)\fP -This array allows you to override some of \fBmakepkg\fP's default behavior when -building packages. To set an option, just include the option name in the -\fBoptions\fP array. To reverse the default behavior, place an "!" at the front -of the option. Only specify the options you specifically want to override, the -rest will be taken from \fBmakepkg.conf\fP. NOTE: 'force' is a special option -only used in \fB\*(PB\fPs, do not use it unless you know what you are doing. -.RS -.TP -.B strip -Strip symbols from binaries and libraries. If you frequently use a debugger on -programs or libraries, it may be helpful to disable this option. -.TP -.B docs -Save doc and info directories. If you wish to delete doc and info directories, -specify "!docs" in the array. -.TP -.B libtool -Leave libtool (.la) files in packages. Specify "!libtool" to remove them. -.TP -.B emptydirs -Leave empty directories in packages. -.TP -.B ccache -Allow the use of \fBccache\fP during build. More useful in its negative form -"!ccache" with select packages that have problems building with \fBccache\fP. -.TP -.B distcc -Allow the use of \fBdistcc\fP during build. More useful in its negative form -"!distcc" with select packages that have problems building with \fBdistcc\fP. -.TP -.B makeflags -Allow the use of user-specific makeflags during build as specified in -\fBmakepkg.conf\fP. More useful in its negative form "!makeflags" with select -packages that have problems building with custom makeflags such as "-j2" (or -higher). -.TP -.B force -Force the package to be upgraded by a \fBpacman\fP system upgrade operation, -even if the version number would normally not trigger such an upgrade. This is -useful when the version numbering scheme of a package changes (or is -alphanumeric). -.RE - -.SH INSTALL/UPGRADE/REMOVE SCRIPTING -\fBPacman\fP 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. - -.P -To use this feature, create a file such as 'pkgname.install' and put it in -the same directory as the \fB\*(PB\fP script. Then use the \fBinstall\fP -directive: - -.RS -.nf -install=pkgname.install -.fi -.RE - -The install script does not need to be specified in the \fBsource\fP array. -A template install file is available in the ABS tree (/var/abs/install.proto). - -.SH EXAMPLE -The following is an example \fB\*(PB\fP for the 'modutils' package. For more -examples, look through the ABS tree. - -.nf -# Maintainer: John Doe <johndoe@archlinux.org> -# Contributor: Bill Smith <billsmith@archlinux.org> -pkgname=modutils -pkgver=2.4.25 -pkgrel=1 -pkgdesc="Utilities for inserting modules in the linux kernel" -url="http://www.kernel.org" -makedepends=('bash' 'mawk') -depends=('glibc' 'zlib') -backup=(etc/modules.conf) -source=(ftp://ftp.kernel.org/pub/linux/utils/kernel/$pkgname/v2.4/$pkgname-$pkgver.tar.bz2 - modules.conf) -arch=('i686') -license=('GPL' 'custom') # dual licensed -md5sums=('2c0cca3ef6330a187c6ef4fe41ecaa4d' - '35175bee593a7cc7d6205584a94d8625') -options=(!libtool) - -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 - -.SH SEE ALSO -.BR makepkg (8), -.BR pacman (8), -.BR makepkg.conf (5) - -See the Arch Linux website at <http://www.archlinux.org> for more current -information on the distribution and the \fBpacman\fP family of tools, and -<http://wiki.archlinux.org/index.php/Arch_Packaging_Standards> for -recommendations on packaging standards. - -.SH AUTHORS -.nf -Judd Vinet <jvinet@zeroflux.org> -Aurelien Foret <aurelien@archlinux.org> -Aaron Griffin <aaron@archlinux.org> -Dan McGee <dan@archlinux.org> -.fi - -See the 'AUTHORS' file for additional contributors. diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt new file mode 100644 index 00000000..be3f1169 --- /dev/null +++ b/doc/PKGBUILD.5.txt @@ -0,0 +1,239 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +PKGBUILD(5) +=========== + +Name +---- +PKGBUILD - Arch Linux package build description file + + +Synopsis +-------- +PKGBUILD + + +Description +----------- +This manual page is meant to describe general rules about PKGBUILDs. Once a +PKGBUILD is written, the actual package is built using makepkg and installed +with pacman. + +NOTE: 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 abs +script included with pacman. + + +Options and Directives +---------------------- +*pkgname*:: + The name of the package. This has be a unix-friendly name as it will be + used in the package filename. + +*pkgver*:: + The version of the software as released from the author (e.g. \'2.7.1'). + +*pkgrel*:: + This is the release number specific to the Arch Linuxs release. This + allows package maintainers to make updates to the package's configure + flags, for example. + +*pkgdesc*:: + This should be a brief description of the package and its functionality. + Try to keep the description to one line of text. + +*url*:: + This field contains a URL that is associated with the software being + packaged. This is typically the project's website. + +*license (array)*:: + This field specifies the license(s) that apply to the package. + Commonly-used licenses are found in '/usr/share/licenses/common'. If you + see the package's license there, simply reference it in the license + field (e.g. `$$license=('GPL')$$`). If the package provides a license not + found in '/usr/share/licenses/common', then you should include the license + in the package itself and set `$$license=('custom')$$` or + `$$license=('custom:LicenseName')$$`. The license should be placed in + '$pkgdir/usr/share/licenses/$pkgname' when building the package. If + multiple licenses are applicable for a package, list all of them: + `$$license=('GPL' 'FDL')$$`. + +*install*:: + Specifies a special install script that is to be included in the package. + This file should reside in the same directory as the PKGBUILD, and will + be copied into the package by makepkg. It does not need to be included + in the source array (e.g. `$$install=pkgname.install$$`). + +*source (array)*:: + An array of source files required to build the package. Source files + must either reside in the same directory as the PKGBUILD file, or be a + fully-qualified URL that makepkg will use to download the file. In order + to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver + variables if possible when specifying the download location. + +*noextract (array)*:: + An array of filenames corresponding to those from the source array. Files + listed here will not be extracted with the rest of the source files. This + is useful for packages which use compressed data which is downloaded but + not necessary to uncompress. + +*md5sums (array)*:: + This array contains an MD5 hash for every source file specified in the + source array (in the same order). makepkg will use this to verify source + file integrity during subsequent builds. To easily generate md5sums, run + ``makepkg -g >> PKGBUILD''. If desired, move the md5sums line to an + appropriate location. *NOTE:* makepkg supports multiple integrity + algorithms and their corresponding arrays (i.e. sha1sums for the SHA1 + algorithm); however, official packages use only md5sums for the time + being. + +*sha1sums, etc.*:: + Alternative integrity checks that makepkg supports, as noted in md5sums + above. + +*groups (array)*:: + An array of symbolic names that represent groups of packages, allowing + you to install multiple packages by requesting a single target. For + example, one could install all KDE packages by installing the 'kde' group. + +*arch (array)*:: + Defines on which architectures the given package is available (e.g. + `$$arch=('i686' 'x86_64')$$`). + +*backup (array)*:: + A space-delimited array of filenames, without preceding slashes, that + should be backed up if the package is removed or upgraded. This is + commonly used for packages placing configuration files in /etc. See + Handling Config Files in manlink:pacman[8] for more information. + +*depends (array)*:: + An array of packages that this package depends on to run. Packages in + this list should be surrounded with single quotes and contain at least + the package name. Entries can also include a version requirement of the + form 'name<>version', where <> is one of three comparisons: >= (greater + than or equal to), <= (less than or equal to), or = (equal to). + +*makedepends (array)*:: + An array of packages that this package depends on to build, but are not + needed at runtime. Packages in this list follow the same format as + depends. + +*conflicts (array)*:: + An array of packages that will conflict with this package (i.e. they + cannot both be installed at the same time). This directive follows the + same format as depends, except you cannot specify versions. + +*provides (array)*:: + An array of ``virtual provisions'' that this package provides. This allows + a package to provide dependencies other than its own package name. For + example, the dcron package can provide 'cron', which allows packages to + depend on 'cron' rather than 'dcron OR fcron'. + +*replaces (array)*:: + An array of packages that this package should replace, and can be used + to handle renamed/combined packages. For example, if the 'j2re' package + is renamed to 'jre', this directive allows future upgrades to continue + as expected even though the package has moved. Sysupgrade is currently + the only pacman operation that utilizes this field, a normal sync will + not use its value. + +*options (array)*:: + This array allows you to override some of makepkg's default behavior + when building packages. To set an option, just include the option name + in the options array. To reverse the default behavior, place an ``!'' at + the front of the option. Only specify the options you specifically want + to override, the rest will be taken from manlink:makepkg.conf[5]. + *NOTE:* 'force' is a special option only used in a manlink:PKGBUILD[5], + do not use it unless you know what you are doing. + + *strip*;; + Strip symbols from binaries and libraries. If you frequently + use a debugger on programs or libraries, it may be helpful to + disable this option. + + *docs*;; + Save doc and info directories. If you wish to delete doc and + info directories, specify `!docs` in the array. + + *libtool*;; + Leave libtool (.la) files in packages. Specify `!libtool` to + remove them. + + *emptydirs*;; + Leave empty directories in packages. + + *ccache*;; + Allow the use of ccache during build. More useful in its negative + form `!ccache` with select packages that have problems building + with ccache. + + *distcc*;; + Allow the use of distcc during build. More useful in its negative + form `!distcc` with select packages that have problems building + with distcc. + + *makeflags*;; + Allow the use of user-specific makeflags during build as specified + in manlink:makepkg.conf[5]. More useful in its negative form + `!makeflags` with select packages that have problems building with + custom makeflags such as `-j2` (or higher). + + *force*;; + Force the package to be upgraded by a pacman system upgrade + operation, even if the version number would normally not trigger + such an upgrade. This is useful when the version numbering scheme + of a package changes (or is alphanumeric). + + +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: + +*pre_install*:: + script is run right before files are extracted. + +*post_install*:: + script is run right after files are extracted. + +*pre_upgrade*:: + script is run right before files are extracted. + +*post_upgrade*:: + script is run after files are extracted. + +*pre_remove*:: + script is run right before files are removed. + +*post_remove*:: + script is run right after files are removed. + +To use this feature, create a file such as 'pkgname.install' and put it in the +same directory as the PKGBUILD script. Then use the install directive: + + install=pkgname.install + +The install script does not need to be specified in the source array. A template +install file is available in the ABS tree (/var/abs/install.proto). + + +Example +------- +The following is an example PKGBUILD for the 'module-init-tools' package. For more +examples, look through the ABS tree. + +----- +include::PKGBUILD-example.txt[] +----- + + +See Also +-------- +manlink:makepkg[8], manlink:pacman[8], manlink:makepkg.conf[5] + +include::footer.txt[] diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf new file mode 100644 index 00000000..92e01179 --- /dev/null +++ b/doc/asciidoc.conf @@ -0,0 +1,64 @@ +# +# Inspired by/borrowed from the GIT source tree at Documentation/asciidoc.conf +# + +## manlink: macro +# +# Usage: manlink:command[manpage-section] +# +# Note, {0} is the manpage section, while {target} is the command. +# +# Show man link as: <command>(<section>); if section is defined, else just show +# the command. + +[attributes] +plus=+ +caret=^ +startsb=[ +endsb=] +tilde=~ + +ifdef::backend-docbook[] +[manlink-inlinemacro] +{0%{target}} +{0#<citerefentry>} +{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>} +{0#</citerefentry>} +endif::backend-docbook[] + +ifdef::backend-docbook[] +# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. +[listingblock] +<example><title>{title}</title> +<literallayout> +| +</literallayout> +{title#}</example> +endif::backend-docbook[] + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] +<refentry> +<refentryinfo> +<date>{pacman_date}</date> +</refentryinfo> +<refmeta> +<refentrytitle>{mantitle}</refentrytitle> +<manvolnum>{manvolnum}</manvolnum> +<refmiscinfo class="source">Pacman</refmiscinfo> +<refmiscinfo class="version">{pacman_version}</refmiscinfo> +<refmiscinfo class="manual">Pacman Manual</refmiscinfo> +</refmeta> +<refnamediv> + <refname>{manname}</refname> + <refpurpose>{manpurpose}</refpurpose> +</refnamediv> +endif::backend-docbook[] +endif::doctype-manpage[] + +ifdef::backend-xhtml11[] +[manlink-inlinemacro] +<a href="{target}.{0}.html">{target}{0?({0})}</a> +endif::backend-xhtml11[] diff --git a/doc/footer.txt b/doc/footer.txt new file mode 100644 index 00000000..d1ee9d1e --- /dev/null +++ b/doc/footer.txt @@ -0,0 +1,24 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +See the Arch Linux website at <http://www.archlinux.org> for more current +information on the distribution and the pacman family of tools, and +<http://wiki.archlinux.org/index.php/Arch_Packaging_Standards> for +recommendations on packaging standards. + + +Bugs +---- +Bugs? You must be kidding, there are no bugs in this software. But if we +happen to be wrong, send us an email with as much detail as possible to +<pacman-dev@archlinux.org>. + + +Authors +------- +* Judd Vinet <jvinet@zeroflux.org> +* Aurelien Foret <aurelien@archlinux.org> +* Aaron Griffin <aaron@archlinux.org> +* Dan McGee <dan@archlinux.org> + +See the 'AUTHORS' file for additional contributors. diff --git a/doc/libalpm.3 b/doc/libalpm.3 deleted file mode 100644 index e78e9eca..00000000 --- a/doc/libalpm.3 +++ /dev/null @@ -1,53 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.ds LV 1.0.0 -.TH libalpm 3 "Feb 08, 2007" "libalpm version \*(LV" "\*(DS Utilities" -.SH NAME - libalpm \- Arch Linux Package Management (ALPM) library - -.SH SYNOPSIS -For ease of access, the libalpm manual has been split up into several sections. - -(TODO) Yes, this man page needs a lot of work. Once we get around to doing good -Doxygen documentation, it will improve. We promise. - -.nf -alpm_databases Database Functions -alpm_interface Interface Functions -alpm_list List Functions -alpm_log Logging Functions -alpm_misc Miscellaneous Functions -alpm_packages Package Functions -alpm_sync Sync Functions -alpm_trans Transaction Functions -.fi - -.SH CONFIGURATION -See -.BR pacman.conf (5) -for more details on configuring \fBlibalpm\fP using the \fBpacman.conf\fP file. - -.SH BUGS -Bugs? You must be kidding, there are no bugs in this software. But if we happen -to be wrong, send us an email with as much detail as possible to -<pacman-dev@archlinux.org>. - -.SH SEE ALSO -.BR pacman (8), -.BR makepkg (8), -.BR pacman.conf (5) - -See the Arch Linux website at <http://www.archlinux.org> for more current -information on the distribution and the \fBpacman\fP family of tools. - -.SH AUTHORS -.nf -Judd Vinet <jvinet@zeroflux.org> -Aurelien Foret <aurelien@archlinux.org> -Aaron Griffin <aaron@archlinux.org> -Dan McGee <dan@archlinux.org> -.fi - -See the 'AUTHORS' file for additional contributors. diff --git a/doc/libalpm.3.txt b/doc/libalpm.3.txt new file mode 100644 index 00000000..d8fb58e8 --- /dev/null +++ b/doc/libalpm.3.txt @@ -0,0 +1,39 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +libalpm(3) +========== + +Name +---- +libalpm - Arch Linux Package Management (ALPM) library + + +Synopsis +-------- +For ease of access, the libalpm manual has been split up into several sections. + +*TODO:* Yes, this man page needs a lot of work. Once we get around to doing +good Doxygen documentation, it will improve. We promise. + +*alpm_databases*:: Database Functions +*alpm_interface*:: Interface Functions +*alpm_list*:: List Functions +*alpm_log*:: Logging Functions +*alpm_misc*:: Miscellaneous Functions +*alpm_packages*:: Package Functions +*alpm_sync*:: Sync Functions +*alpm_trans*:: Transaction Functions + + +Configuration +------------- +See manlink:pacman.conf[5] for more details on configuring libalpm using the +'pacman.conf' file. + + +See Also +-------- +manlink:pacman[8], manlink:makepkg[8], manlink:pacman.conf[5] + +include::footer.txt[] diff --git a/doc/makepkg.8 b/doc/makepkg.8 deleted file mode 100644 index 9135be21..00000000 --- a/doc/makepkg.8 +++ /dev/null @@ -1,146 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.TH makepkg 8 "Feb 07, 2007" "makepkg version \*(VR" "\*(DS Utilities" -.SH NAME -makepkg \- package build utility - -.SH SYNOPSIS -.B makepkg -[\fIoptions\fR] - -.SH DESCRIPTION -\fBmakepkg\fP is a script to automate the building of packages. All it needs is -a build-capable Linux platform and a custom build script for each package you -wish to build (known as a \fB\*(PB\fP). See -.BR \*(PB (5) -for details on creating your own build scripts. - -The advantage to a script-based build is that the work is only done once. Once -you have the build script for a package, makepkg will do the rest: download and -validate source files, check dependencies, configure the build-time 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 \fBmakepkg\fP finds missing -build-time or run-time dependencies, it will look for the dependencies' -\fB\*(PB\fP files under \fIABSROOT\fP (set in \fBmakepkg.conf\fP). If it finds -them it will call \fBmakepkg\fP to build and install the missing dependencies. -The child calls will be made with the \fB-b\fP and \fB-i\fP options. -.TP -.B \-c, --clean -Clean up leftover work files and directories after a successful build. -.TP -.B \-C, --cleancache -Removes all cached source files from the directory specified in \fISRCDEST\fP -in \fBmakepkg.conf\fP. -.TP -.B \-d, --nodeps -Do not perform any dependency checks. This will let you override and ignore any -dependencies required. There is a good chance this option will break the build -process if all of the dependencies are not installed. -.TP -.B \-e, --noextract -Do not extract source files; use whatever source already exists in the src/ -directory. This is handy if you want to go into src and manually patch or tweak -code, then make a package out of the result. Keep in mind that creating a patch -may be a better solution to allow others to use your \fB\*(PB\fP. -.TP -.B \-f, --force -\fBmakepkg\fP will not build a package if a built package already exists in the -\fIPKGDEST\fP (set in \fBmakepkg.conf\fP) directory, which may default to the -current directory. This allows the built package to be overwritten. -.TP -.B \-g, --geninteg -For each source file in the source array of \fB\*(PB\fP, download the file if -required and generate integrity checks. The integrity checks generated are -determined by the value of the \fIINTEGRITY_CHECK\fP array in makepkg.conf. -This output can be redirected into your \fB\*(PB\fP for source validation -(makepkg -g >> \*(PB). -.TP -.B \-h, --help -Output syntax and command line options. -.TP -.B \-i, --install -Install or upgrade the package after a successful build using \fBpacman\fP. -.TP -.B \-L, --log -Log the package build progress to a file. This file is stored in the build -directory with a name similar to that of the built package. -.TP -.B \-m, --nocolor -Disable color in output messages. -.TP -.B \-o, --nobuild -Download and extract files only, but do not build them. Useful with the -\fB--noextract\fP option if you wish to tweak the files in src/ before -building. -.TP -.B \-p \fIbuildscript\fP -Read the package script \fIbuildscript\fP instead of the default, \fI\*(PB\fP. -.TP -.B \-r, --rmdeps -Upon successful build, remove any dependencies installed by \fBmakepkg\fP -during dependency auto-resolution (using \fB-b\fP or \fB-s\fP). -.TP -.B \-R, --repackage -Repackage contents of pkg/ without rebuilding the package. This is useful if -you forgot a depend or install file in your \fB\*(PB\fP and the build itself -will not change. -.TP -.B \-s, --syncdeps -Install missing dependencies using \fBpacman\fP. When missing build-time or -run-time dependencies are found, \fBpacman\fP will try to resolve them. If -successful, the missing packages will be downloaded and installed. -.TP -.B \--asroot -This option allows you to run \fBmakepkg\fP as root. You should not normally -run \fBmakepkg\fP as root unless you know what you are doing. For any -operations that require \fBpacman\fP, \fBsudo\fP is normally used; this switch -will call \fBpacman\fP directly. -.TP -.B \--noconfirm -(Passed to \fBpacman\fP) Prevent \fBpacman\fP from waiting for user input -before proceeding with operations. -.TP -.B \--noprogressbar -(Passed to \fBpacman\fP) Prevent \fBpacman\fP from displaying a progress bar; -useful if you are redirecting makepkg output to file. - -.SH CONFIGURATION -See -.BR makepkg.conf (5) -for more details on configuring \fBmakepkg\fP using the \fBmakepkg.conf\fP file. - -.SH BUGS -Bugs? You must be kidding, there are no bugs in this software. But if we happen -to be wrong, send us an email with as much detail as possible to -<pacman-dev@archlinux.org>. - -.SH SEE ALSO -.BR makepkg.conf (5), -.BR \*(PB (5), -.BR pacman (8) - -See the Arch Linux website at <http://www.archlinux.org> for more current -information on the distribution and the \fBpacman\fP family of tools, and -<http://wiki.archlinux.org/index.php/Arch_Packaging_Standards> for -recommendations on packaging standards. - -.SH AUTHORS -.nf -Judd Vinet <jvinet@zeroflux.org> -Aurelien Foret <aurelien@archlinux.org> -Aaron Griffin <aaron@archlinux.org> -Dan McGee <dan@archlinux.org> -.fi - -See the 'AUTHORS' file for additional contributors. diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt new file mode 100644 index 00000000..02d29f32 --- /dev/null +++ b/doc/makepkg.8.txt @@ -0,0 +1,143 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +makepkg(8) +========== + +Name +---- +makepkg - package build utility + + +Synopsis +-------- +makepkg [options] + + +Description +----------- +makepkg is a script to automate the building of packages. All it needs is a +build-capable Linux platform and a custom build script for each package you +wish to build (known as a PKGBUILD). See manlink:PKGBUILD[5] for details on +creating your own build scripts. + +The advantage to a script-based build is that the work is only done once. Once +you have the build script for a package, makepkg will do the rest: download and +validate source files, check dependencies, configure the build-time settings, +build the package, install the package into a temporary root, make +customizations, generate meta-info, and package the whole thing up for pacman +to use. + +makeworld can be used to rebuild an entire package group or the entire build +tree. See `makeworld \--help` for syntax. + +Options +------- +*-A, \--ignorearch*:: + Ignore a missing or incomplete arch field in the build script. This is + for rebuilding packages from source when the PKGBUILD may be slightly + outdated and not updated with an `$$arch=('yourarch')$$` field. + +*-b, \--builddeps*:: + Build missing dependencies from source. When makepkg finds missing + build-time or run-time dependencies, it will look for the dependencies' + PKGBUILD files under ABSROOT (set in makepkg.conf). If it finds them it + will call makepkg to build and install the missing dependencies. The + child calls will be made with the `-b` and `-i` options. + +*-c, \--clean*:: + Clean up leftover work files and directories after a successful build. + +*-C, \--cleancache*:: + Removes all cached source files from the directory specified in SRCDEST + in manlink:makepkg.conf[5]. + +*-d, \--nodeps*:: + Do not perform any dependency checks. This will let you override and + ignore any dependencies required. There is a good chance this option + will break the build process if all of the dependencies are not + installed. + +*-e, \--noextract*:: + Do not extract source files; use whatever source already exists in the + src/ directory. This is handy if you want to go into src and manually + patch or tweak code, then make a package out of the result. Keep in mind + that creating a patch may be a better solution to allow others to use + your PKGBUILD. + +*-f, \--force*:: + makepkg will not build a package if a built package already exists in + the PKGDEST (set in manlink:makepkg.conf[5]) directory, which may + default to the current directory. This allows the built package to be + overwritten. + +*-g, \--geninteg*:: + For each source file in the source array of PKGBUILD, download the file + if required and generate integrity checks. The integrity checks + generated are determined by the value of the INTEGRITY_CHECK array in + manlink:makepkg.conf[5]. This output can be redirected into your + PKGBUILD for source validation (`makepkg -g >> PKGBUILD`). + +*-h, \--help*:: + Output syntax and command line options. + +*-i, \--install*:: + Install or upgrade the package after a successful build using + manlink:pacman[8]. + +*-m, \--nocolor*:: + Disable color in output messages. + +*-o, \--nobuild*:: + Download and extract files only, but do not build them. Useful with the + `\--noextract` option if you wish to tweak the files in src/ before + building. + +*-p* <`buildscript`>:: + Read the package script `buildscript` instead of the default, see + manlink:PKGBUILD[5]. + +*-r, \--rmdeps*:: + Upon successful build, remove any dependencies installed by makepkg + during dependency auto-resolution (using `-b` or `-s`). + +*-R, \--repackage*:: + Repackage contents of pkg/ without rebuilding the package. This is + useful if you forgot a depend or install file in your PKGBUILD and the + build itself will not change. + +*-s, \--syncdeps*:: + Install missing dependencies using pacman. When missing build-time or + run-time dependencies are found, pacman will try to resolve them. If + successful, the missing packages will be downloaded and installed. + +*\--asroot*:: + Allow makepkg to run as root. This is for security purposes as it is + normally dangerous to do so. This will also disable use of fakeroot and + sudo. + +*\--source*:: + Do not actually build the package, but build a source-only tarball. This + is useful for passing a single tarball to another program such as a + chroot, remote builder, or an AUR upload. + +*\--noconfirm*:: + (Passed to pacman) Prevent pacman from waiting for user input before + proceeding with operations. + +*\--noprogressbar*:: + (Passed to pacman) Prevent pacman from displaying a progress bar; + useful if you are redirecting makepkg output to file. + + +Configuration +------------- +See manlink:makepkg.conf[5] for more details on configuring makepkg using the +'makepkg.conf' file. + + +See Also +-------- +manlink:makepkg.conf[5], manlink:PKGBUILD[5], manlink:pacman[8] + +include::footer.txt[] diff --git a/doc/makepkg.conf.5 b/doc/makepkg.conf.5 deleted file mode 100644 index 08be3fc8..00000000 --- a/doc/makepkg.conf.5 +++ /dev/null @@ -1,152 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.TH \*(PB 5 "Feb 08, 2007" "makepkg.conf version \*(VR" "\*(DS Files" -.SH NAME -makepkg.conf \- makepkg configuration file - -.SH DESCRIPTION -Configuration options for \fBmakekpg\fP are stored in \fBmakepkg.conf\fP. This -file is sourced, so you can include 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 non-standard... - -The default file is fairly well commented, so it may be easiest to simply -follow directions given there for customization. - -.SH OPTIONS -.TP -.B FTPAGENT="\fI/path/to/command\fP [\fIoptions\fP]" -Sets the download agent used to fetch source files specified with a URL in the -\fB\*(PB\fP file. Flags can be specified as well; the download URL is then -placed on the end of the command. -.TP -.B CARCH="\fIcarch\fP" -Specifies your computer architecture; possible values include such things as -"i686", "x86_64", "ppc", etc. This should be automatically set on installation. -.TP -.B CHOST="\fIchost\fP" -A string such as "i686-pc-linux-gnu", do not touch unless you know what you are -doing. -.TP -.B CFLAGS="\fIcflags\fP" -Flags used for the C compiler. This is a key part to the use of makepkg. -Usually several options are specified, and the most common string resembles -something like this: "-march=i686 -O2 -pipe". Another useful option may be --mcpu in place of -march. Read -.BR gcc (1) -for more details on the wide variety of compiler flags available. -.TP -.B CXXFLAGS="\fIcxxflags\fP" -Flags used for the C++ compiler; see \fBCFLAGS\fP for more info. -.TP -.B MAKEFLAGS="\fImakeflags\fP" -This is often used to set the number of jobs used, for example, "-j2". Other -flags that make accepts can also be passed. -.TP -.B BUILDENV=(fakeroot !distcc color !ccache !xdelta) -This array contains options that affect the build environment, the defaults -are shown here. All options should always be left in the array; to enable or -disable an option simply remove or place an "!" at the front of the option. -Each works as follows: -.RS -.TP -.B fakeroot -Allow building packages as a non-root user. This is \fIhighly\fP recommended. -.TP -.B distcc -Use the distributed C/C++/ObjC compiler to spread compilation among multiple -machines. If this is enabled, \fBDISTCC_HOSTS\fP must be specified as well. -.TP -.B color -Colorize output messages, making output easier to read. -.TP -.B ccache -Use ccache to cache compilation by default. This allows for faster compiles if -you are continuously recompiling the same packages. It can be disabled for -individual packages by placing \fB!ccache\fP in the \fB\*(PB\fP options array. -.TP -.B xdelta -Generate delta patch from previous to current package. This is mainly useful -for large package upgrades that have only minor changes between versions where -a binary diff will be a much smaller download. This is only useful if using -the xdelta download script for pacman. -.RE -.TP -.B DISTCC_HOSTS="\fIhost1 ...\fP" -If using DistCC, this is used to specify a space-delimited list of hosts -running in the DistCC cluster. In addition, you will want to modify your -\fBMAKEFLAGS\fP. -.TP -.B OPTIONS=(strip !docs libtool emptydirs) -This array contains four options that affect the default packaging. All four -are equivalent to options that can be placed in the PKGBUILD; the defaults are -shown here. All options should always be left in the array; to enable or -disable an option simply remove or place an "!" at the front of the option. -Each works as follows: -.RS -.TP -.B strip -Strip symbols from binaries and libraries. If you frequently use a debugger on -programs or libraries, it may be helpful to disable this option. -.TP -.B docs -Save doc and info directories. If you wish to delete doc and info directories, -specify "!docs" in the array. -.TP -.B libtool -Leave libtool (.la) files in packages. Specify "!libtool" to remove them. -.TP -.B emptydirs -Leave empty directories in packages. -.RE -.TP -.B INTEGRITY_CHECK=(\fIcheck1 ...\fP) -File integrity checks to use. Multiple checks may be specified; this affects -both generation and checking. The current valid options are: md5, sha1, sha256, -sha384, and sha512. -.TP -.B DOC_DIRS=(usr/{,share/}{info,doc} ...) -If "!docs" is specified in the \fBOPTIONS\fP array, this variable will instruct -makepkg where to look to remove docs. If you build packages that are located in -opt/, you may need to add the directory to this array. NOTE: do not add the -leading slash to the directory name. -.TP -.B PKGDEST=\fI/path/to/folder\fP -If this value is not set, packages will by default be placed in the current -directory (location of the \fB\*(PB\fP). Many people like to keep all their -packages in one place so this option allows this behavior. A common location is -"/home/packages". -.TP -.B SRCDEST=\fI/path/to/folder\fP -If this value is not set, downloaded source files will only be stored in the -current directory. Many people like to keep all source files in a central -location for easy cleanup, so this path can be set here. -.TP -.B PACKAGER="\fIJohn Doe <john@doe.com>\fP" -This value is used when querying a package to see who was the builder. It is -recommended you change this to your name and email address. - -.SH SEE ALSO -.BR makepkg (8), -.BR pacman (8), -.BR \*(PB (5) - -See the Arch Linux website at <http://www.archlinux.org> for more current -information on the distribution and the \fBpacman\fP family of tools, and -<http://wiki.archlinux.org/index.php/Arch_Packaging_Standards> for -recommendations on packaging standards. - -.SH AUTHORS -.nf -Judd Vinet <jvinet@zeroflux.org> -Aurelien Foret <aurelien@archlinux.org> -Aaron Griffin <aaron@archlinux.org> -Dan McGee <dan@archlinux.org> -.fi - -See the 'AUTHORS' file for additional contributors. diff --git a/doc/makepkg.conf.5.txt b/doc/makepkg.conf.5.txt new file mode 100644 index 00000000..17e4bd87 --- /dev/null +++ b/doc/makepkg.conf.5.txt @@ -0,0 +1,154 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +makepkg.conf(5) +=============== + +Name +---- +makepkg.conf - makepkg configuration file + + +Synopsis +-------- +{sysconfdir}/makepkg.conf, ~/.makepkg.conf + + +Description +----------- +Configuration options for makekpg are stored in makepkg.conf. This file is +sourced, so you can include any special compiler flags you wish to use. This is +helpful for building for different architectures, or with different +optimizations. However, only the variables described below are exported to the +build environment. + +NOTE: This does not guarantee that all package Makefiles will use your exported +variables. Some of them are non-standard. + +The default file is fairly well commented, so it may be easiest to simply +follow directions given there for customization. + + +Options +------- +**DLAGENTS=(**\'protocol::/path/to/command [options]' ...**)**:: + Sets the download agents used to fetch source files specified with a URL in + the manlink:PKGBUILD[5] file. Options can be specified for each command as + well; the download URL is placed on the end of the command. This is more + flexible than the former `FTPAGENT` variable, as any protocol can have a + download agent. Several examples are provided in the default makepkg.conf. + +**CARCH=**"carch":: + Specifies your computer architecture; possible values include such things + as ``i686'', ``x86_64'', ``ppc'', etc. This should be automatically set on + installation. + +**CHOST=**"chost":: + A string such as ``i686-pc-linux-gnu'', do not touch unless you know what + you are doing. This can be commented out by most users if desired. + +**CFLAGS=**"cflags":: + Flags used for the C compiler. This is a key part to the use of makepkg. + Usually several options are specified, and the most common string resembles + something like this: ``-march=i686 -O2 -pipe''. Another useful option may + be `-mcpu` in place of `-march`. Read gcc(1) for more details on the wide + variety of compiler flags available. + +**CXXFLAGS=**"cxxflags":: + Flags used for the C++ compiler; see CFLAGS for more info. + +**MAKEFLAGS=**"makeflags":: + This is often used to set the number of jobs used, for example, `-j2`. + Other flags that make accepts can also be passed. + +**BUILDENV=(**fakeroot !distcc color !ccache !xdelta**)**:: + This array contains options that affect the build environment, the defaults + are shown here. All options should always be left in the array; to enable + or disable an option simply remove or place an ``!'' at the front of the + option. Each works as follows: + + *fakeroot*;; + Allow building packages as a non-root user. This is highly recommended. + + *distcc*;; + Use the distributed C/C++/ObjC compiler to spread compilation among + multiple machines. If this is enabled, `DISTCC_HOSTS` must be specified + as well. + + *color*;; + Colorize output messages, making output easier to read. + + *ccache*;; + Use ccache to cache compilation by default. This allows for faster + compiles if you are continuously recompiling the same packages. It can + be disabled for individual packages by placing `!ccache` in the + PKGBUILD options array. + + *xdelta*;; + Generate an xdelta binary patch from previous to current package. The + previous package must be available in the makepkg cache directory for + this to occur. + +**DISTCC_HOSTS=**"host1 ...":: + If using DistCC, this is used to specify a space-delimited list of hosts + running in the DistCC cluster. In addition, you will want to modify your + `MAKEFLAGS`. + +**OPTIONS=(**strip !docs libtool emptydirs**)**:: + This array contains options that affect the default packaging. All four are + equivalent to options that can be placed in the PKGBUILD; the defaults are + shown here. All options should always be left in the array; to enable or + disable an option simply remove or place an ``!'' at the front of the + option. Each works as follows: + + *strip*;; + Strip symbols from binaries and libraries. If you frequently use a + debugger on programs or libraries, it may be helpful to disable this + option. + + *docs*;; + Save doc and info directories. If you wish to delete doc and info + directories, specify `!docs' in the array. + + *libtool*;; + Leave libtool (.la) files in packages. Specify `!libtool' to remove + them. + + *emptydirs*;; + Leave empty directories in packages. + +**INTEGRITY_CHECK=(**check1 ...**)**:: + File integrity checks to use. Multiple checks may be specified; this + affects both generation and checking. The current valid options are: + `md5`, `sha1`, `sha256`, `sha384`, and `sha512`. + +**DOC_DIRS=(**usr/{,share/}{info,doc} ...**)**:: + If "!docs" is specified in the OPTIONS array, this variable will + instruct makepkg where to look to remove docs. If you build packages + that are located in opt/, you may need to add the directory to this + array. *NOTE:* Do not add the leading slash to the directory name. + +**PKGDEST=**"/path/to/folder":: + If this value is not set, packages will by default be placed in the + current directory (location of the manlink:PKGBUILD[5]). Many people + like to keep all their packages in one place so this option allows + this behavior. A common location is ``/home/packages''. + +**SRCDEST=**"/path/to/folder":: + If this value is not set, downloaded source files will only be stored + in the current directory. Many people like to keep all source files in + a central location for easy cleanup, so this path can be set here. + +**PACKAGER=**"John Doe <john@doe.com>":: + This value is used when querying a package to see who was the builder. + It is recommended you change this to your name and email address. + +*BUILDSCRIPT*, *PKGEXT*, *SRCEXT*, *DB_COMPRESSION*, *DB_CHECKSUMS*:: + Do not touch these unless you know what you are doing. + + +See Also +-------- +manlink:makepkg[8], manlink:pacman[8], manlink:PKGBUILD[5] + +include::footer.txt[] diff --git a/doc/pacman.8 b/doc/pacman.8 deleted file mode 100644 index 79097783..00000000 --- a/doc/pacman.8 +++ /dev/null @@ -1,293 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.ds LV 1.0.0 -.TH pacman 8 "Feb 07, 2007" "pacman version \*(VR" "\*(DS Utilities" -.SH NAME -pacman \- package manager utility - -.SH SYNOPSIS -.B pacman -<\fIoperation\fR> [\fIoptions\fR] [\fIpackages\fR] - -.SH DESCRIPTION -\fBpacman\fP is a \fIpackage management\fP utility that tracks installed -packages on a Linux system. It features dependency support, package groups, -install and uninstall hooks, and the ability to sync your local machine with a -remote ftp server to automatically upgrade packages. \fBpacman\fP packages are -a zipped tar format. - -Since version 3.0.0, \fBpacman\fP has been the frontend to \fBlibalpm\fP, the -"Arch Linux Package Management" library. This library allows alternative front -ends to be written (for instance, a GUI front end). - -.SH OPERATIONS -.TP -.B \-A, --add (deprecated) -Add a package to the system. Either a URL or file path can be specified. The -package will be uncompressed into the installation root and the database will -be updated. The package will not be installed if another version is already -installed. NOTE: please use \fB--upgrade\fP in place of this option. -.TP -.B \-F, --freshen -This is like \fB--upgrade\fP except it will only upgrade packages already -installed on the system. -.TP -.B \-Q, --query -Query the package database. This operation allows you to view installed -packages and their files, as well as meta-information 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 .tar.gz -packages. See \fBQUERY OPTIONS\fP below. -.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 -is used. See \fBREMOVE OPTIONS\fP below. -.TP -.B \-S, --sync -Synchronize packages. Packages are installed directly from the ftp servers, -including all dependencies required to run the packages. For example, -\fBpacman -S qt\fP will download and install \fBqt\fP and all the packages it -depends on. You can also use \fBpacman -Su\fP to upgrade all packages that are -out of date. See \fBSYNC OPTIONS\fP below. -.TP -.B \-U, --upgrade -Upgrade or add a package to the system. Either a URL or file path can be -specified. This is 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 \--ask \fInumber\fP -Pre-specify answers to questions. It is doubtful whether this option even -works, so I would not recommend using it. TODO: document this more, as I have -no idea how it works or when you would use it, or if we should just dump it. -.TP -.B \-b, --dbpath \fIpath\fP -Specify an alternative database location (default is "/var/lib/pacman/"). This -should not be used unless you know what you are doing. -.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. -.TP -.B \-f, --force -Bypass file conflict checks and overwrite 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 \fIpath\fP -Specify an alternative installation root (default is "/"). This should -\fInot\fP be used as a way to install software into /usr/local instead of /usr. -This option is 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 and cache location to use. -.TP -.B \-v, --verbose -Output more status messages, such as the Root and DBPath. -.TP -.B \--cachedir \fIdir\fP -Specify an alternative package cache location (default is -"/var/cache/pacman/pkg/"). This should not be used unless you know what you are -doing. -.TP -.B \--config \fIfilepath\fP -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 \--noprogressbar -Do not show a progress bar when downloading files. This can be useful for -scripts that call pacman and capture the output. -.TP -.B \--noscriptlet -If an install scriptlet exists, do not execute it. Do not use this unless you -know what you are doing. - -.SH QUERY OPTIONS -.TP -.B \-c, --changelog -View the ChangeLog of a package. Not every package will provide one but it -will be shown if available. -.TP -.B \-e, --orphans -List all packages that were pulled in by a previously installed package but no -longer required by any installed package. -.TP -.B \-g, --groups -Display all packages that are members of a named group. If not name is -specified, list all grouped packages. -.TP -.B \-i, --info -Display information on a given package. The \fB-p\fP option can be used if -querying a package file instead of the local database. -.TP -.B \-l, --list -List all files owned by a given 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 \fB--upgrade\fP. -.TP -.B \-o, --owns \fIfile\fP -Search for the package that owns \fIfile\fP. -.TP -.B \-p, --file -Signifies that the package supplied on the command line is a file and not an -entry in the database. The file will be decompressed and queried. This is -useful in combination with \fB--info\fP and \fB--list\fP. -.TP -.B \-s, --search \fIregexp\fP -This will search each locally-installed package for names or descriptions that -matche \fIregexp\fP. -.TP -.B \-u, --upgrades -Lists all packages that are out of date on the local system. This option works -best if the sync database is refreshed using \fB-Sy\fP. - -.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 -removed from the system the database is checked to see if the file should be -renamed with a .pacsave extension. -.TP -.B \-s, --recursive -Remove each target specified including all dependencies, provided that (A) they -are not required by other packages; and (B) they were not explicitly installed -by the user. This option is analogous to a backwards \fB--sync\fP operation. - -.SH SYNC OPTIONS -.TP -.B \-c, --clean -Remove old packages from the cache to free up disk space. When \fBpacman\fP -downloads packages, it saves them in \fI/var/cache/pacman/pkg\fP. Use one -\fB--clean\fP switch to remove \fIold\fP packages; use two to remove \fIall\fP -packages from the cache. -.TP -.B \-e, --dependsonly -Install all dependencies of a package, but not the specified package itself. -This is pretty useless and we're not sure why it even exists. -.TP -.B \-g, --groups -Display all the members for each package group specified. If no group names -are provided, all groups will be listed; pass the flag twice to view all -groups and their members. -.TP -.B \-i, --info -Display dependency and other information for a given package. This will search -through all repositories for a matching package. -.TP -.B \-l, --list -List all packages 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 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 \fIregexp\fP -This will search each package in the sync databases for names or descriptions -that match \fIregexp\fP. -.TP -.B \-u, --sysupgrade -Upgrades all packages that are out of date. Each currently-installed package -will be examined and upgraded if a newer package exists. A report of all -packages to upgrade will be presented and the operation 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 server(s) defined in -\fBpacman.conf\fP. This should typically be used each time you use -\fB--sysupgrade\fP or \fB-u\fP. Passing two \fB--refresh\fP or \fB-y\fP flags -will force a refresh of all package lists even if they are thought to be -up to date. -.TP -.B \--ignore \fIpackage\fP -Directs \fBpacman\fP to ignore upgrades of \fIpackage\fP even if there is one -available. - -.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, 3 md5 hashes are used 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 overwrites are not an issue Install the new -file. -.TP -original=\fBX\fP, current=\fBX\fP, new=\fBY\fP -The current file is the same as the original but the new one differs. Since -the user did not ever modify the file, and the new one may contain improvements -or bugfixes, 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. Leave the current file in place. -.TP -original=\fBX\fP, current=\fBY\fP, new=\fBY\fP -The new file is identical to the current file. Install the new file. -.TP -original=\fBX\fP, current=\fBY\fP, new=\fBZ\fP -All three files are different, so install the new file with a .pacnew extension -and warn the user. The user must then manually merge any necessary changes into -the original file. - -.SH CONFIGURATION -See -.BR pacman.conf (5) -for more details on configuring \fBpacman\fP using the \fBpacman.conf\fP file. - -.SH BUGS -Bugs? You must be kidding, there are no bugs in this software. But if we happen -to be wrong, send us an email with as much detail as possible to -<pacman-dev@archlinux.org>. - -.SH SEE ALSO -.BR pacman.conf (5), -.BR makepkg (8), -.BR libalpm (3) - -See the Arch Linux website at <http://www.archlinux.org> for more current -information on the distribution and the \fBpacman\fP family of tools. - -.SH AUTHORS -.nf -Judd Vinet <jvinet@zeroflux.org> -Aurelien Foret <aurelien@archlinux.org> -Aaron Griffin <aaron@archlinux.org> -Dan McGee <dan@archlinux.org> -.fi - -See the 'AUTHORS' file for additional contributors. diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt new file mode 100644 index 00000000..5e5d2f55 --- /dev/null +++ b/doc/pacman.8.txt @@ -0,0 +1,313 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +pacman(8) +========= + +Name +---- +pacman - package manager utility + + +Synopsis +-------- +'pacman' <operation> [options] [packages] + + +Description +----------- +Pacman is a package management utility that tracks installed packages on a Linux +system. It features dependency support, package groups, install and uninstall +hooks, and the ability to sync your local machine with a remote ftp server to +automatically upgrade packages. Pacman packages are a zipped tar format. + +Since version 3.0.0, pacman has been the frontend to manlink:libalpm[3], the +"Arch Linux Package Management" library. This library allows alternative front +ends to be written (for instance, a GUI front end). + + +Operations +---------- +*-A, \--add* (deprecated):: + Add a package to the system. Either a URL or file path can be specified. + The package will be uncompressed into the installation root and the + database will be updated. The package will not be installed if another + version is already installed. *NOTE*: please use '\--upgrade' in place of + this option. + +*-F, \--freshen*:: + This is like '\--upgrade' except it will only upgrade packages already + installed on the system. + +*-Q, \--query*:: + Query the package database. This operation allows you to view installed + packages and their files, as well as meta-information 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 '.tar.gz' packages. See <<QO,Query Options>> below. + +*-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 `.pacsave` extension unless the + '\--nosave' option is used. See <<RO,Remove Options>> below. + +*-S, \--sync*:: + Synchronize packages. Packages are installed directly from the ftp + servers, including all dependencies required to run the packages. For + example, `pacman -S qt` will download and install qt and all the + packages it depends on. You can also use `pacman -Su` to upgrade all + packages that are out of date. See <<SO,Sync Options>> below. + +*-U, \--upgrade*:: + Upgrade or add a package to the system. Either a URL or file path can be + specified. This is a "remove-then-add" process. See <<HCF,Handling Config + Files>> for an explanation on how pacman takes care of config files. + +*-V, \--version*:: + Display version and exit. + +*-h, \--help*:: + Display syntax for the given operation. If no operation was supplied + then the general syntax is shown. + + +Options +------- +*\--asdeps*:: + Install packages non-explicitly; in other works, fake their install reason + to be installed as a dependency. This is useful for makepkg and other + build from source tools that need to install dependencies before building + the package. + +*\--ask* <'number'>:: + Pre-specify answers to questions. It is doubtful whether this option + even works, so I would not recommend using it. *TODO*: document this + more, as I have no idea how it works or when you would use it, or if we + should just dump it. + +*-b, \--dbpath* <'path'>:: + Specify an alternative database location (default is ``/var/lib/pacman''). + This should not be used unless you know what you are doing. + +*-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. + +*-f, \--force*:: + Bypass file conflict checks and overwrite 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. + +*-r, \--root* <'path'>:: + Specify an alternative installation root (default is ``/''). This should + not be used as a way to install software into ``/usr/local'' instead of + ``/usr''. This option is used if you want to install a package on a + temporary mounted partition which is "owned" by another system. + +*-v, --verbose*:: + Output more status messages, such as the Root, DBPath, CacheDir, etc. + +*\--cachedir* <'dir'>:: + Specify an alternative package cache location (default is + ``/var/cache/pacman/pkg''). Multiple cache directories can be specified, + and they are tried in the order they are passed to pacman. + +*\--config* <'file'>:: + Specify an alternate configuration file. + +*\--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. + +*\--noprogressbar*:: + Do not show a progress bar when downloading files. This can be useful + for scripts that call pacman and capture the output. + +*\--noscriptlet*:: + If an install scriptlet exists, do not execute it. Do not use this + unless you know what you are doing. + + +Query Options[[QO]] +------------------- +*-c, \--changelog*:: + View the ChangeLog of a package. Not every package will provide one but + it will be shown if available. + +*-d, \--deps*:: + List all packages installed as dependencies. This option can be combined + with '-t' for listing real orphans- packages that were installed as + dependencies but are no longer required by any installed package. ('-Qdt' + is equivalent to the pacman 3.0.X '-Qe' option.) + +*-e, \--explicit*:: + List all packages explicitly installed. This option can be combined with + '-t' to list top-level packages- those packages that were explicitly + installed but are not required by any other package. ('-Qet' is equivalent + to the pacman 2.9.X '-Qe' option.) + +*-g, \--groups*:: + Display all packages that are members of a named group. If not name is + specified, list all grouped packages. + +*-i, \--info*:: + Display information on a given package. The '-p' option can be used if + querying a package file instead of the local database. + +*-l, \--list*:: + List all files owned by a given package. Multiple packages can be + specified on the command line. + +*-m, \--foreign*:: + Restrict or filter output to packages that were not found in the sync + database(s). Typically these are packages that were downloaded manually + and installed with '\--upgrade'. + +*-o, \--owns* <'file'>:: + Search for the package that owns file. The path can be relative or + absolute. + +*-p, \--file*:: + Signifies that the package supplied on the command line is a file and + not an entry in the database. The file will be decompressed and queried. + This is useful in combination with '\--info' and '\--list'. + +*-s, \--search* <'regexp'>:: + This will search each locally-installed package for names or + descriptions that match `regexp`. + +*-t, \--orphans*:: + Restrict or filter output to packages not required by any currently + installed package. + +*-u, \--upgrades*:: + Lists all packages that are out of date on the local system. This option + works best if the sync database is refreshed using '-Sy'. + +*\--test*:: + Run some brief checks looking at the consistency of the local database. + + +Remove Options[[RO]] +-------------------- +*-c, \--cascade*:: + Remove all target packages, as well as all packages that depend on one + or more target packages. This operation is recursive. + +*-k, \--keep*:: + Removes the database entry only. Leaves all files in place. + +*-n, \--nosave*:: + Instructs pacman to ignore file backup designations. Normally, when a + file is removed from the system the database is checked to see if the + file should be renamed with a ``.pacsave'' extension. + +*-s, \--recursive*:: + Remove each target specified including all dependencies, provided that + (A) they are not required by other packages; and (B) they were not + explicitly installed by the user. This option is analogous to a + backwards '\--sync' operation. + + +Sync Options[[SO]] +------------------ +*-c, \--clean*:: + Remove old packages from the cache to free up disk space. When pacman + downloads packages, it saves them in ``/var/cache/pacman/pkg''. Use one + '\--clean' switch to remove old packages; use two to remove all packages + from the cache. + +*-e, \--dependsonly*:: + Install all dependencies of a package, but not the specified package + itself. This is pretty useless and we're not sure why it even exists. + +*-g, \--groups*:: + Display all the members for each package group specified. If no group + names are provided, all groups will be listed; pass the flag twice to + view all groups and their members. + +*-i, \--info*:: + Display dependency and other information for a given package. This will + search through all repositories for a matching package. + +*-l, \--list*:: + List all packages in the specified repositories. Multiple repositories + can be specified on the command line. + +*-p, \--print-uris*:: + Print out URIs for each package that will be installed, including any + dependencies yet to be installed. These can be piped to a file and + downloaded at a later time, using a program like wget. + +*-s, \--search* <'regexp'>:: + This will search each package in the sync databases for names or + descriptions that match `regexp`. + +*-u, \--sysupgrade*:: + Upgrades all packages that are out of date. Each currently-installed + package will be examined and upgraded if a newer package exists. A + report of all packages to upgrade will be presented and the operation + will not proceed without user confirmation. Dependencies are + automatically resolved at this level and will be installed/upgraded if + necessary. + +*-w, \--downloadonly*:: + Retrieve all packages from the server, but do not install/upgrade + anything. + +*-y, \--refresh*:: + Download a fresh copy of the master package list from the server(s) + defined in pacman.conf. This should typically be used each time you use + '\--sysupgrade' or '-u'. Passing two '\--refresh' or '-y' flags will force + a refresh of all package lists even if they are thought to be up to date. + +*\--ignore* <'package'>:: + Directs pacman to ignore upgrades of package even if there is one + available. + + +Handling Config Files[[HCF]] +---------------------------- +Pacman uses the same logic as rpm to determine action against files that are +designated to be backed up. During an upgrade, 3 md5 hashes are used 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: + +original=X, current=X, new=X:: + All three files are the same, so overwrites are not an issue Install the + new file. + +original=X, current=X, new=Y:: + The current file is the same as the original but the new one differs. + Since the user did not ever modify the file, and the new one may contain + improvements or bugfixes, install the new file. + +original=X, current=Y, new=X:: + Both package versions contain the exact same file, but the one on the + filesystem has been modified. Leave the current file in place. + +original=X, current=Y, new=Y:: + The new file is identical to the current file. Install the new file. + +original=X, current=Y, new=Z:: + All three files are different, so install the new file with a '.pacnew' + extension and warn the user. The user must then manually merge any + necessary changes into the original file. + + +Configuration +------------- +See manlink:pacman.conf[5] for more details on configuring pacman using the +'pacman.conf' file. + + +See Also +-------- +manlink:pacman.conf[5], manlink:makepkg[8], manlink:libalpm[3] + +include::footer.txt[] diff --git a/doc/pacman.conf.5 b/doc/pacman.conf.5 deleted file mode 100644 index f7304aa5..00000000 --- a/doc/pacman.conf.5 +++ /dev/null @@ -1,143 +0,0 @@ -." the string declarations are a start to try and make distro independent -.ds DS Arch Linux -.ds PB PKGBUILD -.ds VR 3.0.0 -.ds LV 1.0.0 -.TH \*(PB 5 "Feb 07, 2007" "pacman.conf version \*(VR" "\*(DS Files" -.SH NAME -pacman.conf \- pacman package manager configuration file - -.SH DESCRIPTION -\fBpacman\fP, using \fBlibalpm\fP, will attempt to read \fBpacman.conf\fP each -time it is invoked. This configuration file is divided into sections or -\fIrepositories\fP. Each section defines a package repository that \fBpacman\fP -can use when searching for packages in \fB--sync\fP mode. The exception to this -is the \fIoptions\fP section, which defines global options. - -.SH EXAMPLE -.RS -.nf -# -# pacman.conf -# -[options] -NoUpgrade = etc/passwd etc/group etc/shadow -NoUpgrade = etc/fstab - -[current] -Include = /etc/pacman.d/current - -[custom] -Server = file:///home/pkgs -.fi -.RE - -.SH OPTIONS -.TP -.B DBPath = \fIpath/to/db/dir\fP -Overrides the default location of the toplevel database directory. The default -is \fIvar/lib/pacman\fP. -.TP -.B CacheDir = \fIpath/to/cache/dir\fP -Overrides the default location of the package cache directory. The default is -\fIvar/cache/pacman\fP. -.TP -.B HoldPkg = \fIpackage\fP ... -If a user tries to \fB--remove\fP a package that's listed in \fBHoldPkg\fI, -\fBpacman\fP will ask for confirmation before proceeding. -.TP -.B IgnorePkg = \fIpackage\fP ... -Instructs \fBpacman\fP to ignore any upgrades for this package when performing a -\fB--sysupgrade\fP. -.TP -.B Include = \fIpath\fP -Include another config file. This file can include repositories or general -configuration options. -.TP -.B XferCommand = \fI/path/to/command %u\fP -If set, an external program will be used to download all remote files. All -instances of \fB%u\fP will be replaced with the download URL. 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 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 = \fIfile\fP ... -All files listed with a \fBNoUpgrade\fP directive will never be touched during -a package install/upgrade. Do \fInot\fP include the leading slash when -specifying files. -.TP -.B NoExtract = \fIfile\fP ... -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 -\fBapache\fP package. -.TP -.B UseSyslog -Log action messages through \fBsyslog()\fP. This will insert log entries into -\fI/var/log/messages\fP or equivalent. -.TP -.B LogFile = \fI/path/to/file\fP -Log actions directly to a file. Default is \fI/var/log/pacman.log\fP. -.TP -.B ShowSize -Display the size of individual packages for \fB--sync\fP and \fB--query\fP -modes. - -.SH REPOSITORY SECTIONS -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 (the two above are 'current' and 'custom'). Locations are -defined with the \fBServer\fP directive and follow a URL naming structure. If -you want to use a local directory, you can specify the full path with -a 'file://' prefix, as shown above. - -The order of repositories in the file matters; repositories listed first will -take precedence over those listed later in the file when packages in two -repositories have identical names, regardless of version number. - -.SH USING YOUR OWN REPOSITORY -If you have numerous custom packages of your own, it is often easier to -generate your own custom local repository than install them all with the -\fB--upgrade\fP option. All you need to do is generate a compressed package -database in the directory with these packages so \fBpacman\fP can find it when -run with \fB--refresh\fP. - -.RS -.nf -repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz -.fi -.RE - -The above command will generate a compressed database named -\fI/home/pkgs/custom.db.tar.gz\fP. Note that the database must be of the form -\fI{treename}.db.tar.gz\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 \fBpacman\fP's --refresh option. - -For more information on the \fBrepo-add\fP command, use \fB repo-add --help\fP. - -.SH SEE ALSO -.BR pacman (8), -.BR libalpm (3) - -See the Arch Linux website at <http://www.archlinux.org> for more current -information on the distribution and the \fBpacman\fP family of tools. - -.SH AUTHORS -.nf -Judd Vinet <jvinet@zeroflux.org> -Aurelien Foret <aurelien@archlinux.org> -Aaron Griffin <aaron@archlinux.org> -Dan McGee <dan@archlinux.org> -.fi - -See the 'AUTHORS' file for additional contributors. diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt new file mode 100644 index 00000000..d422a4b9 --- /dev/null +++ b/doc/pacman.conf.5.txt @@ -0,0 +1,147 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +pacman.conf(5) +============== + +Name +---- +pacman.conf - pacman package manager configuration file + + +Synopsis +-------- +{sysconfdir}/pacman.conf + + +Description +----------- +Pacman, using manlink:libalpm[3], will attempt to read pacman.conf each time it +is invoked. This configuration file is divided into sections or repositories. +Each section defines a package repository that pacman can use when searching +for packages in '\--sync' mode. The exception to this is the options section, +which defines global options. + + +Example +------- +-------- +# +# pacman.conf +# +[options] +NoUpgrade = etc/passwd etc/group etc/shadow +NoUpgrade = etc/fstab + +[current] +Include = /etc/pacman.d/current + +[custom] +Server = file:///home/pkgs +-------- + + +Options +------- +*RootDir =* path/to/root:: + Set the default root directory for pacman to install to. + +*DBPath =* path/to/db/dir:: + Overrides the default location of the toplevel database directory. + The default is ``/var/lib/pacman/''. + +*CacheDir =* path/to/cache/dir:: + Overrides the default location of the package cache directory. The default + is ``/var/cache/pacman/pkg/''. Multiple cache directories can be specified, + and they are tried in the order they are listed in the config file. If a + file is not found in any cache directory, it will be downloaded to the + first cache directory with write access. + +*LogFile =* '/path/to/file':: + Log actions directly to a file. Default is ``/var/log/pacman.log''. + +*HoldPkg =* package ...:: + If a user tries to '\--remove' a package that's listed in `HoldPkg`, + pacman will ask for confirmation before proceeding. + +*IgnorePkg =* package ...:: + Instructs pacman to ignore any upgrades for this package when performing + a '\--sysupgrade'. + +*Include =* path:: + Include another config file. This file can include repositories or + general configuration options. + +*XferCommand =* /path/to/command %u:: + If set, an external program will be used to download all remote files. + All instances of `%u` will be replaced with the download URL. If present, + instances of `%o` 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 built-in + http/ftp support, or need the more advanced proxy support that comes with + utilities like wget. + +*NoPassiveFtp*:: + Disables passive ftp connections when downloading packages. (aka Active Mode) + +*NoUpgrade =* file ...:: + All files listed with a `NoUpgrade` directive will never be touched during + a package install/upgrade. Do not include the leading slash when specifying + files. + +*NoExtract =* file ...:: + All files listed with a `NoExtract` 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. + +*UseSyslog*:: + Log action messages through syslog(). This will insert log entries into + ``/var/log/messages'' or equivalent. + +*ShowSize*:: + Display the size of individual packages for '\--sync' and '\--query' modes. + + +Repository Sections +------------------- +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 (the two above are 'current' and 'custom'). Locations are +defined with the 'Server' directive and follow a URL naming structure. If you +want to use a local directory, you can specify the full path with a ``file://'' +prefix, as shown above. + +The order of repositories in the file matters; repositories listed first will +take precedence over those listed later in the file when packages in two +repositories have identical names, regardless of version number. + +Using Your Own Repository +------------------------- +If you have numerous custom packages of your own, it is often easier to generate +your own custom local repository than install them all with the '\--upgrade' +option. All you need to do is generate a compressed package database in the +directory with these packages so pacman can find it when run with '\--refresh'. + + repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz + +The above command will generate a compressed database named +'/home/pkgs/custom.db.tar.gz'. Note that the database must be of the form +'{treename}.db.tar.gz', where '{treename}' is the name of the section defined in +the configuration file. That's it! Now configure your custom 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. + +For more information on the repo-add command, see ``repo-add \--help'' or +manlink:repo-add[8]. + + +See Also +-------- +manlink:pacman[8], manlink:libalpm[3] + +include::footer.txt[] diff --git a/doc/repo-add.8.txt b/doc/repo-add.8.txt new file mode 100644 index 00000000..27e0e93f --- /dev/null +++ b/doc/repo-add.8.txt @@ -0,0 +1,51 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +repo-add(8) +========== + +Name +---- +//// +* If we use this below line, the manpage name comes out all weird. We also +* can't use two separate lines, which is quite annoying. * +repo-add, repo-remove - package database maintenance utilities +//// +repo-add - package database maintenance utility + + +Synopsis +-------- +repo-add <path-to-db> [--force] <package> ... + +repo-remove <path-to-db> <packagename> ... + + +Description +----------- +repo-add and repo-remove are two scripts to help build a package database for +packages built with manlink:makepkg[8] and installed with manlink:pacman[8]. + +repo-add will update a package database by reading a built package file. +Multiple packages to add can be specified on the command line. + +repo-remove will update a package database by removing the package name +specified on the command line. Multiple packages to remove can be specified +on the command line. + + +Options +------- +*--force* (repo-add only):: + Add a force entry to the sync database, which tells pacman to skip version + number comparison and update the package regardless. This flag can be + specified in the middle of the command line, with any packages listed + before the flag being added as normal entries, and any specified after + being marked as force upgrades. + + +See Also +-------- +manlink:makepkg[8], manlink:pacman[8] + +include::footer.txt[] |