diff --git a/APKBUILD.5 b/APKBUILD.5 new file mode 100644 index 0000000..4392cd1 --- /dev/null +++ b/APKBUILD.5 @@ -0,0 +1,488 @@ +.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 specified +must match the pattern +.Li digit[.digit]*[_suffix[digit]]* +where +.Ar digit +must be a number greater than or equal to zero, +and +.Ar suffix +must be one of +.Em alpha , +.Em beta , +.Em pre , +.Em rc , +.Em cvs , +.Em svn , +.Em git , +.Em hg , +or +.Em p . + +.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 or dependencies 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 +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 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 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. + +.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 Dq $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. +This is typically used for virtual dependencies. + +.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 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: + +.Li Dq $pkgname.trigger=/usr/share/man:/usr/local/share/man + +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. + +.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 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 +(Adélie-specific) Specifies that the package should not be built with a debug +information package. This 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 (such as LLVM). + +.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 !libc_eglibc +Specifies that the package cannot be built on the eglibc libc. + +.It Cm !libc_musl +Specifies that the package cannot be built on the musl libc. + +.It Cm !libc_uclibc +Specifies that the package cannot be built on the uclibc 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 + +.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 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 . +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 +.Li build and +.Li 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 simply write +.Li return 0 +to skip the build phase. + +.It Cm check +Runs the package's test suite. This function must be implemented unless +.Li Dq !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 Dq #!/bin/sh +interpreter declaration as the first line. The +.Cm install +variable must contain the install scripts needed by the package. The different +actions available 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. +The +.Xr abuild 1 +utility as distributed by Alpine uses the ash shell, a part of +.Xr busybox 1 +that is currently undocumented. It is mostly compliant with +.St -p1003.2 , +but this cannot be fully relied upon. The +.Xr abuild 1 +utility as distributed by Adélie uses whatever the user has set as /bin/sh, +which is typically +.Xr bash 1 +or +.Xr dash 1 +on Adélie systems. +This is something to keep in mind as you write more complex packages. + + +.Sh COMPATIBILITY +It is highly recommended that package functions comply with +.St -p1003.2 +for maximum compatibility. + + +.Sh SEE ALSO + +The SPDX License List (Web copy 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 + +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/Makefile b/Makefile index 788ad9f..cf023c6 100644 --- a/Makefile +++ b/Makefile @@ -6,11 +6,14 @@ prefix ?= /usr bindir ?= $(prefix)/bin sysconfdir ?= /etc datadir ?= $(prefix)/share/$(PACKAGE) +mandir ?= $(prefix)/share/man SCRIPTS := abuild abuild-keygen abuild-sign newapkbuild \ abump apkgrel buildlab apkbuild-cpan checkapk \ apkbuild-gem-resolver USR_BIN_FILES := $(SCRIPTS) abuild-tar abuild-gzsplit abuild-sudo abuild-fetch abuild-rmtemp +MAN_1_PAGES := newapkbuild.1 +MAN_5_PAGES := APKBUILD.5 SAMPLES := sample.APKBUILD sample.initd sample.confd \ sample.pre-install sample.post-install AUTOTOOLS_TOOLCHAIN_FILES := config.sub config.guess @@ -91,7 +94,8 @@ help: install: $(USR_BIN_FILES) $(SAMPLES) abuild.conf functions.sh install -d $(DESTDIR)/$(bindir) $(DESTDIR)/$(sysconfdir) \ - $(DESTDIR)/$(datadir) + $(DESTDIR)/$(datadir) $(DESTDIR)/$(mandir)/man1 \ + $(DESTDIR)/$(mandir)/man5 for i in $(USR_BIN_FILES); do\ install -m 755 $$i $(DESTDIR)/$(bindir)/$$i;\ done @@ -99,6 +103,12 @@ install: $(USR_BIN_FILES) $(SAMPLES) abuild.conf functions.sh for i in adduser addgroup apk; do \ ln -fs abuild-sudo $(DESTDIR)/$(bindir)/abuild-$$i; \ done + for i in $(MAN_1_PAGES); do\ + install -m 644 $$i $(DESTDIR)/$(mandir)/man1/$$i;\ + done + for i in $(MAN_5_PAGES); do\ + install -m 644 $$i $(DESTDIR)/$(mandir)/man5/$$i;\ + done if [ -n "$(DESTDIR)" ] || [ ! -f "/$(sysconfdir)"/abuild.conf ]; then\ cp abuild.conf $(DESTDIR)/$(sysconfdir)/; \ fi diff --git a/newapkbuild.1 b/newapkbuild.1 new file mode 100644 index 0000000..93471b9 --- /dev/null +++ b/newapkbuild.1 @@ -0,0 +1,220 @@ +.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 ncopa@alpinelinux.org + +Documentation: +.An A. Wilcox Aq awilfox@adelielinux.org