Pkgfile(5)

NAME
Pkgfile - sourced by pkgmk(8) when building a package in the ports tree

DESCRIPTION
a bash(1) script that tells pkgmk(8) where the source code for a port may be downloaded, and what to do once that source code is unpacked.

FILE FORMAT
Pkgfile starts with a header of commented lines, which are read by prt-get(8) to resolve dependencies, or by portspage(1) to generate an HTML index of the ports collection. After the header pkgmk will expect to find definitions of several mandatory variables, including name, version, release, the bash array source, and the bash function build().

  Example:
    # Description: A library for demonstrating how to create delicious ports.
    # URL:         http://www.gnu.org/software/somelib/index.html
    # Maintainer:  Joe Maintainer, joe at myfantasticisp dot net
    # Depends on:  someotherlib coolness
    name=somelib
    version=1.2.3
    release=1
    source=(ftp://ftp.gnu.org/gnu/$name/archive/$version/$version.tar.gz Makefile.in.patch)
    renames=($name-$version.tar.gz SKIP)
    build() {
    	cd $name-$version
    	patch -p1 < ../Makefile.in.patch
    	./configure --prefix=/usr
    	make
    	make DESTDIR=$PKG install
    	rm -rf $PKG/usr/info
    }

  General guidelines
The name of a package should always be lowercase (e.g. name=eterm and not name=Eterm). In case the package is added to the CRUX ports system the exact same name should be used for the name of the directory in the ports structure, i.e. /usr/ports/???/eterm.

Do not combine several separately distributed programs/libraries into one package. Make several packages instead.

Use prtverify to check the port.

  Variable names

Do not add new variables to the Pkgfile. Only in very few cases does this actually improve the readability or the quality of the package. Further, the only variables that are guaranteed to work with future versions of pkgmk are name, version, release, and source. Other names could be in conflict with internal variables in pkgmk.

Use the $name and $version variables to make the package easier to update/maintain. For example,
    	source=(http://xyz.org/$name-$version.tar.gz)
is better than
    	source=(http://xyz.org/myprog-1.0.3.tar.gz)
since the URL will automatically update when you modify the $version variable.

  Support for renaming source files
Note that in the somelib example above, Joe Maintainer chose to define the optional bash array renames (same length as source), so that the ambiguously-named file retrieved by FTP would not collide with another port's files, if downloaded into a common directory. The keyword ‘SKIP’ was given in the renames array to indicate that renaming was not necessary for the corresponding source file. SKIP should always be used for a file retrieved by ‘ports -u’, because the port maintainer has the freedom to choose an unambiguous name in the source array itself.

Tools from prior versions of CRUX, ignorant of the renames array, will execute the build function using the original filenames given by the remote sources. For maximum compatibility, nothing in your build function should rely on the specific names you choose for the downloaded tarballs (their contents will be unpacked into identically-named work directories anyway, assuming you do not take the liberty of redefining unpack_source() in your Pkgfile). But because earlier CRUX tools also have to be instructed to disregard md5 and signature mismatches, port creators should avoid the renaming feature unless absolutely necessary.

  Directories
In general packages should install files in these directories. Exceptions are of course allowed if there is a good reason. But try to follow the following directory structure as closely as possible.
    Directory           Description
    ---------           ------------
    /usr/bin/           User command/application binaries
    /usr/sbin/          System binaries (e.g. daemons)
    /usr/lib/           Libraries
    /usr/include/       Header files
    /usr/lib/<prog>/    Plug-ins, addons, etc
    /usr/share/man/     Man pages
    /usr/share/<prog>/  Data files
    /usr/etc/<prog>/    Configuration files
    /etc/               Configuration files for system software (daemons, etc)

/opt directory is reserved for manually compiled/installed applications. Packages should never place anything there.

/usr/libexec/ is not used in CRUX, thus packages should never install anything there. Use /usr/lib/<prog>/ instead.

  Junk files

Packages should not contain "junk files". This includes:

•   info pages and other online documentation, man pages excluded (e.g. usr/doc/*, README, *.info, *.html, etc).

•   Files related to NLS (national language support). If --disable-nls is not available as an option to configure, then manually inserting ‘rm -rf $PKG/usr/share/locale’ near the end of the build function is an acceptable alternative.

•   Useless or obsolete binaries (e.g. /usr/games/banner and /sbin/mkfs.minix).

Apart from these global rules, the definition of "junk" is often a matter of personal taste. One user might regard as "junk" the same files that another user sees as indispensible. See Optional dependencies below for a simple way to let your port handle such individual preferences automatically.

  Header
Provide a header including the following fields:
    Name            Meaning
    ----            -------
    Description     A short description of the package; keep it factual
    Maintainer      Your full name and e-mail address, obfuscated if you want
    Packager        The original packager's full name and e-mail address
    URL             A webpage with more information on this software package
    Depends on      A list of dependencies, separated either by spaces or commas
Note that you should use the obfuscated email address (illustrated in the example above) if you want to put your ports in any of the official CRUX repositories. Depends on can be omitted if there are no dependencies.

  Dependencies
Dependencies are supported by CRUX tools like prt-get and pkg-get. The following rules should be respected:

    List all runtime dependencies except for gcc (libstdc++) and glibc.

    core contains essential packages for a CRUX system, and our scripts and ports expect the programs provided by core to be installed; this means that:

    build dependencies provided by core are not listed in the dependency header

    run-time dependencies from core which aren't dynamically linked in are not to be listed, either

Examples:

    opt/sloccount does not list perl, because the program is a perl script -- there's no binary that links to libperl

    opt/libxml2 does list zlib, because libxml is linked to libz.

The reasoning for these guidelines is that you can use revdep to find ports that need to be updated if one of the dependent libraries has become binary incompatible. To find out what libraries a binary is linked to, use ldd or finddeps.

It is permissible to list build dependencies outside of core, whose only purpose is to generate the manpage of the port. But if the dependency chain is too convoluted, try to find alternative ways of providing such static documentation.

Examples:

    greetd does list scdoc (only needed to generate the manpages), because the dependency chain leading to this dependency is just scdoc itself.

    mpd does not list python3-sphinx (only needed to generate the manpages), because of the long dependency chain leading to python3-sphinx, and the possibility of delivering the manpages by simpler means.

  Optional dependencies
A common practice among port maintainers is to put filesystem tests in the build function, allowing the package configuration to vary depending on what other packages the system administrator has installed. This practice can result in footprint mismatches. It is recommended that maintainers build their ports in a container with the bare minimum of dependencies, or prune the auto-generated footprint so that the spurious files are not reported as MISSING on another user's system.

Filesystem tests are also useful at the end of a build function, for example when determining which shell completions should be installed. Here is a template for tests of this kind:
    	prt-get isinst bash-completion || rm -rf $PKG/usr/share/bash-completion
    	prt-get isinst zsh || rm -rf $PKG/usr/share/zsh
    	prt-get isinst fish || rm -rf $PKG/usr/share/fish

If the maintainer built the package in a clean container, then another user with fish installed will see the path /usr/share/fish listed as NEW in the footprint mismatch, and that user can proceed with installation if PKGMK_IGNORE_NEW was enabled in pkgmk.conf(5). More dangerous is the reverse situation: the maintainer built the package in a system with fish, and a user without fish sees /usr/share/fish listed as MISSING in the footprint mismatch. Users should not be encouraged to disregard MISSING, but enabling PKGMK_IGNORE_NEW is generally safe.

  rc start scripts
You can use the following template for ports that provide some sort of daemon. The runnable script should be called $name.rc, and your port should install it to /etc/rc.d/$name. The installation can happen by calling the following in your build function:
    	install -D -m 755 $SRC/$name.rc $PKG/etc/rc.d/$name

See the existing scripts under /etc/rc.d for examples of using start-stop-daemon(8) to generate the necessary pid files, temp directories, and logs for your daemon.

ENVIRONMENT

The build function should use the $SRC variable whenever it needs to access the files listed in the source variable, and the $PKG variable as the root destination of the output files.

Being a shell script executed in the context of pkgmk(8), the entire Pkgfile has access to the variables initialized in pkgmk.conf(5) and the default values set by pkgmk(8). Also, as a side effect of how it is used by pkgmk(8), the Pkgfile can also change the behaviour of pkgmk(8) by rewriting some of its functions and variables before build() is called. However, the build function itself has only read access to these environment variables and shell functions.

ERRORS

Most of the command failures in build() will stop the build process. There is no need to explicitly check the return codes. If you need/want to handle a command failure you should use constructs like:
    	if ! command...; then ...
    	command || ...

SEE ALSO
pkgmk(8), pkgmk.conf(5), https://crux.nu/Main/PortGuidelines, https://crux.nu/Main/PrePostInstallGuidelines.

COPYRIGHT
pkgmk (pkgutils) is Copyright (c) 2000-2005 Per Liden and Copyright (c) 2006-2021 CRUX team (http://crux.nu). pkgmk (pkgutils) is licensed through the GNU General Public License. Read the COPYING file for the complete license.