Add initial manpage drafts

1 files changed, 488 insertions, 0 deletions

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/<repo>/<package>/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 <https://spdx.org/licenses/>),
+.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.