prt-get - Quick start

Getting started with prt-get


Johannes Winkelmann,

Table of Contents

1. Quick start
1.1. Overview
1.2. Basics
2. How prt-get finds the ports
2.1. Port directory listings and order
2.2. Fine grained selection
3. Searching packages
3.1. Search by name
3.2. Searching package descriptions
3.3. Searching files
3.4. Regular expression support
4. Learning more about a port
4.1. General information
4.2. Dependencies
5. Information about installed packages
5.1. Finding differences between installed and available packages
5.2. Checking for installed packages, and their versions
6. Package installation and removal
6.1. Simple install and update
6.2. Installation including dependencies
6.3. Updating all outdated packages
6.4. Removing packages
7. Manipulation of a port's files
8. Where to go from here

1. Quick start

1.1. Overview

This section is a quick start guide to using prt-get. If you'd like to get an idea what prt-get is and what it can do, this is a good starting point.

For further information, have a look at the user manual which covers prt-get's functionality much more in depth.

1.2. Basics

prt-get is a frontend to pkgmk and pkgadd from Per Lidén's pkgutils. Therefore, no changes are required to make ports work with prt-get. The ideas which led to the development of prt-get took place in 2002 in the CRUX mailing list, and the tool modelled after that. Since then, prt-get has evolved quite a bit, and has been improved continuously to address upcoming problems/issues during package management, following the philosophy of CRUX and the CRUX Linux Community CLC as strictly as possible.

The idea behind prt-get is to simplify common tasks and therefore help to avoid repetitive work and making unnecessary errors. It has support for dependency resolution (given a port specifies dependecies) and different search and query functionality. Furthermore, it has several commands to install and update ports, including one to update all outdated ports.

One particularly interestion feature is the abstraction layer for the ports tree prt-get provides: in order to install packages, you don't have to know it's location, prt-get will search it in the file system. The next subsection will contain more information about how prt-get searches for ports.

One important design decision was to keep prt-get from thinking for its user, since this would move the control to the tool which is not wanted. As a consequence, prt-get never does the wrong thing without being told to do so. I tried hard to avoid cases where prt-get would guess what the right thing would be if there's a chance that it's wrong.

2. How prt-get finds the ports

2.1. Port directory listings and order

In order to build a stable and consistent system, it's important that ports are tested against each other. Because of that, prt-get requires you to specify the directories where prt-get should look for package, and the order of these directories are used to choose a port; if more than one port exists for a certain package, the first matching port is used. To illustrate this, consider the following example:

Let's assume you have both CLC's contrib collection and a private repository in your ports tree. The recommended configuration would be to list contrib before the private repository, like this (excerpt from prt-get.conf; note that the default repositories are already there, you just have to add new repositories you subscribe to):

prtdir /usr/ports/contrib
prtdir /usr/ports/private

This ensures that packages will first be taken from contrib and therefore gurantee that it'll work fine with other packages, most notably its dependencies. Of course, you can exchange those two lines to achieve the same effect: prt-get will then choose all matching packages from the private repository, again choosing the matching packages (not one dependency from one collection, and another dependency from another collection). So you see the order is the only criteria here, which is the one I consider the most stable.

2.2. Fine grained selection

A question which comes up from time to time is what to do if you'd like just a single port from one collection, for example if the private repository contains. This can easily be done like this:

prtdir /usr/ports/private1:x11
prtdir /usr/ports/private2:freetype,fontconfig,expat
prtdir /usr/ports/contrib
prtdir /usr/ports/private1
prtdir /usr/ports/private2

The first line tells prt-get to prefer private1 for x11, the second shows how to prefer a list of ports. You'll see that private1 and private2 are added in the end without any filters, which will give you access to all their ports, but with lower priority than contrib

3. Searching packages

3.1. Search by name

Searching for a port by its name is done using the search command:

$ prt-get search mysql

The argument to search is currently just a substring. Future versions of prt-get will have support for regular expressions.

You can get more information out of prt-get search by increasing it's verbosity using the -v (show version) and -vv (show version and description) options. In addition, using --path also prints out the path information:

$ prt-get search -v mysql
mysql 4.1.12-1
mysql-client 4.1.11-1
mysql-python 1.2.0-1
mysql-ruby 2.6-1
mysqlcc 0.9.4-2
$ prt-get search -vv qt 
qt-engines-bluecurve 0.117-1: Bluecurve engine for qt
qt3 3.3.4-1: Qt Free Edition
$ prt-get search --path qt
$ prt-get search --path -v qt
/usr/ports/contrib/qt-engines-bluecurve 0.117-1
/usr/ports/contrib/qt3 3.3.4-1

3.2. Searching package descriptions

If you want to include search the package descriptions, use the dsearch command; it is just like the search command except that it searches both port name and description:

$ prt-get dsearch irc -vv
bnc 2.9.4-1: BouNCe - simple IRC proxy
epic4 2.2-1: EPIC - Enhanced Programmable ircII Client
epic4-help 20050315-1: Help files for the epic IRC client
irssi 0.8.9-3: irssi - Console IRC client.
ngircd 0.8.3-1: Next Generation IRC Server
opera 8.0-1: Lightweight web browser with news, e-mail and IRC
xcircuit 3.3.11-1: electrical circuit schematics editor

3.3. Searching files

