From 0db2d3397aef5b0f44a3b85f509b68553c1a5419 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20Louren=C3=A7o?= Date: Sun, 4 Jul 2021 17:04:46 +0100 Subject: [PATCH] Convert man pages to scdoc Closes #9986. --- .gitignore | 2 + APKBUILD.5 | 575 ---------------------------------------------- APKBUILD.5.scd | 465 +++++++++++++++++++++++++++++++++++++ Makefile | 14 +- newapkbuild.1 | 175 -------------- newapkbuild.1.scd | 146 ++++++++++++ 6 files changed, 624 insertions(+), 753 deletions(-) delete mode 100644 APKBUILD.5 create mode 100644 APKBUILD.5.scd delete mode 100644 newapkbuild.1 create mode 100644 newapkbuild.1.scd diff --git a/.gitignore b/.gitignore index a16fa23..b1c34f7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ *.tar.bz2 *.o +*.1 +*.5 abuild abuild-fetch abuild-gzsplit diff --git a/APKBUILD.5 b/APKBUILD.5 deleted file mode 100644 index bcc129a..0000000 --- a/APKBUILD.5 +++ /dev/null @@ -1,575 +0,0 @@ -.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 -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. -.Pp -The -.Nm -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. -.Pp -Libraries for scripting languages should have a prefix before the library name -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. -.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). -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 , -.Em beta , -.Em pre , -.Em rc , -.Em cvs , -.Em svn , -.Em git , -.Em hg , -or -.Em p , -optionally followed by another number. -If the suffix is -.Em alpha , -.Em beta , -.Em pre , -or -.Em rc , -it is considered to be earlier than the version without a suffix; if the suffix -is -.Em cvs , -.Em svn , -.Em git , -.Em hg , -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. -Always increment -.Cm pkgrel -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, -.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 -.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. -.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. -.It Cm license -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. -.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. -.It Cm depends -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 -.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 -.Cm install_if -to -.Li openrc ${subpkgname%-openrc}=$pkgver-r$pkgrel -which means that the OpenRC subpackage will be automatically installed if -both OpenRC and the origin package are 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 need 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 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 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 -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. -.It Cm subpackages -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 $pkgname-doc -for documentation (such as /usr/share/doc and /usr/share/man). -.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 -.Cm package -function, the -.Li foo -function must move files from -.Pa $pkgdir -or -.Pa $srcdir -to -.Pa $subpkgdir -after creating -.Pa $subpkgdir . -.Pp -The second method is to simply call the subpackage -.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 foo:funcname -where -.Li foo -is the name of the subpackage and -.Li funcname -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 $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 -.Cm foo -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. -You may specify the paths to monitor using the triggers variable as follows: -.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 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. -.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. -.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. -.It Cm checkroot -Specifies that the package's test suite will be run in -.Xr fakeroot 8 . -This is necessary for some test suites which fail when run as non-root. -.It Cm !dbg -Specifies that the package should not be built with a debug information -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 -should use the -.Fl --recursive -argument to -.Xr scanelf 1 -when attempting to find shared library (.so) dependencies for the package. -.It Cm lib64 -Specifies that the package installs files under /lib64 or /usr/lib64 and -that the test for those directories should be skipped. This is discouraged -and should only be used for packages providing compatibility for GNU libc. -.It Cm libtool -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. -.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 -.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. -.It Cm textrels -Specifies that the package's binaries are known to contain relocations against -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 -.Cm builddir . -.It Cm pkgdir -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 -.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. -.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 depends_doc -Specifies the run-time dependencies of the -doc subpackage. -.It Cm depends_libs -Specifies the run-time dependencies of the -libs subpackage. -.It Cm depends_openrc -Specifies the run-time dependencies of the -openrc subpackage. -.It Cm depends_static -Specifies the run-time dependencies of the -static subpackage. -.It Cm giturl -Specifies the URL of the Git repository to use with -.Cm abuild snapshot . -If the default branch of the repository is not desired, a different one may be -specified by appending -.Fl b Ar branch -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 -.Cm prepare -function ensures the build directories are set up correctly and applies any -*.patch files specified in -.Cm source . -You must call -.Cm default_prepare -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. -.It Cm 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 . -Note that -.Ev pkgdir -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 #!/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. -.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), -.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 -.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), -.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), -.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), -.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. -.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 -.St -p1003.2 , -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. diff --git a/APKBUILD.5.scd b/APKBUILD.5.scd new file mode 100644 index 0000000..c3dd6a7 --- /dev/null +++ b/APKBUILD.5.scd @@ -0,0 +1,465 @@ +APKBUILD(5) + +# NAME + +*APKBUILD* - metadata and instructions to build a package + + +# SYNOPSIS + +/usr/src/packages///APKBUILD + + +# DESCRIPTION + +An *APKBUILD* file is used by tools such as abuild(1) to build a package for +eventual installation by the 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. + +The *APKBUILD* format is similar to a typical shell script; you set +pre-defined variables and implement pre-defined functions, and the abuild(1) +(or similar) utility will use them to create the package. + + +## Required Variables + +The following variables must be set in all *APKBUILD* files: + +*pkgname* + Specifies the name of the package. This is typically the name of the + package upstream; however, note that all letters must be lowercased. + + Libraries for scripting languages should have a prefix before the + library name describing the language. Such prefixes include _lua-_, + _perl-_, _py-_, and _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. + +*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). 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). + + After the final number (and optional single letter), a suffix may + be appended, which must be an underscore (\_) followed by one of + _alpha_, _beta_, _pre_, _rc_, _cvs_, _svn_, _git_, _hg_, or _p_, + optionally followed by another number. If the suffix is _alpha_, + _beta_, _pre_, or _rc_, it is considered to be earlier than the + version without a suffix; if the suffix is _cvs_, _svn, _git_, _hg_, + or _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: + + 1.0, 1.1_alpha2, 1.1.3_pre, 1.1.3, 1.1.3_hg, 1.2, 1.2a, 1.2b + +*pkgrel* + 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 *pkgrel* when you + change the contents, dependencies, or metadata of a package. The + first release of a package is always 0. + +*pkgdesc* + Specifies what the package contains. *pkgdesc* must be 128 characters + or less, and should concisely describe what actions the software or + items being package will allow the user to perform. For example, + “Fully-featured word processor with spell check and plugins” + would be a sufficient *pkgdesc* for AbiWord. + +*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 *url* to an empty string (""). + +*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. + + 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. + +*license* + Specifies the license under which the package is distributed. The + value provided must match a SPDX license identifier. + +*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. + + +## Optional Variables + +The following variables are not required, but may be set in any *APKBUILD* +file. + +*checkdepends* + Specifies test-time dependencies of the package. Common packages that + are used for testing include check, dejagnu, and perl-test-command. + +*depends* + Specifies the run-time dependencies of the package. The abuild(1) + utility will automatically scan the resultant package for shared + library (.so) dependencies; do not specify them here. + +*install* + Specifies install scripts for the package, if any. See _Install + Scripts_ for more information about install scripts. + +*install_if* + Specifies a condition when apk(8) should automatically install the + package (or subpackage). For instance, the OpenRC subpackages set + + ``` + install_if="openrc ${subpkgname%-openrc}=$pkgver-r$pkgrel" + ``` + + which means that the OpenRC subpackage will be automatically + installed if both OpenRC and the origin package are installed on + the same computer. + +*makedepends* + Specifies build dependencies for the package. + +*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 script as well; see _Install Scripts_ for more + information about install scripts. + +*pkgusers* + Specifies a space-separated list of user logins to create during + build-time. Note that you will need to create the user logins in a + pre-install install script as well; see _Install Scripts_ for more + information about install scripts. + +*provides* + Specifies that the package "provides" the same contents as another + package. There are two formats that you may use for *provides*: + a provider name, and a provider name with version. + + Specifying a provider name with version such as _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 `apk add foobar` + or similar, and it will conflict with a package named _foobar_. + + Specifying a provider name without a version such as _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 \`apk add baz` they will be provided a list + of packages that provide _baz_ and must select one and install it. + +*provider_priority* + Specifies the numeric value for apk(8) to use for the package when + considering which provider should be installed for the same *provides* + virtual provider. + +*replaces* + Specifies packages that the package replaces. This is typically + used for packages renamed by upstream. + +*subpackages* + Specifies subpackages or split packages built with this + package. Typically, this will include _$pkgname-dev_ for development + files (such as _/usr/include_ and static library files) and + _$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 _$pkgname-foo_ where _foo_ is the name + of the split function specified later in the file. Similar to the + *package* function, the _foo_ function must move files from _$pkgdir_ + or _$srcdir_ to _$subpkgdir_ after creating _$subpkgdir_. + + The second method is to simply call the subpackage _foo_ which will + create a package called _foo_ instead of _$pkgname-foo_. + + However, _foo_ in both of these examples cannot contain an hyphen, + as shell function names cannot have hyphens in them. In this case, + the third method may be used: _foo:funcname_ where _foo_ is the name + of the subpackage and _funcname_ is the name of the shell function + in the *APKBUILD* that creates it. + +*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. You may specify the paths to monitor + using the triggers variable as follows: + + ``` + $pkgname.trigger=/usr/share/man:/usr/local/share/man + ``` + + This will run the package trigger script whenever files in + _/usr/share/man_ or _/usr/local/share/man_ are created, modified, + or removed. + +*options* + The *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 writing a space between each one. + + *!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 + be needed. + + *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. + + *!check* + Specifies that the package will not run a test suite. The + reason for disabling the check phase should be noted in + a comment. + + *checkroot* + Specifies that this package's test suite will be run in + fakeroot(8). This is necessary for some test suites which + fail when run as non-root. + + *!dbg* + Specifies that the package should not be built with a debug + information package. This is the default unless DEFAULT_DBG + is set in the environment or 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. + + *!fhs* + Specifies that the package violates FHS and installs to a + location such as _/usr/local_, _/opt_, or _/srv_. + + *ldpath-recursive* + Specifies that abuild(1) should use the *--recursive* argument + to scanelf(1) when attempting to find shared library (.so) + dependencies for the package. + + *lib64* + Specifies that the package installs files under _/lib64_ + or _/usr/lib64_ and that the test for those directories + should be skipped. This is discouraged and should only be + used for packages providing compatibility for GNU libc. + + *libtool* + Specifies that the package requires its libtool (.la) + files. They will not be automatically removed by abuild(1). + + *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. + + *!strip* + Specifies that strip(1) should not be run on any of the + package's binaries. This is automatically implying if the + _-dbg_ subpackage is enabled, or if you are using DEFAULT_DBG. + + *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. + + *textrels* + Specifies that the package's binaries are known to contain + relocations against text segments. By default, abuild(1) + will refuse to create such a package because this is a + security concern. + + *toolchain* + Specifies that the package is part of the base toolchain + set and may depend on packages like _g++_. + + *!tracedeps* + Specifies that abuild(1) should not automatically populate + *depends* with shared library (.so) or symlink target + dependencies. + + +## Automatic Variables + +The following variables are defined for you by abuild(1), but may be +overridden if necessary. + +*builddir* + Specifies the directory where the source code of the package will + be built. The default value is _$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 *builddir*. + +*pkgdir* + Specifies the directory where the built files will be + installed. Typically, you will call `make DESTDIR="$pkgdir" install` + or similar to install the files. The default value is _$startdir/pkg_ + and you should not modify this variable. + +*srcdir* + Specifies the directory where the files specified in *source* + are downloaded and unpacked. The default value is _$startdir/src_ + and you should not need to modify this. + +*startdir* + Specifies the directory where the *APKBUILD* file resides. + +*subpkgdir* + Specifies the directory where the subpackage's files should be + placed. This variable is only set inside subpackage functions. + + +## 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. + +*depends_dev* + Specifies the run-time dependencies of the _-dev_ subpackage. + +*depends_doc* + Specifies the run-time dependencies of the _-doc_ subpackage. + +*depends_libs* + Specifies the run-time dependencies of the _-libs_ subpackage. + +*depends_openrc* + Specifies the run-time dependencies of the _-openrc_ subpackage. + +*depends_static* + Specifies the run-time dependencies of the _-static_ subpackage. + +*giturl* + Specifies the URL of the Git repository to use with `abuild + snapshot`. If the default branch of the repository is not desired, + a different one may be specified by appending *-b* _branch_ where + _branch_ is the branch to checkout. + + +## Functions + +Functions specified here may be present in any *APKBUILD* file, but with +the exception of *package*, are not strictly required. + +*fetch* + This function is called to download the remote files in *source*. + +*unpack* + This function unpacks any archives in *source* to *srcdir*. + +*prepare* + Prepares the source in *srcdir* to be built. The default *prepare* + function ensures the build directories are set up correctly and + applies any _\*.patch_ files specified in *source*. You must call + *default_prepare* if you write a custom *prepare* function. + +*build* + Compiles the source in *builddir*. You must implement this function + yourself. If no compilation is required, you may omit it. + +*check* + Runs the package's test suite. This function must implemented unless + *!check* was specified in *options*. + +*package* + Installs the package into *pkgdir*. Note that *pkgdir* is not + created for you; if this package installs no files (for example, + a metapackage), you must use `mkdir -p "$pkgdir"` to skip the + package phase. + + +## Install Scripts + +An install script is run when an action is taken on a package by apk(8). An +install script must be written in shell and must have a _#!/bin/sh_ +interpreter declaration as the first line. The *install* variable must +contain the install scripts needed by the package. + +The install script will be run inside the root filesystem where the package +is being installed. A single argument will be passed to call 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. + +The different actions that may have install scripts specified are as follows: + +*$pkgname.pre-install* + Executed before the package is installed. If this script exits with + an error (non-zero exit code), 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 *pkggroups* + and *pkgusers*. + +*$pkgname.post-install* + Executed after the package is installed. If this script exits + with an error (non-zero exit code), apk(8) will mark the package as + broken. The `apk fix` command will attempt to re-run the post-install + script if this occurs. + +*$pkgname.pre-upgrade* + Executed before the package is upgraded. If this script exits with + an error (non-zero exit code), apk(8) will mark the package as broken. + +*$pkgname.post-upgrade* + Executed after the package is upgraded. If this script exits with + an error (non-zero exit code), apk(8) will mark the package as + broken. The `apk fix` command will attempt to re-run the post-upgrade + script if this occurs. + +*$pkgname.pre-deinstall* + Executed before the package is removed from the system. If this + script exits with an error (non-zero exit code), apk(8) will not + remove the package from the system. + +*$pkgname.post-deinstall* + Executed after the package is removed from the system. Exiting with + an error will have no effect. + + +# IMPLEMENTATION NOTES + +Currently, *APKBUILD* files are sourced as normal shells scripts. This may +change at a later date. + + +# COMPATIBILITY + +The abuild(1) utility as distributed by Alpine Linux uses the BusyBox +Almquist shell, a part of busybox(1) that is currently undocumented. It is +mostly compliant with IEEE Std 1003.2 (“POSIX.2”), with some bash-like +extensions. The abuild(1) utility as distributed by Adélie uses the user's +preferred /bin/sh, which is typically bash(1). + + +# SEE ALSO + +SPDX license reference (on the Web at ), +abuild(1), newapkbuild(1), apk(8). + + +# HISTORY + +The *APKBUILD* format and abuild(1) utility first appeared in Alpine +Linux 1.9. + + +# AUTHORS + +Timo Teräs <_timo.teras@iki.fi_>++ +Natanael Copa <_ncopa@alpinelinux.org_> + +Documentation:++ +A. Wilcox <_awilfox@adelielinux.org_> + diff --git a/Makefile b/Makefile index f525adc..a58e0b2 100644 --- a/Makefile +++ b/Makefile @@ -15,6 +15,7 @@ MAN_1_PAGES := newapkbuild.1 MAN_5_PAGES := APKBUILD.5 SAMPLES := sample.APKBUILD sample.initd sample.confd \ sample.pre-install sample.post-install +MAN_PAGES := $(MAN_1_PAGES) $(MAN_5_PAGES) AUTOTOOLS_TOOLCHAIN_FILES := config.sub config.guess SCRIPT_SOURCES := $(addsuffix .in,$(SCRIPTS)) @@ -30,6 +31,7 @@ endif CHMOD := chmod SED := sed TAR := tar +SCDOC := scdoc LINK = $(CC) $(OBJS-$@) -o $@ $(LDFLAGS) $(LDFLAGS-$@) $(LIBS-$@) CFLAGS ?= -Wall -Werror -g @@ -65,12 +67,18 @@ OBJS-abuild-fetch = abuild-fetch.o ${SED} ${SED_REPLACE} ${SED_EXTRA} $< > $@ ${CHMOD} +x $@ +%.1: %.1.scd + ${SCDOC} < $< > $@ + +%.5: %.5.scd + ${SCDOC} < $< > $@ + P=$(PACKAGE)-$(VERSION) -all: $(USR_BIN_FILES) functions.sh +all: $(USR_BIN_FILES) $(MAN_PAGES) functions.sh clean: - @rm -f $(USR_BIN_FILES) *.o functions.sh + @rm -f $(USR_BIN_FILES) $(MAN_PAGES) *.o functions.sh %.o: %.c $(CC) $(CPPFLAGS) $(CFLAGS) $(CFLAGS-$@) -o $@ -c $< @@ -97,7 +105,7 @@ help: check: $(USR_BIN_FILE) functions.sh cd tests && bats $${FILTER:+ --filter $$FILTER} *.bats -install: $(USR_BIN_FILES) $(SAMPLES) abuild.conf functions.sh +install: $(USR_BIN_FILES) $(SAMPLES) $(MAN_PAGES) abuild.conf functions.sh install -d $(DESTDIR)/$(bindir) $(DESTDIR)/$(sysconfdir) \ $(DESTDIR)/$(sharedir) $(DESTDIR)/$(mandir)/man1 \ $(DESTDIR)/$(mandir)/man5 diff --git a/newapkbuild.1 b/newapkbuild.1 deleted file mode 100644 index 5188e82..0000000 --- a/newapkbuild.1 +++ /dev/null @@ -1,175 +0,0 @@ -.Dd November 4, 2017 -.Dt NEWAPKBUILD 1 PRM -.Os "Alpine Linux" -.Sh NAME -.Nm newapkbuild -.Nd generate a new APKBUILD -.Sh SYNOPSIS -.Nm -.Op Fl n Ar NAME -.Op Fl d Ar DESC -.Op Fl l Ar LICENSE -.Op Fl u Ar URL -.Op Fl aCmpy -.Op Fl cfhs -.Op Ar pkgname Op Ar -pkgver -.Nm -.Op Fl n Ar NAME -.Op Fl d Ar DESC -.Op Fl l Ar LICENSE -.Op Fl u Ar URL -.Op Fl aCmpy -.Op Fl cfhs -.Op Ar source_url -.Sh DESCRIPTION -.Nm -generates a new APKBUILD for use with -.Xr abuild 1 . -.Bl -tag -width "pkgname-pkgver" -offset indent -compact -.It Fl n Ar NAME -Specifies the name of the new package. -A new directory called -.Ar NAME -will be created in the current directory, with the APKBUILD file. -.It Fl d Ar DESC -Specifies the description (pkgdesc=) for the new package. -.It Fl l Ar LICENSE -Specifies the license under which the new package is distributed. -This should match an SPDX Identifier. -.It Fl u Ar URL -Specifies the Web page (url=) for the new package. -This should -.Em not -be the source package URL; it should be the project's main Web page. -.It Fl c -Causes -.Nm -to additionally copy an init.d script, conf.d file, and sample pre- and post- -install scripts to the APKBUILD directory. -This allows you to have a quick start for daemon packages. -.It Fl f -Forces -.Nm -to overwrite an existing APKBUILD, if one already exists in the package -directory. -.It Fl h -Displays usage information. -.It Fl s -Create an automatic SourceForge URL for the package based on its name and -version. -This is only valid if -.Ar pkgname-pkgver -is specified on the command line. -.It Ar pkgname-pkgver -Specify the package name, if not already specified by -.Fl n . -If followed by a dash (-) and a valid version string, additionally specify the -package's version. -.El -.Ss Build system type -.Nm -will try to automatically detect the build system by inspecting the source -directory if -.Ar source_url -is specified, and write out typical build instructions for that build system. -If you do not specify the source URL, or you want to override auto-detection, -you may specify one of the following four flags: -.Bl -tag -width "-a" -offset indent -compact -.It Fl a -Specifies that the package uses autotools. -The APKBUILD will contain a typical invocation of ./configure, make, and make -install. -.It Fl C -Specifies that the package uses CMake. -CMake will be added to the makedepends and a typical CMake invocation will be -added to the APKBUILD. -.It Fl m -Specifies that the package uses Meson. -A typical Meson and Ninja invocation will be added to the APKBUILD. -.It Fl p -Specifies that the package uses a Perl Makefile.PL file. -The CPAN template will be used. -.It Fl y -Specifies that the package uses a Python setup.py build system. -Python will be added to the makedepends. -.El -If you do not specify any option, and you do not specify the source URL, the -generated APKBUILD file will not contain any build instructions. -.Sh FILES -All files generated will be placed in a -.Pa pkgname -directory inside the current working directory, with -.Pa pkgname -being created if it does not exist. -.Bl -tag -width "pkgname.post-install" -compact -.It Pa APKBUILD -.Nm -will create -.Pa APKBUILD -with the details gathered from the invocation of -.Nm , -and introspection of the downloaded package source if -.Ar source_url -is provided. -For more information about APKBUILD and its format, see -.Xr APKBUILD 5 . -.It Pa pkgname.initd -If -.Fl c -is given, -.Nm -will create -.Pa pkgname.initd -with example data to assist in the creation of an init.d script for a daemon. -.It Pa pkgname.confd -If -.Fl c -is given, -.Nm -will create -.Pa pkgname.confd -to assist in the creation of a conf.d file for a daemon, used by init.d -scripts. -conf.d files are used to configure init.d scripts; for more information, see -.Xr openrc 8 -and -.Xr rc_config 3 . -.It Pa pkgname.pre-install -If -.Fl c -is given, -.Nm -will create -.Pa pkgname.pre-install , -the contents of which will be run by -.Xr apk 8 -before the package is installed. -.It Pa pkgname.post-install -If -.Fl c -is given, -.Nm -will create -.Pa pkgname.post-install , -the contents of which will be run by -.Xr apk 8 -after the package is successfully installed. -For more information about apk install hooks, consult the -.Xr apk 8 -manual. -.El -.Sh EXAMPLES -newapkbuild -n sharutils -d "Utilities for manipulating shell archives" \\ - -l "GPL-3.0+" -u "https://www.gnu.org/software/sharutils/" -a \\ - https://ftp.gnu.org/gnu/sharutils/sharutils-4.15.2.tar.xz -.Sh SEE ALSO -SPDX license reference (on the Web at ), -.Xr abuild 1 , -.Xr apk 8 , -.Xr APKBUILD 5 . -.Sh AUTHORS -.Nm : -.An Natanael Copa Aq Mt ncopa@alpinelinux.org -.Pp -Documentation: -.An A. Wilcox Aq Mt awilfox@adelielinux.org diff --git a/newapkbuild.1.scd b/newapkbuild.1.scd new file mode 100644 index 0000000..6fb17b9 --- /dev/null +++ b/newapkbuild.1.scd @@ -0,0 +1,146 @@ +newapkbuild(1) + +# NAME + + *newapkbuild* - generate a new APKBUILD + + +# SYNOPSIS + + *newapkbuild* _options_... [_pkgname_[-_pkgver_] | _source_url_] + + +# DESCRIPTION + +*newapkbuild* generates a new APKBUILD for use with abuild(1). _pkgname_ +specifies the package name, if not already specified with *-n*. If followed +by a dash (-) and a valid version string _pkgver_, additionally specify +the package's version. + +*newapkbuild* will try to automatically detect the build system by inspecting +the source directory if _source_url_ is specified, and write out typical +build instructions for that build system. If you do not specify the source +URL, or want to override auto-detection, you may specify the build system +with the appropriate option. If no _source_url_ and no option are specified, +the generated APKBUILD file will not contain any build instructions. + + +# OPTIONS + +*-a* + Specifies that the package uses autotools. + +*-C* + Specifies that the package uses CMake. CMake will be added to + the makedepends. + +*-c* + Causes *newapkbuild* to additionally copy an init.d script, conf.d + file, and sample pre- and post- install scripts to the APKBUILD + directory. This allows you to have a quick start for daemon + packages. See the FILES section for details. + +*-d* _DESC_ + Specifies the description (pkgdesc=) for the new package. + +*-f* + Forces *newapkbuild* to overwrite an existing APKBUILD, if one + already exists in the package directory. + +*-h* + Displays usage information. + +*-l* _LICENSE_ + Specifies the license under which the new package is distributed. This + should match an SPDX Identifier. + +*-m* + Specifies that the package uses Meson. Meson will be added to + the makedepends. + +*-n* _NAME_ + Specifies the name of the new package. A new directory called _NAME_ + will be created in the current directory, with the APKBUILD file. + +*-p* + Specifies that the package uses a Perl Makefile.PL file. The CPAN + template will be used and Perl will be added to the depends. + +*-r* + Specifies that the package uses Cargo. Cargo will be added to + the makedepends. + +*-s* + Create an automatic SourceForge URL for the package based on its + name and version. This is only valid if _pkgname-pkgver_ is specified + on the command line. + +*-u* _URL_ + Specifies the Web page (url=) for the new package. This should _not_ + be the source package URL; it should be the project's main Web page. + +*-y* + Specifies that the package uses a Python setup.py build + system. Python's setuptools will be added to the makedepends and + Python to the depends. + + +# FILES + +All files generated will be places in a _pkgname_ directory inside the +current working directory, with _pkgname_ being created if it does not exist. + +APKBUILD + *newapkbuild* will create an APKBUILD with the details gathered + from the invocation of *newapkbuild*, and introspection of the + downloaded package source if _source_url_ is provided. For more + information about APKBUILD and its format, see APKBUILD(5). + +_pkgname_.initd + If *-c* is given, *newapkbuild* will create _pkgname_.initd with + example data to assist in the creation of an init.d script for + a daemon. + +_pkgname_.confd + If *-c* is given, *newapkbuild* will create _pkgname_.confd to + assist in the creation of a conf.d file for a daemon, used by + init.d scripts. conf.d files are used to configure init.d scripts; + for more information, see openrc(8) and rc_config(3). + +_pkgname_.pre-install + If *-c* is given, *newapkbuild* will create _pkgname_.pre-install, + the contents of which will be run by apk(8) before the package + is installed. + +_pkgname_.post-install + If *-c* is given, *newapkbuild* will create _pkgname_.post-install, + the contents of which will be run by apk(8) after the package is + successfully installed. For more information about apk install hooks, + consult the apk(8) manual. + + +# EXAMPLES + +``` +newapkbuild \\ + -n sharutils \\ + -d "Utilities for manipulating shell archives" \\ + -l "GPL-3.0+" \\ + -u "https://www.gnu.org/software/sharutils/" \\ + -a \\ + "https://ftp.gnu.org/gnu/sharutils/sharutils-4.15.2.tar.xz" +``` + + +# SEE ALSO + +SPDX license reference (on the Web at ), +abuild(1), apk(8), APKBUILD(5). + + +# AUTHORS + +*newapkbuild*: Natanael Copa <_ncopa@alpinelinux.org_> + +Documentation:++ +A. Wilcox <_wilfox@adelielinux.org_>