Commit 3e9503bc authored by A. Wilcox's avatar A. Wilcox Committed by Natanael Copa

Add initial manpage drafts

parent 7fc859d6
.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.
......@@ -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
......
.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 <https://spdx.org/licenses/>),
.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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment