diff --git a/man8/pkgmeek.8 b/man8/pkgmeek.8 new file mode 100644 index 0000000..9d5cdf1 --- /dev/null +++ b/man8/pkgmeek.8 @@ -0,0 +1,196 @@ +.TH pkgmeek 8 "" "CRUX package utilities" "" +.SH NAME +pkgmeek \- make a binary package that can be installed by pkgadd +.SH SYNOPSIS +\fBpkgmeek [options]\fP +.SH DESCRIPTION +\fBpkgmeek\fP is a tool for building \fIbinary packages\fP using the +instructions found in a CRUX ports tree. A \fIbinary package\fP is an +archive of files (.pkg.tar.gz, .pkg.tar.bz2 or .pkg.tar.xz) +that can be installed using pkgadd(8). + +In order to use pkgmeek, you must change to a directory containing a +\fIPkgfile\fP(5), which describes how the package should be built. Such +directories are typically populated over rsync, git, or http, using the appropriate +driver for \fIports\fP(8). Once a suitable \fIPkgfile\fP has been written, each time +you change some source files, you simply execute pkgmeek to bring the package up to date. +The pkgmeek program uses the last-modification times of \fIPkgfile\fP and all source files +to decide if the package needs to be updated. + +Global build configuration is stored in \fI/etc/pkgmk.conf\fP, the same file that governs +the operation of \fIpkgmk\fP(8). This file is read by pkgmeek at startup. +.SH OPTIONS +.TP +.B "\-i, \-\-install" +Install package using pkgadd(8) after successful build. +.TP +.B "\-u, \-\-upgrade" +Install package as an upgrade using pkgadd(8) after successful build. +.TP +.B "\-r, \-\-recursive" +Search for Pkgfiles in all subdirectories under the current working directory, +and perform the requested action (download, extract, ...) in each subdirectory found. +.TP +.B "\-do, \-\-download\-only" +Do not build, stop after obtaining all the source file(s). +.TP +.B "\-utd, \-\-up\-to\-date" +Do not build, only check if the package is up to date. +.TP +.B "\-in, \-\-ignore\-new" +Build package, ignore new files in a footprint mismatch. +.TP +.B "\-if, \-\-ignore\-footprint" +Build package without checking footprint. +.TP +.B "\-uf, \-\-update\-footprint" +Update footprint and treat last build as successful. +.TP +.B "\-us, \-\-update\-signature" +Update port signature and sha256sums. +.TP +.B "\-um, \-\-update\-md5sum" +Update md5sum using the current source files. +.TP +.B "\-im, \-\-ignore\-md5sum" +Build package without checking md5sum first. +.TP +.B "\-cs, \-\-check\-signature" +Check the validity of Pkgfile, footprint, and sources using the signature and sha256sums. +.TP +.B "\-is, \-\-ignore\-signature" +Build package without checking the signature and sha256sums. +.TP +.B "\-rs, \-\-refresh\-signature" +Create new signature and keep existing sha256sums. +.TP +.B "\-sk, \-\-secret\-key " +Use private key in to sign the port. By default, the directories /etc/ports +and ~/.ssh are searched for files named $repo.sec, where $repo is the name of the port's +parent directory. +.TP +.B "\-pk, \-\-public\-key " +Use public key in to check the signature. By default, the name of the +port's parent directory $repo is evaluated and the public key is read from /etc/ports/$repo.pub, if +it exists. +.TP +.B "\-ns, \-\-no\-strip" +Do not strip executable binaries or libraries. +.TP +.B "\-f, \-\-force" +Build package even if it appears to be up to date. +.TP +.B "\-c, \-\-clean" +Remove the (previously built) package and the downloaded source files. +.TP +.B "\-kw, \-\-keep-work" +Keep temporary working directory. +.TP +.B "\-cf, \-\-config\-file " +Use alternative configuration file (default is /etc/pkgmk.conf). +.TP +.B "\-v, \-\-version" +Print version and exit. +.TP +.B "\-h, \-\-help" +Print help and exit. +.SH FILES +.TP +.B "Pkgfile" +Package build description. +.TP +.B ".footprint" +Package footprint (a listing of all the files that would be unpacked from the +compressed archive, complete with owner/group/permissions and full paths) +.TP +.B ".md5sum" +MD5 checksum of each file listed in the \fIsource\fP array of the Pkgfile. +.TP +.B ".signature" +SHA256 checksum of footprint, Pkgfile, and each source file, and a signify checksum. +.TP +.B "/etc/pkgmk.conf" +Configuration file, recognized by both \fBpkgmeek\fP and \fBpkgmk\fP. +.SH EXIT CODES +.TP +.B 0 +No error occured. +.TP +.B 1 +A general error has occured. +.TP +.B 2 +The Pkgfile is missing one of the mandatory elements. +.TP +.B 3 +The source or build directory is missing or is lacking read/write permissions. +.TP +.B 4 +An error occured during the download of source files. +.TP +.B 5 +An error occured during unpacking of source files. +.TP +.B 6 +A mismatch in the footprint or the md5sum was detected. +.TP +.B 7 +An error occured while running the build function. +.TP +.B 8 +An error occured while installing the package via pkgadd. +.TP +.B 9 +An error occured while verifying the signature. + +.SH PROGRAM DESIGN + +\fBpkgmeek\fP aims to provide the same feature set that users of \fBpkgmk\fP have +come to rely upon, but without the sprawling code base that discourages would-be +contributors from stepping in to help. Its core function of building a package is +based on \fBupkgmk\fP, a 100-line bash script written by Fun. Upon this foundation, +new code in the same pithy style was added, but not haphazardly. A deliberately linear +sequence was imposed, letting new users discern a narrative arc to the process of building +a binary package, and each exit ramp along that story line is clearly marked. By moving the +linear sequence of main() to the top of the file, \fBpkgmeek\fP provides new users an overview of +the entire process, so they can quickly identify where a new feature is best inserted. + +When the first version of \fBpkgmk\fP was written, it had a modest goal: read the Pkgfile +and build a compressed archive. As Fun demonstrated, this goal can be achieved in 100 lines +of bash --- hardly an intimidating code base. Over the years \fBpkgmk\fP acquired more features, +such as the ability to use a shared directory for downloads. The addition of features to +\fBpkgmk\fP was rarely accompanied by the thankless work of weaving these disparate parts +into a coherent structure. As a result, the typical response when new users scroll through the +\fBpkgmk\fP source code is to feel lost, constantly paging up and down to acquire their bearings +and understand how all the pieces fit together. + +Satisfying requests for new \fBpkgmk\fP features has probably suffered years of delay, due to the +small fraction of CRUX users who feel at home in the \fBpkgmk\fP source code. For example, a new +contributor might wonder: "do I need to make my changes in the download_file() function, the +download_source() function, or both? should I be passing this argument to get_filename() or +get_basename()? has make_work_dir() been called by this point or not?" In contrast, the +\fBpkgmeek\fP source code aims to introduce as few subroutines as possible, and never to use two +function names that are easily confused. With less mental bandwith allocated to remembering the +distinction between similarly-named functions, or to keeping an inventory of all the subroutines that +might be impacted by a new line of code, the would-be contributor can quickly zoom in on the +place where new code should be added. + +Time will only tell whether this design can be retained as core maintainers come and go. At the time +of writing, patch submissions on our bug tracker are nowhere near the volume they were in 2017. +Either the interest in CRUX is waning (and could stand to be reinvigorated), or the would-be +contributors start paging through a legacy code base and lose confidence in their ability to help +out. Whichever the explanation, \fBpkgmeek\fP is offered as a partial remedy to the problem that +"we don't have people that actually sign up to care about our core tools" (FS#1410). + +.SH SEE ALSO +pkgmk.conf(5), Pkgfile(5), pkgadd(8), pkgrm(8), pkginfo(8), rejmerge(8), signify(1), curl(1), wget(1) +.SH COPYRIGHT +pkgmeek contains code from: + +\ \ \ \(bu pkgmk (c) 2004--2021 Per Liden and the CRUX team (http://crux.nu). + +\ \ \ \(bu upkgmk (c) 2018 Fun (http://gitlab.com/therealfun) + +Unifying these two code bases and eliminating awkward transitions between their radically +different styles was the work of John McQuah (2022). All code is released under the GNU General +Public License. See COPYING for more details.