Instructions and reference for creating CRUX ports

A CRUX port is a directory containing several files which specify the build process for a particular software package. Most of the build process itself is defined in a file named Pkgfile. You can think of this as a Makefile for pkgmk, the utility which builds the port.

Other files which should appear in a port directory are .md5sum and .footprint. These files are used to verify the integrity of the source and build result of the port, respectively. Pkgmk will create each of them for you, as you build your port for the first time.

Example port directory:

$ ls -a /usr/ports/myports/somelib
.  ..  .footprint  .md5sum  Makefile.in.patch  Pkgfile

Example Pkgfile:

# Maintainer: Joe Maintainer, joe at myfantasticisp dot net
# Description: A library for demonstrating how to create delicious ports
# Url: http://www.gnu.org/software/somelib/index.html
# Depends on: someotherlib, coolness

name=somelib
version=1.2.3
release=1
source=(ftp://ftp.gnu.org/gnu/$name/$name-$version.tar.gz Makefile.in.patch)

build() {
	    cd $name-$version
	    patch -p1 < ../Makefile.in.patch
	    ./configure --prefix=/usr
	    make
	    make DESTDIR=$PKG install
	    rm -rf $PKG/usr/info
}

Note that you should use this specific format for the email address if you want to put your ports in any of the official CRUX repositories.

Listing of dependencies

Dependencies are supported by some CRUX tools like prt-get and pkg-get, the following rules should be respected:

• We 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 this policy 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.

Pre- and post-install routines

Pre- and post-install routines are unofficially supported by some CRUX tools, and therefore may exist in a port directory as well. The files pre-install and post-install are reserved for this purpose. Be advised, if you're planning to make use of these files, of the following caveats:

• Users must opt to run pre- and post-install scripts. They are not executed by default.
• These scripts must be smart enough to be invoked multiple times safely.
• Pre- and post-install scripts will be executed with /bin/sh.

Once you have created your port(s), you may wish to share them via HttpUp and/or the ContribCollection.

Use of the "INSTALL" rule in pkgadd.conf

Starting with pkgutils 5.21, pkgadd can ignore installation of certain files. This is meant to allow the user to control installation of groups of files. Thanks to this, we now recommend to install files in /usr/share/applications and /usr/share/pixmaps, since they can be ignored easily.

It is recommended to not use per port INSTALL rules, since this may quickly lead to a maintenance nightmare for users. If you think a group of files is worth identifying please send an e-mail to crux@lists.crux.nu, explaining your idea.

Packages providing rc start scripts

You can use the following template script for ports, that provide some sort of daemon that should be runnable from a script called $name.rc, your port installed 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

The script could look like

#!/bin/sh
#
# /etc/rc.d/name: start/stop name daemon
#

SSD=/sbin/start-stop-daemon
PROG=/usr/sbin/name
PID=/var/run/name.pid
OPTS=""

case $1 in
start)
        $SSD --start --pidfile $PID --exec $PROG -- $OPTS
        ;;
stop)
        $SSD --stop --remove-pidfile --retry 10 --pidfile $PID
        ;;
restart)
        $0 stop
        $0 start
        ;;
status)
        $SSD --status --pidfile $PID
        case $? in
        0) echo "$PROG is running with pid $(cat $PID)" ;;
        1) echo "$PROG is not running but the pid file $PID exists" ;;
        3) echo "$PROG is not running" ;;
        4) echo "Unable to determine the program status" ;;
        esac
        ;;
*)
        echo "usage: $0 [start|stop|restart|status]"
        ;;
esac

# End of file