CRUX : Home

Home :: Documentation :: Download :: Development :: Community :: Wiki :: Ports :: Bugs :: Links :: About

The Ports System


What is a Port?

A port is a directory containing the files needed for building a package using pkgmk. This means that this directory at least has the files Pkgfile (which is the package build description) and .footprint (which is used for regression testing and contains a list of files this package is expected to contain once it is built). Further, a port directory can contain patches and/or other files needed for building the package. It is important to understand that the actual source code for the package is not necessarily present in port directory. Instead the Pkgfile contains an URL which points to a location where the source can be downloaded.

The use of the word port in this context is borrowed from the BSD world, where a port refers to a program that has been ported to a system or platform. The word can sometimes be a bit misleading since most programs require no actual porting to run on CRUX (or on Linux in general).

What is the Ports System?

The term Ports System refers to a remote repository containing ports and a client program capable of downloading ports from that repository. CRUX users use the ports(8) utility to download ports from the repository and place them in /usr/ports/. The ports utility uses rsync(1) to do the actual downloading/synchronization.

Port collections

CRUX' ports are organized in so called collections. There are three different layers of ports:

The official collection 'core', 'opt' and 'xorg'

core, opt and xorg are the three primary collections of CRUX. They're maintained by the CRUX development team which ensures that they're consistent and working well together. Those three collections are also enabled by default in CRUX.

The user contributed collection 'contrib'

The contrib collection is a relatively new collection which is provided by experienced port maintainers, some part of the CRUX development team, some regular users. Its goal is to reduce the number of duplicate ports provided in the individual collections. If you're a seasoned port maintainer, you might even want to join the contrib collection.

As those ports are not provided officially by the CRUX development team, this collection is disabled by default.

The individual collections from CRUX users

Using HttpUp, every user can publish his or her own ports easily; the only requirement for that is some webspace to upload the ports. Publishing ports in an HttpUp repository is the easiest way to contribute back to the CRUX community.

Using the Ports System

Synchronizing Your Local Ports Structure

When CRUX is installed for the first time the local ports structure (/usr/ports/) is empty. To bring your local ports structure up to date you use the ports utility with the -u option. Example:

 $ ports -u

The -u option means update, and tells ports to contact the ports repository and download new and updated ports. The output from this execution is something like this:

 Updating file list from
 Updating collection ports/crux-2.3/core/
 Updating file list from
 Updating collection ports/crux-2.3/opt/
 Updating file list from
 Updating collection ports/crux-2.3/xorg/
 Finished successfully

The output reveals which files are downloaded, updated and deleted.

Listing Local Ports

When the local ports structure has been updated the directory /usr/ports/ will contain two package categories, core and opt. Under each of these directories you will find ports. You can simply browse around in the directory structure to find out which ports are available.

 $ cd /usr/ports/core/
 $ ls
 autoconf/    gdbm/               ncurses/        sendmail/
 automake/    gettext/            net-tools/      shadow/
 bash/        glibc/              netkit-base/    slocate/
 bc/          grep/               netkit-ftp/     strace/
 bin86/       groff/              netkit-telnet/  sysfsutils/
 bindutils/   grub/               nfs-utils/      sysklogd/
 binutils/    gzip/               openssh/        sysvinit/
 bison/       hdparm/             openssl/        tar/
 bzip2/       hotplug/            patch/          tcp_wrappers/
 coreutils/   httpup/             pciutils/       tcsh/
 cpio/        iptables/           perl/           time/
 curl/        jfsutils/           pkg-config/     traceroute/
 db/          kbd/                pkgutils/       udev/
 dcron/       less/               portmap/        unzip/
 dhcpcd/      libstdc++-compat/   ports/          usbutils/
 diffutils/   libtool/            ppp/            util-linux/
 e2fsprogs/   libusb/             procps/         vim/
 ed/          lilo/               prt-get/        wget/
 expat/       m4/                 psmisc/         which/
 file/        make/               rc/             xfsprogs/
 filesystem/  man/                rdate/          zip/
 findutils/   man-pages/          readline/       zlib/
 flex/        mktemp/             reiserfsprogs/
 gawk/        module-init-tools/  rsync/
 gcc/         nasm/               sed/

You can also use ports with the -l option to list all local ports. Example:

 $ ports -l

If you are looking for a specific package it might be easier to use this approach (e.g. ports -l | grep sendmail) to find out if the package is available and if so in which category it is located.

Listing Version Differences

To find out if the ports structure carries ports that are different (likely newer) compared to the versions currently installed you can use the option -d. If version differences are found, the output from the above command could look something like this:

 $ ports -d
 Collection  Name     Port      Installed
 core        glibc    2.3.6-3   2.3.6-2
 opt         gtk      2.8.12-1  2.8.11-1

If no version differences were found, i.e. the system is in sync with the ports structure. Then output will simply be:

 $ ports -d
 No differences found

Building and Installing Packages

Once you have found a port that you want to build and install you simply go into the desired port directory and use pkgmk to build it. Example:

 $ cd /usr/ports/core/gawk
 $ pkgmk -d

The -d option means download missing source files and tells pkgmk to download the source(s) specified in the Pkgfile (in case the source is already downloaded this option is ignored). When the download is completed the package will be built. If the package was built successfully you can use pkgadd to install or upgrade it. Example:

 $ pkgadd gawk#3.1.5-3.pkg.tar.gz

To make life a bit easier these two steps can be made into one by using the options -i (for install) or -u (for upgrade). Example:

 $ pkgmk -d -i


 $ pkgmk -d -u

This will download, build and then install/upgrade the package. Note that the package will only be installed/upgraded if the build is successful.

Enabling the 'contrib' collection

As previously mentioned, the 'contrib' collection contains useful ports of experienced port maintainers. Since they are not provided by the CRUX development team, you should be slightly more critical with respect to quality and security. Most members of the 'contrib' collections are well respected community members though.

To enable it for ports, do

$ cd /etc/ports
$ mv contrib.rsync.inactive contrib.rsync

To let prt-get know that you want it to use the contrib tree to, edit /etc/prt-get.conf and uncomment the line prtdir /usr/ports/contrib (i.e. remove the hashmark in the beginning of the line. After that, it should look like this:

### prt-get conf

# note: the order matters: the package found first is used
prtdir /usr/ports/core
prtdir /usr/ports/opt

# the folloing line enables the user maintained contrib collection
prtdir /usr/ports/contrib

Now, run ports -u and you're ready to use the ports from contrib.

Additional tools

Building ports as unprivileged user

Normaly building packages requires root-privileges. This is critical because a malicious or badly designed port can damage your system. The fakeroot command provides a way to build ports as normal user. Particularly when you build packages from user contributed repositories you should always invoke fakeroot:

$ fakeroot pkgmk -d

You can also make prt-get to use fakeroot. There is manual on the CRUX website describing how to achieve that.

Useful scripts

Reagarding package and ports management there are many tasks which can be done in several steps with the CRUX standard tools introduced above. The port prt-utils in the opt repository contains a collection of such scripts. The usage of these scripts is documented in the corresponding man pages. In the documentation section of the CRUX website is an overview of all the scripts in prt-utils.