Commit 6a71529f authored by A. Wilcox's avatar A. Wilcox Committed by Natanael Copa

man: Write requested improvements to documentation

parent 3e9503bc
......@@ -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,6 +118,15 @@ 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.
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.
......@@ -109,6 +136,7 @@ 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
......@@ -118,15 +146,6 @@ The following variables are not required, but may be set in any
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
......@@ -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.
.Sh COMPATIBILITY
The
.Xr abuild 1
utility as distributed by Alpine uses the ash shell, a part of
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 ,
but this cannot be fully relied upon. The
with some bash-like extensions. 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.
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
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment