RepoMirrors
/
abuild
mirror of https://gitlab.alpinelinux.org/alpine/abuild.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Convert man pages to scdoc 

Closes #9986.
This commit is contained in:
Rodrigo Lourenço 2021-07-04 17:04:46 +01:00 committed by Kevin Daudt
parent f550705177
commit 0db2d3397a
6 changed files with 624 additions and 753 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -1,5 +1,7 @@
*.tar.bz2
*.o
*.1
*.5
abuild
abuild-fetch
abuild-gzsplit

575
APKBUILD.5
View File

@ -1,575 +0,0 @@
.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 of a package must consist of one or more numbers separated by the
radix (decimal point).
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).
.Pp
After the final number (and optional single letter), a suffix may be appended,
which must be an underscore (_) followed by one of
.Em alpha ,
.Em beta ,
.Em pre ,
.Em rc ,
.Em cvs ,
.Em svn ,
.Em git ,
.Em hg ,
or
.Em p ,
optionally followed by another number.
If the suffix is
.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:
.Pp
1.0, 1.1_alpha2, 1.1.3_pre, 1.1.3, 1.1.3_hg, 1.2, 1.2a, 1.2b
.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, dependencies, or metadata 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,
.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 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.
.Pp
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 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 checkdepends
Specifies test-time dependencies of the package.
Common packages that are used for testing include check, dejagnu, and
perl-test-command.
.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 openrc ${subpkgname%-openrc}=$pkgver-r$pkgrel
which means that the OpenRC subpackage will be automatically installed if
both OpenRC and the origin package are 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 need 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.
There are two formats that you may use for
.Cm provides :
a provider name, and a provider name with version.
.Pp
Specifying a provider name with version such as
.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
.Li apk add foobar
or similar, and it will conflict with a package named foobar.
.Pp
Specifying a provider name without a version such as
.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
.Li apk add baz
they will provided a list of packages that provide baz and must select one and
install it.
.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 subpackages
Specifies subpackages or split packages built with this package.
Typically, this will include
.Li $pkgname-dev
for development files (such as /usr/include and static library files) and
.Li $pkgname-doc
for documentation (such as /usr/share/doc and /usr/share/man).
.Pp
Each subpackage may be specified using three different methods.
The first, and most common, is
.Li $pkgname-foo
where
.Li foo
is the name of the split function specified later in the file.
Similar to the
.Cm package
function, the
.Li foo
function must move files from
.Pa $pkgdir
or
.Pa $srcdir
to
.Pa $subpkgdir
after creating
.Pa $subpkgdir .
.Pp
The second method is to simply call the subpackage
.Li foo
which will create a package called
.Li foo
instead of pkgname-foo.
.Pp
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:
.Li foo:funcname
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.
.Pp
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
not architecture-specific as noarch.
For example,
.Li $pkgname-doc $pkgname-foo $pkgname-foo-misc:foo_misc:noarch
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.
.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:
.Pp
.Li $pkgname.trigger=/usr/share/man:/usr/local/share/man
.Pp
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 writing 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 in
.Xr fakeroot 8 .
This is necessary for some test suites which fail when run as non-root.
.It Cm !dbg
Specifies that the package should not be built with a debug information
package.
This is the default unless
.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.
.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 lib64
Specifies that the package installs files under /lib64 or /usr/lib64 and
that the test for those directories should be skipped. This is discouraged
and should only be used for packages providing compatibility for GNU 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 are known to contain relocations against
text segments.
By default,
.Xr abuild 1
will refuse to create such a package because this is a security concern.
.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 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
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
.Cm builddir .
.It Cm pkgdir
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
.Pa $startdir/pkg
and you should not modify this variable.
.It Cm srcdir
Specifies the directory where the files specified in
.Cm source
are downloaded and unpacked.
The default value is
.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
Specifies the directory where the subpackage's files should be placed.
This variable is only set inside subpackage functions.
.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 depends_doc
Specifies the run-time dependencies of the -doc subpackage.
.It Cm depends_libs
Specifies the run-time dependencies of the -libs subpackage.
.It Cm depends_openrc
Specifies the run-time dependencies of the -openrc subpackage.
.It Cm depends_static
Specifies the run-time dependencies of the -static subpackage.
.It Cm giturl
Specifies the URL of the Git repository to use with
.Cm abuild snapshot .
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
.Cm 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 omit it.
.It Cm check
Runs the package's test suite.
This function must be implemented unless
.Li !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 #!/bin/sh
interpreter declaration as the first line.
The
.Cm install
variable must contain the install scripts needed by the package.
.Pp
The install script will be run inside the root filesystem where the package is
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
The different actions that may have install scripts specified 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.
.Sh COMPATIBILITY
The
.Xr abuild 1
utility as distributed by Alpine uses the BusyBox Almquist shell, a part of
.Xr busybox 1
that is currently undocumented.
It is mostly compliant with
.St -p1003.2 ,
with some bash-like extensions.
The
.Xr abuild 1
utility as distributed by Adélie uses the user's preferred /bin/sh, which is
typically
.Xr bash 1 .
.Sh SEE ALSO
SPDX license reference (on the Web 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
.Pp
Documentation:
.An A. Wilcox Aq Mt awilfox@adelielinux.org
.\" .Sh BUGS
.\" if we end up finding bugs that should be documented, put them here.

465
APKBUILD.5.scd Normal file
View File

@ -0,0 +1,465 @@
APKBUILD(5)
# NAME
*APKBUILD* - metadata and instructions to build a package
# SYNOPSIS
/usr/src/packages/<repo>/<package>/APKBUILD
# DESCRIPTION
An *APKBUILD* file is used by tools such as abuild(1) to build a package for
eventual installation by the 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.
The *APKBUILD* format is similar to a typical shell script; you set
pre-defined variables and implement pre-defined functions, and the abuild(1)
(or similar) utility will use them to create the package.
## Required Variables
The following variables must be set in all *APKBUILD* files:
*pkgname*
Specifies the name of the package. This is typically the name of the
package upstream; however, note that all letters must be lowercased.
Libraries for scripting languages should have a prefix before the
library name describing the language. Such prefixes include _lua-_,
_perl-_, _py-_, and _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.
*pkgver*
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). 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).
After the final number (and optional single letter), a suffix may
be appended, which must be an underscore (\_) followed by one of
_alpha_, _beta_, _pre_, _rc_, _cvs_, _svn_, _git_, _hg_, or _p_,
optionally followed by another number. If the suffix is _alpha_,
_beta_, _pre_, or _rc_, it is considered to be earlier than the
version without a suffix; if the suffix is _cvs_, _svn, _git_, _hg_,
or _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:
1.0, 1.1_alpha2, 1.1.3_pre, 1.1.3, 1.1.3_hg, 1.2, 1.2a, 1.2b
*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 *pkgrel* when you
change the contents, dependencies, or metadata of a package. The
first release of a package is always 0.
*pkgdesc*
Specifies what the package contains. *pkgdesc* must be 128 characters
or less, and should concisely describe what actions the software or
items being package will allow the user to perform. For example,
“Fully-featured word processor with spell check and plugins”
would be a sufficient *pkgdesc* for AbiWord.
*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 *url* to an empty string ("").
*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.
*license*
Specifies the license under which the package is distributed. The
value provided must match a SPDX license identifier.
*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.
## Optional Variables
The following variables are not required, but may be set in any *APKBUILD*
file.
*checkdepends*
Specifies test-time dependencies of the package. Common packages that
are used for testing include check, dejagnu, and perl-test-command.
*depends*
Specifies the run-time dependencies of the package. The abuild(1)
utility will automatically scan the resultant package for shared
library (.so) dependencies; do not specify them here.
*install*
Specifies install scripts for the package, if any. See _Install
Scripts_ for more information about install scripts.
*install_if*
Specifies a condition when apk(8) should automatically install the
package (or subpackage). For instance, the OpenRC subpackages set
```
install_if="openrc ${subpkgname%-openrc}=$pkgver-r$pkgrel"
```
which means that the OpenRC subpackage will be automatically
installed if both OpenRC and the origin package are installed on
the same computer.
*makedepends*
Specifies build dependencies for the package.
*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 script as well; see _Install Scripts_ for more
information about install scripts.
*pkgusers*
Specifies a space-separated list of user logins to create during
build-time. Note that you will need to create the user logins in a
pre-install install script as well; see _Install Scripts_ for more
information about install scripts.
*provides*
Specifies that the package "provides" the same contents as another
package. There are two formats that you may use for *provides*:
a provider name, and a provider name with version.
Specifying a provider name with version such as _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 `apk add foobar`
or similar, and it will conflict with a package named _foobar_.
Specifying a provider name without a version such as _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 \`apk add baz` they will be provided a list
of packages that provide _baz_ and must select one and install it.
*provider_priority*
Specifies the numeric value for apk(8) to use for the package when
considering which provider should be installed for the same *provides*
virtual provider.
*replaces*
Specifies packages that the package replaces. This is typically
used for packages renamed by upstream.
*subpackages*
Specifies subpackages or split packages built with this
package. Typically, this will include _$pkgname-dev_ for development
files (such as _/usr/include_ and static library files) and
_$pkgname-doc_ for documentation (such as _/usr/share/doc_ and
_/usr/share/man_).
Each subpackage may be specified using three different methods. The
first, and most common, is _$pkgname-foo_ where _foo_ is the name
of the split function specified later in the file. Similar to the
*package* function, the _foo_ function must move files from _$pkgdir_
or _$srcdir_ to _$subpkgdir_ after creating _$subpkgdir_.
The second method is to simply call the subpackage _foo_ which will
create a package called _foo_ instead of _$pkgname-foo_.
However, _foo_ in both of these examples cannot contain an hyphen,
as shell function names cannot have hyphens in them. In this case,
the third method may be used: _foo:funcname_ where _foo_ is the name
of the subpackage and _funcname_ is the name of the shell function
in the *APKBUILD* that creates it.
*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:
```
$pkgname.trigger=/usr/share/man:/usr/local/share/man
```
This will run the package trigger script whenever files in
_/usr/share/man_ or _/usr/local/share/man_ are created, modified,
or removed.
*options*
The *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 writing a space between each one.
*!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
be needed.
*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.
*!check*
Specifies that the package will not run a test suite. The
reason for disabling the check phase should be noted in
a comment.
*checkroot*
Specifies that this package's test suite will be run in
fakeroot(8). This is necessary for some test suites which
fail when run as non-root.
*!dbg*
Specifies that the package should not be built with a debug
information package. This is the default unless DEFAULT_DBG
is set in the environment or 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.
*!fhs*
Specifies that the package violates FHS and installs to a
location such as _/usr/local_, _/opt_, or _/srv_.
*ldpath-recursive*
Specifies that abuild(1) should use the *--recursive* argument
to scanelf(1) when attempting to find shared library (.so)
dependencies for the package.
*lib64*
Specifies that the package installs files under _/lib64_
or _/usr/lib64_ and that the test for those directories
should be skipped. This is discouraged and should only be
used for packages providing compatibility for GNU libc.
*libtool*
Specifies that the package requires its libtool (.la)
files. They will not be automatically removed by abuild(1).
*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.
*!strip*
Specifies that strip(1) should not be run on any of the
package's binaries. This is automatically implying if the
_-dbg_ subpackage is enabled, or if you are using DEFAULT_DBG.
*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.
*textrels*
Specifies that the package's binaries are known to contain
relocations against text segments. By default, abuild(1)
will refuse to create such a package because this is a
security concern.
*toolchain*
Specifies that the package is part of the base toolchain
set and may depend on packages like _g++_.
*!tracedeps*
Specifies that abuild(1) should not automatically populate
*depends* with shared library (.so) or symlink target
dependencies.
## Automatic Variables
The following variables are defined for you by abuild(1), but may be
overridden if necessary.
*builddir*
Specifies the directory where the source code of the package will
be built. The default value is _$srcdir/$pkgname-$pkgver_ 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 *builddir*.
*pkgdir*
Specifies the directory where the built files will be
installed. Typically, you will call `make DESTDIR="$pkgdir" install`
or similar to install the files. The default value is _$startdir/pkg_
and you should not modify this variable.
*srcdir*
Specifies the directory where the files specified in *source*
are downloaded and unpacked. The default value is _$startdir/src_
and you should not need to modify this.
*startdir*
Specifies the directory where the *APKBUILD* file resides.
*subpkgdir*
Specifies the directory where the subpackage's files should be
placed. This variable is only set inside subpackage functions.
## 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.
*depends_dev*
Specifies the run-time dependencies of the _-dev_ subpackage.
*depends_doc*
Specifies the run-time dependencies of the _-doc_ subpackage.
*depends_libs*
Specifies the run-time dependencies of the _-libs_ subpackage.
*depends_openrc*
Specifies the run-time dependencies of the _-openrc_ subpackage.
*depends_static*
Specifies the run-time dependencies of the _-static_ subpackage.
*giturl*
Specifies the URL of the Git repository to use with `abuild
snapshot`. If the default branch of the repository is not desired,
a different one may be specified by appending *-b* _branch_ where
_branch_ is the branch to checkout.
## Functions
Functions specified here may be present in any *APKBUILD* file, but with
the exception of *package*, are not strictly required.
*fetch*
This function is called to download the remote files in *source*.
*unpack*
This function unpacks any archives in *source* to *srcdir*.
*prepare*
Prepares the source in *srcdir* to be built. The default *prepare*
function ensures the build directories are set up correctly and
applies any _\*.patch_ files specified in *source*. You must call
*default_prepare* if you write a custom *prepare* function.
*build*
Compiles the source in *builddir*. You must implement this function
yourself. If no compilation is required, you may omit it.
*check*
Runs the package's test suite. This function must implemented unless
*!check* was specified in *options*.
*package*
Installs the package into *pkgdir*. Note that *pkgdir* is not
created for you; if this package installs no files (for example,
a metapackage), you must use `mkdir -p "$pkgdir"` to skip the
package phase.
## Install Scripts
An install script is run when an action is taken on a package by apk(8). An
install script must be written in shell and must have a _#!/bin/sh_
interpreter declaration as the first line. The *install* variable must
contain the install scripts needed by the package.
The install script will be run inside the root filesystem where the package
is being installed. A single argument will be passed to call 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.
The different actions that may have install scripts specified are as follows:
*$pkgname.pre-install*
Executed before the package is installed. If this script exits with
an error (non-zero exit code), 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 *pkggroups*
and *pkgusers*.
*$pkgname.post-install*
Executed after the package is installed. If this script exits
with an error (non-zero exit code), apk(8) will mark the package as
broken. The `apk fix` command will attempt to re-run the post-install
script if this occurs.
*$pkgname.pre-upgrade*
Executed before the package is upgraded. If this script exits with
an error (non-zero exit code), apk(8) will mark the package as broken.
*$pkgname.post-upgrade*
Executed after the package is upgraded. If this script exits with
an error (non-zero exit code), apk(8) will mark the package as
broken. The `apk fix` command will attempt to re-run the post-upgrade
script if this occurs.
*$pkgname.pre-deinstall*
Executed before the package is removed from the system. If this
script exits with an error (non-zero exit code), apk(8) will not
remove the package from the system.
*$pkgname.post-deinstall*
Executed after the package is removed from the system. Exiting with
an error will have no effect.
# IMPLEMENTATION NOTES
Currently, *APKBUILD* files are sourced as normal shells scripts. This may
change at a later date.
# COMPATIBILITY
The abuild(1) utility as distributed by Alpine Linux uses the BusyBox
Almquist shell, a part of busybox(1) that is currently undocumented. It is
mostly compliant with IEEE Std 1003.2 (“POSIX.2”), with some bash-like
extensions. The abuild(1) utility as distributed by Adélie uses the user's
preferred /bin/sh, which is typically bash(1).
# SEE ALSO
SPDX license reference (on the Web at <https://spdx.org/licenses/>),
abuild(1), newapkbuild(1), apk(8).
# HISTORY
The *APKBUILD* format and abuild(1) utility first appeared in Alpine
Linux 1.9.
# AUTHORS
Timo Teräs <_timo.teras@iki.fi_>++
Natanael Copa <_ncopa@alpinelinux.org_>
Documentation:++
A. Wilcox <_awilfox@adelielinux.org_>

14
Makefile
View File

@ -15,6 +15,7 @@ MAN_1_PAGES := newapkbuild.1
MAN_5_PAGES := APKBUILD.5
SAMPLES := sample.APKBUILD sample.initd sample.confd \
sample.pre-install sample.post-install
MAN_PAGES := $(MAN_1_PAGES) $(MAN_5_PAGES)
AUTOTOOLS_TOOLCHAIN_FILES := config.sub config.guess
SCRIPT_SOURCES := $(addsuffix .in,$(SCRIPTS))
@ -30,6 +31,7 @@ endif
CHMOD := chmod
SED := sed
TAR := tar
SCDOC := scdoc
LINK = $(CC) $(OBJS-$@) -o $@ $(LDFLAGS) $(LDFLAGS-$@) $(LIBS-$@)
CFLAGS ?= -Wall -Werror -g
@ -65,12 +67,18 @@ OBJS-abuild-fetch = abuild-fetch.o
${SED} ${SED_REPLACE} ${SED_EXTRA} $< > $@
${CHMOD} +x $@
%.1: %.1.scd
${SCDOC} < $< > $@
%.5: %.5.scd
${SCDOC} < $< > $@
P=$(PACKAGE)-$(VERSION)
all: $(USR_BIN_FILES) functions.sh
all: $(USR_BIN_FILES) $(MAN_PAGES) functions.sh
clean:
@rm -f $(USR_BIN_FILES) *.o functions.sh
@rm -f $(USR_BIN_FILES) $(MAN_PAGES) *.o functions.sh
%.o: %.c
$(CC) $(CPPFLAGS) $(CFLAGS) $(CFLAGS-$@) -o $@ -c $<
@ -97,7 +105,7 @@ help:
check: $(USR_BIN_FILE) functions.sh
cd tests && bats $${FILTER:+ --filter $$FILTER} *.bats
install: $(USR_BIN_FILES) $(SAMPLES) abuild.conf functions.sh
install: $(USR_BIN_FILES) $(SAMPLES) $(MAN_PAGES) abuild.conf functions.sh
install -d $(DESTDIR)/$(bindir) $(DESTDIR)/$(sysconfdir) \
$(DESTDIR)/$(sharedir) $(DESTDIR)/$(mandir)/man1 \
$(DESTDIR)/$(mandir)/man5

175
newapkbuild.1
View File

@ -1,175 +0,0 @@
.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 Mt ncopa@alpinelinux.org
.Pp
Documentation:
.An A. Wilcox Aq Mt awilfox@adelielinux.org

146
newapkbuild.1.scd Normal file
View File

@ -0,0 +1,146 @@
newapkbuild(1)
# NAME
*newapkbuild* - generate a new APKBUILD
# SYNOPSIS
*newapkbuild* _options_... [_pkgname_[-_pkgver_] | _source_url_]
# DESCRIPTION
*newapkbuild* generates a new APKBUILD for use with abuild(1). _pkgname_
specifies the package name, if not already specified with *-n*. If followed
by a dash (-) and a valid version string _pkgver_, additionally specify
the package's version.
*newapkbuild* will try to automatically detect the build system by inspecting
the source directory if _source_url_ is specified, and write out typical
build instructions for that build system. If you do not specify the source
URL, or want to override auto-detection, you may specify the build system
with the appropriate option. If no _source_url_ and no option are specified,
the generated APKBUILD file will not contain any build instructions.
# OPTIONS
*-a*
Specifies that the package uses autotools.
*-C*
Specifies that the package uses CMake. CMake will be added to
the makedepends.
*-c*
Causes *newapkbuild* 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. See the FILES section for details.
*-d* _DESC_
Specifies the description (pkgdesc=) for the new package.
*-f*
Forces *newapkbuild* to overwrite an existing APKBUILD, if one
already exists in the package directory.
*-h*
Displays usage information.
*-l* _LICENSE_
Specifies the license under which the new package is distributed. This
should match an SPDX Identifier.
*-m*
Specifies that the package uses Meson. Meson will be added to
the makedepends.
*-n* _NAME_
Specifies the name of the new package. A new directory called _NAME_
will be created in the current directory, with the APKBUILD file.
*-p*
Specifies that the package uses a Perl Makefile.PL file. The CPAN
template will be used and Perl will be added to the depends.
*-r*
Specifies that the package uses Cargo. Cargo will be added to
the makedepends.
*-s*
Create an automatic SourceForge URL for the package based on its
name and version. This is only valid if _pkgname-pkgver_ is specified
on the command line.
*-u* _URL_
Specifies the Web page (url=) for the new package. This should _not_
be the source package URL; it should be the project's main Web page.
*-y*
Specifies that the package uses a Python setup.py build
system. Python's setuptools will be added to the makedepends and
Python to the depends.
# FILES
All files generated will be places in a _pkgname_ directory inside the
current working directory, with _pkgname_ being created if it does not exist.
APKBUILD
*newapkbuild* will create an APKBUILD with the details gathered
from the invocation of *newapkbuild*, and introspection of the
downloaded package source if _source_url_ is provided. For more
information about APKBUILD and its format, see APKBUILD(5).
_pkgname_.initd
If *-c* is given, *newapkbuild* will create _pkgname_.initd with
example data to assist in the creation of an init.d script for
a daemon.
_pkgname_.confd
If *-c* is given, *newapkbuild* will create _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 openrc(8) and rc_config(3).
_pkgname_.pre-install
If *-c* is given, *newapkbuild* will create _pkgname_.pre-install,
the contents of which will be run by apk(8) before the package
is installed.
_pkgname_.post-install
If *-c* is given, *newapkbuild* will create _pkgname_.post-install,
the contents of which will be run by apk(8) after the package is
successfully installed. For more information about apk install hooks,
consult the apk(8) manual.
# 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"
```
# SEE ALSO
SPDX license reference (on the Web at <https://spdx.org/licenses/>),
abuild(1), apk(8), APKBUILD(5).
# AUTHORS
*newapkbuild*: Natanael Copa <_ncopa@alpinelinux.org_>
Documentation:++
A. Wilcox <_wilfox@adelielinux.org_>