From 2f8c3124cfdfce9589bd6125ae4c336f387f0623 Mon Sep 17 00:00:00 2001 From: John McQuah Date: Sun, 9 Nov 2025 18:13:20 +0000 Subject: [PATCH] pkgfile.5: recommend filesystem tests instead of prt-get isinst tests --- man5/pkgfile.5 | 100 +++++++++++++++++++++---------------------------- 1 file changed, 43 insertions(+), 57 deletions(-) diff --git a/man5/pkgfile.5 b/man5/pkgfile.5 index 11585ed..7be3ea8 100644 --- a/man5/pkgfile.5 +++ b/man5/pkgfile.5 @@ -1,6 +1,6 @@ .\" .\" Pkgfile manual page. -.\" (C) 2018 by Fun, updated 2021--2023 by John McQuah +.\" (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). @@ -174,23 +153,25 @@ individual preferences automatically. Provide a header including the following fields: .EX -Name Meaning ----- ------- -Description A short description of the package; keep it factual -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 +Name Meaning +---- ------- +Description A short description of the package; keep it factual +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.