Documentation/man8/pkgmeek.8

.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 <file>"
Use private key in <file> 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 <file>"
Use public key in <file> 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 <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.
The patch submissions that do arrive are not dealt with in a timely manner, which is more easily
explained by a reduction in the number of core developers than by stipulating that CRUX package
tools have reached full maturity and cannot gain much benefit from new patches. The next most
probable explanations for the slow response to bug reports are: 1, interest in CRUX is waning (and
could stand to be reinvigorated), or 2, the would-be contributors start paging through a legacy code
base and lose confidence in their ability to help out. If either of these latter explanations has
any merit, \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.