pkgmeek.8: mention the native support for git sources

This commit is contained in:
John McQuah 2022-12-23 13:39:39 -05:00
parent 8f535898c8
commit 1239bdf4ad
1 changed files with 24 additions and 40 deletions

View File

@ -147,47 +147,31 @@ 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.
\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 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.
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).
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 "master",
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)