Skip to content
GitLab
Menu
Projects
Groups
Snippets
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
alpine
abuild
Commits
3e9503bc
Commit
3e9503bc
authored
Nov 04, 2017
by
A. Wilcox
Committed by
Natanael Copa
Oct 03, 2018
Browse files
Add initial manpage drafts
parent
7fc859d6
Changes
3
Hide whitespace changes
Inline
Side-by-side
APKBUILD.5
0 → 100644
View file @
3e9503bc
.
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.
Makefile
View file @
3e9503bc
...
...
@@ -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
...
...
newapkbuild.1
0 → 100644
View file @
3e9503bc
.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