diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/PKGBUILD.5.txt | 256 | ||||
| -rw-r--r-- | doc/libalpm.3.txt | 36 | ||||
| -rw-r--r-- | doc/makepkg.8.txt | 124 | ||||
| -rw-r--r-- | doc/makepkg.conf.5.txt | 136 | ||||
| -rw-r--r-- | doc/pacman.8.txt | 2 |
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 |