mirror of
https://gitlab.alpinelinux.org/alpine/abuild.git
synced 2025-01-11 09:19:40 +00:00
man: Write requested improvements to documentation
This commit is contained in:
A. Wilcox
Natanael Copa
parent
3e9503bc83
commit
6a71529fe3
253
APKBUILD.5
253
APKBUILD.5
@ -53,15 +53,13 @@ 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
|
||||
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
|
||||
.Em alpha ,
|
||||
.Em beta ,
|
||||
.Em pre ,
|
||||
@ -71,15 +69,35 @@ must be one of
|
||||
.Em git ,
|
||||
.Em hg ,
|
||||
or
|
||||
.Em p .
|
||||
.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:
|
||||
|
||||
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 or dependencies of a package. The first release
|
||||
of a package is always
|
||||
when you change the contents, dependencies, or metadata of a package. The
|
||||
first release of a package is always
|
||||
.Li 0 .
|
||||
|
||||
.It Cm pkgdesc
|
||||
@ -100,24 +118,6 @@ 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.
|
||||
@ -127,6 +127,25 @@ 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 depends
|
||||
Specifies the run-time dependencies of the package. The
|
||||
.Xr abuild 1
|
||||
@ -168,7 +187,25 @@ 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.
|
||||
There are two formats that you may use for
|
||||
.Cm provides :
|
||||
a provider name, and a provider name with version.
|
||||
|
||||
Specifying a provider name with version such as
|
||||
.Li Dq 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.
|
||||
|
||||
Specifying a provider name without a version such as
|
||||
.Li Dq 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
|
||||
@ -182,6 +219,63 @@ virtual provider.
|
||||
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 Dq $pkgname-dev
|
||||
for development files (such as /usr/include and static library files) and
|
||||
.Li Dq $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
|
||||
.Li Dq $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 .
|
||||
|
||||
The second method is to simply call the subpackage
|
||||
.Li Dq foo
|
||||
which will create a package called
|
||||
.Li foo
|
||||
instead of pkgname-foo.
|
||||
|
||||
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 Dq 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.
|
||||
|
||||
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 Dq $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.
|
||||
@ -227,10 +321,14 @@ instead of using
|
||||
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).
|
||||
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
|
||||
@ -279,7 +377,10 @@ 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
|
||||
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
|
||||
@ -296,6 +397,47 @@ 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 Dq 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
|
||||
@ -314,6 +456,7 @@ specified by appending
|
||||
where
|
||||
.Cm branch
|
||||
is the branch to checkout.
|
||||
|
||||
.El
|
||||
|
||||
|
||||
@ -321,8 +464,7 @@ is the branch to checkout.
|
||||
Functions specified here may be present in any
|
||||
.Nm
|
||||
file, but with the exception of
|
||||
.Li build and
|
||||
.Li package ,
|
||||
.Cm package ,
|
||||
are not strictly required.
|
||||
|
||||
.Bl -tag -width Ds
|
||||
@ -354,9 +496,7 @@ function.
|
||||
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.
|
||||
may omit it.
|
||||
|
||||
.It Cm check
|
||||
Runs the package's test suite. This function must be implemented unless
|
||||
@ -437,32 +577,25 @@ will have no effect.
|
||||
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.
|
||||
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
|
||||
|
||||
The SPDX License List (Web copy at <https://spdx.org/licenses/>),
|
||||
SPDX license reference (on the Web at <https://spdx.org/licenses/>),
|
||||
.Xr abuild 1 ,
|
||||
.Xr newapkbuild 1 ,
|
||||
.Xr apk 8 .
|
||||
|
||||
@ -214,7 +214,7 @@ SPDX license reference (on the Web at <https://spdx.org/licenses/>),
|
||||
.Sh AUTHORS
|
||||
|
||||
.Nm :
|
||||
.An Natanael Copa Aq ncopa@alpinelinux.org
|
||||
.An Natanael Copa Aq Mt ncopa@alpinelinux.org
|
||||
|
||||
Documentation:
|
||||
.An A. Wilcox Aq awilfox@adelielinux.org
|
||||
.An A. Wilcox Aq Mt awilfox@adelielinux.org
|
||||
|
||||
Loading…
Reference in New Issue
Block a user