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 "\-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. Only needed after editing a
previously-built port, since the first build of a new port will automatically
create \fB.signature\fP in the port directory.
.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 "\-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 DEPRECATED OPTIONS
.TP
.B "\-c, \-\-clean"
Using \fBprtwash(1)\fP to remove the built package and downloaded
source files gives you the flexibility to specify exactly what you want
deleted. There is no longer a need to have this functionality included
in \fBpkgmeek\fP.
.TP
.B "\-r, \-\-recursive"
If you want to traverse the working directory for all valid port dirs
(containing a \fBPkgfile(5)\fP, .signature, and .footprint) and run
\fBpkgmeek\fP in each directory found, you should write a wrapper
script instead. Putting that functionality inside \fBpkgmeek\fP itself
requires either hard-coding a specific set of flags passed to the
\fBfind(1)\fP command (such as whether to follow symlinks), or asking
the user to supply the flags. Each of these design decisions would 
fit poorly in some use cases, so recursive invocations are now the
user's responsibility.
.TP
.B "\-cm, \-\-check-md5sum, \-im, \-\-ignore-md5sum, \-um, \-\-update-md5sum"
The code to generate a listing of md5 hashes for the source files has been removed
from \fBpkgmeek\fP. Verifying the integrity of source files should be handled
by \fBsignify(1)\fP instead. If you are maintaining a personal port collection and
have not saved the signify public key in /etc/ports (corresponding private key in
~/.ssh or /etc/ports), then other users of your port collection will have no way 
to ensure the integrity of the downloaded source files. Read the CRUX wiki to learn
how to configure a signify public key for your port collection.

.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 ".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 footprint mismatch 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 all the essential features of the 
official \fBpkgmk\fP, but in a more compact code base to allow for
extensibility and easier auditing. A few less-frequently-used features
have been omitted from \fBpkgmeek\fP, as explained in
.B DEPRECATED OPTIONS
above. 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. Reviewers of the
\fBpkgmeek\fP script should be able to discern a linear narrative leading to
the desired binary package, with clearly marked exit ramps if the user
desires only a subset of the full \fBpkgmeek\fP functionality. 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.

One new feature that sets \fBpkgmeek\fP apart from \fBpkgmk\fP is its native
support for git sources. If the prefix \fI__git__\fP appears among any of
the entries in the source array, then \fBpkgmeek\fP will strip off this
prefix and interpret the rest of the entry as the URL of a git project.
The port maintainer can also specify a branch or a tag other than "main",
by appending the tag to the base URL, with the hash symbol (#) as 
separator. The downloaded git project will be saved under the directory
specified by PKGMK_SOURCE_DIR, using either the project name (the default)
or the entry designated by the \fBrenames\fP array. Rebuilding the port when
a directory of the designated name already exists will trigger a fresh pull
from the upstream git repository, thereby guarding against possible bit rot
in the local copy. See \fBPkgfile(5)\fP for more details and an example
source array.

.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.