jmq/Documentation
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

pkgfile.5: recommend filesystem tests instead of prt-get isinst tests

Browse Source
This commit is contained in:
John McQuah
2025-11-09 18:13:20 +00:00
parent 4145a63e04
commit 2f8c3124cf
1 changed files with 43 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
man5/pkgfile.5
View File

@@ -1,6 +1,6 @@
.\"
.\" Pkgfile manual page.
.\" (C) 2018 by Fun, updated 2021--2023 by John McQuah <jmcquah at disroot dot org>
.\" (C) 2018 by Fun, updated 2021--2025 by jmq
.\"
.TH Pkgfile 5
.SH NAME
@@ -9,7 +9,7 @@ Pkgfile \- sourced by \fBpkgmk\fP(8) when building a package in the ports tree
a \fBbash\fP(1) script that tells \fBpkgmk\fP(8) where the source code for a port may be downloaded,
and what to do once that source code is unpacked.
.SH FILE FORMAT
\fBPkgfile\fP starts with a header of commented lines, which are read by \fBprt-get\fP(8)
\fBPkgfile\fP starts with a header of commented lines, which are read by \fBprt\-get\fP(8)
to resolve dependencies, or by \fBportspage\fP(1) to generate an HTML index of the ports collection.
After the header \fBpkgmk\fP will expect to find definitions of several mandatory variables, including
\fIname\fP, \fIversion\fP, \fIrelease\fP, the bash array \fIsource\fP, and
@@ -20,20 +20,20 @@ the bash function \fIbuild()\fP.
# URL: http://www.gnu.org/software/somelib/index.html
# Maintainer: Joe Maintainer, joe at myfantasticisp dot net
# Depends on: someotherlib coolness
# Build depends on: meson
name=somelib
version=1.2.3
release=1
source=(ftp://ftp.gnu.org/gnu/$name/archive/$version/$version.tar.gz Makefile.in.patch)
renames=($name-$version.tar.gz SKIP)
renames=($name\-$version.tar.gz SKIP)
build() {
cd $name-$version
patch -p1 < ../Makefile.in.patch
./configure --prefix=/usr
make
make DESTDIR=$PKG install
rm -rf $PKG/usr/info
patch \-p1 \-d ${name}\-${version} Makefile.in.patch
meson setup ${name}\-${version} build
meson compile \-C build
DESTDIR="$PKG" meson install \-C build
rm \-rf $PKG/usr/info
}
.EE
@@ -46,7 +46,7 @@ ports structure, i.e. \fI/usr/ports/???/eterm\fP.
Do not combine several separately distributed programs/libraries into
one package. Make several packages instead.
.LP
Use \fBprtverify\fP to check the port. This script uses bash and awk to identify
Use \fBprtverify\fP to check the port. This script uses awk to identify
common errors, such as writing to a directory outside $PKG, or forgetting to remove
\(dqjunk files\(dq.
.LP
@@ -55,14 +55,14 @@ connectivity. All fetching from remote servers should be limited to the
\fBcurl(1)\fP or \fBwget(1)\fP processes that run when \fBpkgmk(8)\fP parses
the \fIsource\fP array. This separation between download and build is meant
to accommodate users with intermittent internet access, who might like to run
\fBpkgmk -do\fP for each outdated port, and then go offline to continue the
\fBpkgmk \-do\fP for each outdated port, and then go offline to continue the
build. While the inability of \fBpkgmk(8)\fP to parse \fBgit\fP urls in the
source array was historically the greatest temptation to violate the separation
between download and build, certain language ecosystems and build toolchains
also make it more difficult to achieve this separation. In particular, you
should be wary when the upstream project talks about \fImeson subprojects\fP or
\fIcargo fetch\fP commands in its compilation instructions, for which the most
CRUX-like solution is to write separate ports for each needed dependency (and
CRUX\-like solution is to write separate ports for each needed dependency (and
put them in the \(dqDepends on:\(dq line).
.SS Variable names
@@ -84,7 +84,7 @@ package easier to update/maintain. For example,
is better than
.EX
source=(http://xyz.org/myprog-1.0.3.tar.gz)
source=(http://xyz.org/myprog\-1.0.3.tar.gz)
.EE
since the URL will automatically update when you modify the \fI$version\fP variable.
@@ -95,7 +95,7 @@ Note that in the \fBsomelib\fP example above, Joe Maintainer chose to define the
would not collide with another port's files, if downloaded into a common directory.
The keyword \(oqSKIP\(cq was given in the \fIrenames\fP array to indicate that renaming was not
necessary for the corresponding source file. SKIP should always be used for a file retrieved by
\(oqports -u\(cq, because the port maintainer has the freedom to choose an unambiguous name in the
\(oqports \-u\(cq, because the port maintainer has the freedom to choose an unambiguous name in the
\fisource\fP array itself.
.PP
Tools from prior versions of CRUX (before 3.7), ignorant of the \fIrenames\fP array, will
@@ -104,27 +104,6 @@ remote sources. For backwards compatibility, write a \fIbuild\fP function that
does not rely on the specific names chosen for downloaded sources (it helps that
the directory created by unpacking a tarball will have the same name, regardless
of how the tarball itself is saved on disk).
.PP
CRUX 3.7 introduced the possibility of using the \fIrenames\fP array to
prevent automatic unpacking of archives whose original filenames would have
matched the pattern *.(tar|tar.gz|tar.bz2|tar.xz|zip|rpm|7z); in previous
CRUX versions the clunky workaround was to redefine the \fBpkgmk(8)\fP
function \fIunpack_source()\fP and delay that pattern match until
specially-designated source files are given special treatment.
Because this use of \fIrenames\fP is not a very intuitive solution to the
problem of coping tarballs intact, another mechanism was proposed. Starting
in CRUX 3.7.1 you can define a \fInounpack\fP array in your Pkgfile,
containing the on-disk filenames of tarballs that you want copied as-is into
the work directory. Filenames that do not match the pattern
*.(tar|tar.gz|tar.bz2|tar.xz|zip|rpm|7z) will be treated exactly as before;
you never need to define \fInounpack\fP (or \fIrenames\fP) if the pre-3.7
pkgmk behaviour is what you want. During the gradual rollout of the new
pkgmk feature, it is safer to try finding alternative source files that will
populate the work directory appropriately, regardless of which pkgmk the
user has installed. For example: instead of
.B source=(pkg1.rpm pkg2.rpm pkg3.rpm),
distribute a tarball containing all these rpms, and then define logic in
\fIbuild()\fP that lets bsdtar handle each rpm as needed for your port.
.SS Directories
In general packages should install files in these directories. Exceptions
@@ -158,8 +137,8 @@ Packages should not contain "junk files". This includes:
info pages and other online documentation, man pages excluded (e.g. \fIusr/doc/*\fP,
\fIREADME\fP, \fI*.info\fP, \fI*.html\fP, etc).
.IP \[bu]
Files related to NLS (national language support). If \fB--disable-nls\fP is not available as
an option to \fBconfigure\fP, then manually inserting \(oqrm -rf $PKG/usr/share/locale\(cq near the
Files related to NLS (national language support). If \fB\-\-disable\-nls\fP is not available as
an option to \fBconfigure\fP, then manually inserting \(oqrm \-rf $PKG/usr/share/locale\(cq near the
end of the \fBbuild\fP function is an acceptable alternative.
.IP \[bu]
Useless or obsolete binaries (e.g. \fI/usr/games/banner\fP and \fI/sbin/mkfs.minix\fP).
@@ -181,16 +160,18 @@ Maintainer Your full name and e-mail address, obfuscated if you want
Packager The original packager's full name and e-mail address
URL A webpage with more information on this software package
Depends on A list of dependencies, separated either by spaces or commas
Build depends on Dependencies that are only needed at build-time, not runtime
.EE
Note that you should use the obfuscated email address (illustrated in the example above) if
you want to put your ports in any of the official CRUX repositories.
\fIDepends on\fP can be omitted if there are no dependencies.
\fIBuild depends on\fP, if provided, will be used by future implementations of prt\-get(8) and pkg\-get(8)to keep the filesystem tidy in between install/update/sysup transactions. Consult your version of prt\-get(8) to see whether this header is recognized.
.SS Dependencies
Dependencies are supported by CRUX tools like \fBprt-get\fP and \fBpkg-get\fP.
Dependencies are supported by CRUX tools like \fBprt\-get\fP and \fBpkg\-get\fP.
The following rules should be respected:
.IP "" 4
@@ -200,13 +181,15 @@ List all runtime dependencies except for gcc (libstdc++) and glibc.
and ports expect the programs provided by \fBcore\fP to be installed; this
means that:
.IP "" 8
build dependencies provided by \fBcore\fP are not listed in the dependency header
run\-time dependencies from \fBcore\fP which aren't dynamically linked in are not to be listed.
.IP "" 8
run-time dependencies from \fBcore\fP which aren't dynamically linked in are not to be listed, either
build\-time dependencies provided by \fBcore\fP are not listed in the dependency header
.IP "" 8
build\-time dependencies provided by \fBnon\-core\fP ports should be listed in the header \(dqBuild depends on\(dq, so that newer versions of prt\-get and pkg\-get can purge them from the filesystem after a successful build (unless the user already installed them for some other reason).
.TP
Examples:
.IP "" 4
\fBopt/sloccount\fP does \fInot\fP list \fBperl\fP, because the program is a perl script -- there's no binary that links to \fBlibperl\fP
\fBopt/sloccount\fP does \fInot\fP list \fBperl\fP, because the program is a perl script \-\- there's no binary that links to \fBlibperl\fP
.IP "" 4
\fBopt/libxml2\fP \fIdoes\fP list \fBzlib\fP, because \fBlibxml\fP is linked to \fBlibz.so\fP.
.LP
@@ -224,9 +207,12 @@ Examples:
\fBgreetd\fP \fIdoes\fP list \fBscdoc\fP (only needed to generate the manpages), because the dependency chain
leading to this dependency is just \fBscdoc\fP itself.
.IP "" 4
\fBmpd\fP does \fInot\fP list \fBpython3-sphinx\fP (only needed to generate the manpages), because of the
long dependency chain leading to \fBpython3-sphinx\fP, and the possibility of delivering the manpages by
simpler means.
\fBmpd\fP does \fInot\fP list \fBpython3\-sphinx\fP (only needed to generate the manpages), because of the
long dependency chain leading to \fBpython3\-sphinx\fP, and the possibility of delivering the manpages by simpler means.
.TP
Example transaction:
.IP "" 4
\fBprt\-get depinst somelib\fP begins by parsing the headers of the Pkgfile above, satisfying dependencies recursively to determine the minimal set of install targets: meson someotherlib somelib. Because meson is marked as a build\-time dependency, prt\-get now tests whether meson is already installed at the time of this transaction. Not finding meson yet installed, prt\-get flags it for removal once the somelib is successfully built. Each port in this sorted list of dependencies becomes the working directory for a pkgmk process. After all the targets are built and installed, prt\-get then concludes with \(aqpkgrm meson\(aq to keep the filesystem tidy. The built package meson#1.8.0\-1.tar.gz is kept around for later use, in case other ports require it for compilation.
.SS Optional dependencies
@@ -240,9 +226,9 @@ system.
Filesystem tests are also useful at the end of a \fIbuild\fP function, for example when determining
which shell completions should be installed. Here is a template for tests of this kind:
.EX
prt-get isinst bash-completion || rm -rf $PKG/usr/share/bash-completion
prt-get isinst zsh || rm -rf $PKG/usr/share/zsh
prt-get isinst fish || rm -rf $PKG/usr/share/fish
[ \-f /etc/bash\-completion ] || rm \-rf $PKG/usr/share/bash\-completion
[ \-x /usr/bin/zsh ] || rm \-rf $PKG/usr/share/zsh
[ \-x /usr/bin/fish ] || rm \-rf $PKG/usr/share/fish
.EE
.PP
If the maintainer built the package in a clean container, then another user with fish installed will
@@ -260,10 +246,10 @@ and your port should install it to \fI/etc/rc.d/$name\fP. The installation
can happen by calling the following in your \fIbuild\fP function:
.EX
install -D -m 755 $SRC/$name.rc $PKG/etc/rc.d/$name
install \-D \-m 755 $SRC/$name.rc $PKG/etc/rc.d/$name
.EE
.LP
See the existing scripts under /etc/rc.d for examples of using \fBstart-stop-daemon\fP(8)
See the existing scripts under /etc/rc.d for examples of using \fBstart\-stop\-daemon\fP(8)
to generate the necessary pid files, temp directories, and logs for your daemon.
.SH ENVIRONMENT
@@ -298,6 +284,6 @@ pkgmk(8), pkgmk.conf(5),
.UR https://crux.nu/Main/PrePostInstallGuidelines
.UE .
.SH COPYRIGHT
pkgmk (pkgutils) is Copyright (c) 2000-2005 Per Liden and Copyright (c) 2006-2022 CRUX team (http://crux.nu).
pkgmk (pkgutils) is Copyright (c) 2000-2005 Per Liden and Copyright (c) 2006-2025 CRUX team (http://crux.nu).
pkgmk (pkgutils) is licensed through the GNU General Public License.
Read the COPYING file for the complete license.