diff --git a/pkgfile.5.in b/pkgfile.5.in index 857681af..1473a3b8 100644 --- a/pkgfile.5.in +++ b/pkgfile.5.in @@ -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 @@ -25,15 +25,15 @@ 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 + cd $name\-$version + patch \-p1 < ../Makefile.in.patch + ./configure \-\-prefix=/usr make make DESTDIR=$PKG install - rm -rf $PKG/usr/info + 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. +Use \fBprtverify\fP(1) to check the port. .SS Variable names .LP @@ -61,33 +61,37 @@ Use the \fI$name\fP and \fI$version\fP variables to make the package easier to update/maintain. For example, .EX - source=(http://xyz.org/$name-$version.tar.gz) + source=(http://xyz.org/$name\-$version.tar.gz) .EE 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. .SS Support for renaming source files Note that in the \fBsomelib\fP example above, Joe Maintainer chose to define the optional bash array -\fIrenames\fP (same length as \fIsource\fP), so that the ambiguously-named file retrieved by FTP +\fIrenames\fP (same length as \fIsource\fP), so that the ambiguously\-named file retrieved by FTP 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, ignorant of the \fIrenames\fP array, will -execute the \fIbuild\fP function using the original filenames given by the remote sources. -For maximum compatibility, nothing in your \fIbuild\fP function should rely on the specific names -you choose for the downloaded tarballs (their contents will be unpacked into identically-named -work directories anyway, assuming you do not take the liberty of redefining \fIunpack_source()\fP in your -Pkgfile). But because earlier CRUX tools also have to be instructed to disregard md5 and signature -mismatches, port creators should avoid the renaming feature unless absolutely necessary. +execute the \fIbuild\fP function using the original filenames given by the remote sources, +after unpacking anything that matches the glob +\(dq*.(tar|tar.gz|tar.Z|tgz|tar.bz2|tbz2|tar.xz|txz|tar.lzma|tar.lz|zip|rpm|7z)\(dq. +A \fIbuild\fP function that does not rely on the specific names you choose for the downloaded +sources will have maximum compatibility with previous versions of CRUX. At present the number +of CRUX 3.6 (or earlier) deployments is probably too low for the use of \fIrenames\fP to be +an issue. It thus becomes possible to avoid redefining \fIunpack_source()\fP when you want to +keep a particular tarball intact, or to handle it with something other than the default +bsdtar: simply rename the not\-to\-be\-unpacked tarball so that the new name fails to match +the glob above, and then work with the new filename in \fIbuild()\fP. .SS Directories In general packages should install files in these directories. Exceptions @@ -101,7 +105,7 @@ Directory Description /usr/sbin/ System binaries (e.g. daemons) /usr/lib/ Libraries /usr/include/ Header files -/usr/lib// Plug-ins, addons, etc +/usr/lib// Plug\-ins, addons, etc /usr/share/man/ Man pages /usr/share// Data files /usr/etc// Configuration files @@ -121,8 +125,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\-\-disablei\-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). @@ -140,20 +144,23 @@ Provide a header including the following fields: 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 +Maintainer Your full name and e\-mail address, obfuscated if you want URL A webpage with more information on this software package Depends on A list of dependencies, separated either by spaces or commas +Optional A list of ports whose presence might affect the build process .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. +\fIDepends on\fP can be omitted if there are no dependencies. +\fIOptional\fP can be omitted entirely, or just pared down to the set of optional dependencies +that the maintainer has been able to test. There is currently no obligation for a maintainer to +test all possible configurations when writing a port. .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 @@ -169,7 +176,7 @@ run-time dependencies from \fBcore\fP which aren't dynamically linked in are not .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\fP. .LP @@ -177,19 +184,6 @@ The reasoning for these guidelines is that you can use \fBrevdep\fP to find port that need to be updated if one of the dependent libraries has become binary incompatible. To find out what libraries a binary is linked to, use \fBldd\fP or \fBfinddeps\fP. -.LP -It \fIis\fP permissible to list build dependencies outside of \fBcore\fP, whose only purpose is to -generate the manpage of the port. But if the dependency chain is too convoluted, try to find -alternative ways of providing such static documentation. -.TP -Examples: -.IP "" 4 -\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. .SS Optional dependencies @@ -197,15 +191,15 @@ A common practice among port maintainers is to put filesystem tests in the \fIbu allowing the package configuration to vary depending on what other packages the system administrator has installed. This practice can result in footprint mismatches. It is recommended that maintainers build their ports in a container with the bare minimum of dependencies, or prune the -auto-generated footprint so that the spurious files are not reported as MISSING on another user's -system. +auto\-generated footprint so that the spurious files are not reported as MISSING on another +user's system. .PP 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 + 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 .EE .PP If the maintainer built the package in a clean container, then another user with fish installed will @@ -214,7 +208,18 @@ installation if PKGMK_IGNORE_NEW was enabled in \fBpkgmk.conf\fP(5). More danger situation: the maintainer built the package in a system with fish, and a user without fish sees /usr/share/fish listed as MISSING in the footprint mismatch. Users should not be encouraged to disregard MISSING, but enabling PKGMK_IGNORE_NEW is generally safe. - +.PP +Maintainers are encouraged to build offline documentation (man\-pages) into their ports, but +this practice nowadays might involve dependencies that are not necessary for running the +actual program. If the dependency chain is too convoluted, list the man\-page\-generating +dependency as \fBOptional\fP, or provide pre\-compiled man\-pages with the port itself. +.TP +Examples: +.IP "" 4 +\fBgreetd\fP lists \fBscdoc\fP among the optional dependencies, which if installed will allow +the man\-pages to be generated during the build. +.IP "" 4 +\fBmpd\fP lists \fBpython3\-sphinx\fP among the optional dependencies for the same reason. .SS rc start scripts You can use the following template for ports that provide some @@ -223,26 +228,11 @@ 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 -.LP -The \fIbuild\fP function should use the \fI$SRC\fP variable whenever it needs -to access the files listed in the source variable, and the \fI$PKG\fP -variable as the root destination of the output files. -.LP -Being a shell script executed in the context of \fBpkgmk\fP(8), the -entire \fBPkgfile\fP has access to the variables initialized -in \fBpkgmk.conf\fP(5) and the default values set by \fBpkgmk\fP(8). Also, as a -side effect of how it is used by \fBpkgmk\fP(8), the Pkgfile can also -change the behaviour of \fBpkgmk\fP(8) by rewriting some of its functions -and variables before \fIbuild()\fP is called. However, the \fIbuild\fP -function itself has only read access to these environment variables -and shell functions. .SH ERRORS .LP Most of the command failures in \fIbuild()\fP will stop @@ -253,14 +243,90 @@ constructs like: .EX \fBif ! command...; then ...\fP \fBcommand || ...\fP +.SH ENVIRONMENT +.LP +The \fIbuild\fP function should use the \fISRC\fP variable whenever it needs +to access the files listed in the source variable, and the \fIPKG\fP +variable as the root destination of the output files. +.LP +Being a shell script executed in the context of \fBpkgmk\fP(8), the +entire \fBPkgfile\fP has access to the variables initialized +in \fBpkgmk.conf\fP(5) and the default values set by \fBpkgmk\fP(8). Also, as a +side effect of how it is used by \fBpkgmk\fP(8), the Pkgfile can also +change the behaviour of \fBpkgmk\fP(8) by rewriting some of its functions +and variables before \fIbuild()\fP is called. However, the \fIbuild\fP +function itself has only read access to these environment variables +and shell functions. +.LP +The separation between the bash\-interpreted lines (uncommented) and the Pkgfile header +(commented, at the top) does not map cleanly onto the separation between \fBpkgmk\fP(8) +and \fBprt\-get\fP(8). At least two of the variables initialized in the Pkgfile are also +parsed by \fBprt\-get\fP(8), namely, \fIversion\fP and \fIrelease\fP which are needed +to obtain the filename that should be passed to \fBpkgadd\fP(8). Note that to determine +the value of \fIversion\fP (or \fIrelease\fP), \fBprt\-get\fP uses neither \fBbash\fP(1) +nor the rest of the Pkgfile, but instead /bin/sh and the single line that begins with +\(dqversion=\(dq (or \(dqrelease=\(dq). Defining \fIversion\fP (or \fIrelease\fP) as +anything other than a constant string (or positive integer) might cause breakage after +the pkgmk step. +.SH FUTURE\-PROOFING +Ideas for future development of \fBpkgmk\fP, if implemented, would entail corresponding +amendments of the Pkgfile format. Port maintainers should be alert to several such +possibilities. +.PP +One shortcoming of the current pkgmk is its lack of support for the git protocol when +downloading sources. If this feature is added, then the \fIsource\fP array will acquire +further restrictions (e.g., a special prefix that tells pkgmk to switch from curl/wget +and use git instead). Implementing git support should not cause widespread breakage, unless +Pkgfile authors inadvertently populate their \fIsource\fP arrays with names that collide with +the globs we decide to reserve for git. +.PP +Another proposal under consideration is to allow end users to incorporate their port +customizations at the pkgmk step, rather than into a post\-sync hook (where the attempt to +apply an outdated patch might corrupt a freshly-synced ports tree). To plan for this +possibility, Pkgfile authors should avoid the function names \fIoverlay_download\fP and +\fIoverlay_build\fP, which might complement \fIdownload_source\fP or replace +\fIbuild\fP, respectively. The simple overlay proposal in its current form cannot influence +dependency resolution, because there is no mechanism for passing information from pkgmk +into a prt\-get dependency calculation. Authors of Pkgfiles can still expect feedback +from downstream users who want to see something added or removed in the \(dqDepends on:\(dq +or \(dqOptional:\(dq lines; the current overlay proposal would not distribute this aspect of +port maintenance among the wider CRUX userbase. +.PP +Breaking up the current \fIbuild()\fP into two separate functions, \fIconfigure()\fP +and \fIbuild()\fP, would make the simple overlay proposal smoother to implement. Pkgfiles +that define a standalone \fIconfigure()\fP and call that function from within +the current \fIbuild()\fP are well\-prepared for transitioning to such a future Pkgfile +format. +.PP +A crux\-devel thread from February 2004 debated whether to have dependencies listed as +array variables (visible to the pkgmk process) or to leave them as commented lines +in the header (visible to prt\-get and tools of a similar scope). The current separation +of concerns (prt\-get and friends concerned with the header and a few of the uncommented lines, +from \fBevery port in the active repos\fP; pkgmk concerned only with the uncommented lines, in +the Pkgfile under $PWD and the global config /etc/pkgmk.conf) was regarded as the tidiest way +to coordinate our tools. +If the simple overlay proposal acquires ambitions to influence prt\-get operations too, +then a channel must be opened to inform prt\-get about whatever pkgmk learns from the +user's overlay. Such a channel can only rely on definitions that pkgmk is aware of, which +might require promoting some header fields to actual shell variables. To guard against such +a promotion causing problems, port maintainers are advised to inspect their Pkgfile header +fields for strings that bash would not accept as values of a shell variable. .EE .SH SEE ALSO -pkgmk(8), pkgmk.conf(5), -.UR https://crux.nu/Main/PortGuidelines -.UE , -.UR https://crux.nu/Main/PrePostInstallGuidelines -.UE . +.TP +pkgmk(8) +.TP +pkgmk.conf(5) +.TP +https://crux.nu/Main/PortGuidelines +.TP +https://crux.nu/Main/PrePostInstallGuidelines +.TP +https://lists.crux.nu/archives/list/crux\-devel@lists.crux.nu/thread/CW7FMOR2QZYUY5BU3GNKMY3G6BMP7Q3U/#52BWHNUXTTLKB4X53PT52T7XGBT7QURV +.TP +https://crux.nu/Wiki/PkgutilsIdeas .SH COPYRIGHT -pkgmk (pkgutils) is Copyright (c) 2000-2005 Per Liden and Copyright (c) 2006-2021 CRUX team (http://crux.nu). +pkgmk (pkgutils) is Copyright (c) 2000\-2005 Per Liden and Copyright (c) 2006\-2024 CRUX team +(https://crux.nu). pkgmk (pkgutils) is licensed through the GNU General Public License. Read the COPYING file for the complete license. diff --git a/pkgmk.conf.5.in b/pkgmk.conf.5.in index 3e054362..242578d2 100644 --- a/pkgmk.conf.5.in +++ b/pkgmk.conf.5.in @@ -2,7 +2,7 @@ .SH NAME \fBpkgmk.conf\fP \- Configuration file for pkgmk. .SH DESCRIPTION -\fBpkgmk.conf\fP configures pkgutils package make, pkgmk(8). +\fBpkgmk.conf\fP governs the operation of pkgmk(8), the package\-making script from CRUX pkgutils. .SH FILE FORMAT The file consists of a number of variable assignments of the form \fBoption\fP=\fBvalue\fP. Comments can be specified by putting a hash (#) symbol as the first character on the line. .SH DIRECTIVES @@ -79,7 +79,9 @@ If set to 'yes', pkgmk will ignore new files in a footprint mismatch. Default: 'no' .TP \fBPKGMK_NO_STRIP='STRING'\fP -If set to 'no', pkgmk will strip built binaries. +If set to 'yes', pkgmk will leave all built binaries unstripped, as if it had read +the \(oqmatch-everything\(cq regexp \fI.*\fP from the \fI.nostrip\fP file in the port +directory. .br Default: 'no' .TP @@ -87,9 +89,47 @@ Default: 'no' Option to select the mode used to compress the packages. Valid strings are gz, bz2, xz and lz. .br Default: 'gz' +.SH OVERRIDING DEFAULT DIRECTORIES +The work directory is created (and removed) by pkgmk itself, so the user is not expected to +preemptively create this directory for each port. In contrast, PKGMK_PACKAGE_DIR and +PKGMK_SOURCE_DIR, when not left at their defaults, must point to directories that exist at +the time pkgmk is invoked. Because the default value is the port dir ($PWD of the pkgmk +process), there is currently no logic in pkgmk to create $PKGMK_PACKAGE_DIR and +$PKGMK_SOURCE_DIR if they do not already exist. +.PP +For example, one might be tempted to write something like +.IP +PKGMK_SOURCE_DIR="/var/work/sources/$name" +.PP +to save all downloaded sources in a per\-port directory structure outside the ports tree +(https://libera.irclog.whitequark.org/crux\-social/2024\-09\-08#36969244;). +\fBThis definition would fail\fP under the current pkgmk design, unless /var/work/sources were +preemptively populated with directories for all the ports. A more robust solution is to +leave PKGMK_SOURCE_DIR at the default, and incorporate the test mode of \fIprtwash\fP(8) or +\fIprtsweep\fP(8) into a wrapper script that periodically moves downloaded sources out of +the ports tree. +.PP +In general, it is fragile to define PKGMK_PACKAGE_DIR or PKGMK_SOURCE_DIR in terms of other +variables initialized by reading the \fIPkgfile\fP(5). Use a constant string instead. The +setting for PKGMK_PACKAGE_DIR also governs the operation of \fIprt\-get\fP(8), which has its +own method of reading the \fIPkgfile\fP(5) and \fIpkgmk.conf\fP. \fIprt\-get\fP will extract +only the single line that defines each variable, and pass the line to \fI/bin/sh\fP for +evaluation. In recent versions of CRUX, \fI/bin/sh\fP is no longer a symlink to \fIbash\fP(1), +so the different interpreters (and \fIprt\-get\fP's willful ignorance of the other lines +in \fIPkgfile\fP and \fIpkgmk.conf\fP) might produce different results. +.PP +For example, it will trigger a pkgadd failure (but not a pkgmk failure) to define +.IP +PKGMK_PACKAGE_DIR="/crux/packages/$HOSTNAME" +.PP +as a way to have each CRUX box store its packages in its own directory on an NFS server +(crux\-devel mailing list, 2016\-08\-14). To avoid such disagreements between \fIpkgmk\fP and +\fIprt\-get\fP in parsing the same input, use a constant string for any parameter that governs +both commands. .SH SEE ALSO pkgmk(8) .SH COPYRIGHT -pkgmk (pkgutils) is Copyright (c) 2000-2005 Per Liden and Copyright (c) 2006-2021 CRUX team (http://crux.nu). +pkgmk (pkgutils) is Copyright (c) 2000\-2005 Per Liden and Copyright (c) 2006\-2024 CRUX team +(https://crux.nu). pkgmk (pkgutils) is licensed through the GNU General Public License. Read the COPYING file for the complete license.