If you're interested which package provides or would provide a certain file, use the fsearch command. It searches the footprints of the ports in your ports tree for the pattern you specify. Unlike search, fsearch doesn't take a substring as argument but a shell wildcard pattern (see man(7) for more information). Use --full to search both filename and path.

$ prt-get fsearch iwconfig
Found in /usr/ports/contrib/wireless-tools:

$ prt-get fsearch libttf\*
Found in /usr/ports/contrib/freetype1:
  usr/lib/ ->
  usr/lib/ ->

3.4. Regular expression support

Starting with version 0.5.11, prt-get understands regular expressions in all search commands. Use --regex or set 'useregex yes' in prt-get.conf to enable that.

4. Learning more about a port

4.1. General information

Once you've found a port of interest, you'd probably like to know more about it. Use the info command to start:

$ prt-get info cups
Name:         cups
Path:         /usr/ports/contrib
Version:      1.1.23
Release:      2
Description:  CUPS - Common UNIX Printing System
Maintainer:   Jürgen Daubert, juergen dot daubert at t-online dot de
Dependencies: openssl
Files:        README

This shows you the most interesting things about the package as an overview.

4.2. Dependencies

prt-get can cope with package dependencies if they are specified in the Pkgfiles. To list them, use the depends command:

$ prt-get depends gconf
-- dependencies ([i] = installed)
[i] gettext
[i] pkgconfig
[i] libxml2
[i] popt
[i] glib
[i] libidl
[ ] orbit2
[ ] gconf

This output also tells you which packages you already have installed on your system.

To unterstand the dependencies better, the deptree command prints a tree structure of the dependencies where you can directly see which packages depend on which:

$ prt-get deptree x11
-- dependencies ([i] = installed, '-->' = seen before)
[i] x11
[i]   fontconfig
[i]     freetype
[i]     expat
[i]     pkgconfig
[i]   libpng
[i]     pkgconfig

The output here can be interpreted as "x11 depends fontconfig and libpng; fontconfig depends on freetype, expat and pkgconfig; libpng depends on pkgconfig".

If you'd like to know which packages depend on a certain package, there's a command to list reverse dependencies called dependent:

$ prt-get dependent freetype 

By default, this command only lists packages currently installed. Use the --all switch to display all dependent packages found in your ports tree. It also understand the -v and -vv options, which do the same as for search. Note that dependent only lists direct dependencies.

5. Information about installed packages

5.1. Finding differences between installed and available packages

Use prt-get diff to find packages which are outdated:

$ prt-get diff
Differences between installed packages and ports tree:

Ports               Installed           Available in the ports tree

bash                3.0-1               3.0-2               
bmp                 0.9.7-1             0.9.7-2

Have a look at the next section to learn how to update those packages (either selectively, or all together).

5.2. Checking for installed packages, and their versions

If you're uncertain whether a particular is installed, you can used the isinst command. If it is, current will print its version:

$ prt-get isinst xmms
package xmms is not installed

$ prt-get isinst bmp
package bmp is installed

prt-get current bmp

6. Package installation and removal

6.1. Simple install and update

Installing a package is a simple matter of executing prt-get install <packagename>. You can also specify a list of packages to install in a single command.

The very same applies for updating already installed packages, except that the update command has to be used.

6.2. Installation including dependencies

prt-get can install packages including its dependencies, using the depinst command:

$ prt-get depinst licq

Just like all other install commands, you'll get a nice listing about installed packages afterwards, or a note saying where a build failed. There are too options which are common to all install commands but make especially sense for depinst: --test which just calculates the dependencies and prints the installation result without actually performing the install, and --log which creates log files per port (by default, can be configured differently). In order to use log files, make sure you have a valid 'logfile' pattern in your /etc/prt-get.conf.

6.3. Updating all outdated packages

To update all outdated packages, use the sysup command. The same notes as for depinst apply, using the --test option to do a test run first is a good idea, and --log for the actual update run.

If you'd like to exclude certain packages from being updated in sysup, you have two choices: you can use the lock command to lock a package permanentely, or the --ignore=<package> option, like this:

$ prt-get sysup --log --ignore=gcc,glibc

For more information on package locking, please have a look in the user manual.

6.4. Removing packages

To remove packages, use the remove command. It can take a list of packages to remove, but be aware that it doesn't check for dependencies at this point it time and just remove a package if it's asked to do so.

7. Manipulation of a port's files

The fact that prt-get abtracts the physical location from ports doesn't mean that we don't want to inspect or edit their files. There are a few commands to simplify that, which are:

  • ls - list files in a port's directory

  • cat - write out a file to stdout

  • readme - write out the readme file

  • edit - edit a file (one must set environment variable EDITOR to be able to use it)

$ prt-get ls cups
$ prt-get cat cups .footprint
drwxr-xr-x      root/root       etc/
drwxr-xr-x      root/root       etc/cups/
drwx--x--x      root/root       etc/cups/certs/
-rw-r--r--      root/root       etc/cups/classes.conf
[full output omitted]

$ prt-get readme cups
README for cups 1.1.x

[full output omitted]
$ prt-get edit cups Pkgfile
[opens editor]

8. Where to go from here

I'd warmly recommend you to have a look at the user manual, which explains the rest of prt-get's features as well as those features mentioned here in more detail. Also, feel free to contact me directly or via the crux mailing list if you have problems with prt-get.