diff --git a/APKBUILD.5 b/APKBUILD.5 index ad3f82e..67f2eaa 100644 --- a/APKBUILD.5 +++ b/APKBUILD.5 @@ -1,17 +1,11 @@ .Dd February 13, 2018 .Dt APKBUILD 5 PRM .Os "Alpine Linux" - - .Sh NAME .Nm APKBUILD .Nd metadata and instructions to build a package - - .Sh SYNOPSIS .Nm /usr/src/packages///APKBUILD - - .Sh DESCRIPTION An .Nm @@ -19,10 +13,11 @@ file is used by tools such as .Xr abuild 1 to build a package for eventual installation by the .Xr apk 8 -package manager. It defines metadata such as the name of the package, the -version information, the source license, and contact information for the -developer. It additionally contains the commands needed to build, test, and -install the package. +package manager. +It defines metadata such as the name of the package, the version information, +the source license, and contact information for the developer. +It additionally contains the commands needed to build, test, and install the +package. .Pp The .Nm @@ -30,34 +25,34 @@ format is similar to a typical shell script; you set pre-defined variables and implement pre-defined functions, and the .Xr abuild 1 (or similar) utility will use them to create the package. - - .Ss Required Variables The following variables must be set in all .Nm files: - .Bl -tag -width Ds .It Cm pkgname -Specifies name of the package. This is typically the name of the package -upstream; however, note that all letters must be lowercased. +Specifies name of the package. +This is typically the name of the package upstream; however, note that all +letters must be lowercased. .Pp Libraries for scripting languages should have a prefix before the library name -describing the language. Such prefixes include +describing the language. +Such prefixes include .Em lua- , .Em perl- , .Em py- , and .Em rb- . -Not all languages use prefixes. For a definitive list, consult the PREFIXES -file in the root directory of the repository you are using for packaging. - +Not all languages use prefixes. +For a definitive list, consult the PREFIXES file in the root directory of the +repository you are using for packaging. .It Cm pkgver -Specifies the version of the software being packaged. The version of a package -must consist of one or more numbers separated by the radix (decimal point). +Specifies the version of the software being packaged. +The version of a package must consist of one or more numbers separated by the +radix (decimal point). The final number may have a single letter following it, for upstreams that use such a versioning scheme (such as 1.5a, 1.5b, 1.5c). - +.Pp After the final number (and optional single letter), a suffix may be appended, which must be an underscore (_) followed by one of .Em alpha , @@ -70,7 +65,8 @@ which must be an underscore (_) followed by one of .Em hg , or .Em p , -optionally followed by another number. If the suffix is +optionally followed by another number. +If the suffix is .Em alpha , .Em beta , .Em pre , @@ -85,132 +81,121 @@ is or .Em p , it is considered to be later than the version without a suffix. - All of the following examples are valid versions, in order from lowest to highest: - +.Pp 1.0, 1.1_alpha2, 1.1.3_pre, 1.1.3, 1.1.3_hg, 1.2, 1.2a, 1.2b - .It Cm pkgrel -Specifies the package release number of this particular package version. This -indicates when a package has changed without a corresponding change in version. +Specifies the package release number of this particular package version. +This indicates when a package has changed without a corresponding change in +version. Always increment .Cm pkgrel -when you change the contents, dependencies, or metadata of a package. The -first release of a package is always +when you change the contents, dependencies, or metadata of a package. +The first release of a package is always .Li 0 . - .It Cm pkgdesc Specifies what the package contains. .Cm pkgdesc must be 128 characters or less, and should concisely describe what actions the -software or items being packaged will allow the user to perform. For example, -.Li Dq Fully-featured word processor with spell check and many plugins +software or items being packaged will allow the user to perform. +For example, +.Dq Fully-featured word processor with spell check and many plugins would be a sufficient .Cm pkgdesc for AbiWord. - .It Cm url -Specifies the Web address of the package's upstream. This allows users and -future maintainers to find documentation, release information, and contact -information for the package. If no Web address is available for the package, -you must set +Specifies the Web address of the package's upstream. +This allows users and future maintainers to find documentation, release +information, and contact information for the package. +If no Web address is available for the package, you must set .Cm url to an empty string (""). - .It Cm arch -Specifies the architectures for which the package may be built. It is highly -recommended that you set this variable to "all" if the package is portable. - +Specifies the architectures for which the package may be built. +It is highly recommended that you set this variable to "all" if the package is +portable. +.Pp You may use "noarch" if the package does not contain any architecture-specific -binary files - that is, any files that are compiled for the target only. Such -packages may include pure Python packages, shell script packages, and JARs. If -you are not sure what this means, using "all" is safe. - +binary files - that is, any files that are compiled for the target only. +Such packages may include pure Python packages, shell script packages, and +JARs. +If you are not sure what this means, using "all" is safe. .It Cm license -Specifies the license under which the package is distributed. The value -provided must match a SPDX license identifier. - +Specifies the license under which the package is distributed. +The value provided must match a SPDX license identifier. .It Cm source Specifies the location of both local and remote source files used to build the -package. Typically, the remote source file(s) or archive(s) is specified, -followed by any local patches, install scripts, configuration files, or other -necessary files. - +package. +Typically, the remote source file(s) or archive(s) is specified, followed by +any local patches, install scripts, configuration files, or other necessary +files. .El - - .Ss Optional Variables The following variables are not required, but may be set in any .Nm file: - .Bl -tag -width Ds .It Cm checkdepends -Specifies test-time dependencies of the package. Common packages that are -used for testing include check, dejagnu, and perl-test-command. - +Specifies test-time dependencies of the package. +Common packages that are used for testing include check, dejagnu, and +perl-test-command. .It Cm depends -Specifies the run-time dependencies of the package. The +Specifies the run-time dependencies of the package. +The .Xr abuild 1 utility will automatically scan the resultant package for shared library (.so) dependencies; do not specify them here. - .It Cm install -Specifies install scripts for the package, if any. See +Specifies install scripts for the package, if any. +See .Sx Install Scripts for more information about install scripts. - .It Cm install_if Specifies a condition when .Xr apk 8 -should automatically install the package (or subpackage). For instance, the -OpenRC subpackages set +should automatically install the package (or subpackage). +For instance, the OpenRC subpackages set .Cm install_if to -.Li Dq $pkgname=$pkgver openrc +.Li $pkgname=$pkgver openrc which means that the OpenRC subpackage will be automatically installed if the origin package and OpenRC are both installed on the same computer. - .It Cm makedepends Specifies build dependencies for the package. - .It Cm pkggroups Specifies a space-separated list of login groups to create during build-time. Note that you will need to create the login groups in a pre-install install script as well; see .Sx Install Scripts for more information about install scripts. - .It Cm pkgusers Specifies a space-separated list of user logins to create during build-time. Note that you will ned to create the user logins in a pre-install install script as well; see .Sx Install Scripts for more information about install scripts. - .It Cm provides Specifies that the package "provides" the same contents as another package. There are two formats that you may use for .Cm provides : a provider name, and a provider name with version. - +.Pp Specifying a provider name with version such as -.Li Dq foobar=1.2 -will cause the package to be an "alias" of foobar version 1.2. It will be -automatically installed if a user then runs +.Li foobar=1.2 +will cause the package to be an "alias" of foobar version 1.2. +It will be automatically installed if a user then runs .Li apk add foobar or similar, and it will conflict with a package named foobar. - +.Pp Specifying a provider name without a version such as -.Li Dq baz -will cause the package to provide a "virtual" called baz. Multiple packages -with the same virtual provider can be installed on a system; however, if a user -runs +.Li baz +will cause the package to provide a "virtual" called baz. +Multiple packages with the same virtual provider can be installed on a system; +however, if a user runs .Li apk add baz they will provided a list of packages that provide baz and must select one and install it. - .It Cm provider_priority Specifies the numeric value for .Xr apk 8 @@ -218,25 +203,24 @@ to use for the package when considering which provider should be installed for the same .Cm provides virtual provider. - .It Cm replaces -Specifies packages that the package replaces. This is typically used for -packages renamed by upstream. - +Specifies packages that the package replaces. +This is typically used for packages renamed by upstream. .It Cm subpackages -Specifies subpackages or split packages built with this package. Typically, -this will include -.Li Dq $pkgname-dev +Specifies subpackages or split packages built with this package. +Typically, this will include +.Li $pkgname-dev for development files (such as /usr/include and static library files) and -.Li Dq $pkgname-doc +.Li $pkgname-doc for documentation (such as /usr/share/doc and /usr/share/man). - -Each subpackage may be specified using three different methods. The first, and -most common, is -.Li Dq $pkgname-foo +.Pp +Each subpackage may be specified using three different methods. +The first, and most common, is +.Li $pkgname-foo where .Li foo -is the name of the split function specified later in the file. Similar to the +is the name of the split function specified later in the file. +Similar to the .Cm package function, the .Li foo @@ -248,18 +232,18 @@ to .Pa $subpkgdir after creating .Pa $subpkgdir . - +.Pp The second method is to simply call the subpackage -.Li Dq foo +.Li foo which will create a package called .Li foo instead of pkgname-foo. - +.Pp However, .Li foo in both of these examples cannot contain a hyphen, as shell function names cannot have hyphens in them. In this case, the third method may be used: -.Li Dq foo:funcname +.Li foo:funcname where .Li foo is the name of the subpackage and @@ -267,11 +251,12 @@ is the name of the subpackage and is the name of the shell function in the .Nm that creates it. - +.Pp Note that an additional colon may be used to specify an architecture for the subpackage; typically, this is used for marking miscellaneous files that are -not architecture-specific as noarch. For example, -.Li Dq $pkgname-doc $pkgname-foo $pkgname-foo-misc:foo_misc:noarch +not architecture-specific as noarch. +For example, +.Li $pkgname-doc $pkgname-foo $pkgname-foo-misc:foo_misc:noarch will create the $pkgname-doc package using the .Cm doc function, the $pkgname-foo package using the @@ -279,68 +264,61 @@ function, the $pkgname-foo package using the function, and the $pkgname-foo-misc package using the .Cm foo_misc function and set $pkgname-foo-misc as noarch. - .It Cm triggers -Specifies a trigger script used by the package. A trigger script is a shell -script that is called whenever monitored files or directories are modified. +Specifies a trigger script used by the package. +A trigger script is a shell script that is called whenever monitored files or +directories are modified. You may specify the paths to monitor using the triggers variable as follows: - -.Li Dq $pkgname.trigger=/usr/share/man:/usr/local/share/man - +.Pp +.Li $pkgname.trigger=/usr/share/man:/usr/local/share/man +.Pp This will run the package trigger script whenever files in .Pa /usr/share/man or .Pa /usr/local/share/man are created, modified, or removed. - .El - - .Ss options The .Cm options -variable allows you to set parameters for the package at build time. There are -a number of valid options you may set, and you may set multiple options by -inserting a space between each one. - +variable allows you to set parameters for the package at build time. +There are a number of valid options you may set, and you may set multiple +options by writing a space between each one. .Bl -tag -width Ds .It Cm !archcheck Specifies that the package contains binaries that cannot run on the target -architecture. This is primarily used for packages containing firmware, and -should typically never need to be used. - +architecture. +This is primarily used for packages containing firmware, and should typically +never need to be used. .It Cm charset.alias Specifies that the package ships a /usr/lib/charset.alias file and that it -should be installed on the user's system. This is almost never the case. Do -not use this option. - +should be installed on the user's system. +This is almost never the case. +Do not use this option. .It Cm !check -Specifies that the package will not run a test suite. The reason for disabling -the check phase should be noted in a comment. - +Specifies that the package will not run a test suite. +The reason for disabling the check phase should be noted in a comment. .It Cm !checkroot Specifies that the package's test suite will be run as a non-privileged user instead of using .Xr fakeroot 8 . This is necessary for some test suites which fail when run as root. - .It Cm !dbg Specifies that the package should not be built with a debug information -package. This is the default unless +package. +This is the default unless .Ev DEFAULT_DBG is set in the environment or .Xr abuild.conf 5 . It is typically used on packages that do not generate debug information (such as pure Python packages) or packages that do not support debug information packages. - .It Cm !fhs Specifies that the package violates FHS and installs to a location such as .Pa /usr/local , .Pa /opt , or .Pa /srv . - .It Cm ldpath-recursive Specifies that .Xr abuild 1 @@ -349,99 +327,84 @@ should use the argument to .Xr scanelf 1 when attempting to find shared library (.so) dependencies for the package. - .It Cm libtool -Specifies that the package requires its libtool (.la) files. They will not be -automatically removed by +Specifies that the package requires its libtool (.la) files. +They will not be automatically removed by .Xr abuild 1 . - .It Cm net -Specifies that the package build system requires access to a network. This is -discouraged and an issue should be filed with the package's authors. - +Specifies that the package build system requires access to a network. +This is discouraged and an issue should be filed with the package's authors. .It Cm !strip Specifies that .Xr strip 1 -should not be run on any of the package's binaries. This is automatically -implied if the -dbg subpackage is enabled, or if you are using +should not be run on any of the package's binaries. +This is automatically implied if the -dbg subpackage is enabled, or if you are +using .Ev DEFAULT_DBG . - .It Cm suid -Specifies that binaries in the package may be installed set-uid. This is a -security risk and it is highly recommended to use capabilities or process -separation instead of set-uid where available. - +Specifies that binaries in the package may be installed set-uid. +This is a security risk and it is highly recommended to use capabilities or +process separation instead of set-uid where available. .It Cm textrels Specifies that the package's binaries are known to contain relocations against -text segments. By default, +text segments. +By default, .Xr abuild 1 will refuse to create such a package because this is a security concern. - .It Cm toolchain Specifies that the package is part of the base toolchain set and may depend on packages like .Li g++ . - .It Cm !tracedeps Specifies that .Xr abuild 1 should not automatically populate .Cm depends with shared library (.so) or symlink target dependencies. - .El - - .Ss Automatic Variables The following variables are defined for you by .Xr abuild 1 , but may be overridden if necessary. - .Bl -tag -width Ds .It Cm builddir Specifies the directory where the source code of the package will be built. The default value is .Pa $srcdir/$pkgname-$pkgver -which is appropriate for most source distributions. If the source tarball does -not create a $pkgname-$pkgver directory when it is unpacked, you must override +which is appropriate for most source distributions. +If the source tarball does not create a $pkgname-$pkgver directory when it is +unpacked, you must override .Cm builddir . - .It Cm pkgdir -Specifies the directory where the built files will be installed. Typically, -you will call -.Li Dq make DESTDIR="$pkgdir" install -or similar to install the files. The default value is +Specifies the directory where the built files will be installed. +Typically, you will call +.Li make DESTDIR="$pkgdir" install +or similar to install the files. +The default value is .Pa $startdir/pkg and you should not modify this variable. - .It Cm srcdir Specifies the directory where the files specified in .Cm source -are downloaded and unpacked. The default value is +are downloaded and unpacked. +The default value is .Pa $startdir/src and you should not need to modify this. - .It Cm startdir Specifies the directory where the .Nm file resides. - .It Cm subpkgdir -Specifies the directory where the subpackage's files should be placed. This -variable is only set inside subpackage functions. - +Specifies the directory where the subpackage's files should be placed. +This variable is only set inside subpackage functions. .El - - .Ss Special Variables The following variables are used only in special circumstances, and may be required or optional depending on their usage and the contents of other variables. - .Bl -tag -width Ds .It Cm depends_dev Specifies the run-time dependencies of the -dev subpackage. - .It Cm giturl Specifies the URL of the Git repository to use with .Cm abuild checkout . @@ -451,32 +414,27 @@ specified by appending where .Cm branch is the branch to checkout. - .El - - .Ss Functions Functions specified here may be present in any .Nm file, but with the exception of .Cm package , are not strictly required. - .Bl -tag -width Ds .It Cm fetch This function is called to download the remote files in .Cm source . - .It Cm unpack This function unpacks any archives in .Cm source to .Ev srcdir . - .It Cm prepare Prepares the source in .Ev srcdir -to be built. The default +to be built. +The default .Cm prepare function ensures the build directories are set up correctly and applies any *.patch files specified in @@ -486,19 +444,17 @@ You must call if you write a custom .Cm prepare function. - .It Cm build Compiles the source in .Ev builddir . -You must implement this function yourself. If no compilation is required, you -may omit it. - +You must implement this function yourself. +If no compilation is required, you may omit it. .It Cm check -Runs the package's test suite. This function must be implemented unless -.Li Dq !check +Runs the package's test suite. +This function must be implemented unless +.Li !check was specified in .Cm options . - .It Cm package Installs the package into .Ev pkgdir . @@ -508,116 +464,101 @@ is not created for you; if this package installs no files (for example, a metapackage), you must use .Li mkdir -p "$pkgdir" to skip the package phase. - .El - - .Ss Install Scripts An install script is run when an action is taken on a package by .Xr apk 8 . An install script must be written in shell and must have a -.Li Dq #!/bin/sh -interpreter declaration as the first line. The +.Li #!/bin/sh +interpreter declaration as the first line. +The .Cm install variable must contain the install scripts needed by the package. - +.Pp The install script will be run inside the root filesystem where the package is -being installed. A single argument will be passed to all scripts, which is the -version of the package being currently installed (or deinstalled). The -pre-upgrade and post-upgrade scripts will have an additional second argument, -which specifies the version of the package before the upgrade process. - +being installed. +A single argument will be passed to all scripts, which is the version of the +package being currently installed (or deinstalled). +The pre-upgrade and post-upgrade scripts will have an additional second +argument, which specifies the version of the package before the upgrade +process. +.Pp The different actions that may have install scripts specified are as follows: - .Bl -tag -width Ds .It Ic $pkgname.pre-install -Executed before the package is installed. If this script exits with an error -(non-zero exit code), +Executed before the package is installed. +If this script exits with an error (non-zero exit code), .Xr apk 8 -will halt the installation and the package will not be installed. This install -script is typically used to create any users or groups needed as described in +will halt the installation and the package will not be installed. +This install script is typically used to create any users or groups needed as +described in .Cm pkggroups and .Cm pkgusers . - .It Ic $pkgname.post-install -Executed after the package is installed. If this script exits with an error -(non-zero exit code), -.Xr apk 8 -will mark the package as broken. The -.Li apk fix -command will attempt to re-run the post-install script if this occurs. - -.It Ic $pkgname.pre-upgrade -Executed before the package is upgraded. If this script exits with an error -(non-zero exit code), +Executed after the package is installed. +If this script exits with an error (non-zero exit code), .Xr apk 8 will mark the package as broken. - -.It Ic $pkgname.post-upgrade -Executed after the package is upgraded. If this script exits with an error -(non-zero exit code), +The +.Li apk fix +command will attempt to re-run the post-install script if this occurs. +.It Ic $pkgname.pre-upgrade +Executed before the package is upgraded. +If this script exits with an error (non-zero exit code), .Xr apk 8 -will mark the package as broken. The +will mark the package as broken. +.It Ic $pkgname.post-upgrade +Executed after the package is upgraded. +If this script exits with an error (non-zero exit code), +.Xr apk 8 +will mark the package as broken. +The .Li apk fix command will attempt to re-run the post-upgrade script if this occurs. - .It Ic $pkgname.pre-deinstall -Executed before the package is removed from the system. If this script exits -with an error (non-zero exit code), +Executed before the package is removed from the system. +If this script exits with an error (non-zero exit code), .Xr apk 8 will not remove the package from the system. - .It Ic $pkgname.post-deinstall -Executed after the package is removed from the system. Exiting with an error -will have no effect. - +Executed after the package is removed from the system. +Exiting with an error will have no effect. .El - - .Sh IMPLEMENTATION NOTES Currently, .Nm files are sourced as normal shell scripts. This may change at a later date. - - .Sh COMPATIBILITY The .Xr abuild 1 utility as distributed by Alpine uses the BusyBox Almquist shell, a part of .Xr busybox 1 -that is currently undocumented. It is mostly compliant with +that is currently undocumented. +It is mostly compliant with .St -p1003.2 , -with some bash-like extensions. The +with some bash-like extensions. +The .Xr abuild 1 utility as distributed by Adélie uses the user's preferred /bin/sh, which is typically .Xr bash 1 . - - .Sh SEE ALSO - SPDX license reference (on the Web at ), .Xr abuild 1 , .Xr newapkbuild 1 , .Xr apk 8 . - - .Sh HISTORY The .Nm format and .Xr abuild 1 utility first appeared in Alpine Linux 1.9. - - .Sh AUTHORS .An Timo Teräs Aq Mt timo.teras@iki.fi .An Natanael Copa Aq Mt ncopa@alpinelinux.org - +.Pp Documentation: .An A. Wilcox Aq Mt awilfox@adelielinux.org - - .\" .Sh BUGS .\" if we end up finding bugs that should be documented, put them here.