APKBUILD.5 17.2 KB
Newer Older
A. Wilcox's avatar
A. Wilcox committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
.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
16 17 18 19 20
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.
A. Wilcox's avatar
A. Wilcox committed
21 22 23 24 25 26 27 28 29 30 31 32 33
.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
34 35 36
Specifies name of the package.
This is typically the name of the package upstream; however, note that all
letters must be lowercased.
A. Wilcox's avatar
A. Wilcox committed
37 38
.Pp
Libraries for scripting languages should have a prefix before the library name
39 40
describing the language.
Such prefixes include
A. Wilcox's avatar
A. Wilcox committed
41 42 43 44 45
.Em lua- ,
.Em perl- ,
.Em py- ,
and
.Em rb- .
46 47 48
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.
A. Wilcox's avatar
A. Wilcox committed
49
.It Cm pkgver
50 51 52
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).
53 54
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).
55
.Pp
56 57
After the final number (and optional single letter), a suffix may be appended,
which must be an underscore (_) followed by one of
A. Wilcox's avatar
A. Wilcox committed
58 59 60 61 62 63 64 65 66
.Em alpha ,
.Em beta ,
.Em pre ,
.Em rc ,
.Em cvs ,
.Em svn ,
.Em git ,
.Em hg ,
or
67
.Em p ,
68 69
optionally followed by another number.
If the suffix is
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
.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:
86
.Pp
87
1.0, 1.1_alpha2, 1.1.3_pre, 1.1.3, 1.1.3_hg, 1.2, 1.2a, 1.2b
A. Wilcox's avatar
A. Wilcox committed
88
.It Cm pkgrel
89 90 91
Specifies the package release number of this particular package version.
This indicates when a package has changed without a corresponding change in
version.
A. Wilcox's avatar
A. Wilcox committed
92 93
Always increment
.Cm pkgrel
94 95
when you change the contents, dependencies, or metadata of a package.
The first release of a package is always
A. Wilcox's avatar
A. Wilcox committed
96 97 98 99 100
.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
101 102 103
software or items being packaged will allow the user to perform.
For example,
.Dq Fully-featured word processor with spell check and many plugins
A. Wilcox's avatar
A. Wilcox committed
104 105 106 107
would be a sufficient
.Cm pkgdesc
for AbiWord.
.It Cm url
108 109 110 111
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
A. Wilcox's avatar
A. Wilcox committed
112 113
.Cm url
to an empty string ("").
114
.It Cm arch
115 116 117 118
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
119
You may use "noarch" if the package does not contain any architecture-specific
120 121 122 123
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.
A. Wilcox's avatar
A. Wilcox committed
124
.It Cm license
125 126
Specifies the license under which the package is distributed.
The value provided must match a SPDX license identifier.
A. Wilcox's avatar
A. Wilcox committed
127 128
.It Cm source
Specifies the location of both local and remote source files used to build the
129 130 131 132
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.
A. Wilcox's avatar
A. Wilcox committed
133 134 135 136 137 138
.El
.Ss Optional Variables
The following variables are not required, but may be set in any
.Nm
file:
.Bl -tag -width Ds
A. Wilcox's avatar
A. Wilcox committed
139
.It Cm checkdepends
140 141 142
Specifies test-time dependencies of the package.
Common packages that are used for testing include check, dejagnu, and
perl-test-command.
A. Wilcox's avatar
A. Wilcox committed
143
.It Cm depends
144 145
Specifies the run-time dependencies of the package.
The
A. Wilcox's avatar
A. Wilcox committed
146 147 148 149
.Xr abuild 1
utility will automatically scan the resultant package for shared library (.so)
dependencies; do not specify them here.
.It Cm install
150 151
Specifies install scripts for the package, if any.
See
A. Wilcox's avatar
A. Wilcox committed
152 153 154 155 156
.Sx Install Scripts
for more information about install scripts.
.It Cm install_if
Specifies a condition when
.Xr apk 8
157 158
should automatically install the package (or subpackage).
For instance, the OpenRC subpackages set
A. Wilcox's avatar
A. Wilcox committed
159 160
.Cm install_if
to
161
.Li $pkgname=$pkgver openrc
A. Wilcox's avatar
A. Wilcox committed
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179
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.
180 181 182
There are two formats that you may use for
.Cm provides :
a provider name, and a provider name with version.
183
.Pp
184
Specifying a provider name with version such as
185 186 187
.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
188 189
.Li apk add foobar
or similar, and it will conflict with a package named foobar.
190
.Pp
191
Specifying a provider name without a version such as
192 193 194 195
.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
196 197 198
.Li apk add baz
they will provided a list of packages that provide baz and must select one and
install it.
A. Wilcox's avatar
A. Wilcox committed
199 200 201 202 203 204 205 206
.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
207 208
Specifies packages that the package replaces.
This is typically used for packages renamed by upstream.
209
.It Cm subpackages
210 211 212
Specifies subpackages or split packages built with this package.
Typically, this will include
.Li $pkgname-dev
213
for development files (such as /usr/include and static library files) and
214
.Li $pkgname-doc
215
for documentation (such as /usr/share/doc and /usr/share/man).
216 217 218 219
.Pp
Each subpackage may be specified using three different methods.
The first, and most common, is
.Li $pkgname-foo
220 221
where
.Li foo
222 223
is the name of the split function specified later in the file.
Similar to the
224 225 226 227 228 229 230 231 232 233 234
.Cm package
function, the
.Li foo
function must move files from
.Pa $pkgdir
or
.Pa $srcdir
to
.Pa $subpkgdir
after creating
.Pa $subpkgdir .
235
.Pp
236
The second method is to simply call the subpackage
237
.Li foo
238 239 240
which will create a package called
.Li foo
instead of pkgname-foo.
241
.Pp
242 243 244 245
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:
246
.Li foo:funcname
247 248 249 250 251 252 253
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.
254
.Pp
255 256
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
257 258 259
not architecture-specific as noarch.
For example,
.Li $pkgname-doc $pkgname-foo $pkgname-foo-misc:foo_misc:noarch
260 261 262 263 264 265 266
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.
A. Wilcox's avatar
A. Wilcox committed
267
.It Cm triggers
268 269 270
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.
A. Wilcox's avatar
A. Wilcox committed
271
You may specify the paths to monitor using the triggers variable as follows:
272 273 274
.Pp
.Li $pkgname.trigger=/usr/share/man:/usr/local/share/man
.Pp
A. Wilcox's avatar
A. Wilcox committed
275 276 277 278 279 280 281 282 283
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
284 285 286
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.
A. Wilcox's avatar
A. Wilcox committed
287 288 289
.Bl -tag -width Ds
.It Cm !archcheck
Specifies that the package contains binaries that cannot run on the target
290 291 292
architecture.
This is primarily used for packages containing firmware, and should typically
never need to be used.
A. Wilcox's avatar
A. Wilcox committed
293 294
.It Cm charset.alias
Specifies that the package ships a /usr/lib/charset.alias file and that it
295 296 297
should be installed on the user's system.
This is almost never the case.
Do not use this option.
A. Wilcox's avatar
A. Wilcox committed
298
.It Cm !check
299 300
Specifies that the package will not run a test suite.
The reason for disabling the check phase should be noted in a comment.
301 302
.It Cm checkroot
Specifies that the package's test suite will be run in
A. Wilcox's avatar
A. Wilcox committed
303
.Xr fakeroot 8 .
304
This is necessary for some test suites which fail when run as non-root.
A. Wilcox's avatar
A. Wilcox committed
305
.It Cm !dbg
306
Specifies that the package should not be built with a debug information
307 308
package.
This is the default unless
309 310 311 312 313 314
.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.
A. Wilcox's avatar
A. Wilcox committed
315 316 317 318 319 320 321 322 323 324 325 326 327 328 329
.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 libtool
330 331
Specifies that the package requires its libtool (.la) files.
They will not be automatically removed by
A. Wilcox's avatar
A. Wilcox committed
332 333
.Xr abuild 1 .
.It Cm net
334 335
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.
A. Wilcox's avatar
A. Wilcox committed
336 337 338
.It Cm !strip
Specifies that
.Xr strip 1
339 340 341
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
A. Wilcox's avatar
A. Wilcox committed
342 343
.Ev DEFAULT_DBG .
.It Cm suid
344 345 346
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.
A. Wilcox's avatar
A. Wilcox committed
347
.It Cm textrels
348
Specifies that the package's binaries are known to contain relocations against
349 350
text segments.
By default,
351 352
.Xr abuild 1
will refuse to create such a package because this is a security concern.
A. Wilcox's avatar
A. Wilcox committed
353 354 355 356 357 358 359 360 361 362 363
.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
364 365 366 367 368 369 370 371 372
.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
373 374 375
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
376 377
.Cm builddir .
.It Cm pkgdir
378 379 380 381 382
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
383 384 385 386 387
.Pa $startdir/pkg
and you should not modify this variable.
.It Cm srcdir
Specifies the directory where the files specified in
.Cm source
388 389
are downloaded and unpacked.
The default value is
390 391 392 393 394 395 396
.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
397 398
Specifies the directory where the subpackage's files should be placed.
This variable is only set inside subpackage functions.
399
.El
A. Wilcox's avatar
A. Wilcox committed
400 401 402 403 404 405 406
.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.
407 408
.It Cm depends_doc
Specifies the run-time dependencies of the -doc subpackage.
409 410
.It Cm depends_libs
Specifies the run-time dependencies of the -libs subpackage.
411 412
.It Cm depends_openrc
Specifies the run-time dependencies of the -openrc subpackage.
A. Wilcox's avatar
A. Wilcox committed
413 414 415 416 417 418 419 420 421 422 423 424 425 426
.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
427
.Cm package ,
A. Wilcox's avatar
A. Wilcox committed
428 429 430 431 432 433 434 435 436 437 438 439 440
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
441 442
to be built.
The default
A. Wilcox's avatar
A. Wilcox committed
443 444 445 446 447 448 449 450 451 452 453 454
.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 .
455 456
You must implement this function yourself.
If no compilation is required, you may omit it.
A. Wilcox's avatar
A. Wilcox committed
457
.It Cm check
458 459 460
Runs the package's test suite.
This function must be implemented unless
.Li !check
A. Wilcox's avatar
A. Wilcox committed
461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476
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
477 478 479
.Li #!/bin/sh
interpreter declaration as the first line.
The
A. Wilcox's avatar
A. Wilcox committed
480
.Cm install
481
variable must contain the install scripts needed by the package.
482
.Pp
483
The install script will be run inside the root filesystem where the package is
484 485 486 487 488 489 490
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
491
The different actions that may have install scripts specified are as follows:
A. Wilcox's avatar
A. Wilcox committed
492 493
.Bl -tag -width Ds
.It Ic $pkgname.pre-install
494 495
Executed before the package is installed.
If this script exits with an error (non-zero exit code),
A. Wilcox's avatar
A. Wilcox committed
496
.Xr apk 8
497 498 499
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
A. Wilcox's avatar
A. Wilcox committed
500 501 502 503
.Cm pkggroups
and
.Cm pkgusers .
.It Ic $pkgname.post-install
504 505
Executed after the package is installed.
If this script exits with an error (non-zero exit code),
A. Wilcox's avatar
A. Wilcox committed
506
.Xr apk 8
507 508
will mark the package as broken.
The
A. Wilcox's avatar
A. Wilcox committed
509 510 511
.Li apk fix
command will attempt to re-run the post-install script if this occurs.
.It Ic $pkgname.pre-upgrade
512 513
Executed before the package is upgraded.
If this script exits with an error (non-zero exit code),
A. Wilcox's avatar
A. Wilcox committed
514 515 516
.Xr apk 8
will mark the package as broken.
.It Ic $pkgname.post-upgrade
517 518
Executed after the package is upgraded.
If this script exits with an error (non-zero exit code),
A. Wilcox's avatar
A. Wilcox committed
519
.Xr apk 8
520 521
will mark the package as broken.
The
A. Wilcox's avatar
A. Wilcox committed
522 523 524
.Li apk fix
command will attempt to re-run the post-upgrade script if this occurs.
.It Ic $pkgname.pre-deinstall
525 526
Executed before the package is removed from the system.
If this script exits with an error (non-zero exit code),
A. Wilcox's avatar
A. Wilcox committed
527 528 529
.Xr apk 8
will not remove the package from the system.
.It Ic $pkgname.post-deinstall
530 531
Executed after the package is removed from the system.
Exiting with an error will have no effect.
A. Wilcox's avatar
A. Wilcox committed
532 533 534 535 536
.El
.Sh IMPLEMENTATION NOTES
Currently,
.Nm
files are sourced as normal shell scripts.  This may change at a later date.
537
.Sh COMPATIBILITY
A. Wilcox's avatar
A. Wilcox committed
538 539
The
.Xr abuild 1
540
utility as distributed by Alpine uses the BusyBox Almquist shell, a part of
A. Wilcox's avatar
A. Wilcox committed
541
.Xr busybox 1
542 543
that is currently undocumented.
It is mostly compliant with
A. Wilcox's avatar
A. Wilcox committed
544
.St -p1003.2 ,
545 546
with some bash-like extensions.
The
A. Wilcox's avatar
A. Wilcox committed
547
.Xr abuild 1
548 549 550
utility as distributed by Adélie uses the user's preferred /bin/sh, which is
typically
.Xr bash 1 .
A. Wilcox's avatar
A. Wilcox committed
551
.Sh SEE ALSO
552
SPDX license reference (on the Web at <https://spdx.org/licenses/>),
A. Wilcox's avatar
A. Wilcox committed
553 554 555 556 557 558 559 560 561 562 563 564
.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
565
.Pp
A. Wilcox's avatar
A. Wilcox committed
566 567 568 569
Documentation:
.An A. Wilcox Aq Mt awilfox@adelielinux.org
.\" .Sh BUGS
.\" if we end up finding bugs that should be documented, put them here.