summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndrew Fyfe <andrew@neptune-one.net>2007-07-03 00:22:01 +0100
committerDan McGee <dan@archlinux.org>2007-07-09 13:47:56 -0400
commitbe0a472cb798f0bfd4a75d1cfe165b4005a8ca90 (patch)
treeab95c5b6703df7a3cb4f51d4769ab26a4e7e8506
parent493e5fb7828793a8b834d5ecfd2e83050fcd920c (diff)
Convert the remaining man pages to asciidoc.
Signed-off-by: Andrew Fyfe <andrew@neptune-one.net>
-rw-r--r--doc/PKGBUILD.5.txt256
-rw-r--r--doc/libalpm.3.txt36
-rw-r--r--doc/makepkg.8.txt124
-rw-r--r--doc/makepkg.conf.5.txt136
-rw-r--r--doc/pacman.8.txt2
5 files changed, 553 insertions, 1 deletions
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
new file mode 100644
index 00000000..642f8884
--- /dev/null
+++ b/doc/PKGBUILD.5.txt
@@ -0,0 +1,256 @@
+PKGBUILD(5)
+===========
+
+Name
+----
+PKGBUILD - Arch Linux package build description file
+
+
+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
+ $startdir/pkg/usr/share/licenses/$pkgname when building the package. If
+ multiple licenses are applicable for a package, list all of them:
+ licenses=('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.
+
+*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 manlink:PKGBUILD[5]s,
+ 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 'modutils' package. For more
+examples, look through the ABS tree.
+
+-----
+# 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
+}
+-----
+
+
+See Also
+--------
+manlink:makepkg[8], manlink:pacman[8], manlink:makepkg.conf[5]
+
+include::footer.txt[]
diff --git a/doc/libalpm.3.txt b/doc/libalpm.3.txt
new file mode 100644
index 00000000..c9951311
--- /dev/null
+++ b/doc/libalpm.3.txt
@@ -0,0 +1,36 @@
+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.txt b/doc/makepkg.8.txt
new file mode 100644
index 00000000..636d409f
--- /dev/null
+++ b/doc/makepkg.8.txt
@@ -0,0 +1,124 @@
+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
+-------
+*-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 pacman.
+
+*-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,
+ 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.
+
+*--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.txt b/doc/makepkg.conf.5.txt
new file mode 100644
index 00000000..fd867f6b
--- /dev/null
+++ b/doc/makepkg.conf.5.txt
@@ -0,0 +1,136 @@
+makepkg.conf(5)
+===============
+
+Name
+----
+makepkg.conf - makepkg configuration file
+
+
+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.
+
+*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
+-------
+*FTPAGENT="*'/path/to/command [options]'*"*::
+ Sets the download agent used to fetch source files specified with a URL
+ in the manlink:PKGBUILD[5] file. Flags can be specified as well; the
+ download URL is then placed on the end of the command.
+
+*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.
+
+*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'*)*::
+ This array contains four 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.
+
+*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 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:
+
+ *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.
+
+
+See Also
+--------
+manlink:makepkg[8], manlink:pacman[8], manlink:PKGBUILD[5]
+
+include::footer.txt[]
diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt
index dbdb146c..891be7dd 100644
--- a/doc/pacman.8.txt
+++ b/doc/pacman.8.txt
@@ -1,4 +1,4 @@
-PACMAN(8)
+pacman(8)
=========
Name