204 lines
8.7 KiB
Groff
204 lines
8.7 KiB
Groff
.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 "\-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 DEPRECATED OPTIONS
|
|
.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 the same feature set as the original \fBpkgmk\fP by
|
|
Per Liden, but in a more compact code base to allow for extensibility and easier auditing.
|
|
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 each exit ramp along that story line 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, an accelerated pace of upstream
|
|
development keeps core maintainers too busy bumping the version numbers in the ports tree, so
|
|
patches to system tools cannot be reviewed as quickly as in 2017, or 2, 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.
|