# Using MacPorts

This chapter describes using the `port` command, port variants, common tasks and port binaries.

## The port Command

The MacPorts `port` command is the main utility used to interact with MacPorts. It is used to update `Portfile`s and the MacPorts infrastructure, and install and manage ports.

### selfupdate

The `selfupdate` option should be used regularly to `sync` the local ports tree with the global MacPorts ports repository so you will have the latest port versions. It also checks for new revisions of the MacPorts infrastructure, called MacPorts base, and upgrades it when necessary.

Selfupdate runs only on Mac OS X. If you are running MacPorts on another platform, you must use option sync to update the ports tree; to update MacPorts base you must manually install a newer version from source.

    %% sudo port selfupdate

Use the debug flag for verbose output.

    %% sudo port -d selfupdate

    DEBUG: Rebuilding the MacPorts base system if needed.
    DEBUG: Synchronizing ports tree(s)
    Synchronizing from rsync://rsync.macports.org/release/ports/
    DEBUG: /usr/bin/rsync -rtzv --delete-after rsync://rsync.macports.org/release/ports/
    receiving file list ... done

    [ ... trimmed ... ]

    The MacPorts installation is not outdated and so was not updated
    DEBUG: Setting ownership to root
    selfupdate done!

If selfupdate detects that a newer version of MacPorts base is available, it automatically updates the installed copy of MacPorts base to the latest released version. In that case, you will see the upgrade Makefile execute, and when it finishes you will see this message:

    DEBUG: Updating using rsync
    receiving file list ... done

    Congratulations, you have successfully installed the MacPorts system.

### sync

The `sync` option performs a subset of `selfupdate` actions. It synchronizes the ports tree, as does `selfupdate`, but it does not check for upgrades to MacPorts base. On Mac OS X, unless there is a special reason not to do so, you should run selfupdate.

For platforms other than Mac OS X, `sync` is the only way to get port updates because `selfupdate` is supported only on Mac OS X.

### list

The `list` option is used to get a list of all available ports. The list of available ports is very long, so use search if you know a port's name or part of it.

    %% port list

### search

The `search` option is very useful to find port names by partial matches.

    %% port search rrd

    rrdtool          net/rrdtool       1.2.23    Round Robin Database
    php5-rrdtool     www/php5-rrdtool  1.0       PHP 5 glue for RRDtool

### info

The `info` option is used to get information about a port: description, maintainer, etc.

    %% port info flowd

    flowd 0.9, net/flowd (Variants: universal, darwin_8)
    http://www.mindrot.org/flowd.html

    flowd is a small, fast and secure NetFlow collector.

    Platforms: darwin
    Maintainers: nomaintainer@macports.org

### deps

The `deps` option shows you the dependencies of a port; dependencies are explicitly declared in `Portfile`s.

    %% port deps apache2

    apache2 has library dependencies on:
            apr
            apr-util
            expat
            openssl
            pcre

### variants

The `variants` option allows you to check what variations of a port are available before you install it. Variants are a way for port authors to provide options that may be invoked at install time. See Invoking Port Variants below to install ports that have variants.

    %% port variants nmap

    nmap has the variants:
            universal
            gtk2
            no_ssl
            no_pcre

### install

The option `install` is used to install a port. See Invoking Port Variants below to install ports that have variants.

    %% sudo port install nmap

You may break up a port's installation into smaller steps for troubleshooting by passing `port` a prior installation phase such as fetch, configure, build, or destroot. See section Port Phases for a complete list of phases.

### clean

The option `clean` deletes all intermediate files that MacPorts creates while building a port. A `port clean` is also often necessary to remove corrupted tarballs after a failed `fetch` phase.

    %% port clean --all vile

You may also clean files selectively by using options `--dist`, `--archive`, or `--work`.

### uninstall

The `uninstall` option will uninstall an installed port.

    %% port uninstall vile

If a port as installed as a dependency of another port, uninstall will not remove it unless you remove the dependent ports first. To override this behavior, use the `-f` (force) switch. But some ports need to be rebuilt if dependencies change, so you should know what you are doing if you force uninstall ports.

    %% port -f uninstall vile

### contents

The `contents` option displays the files that have been installed by a given port. Uninstalled ports will always show no contents.

    %% port contents render

    Port render contains:
      /opt/local/include/X11/extensions/render.h
      /opt/local/include/X11/extensions/renderproto.h
      /opt/local/lib/pkgconfig/render.pc
      /opt/local/share/doc/render/library
      /opt/local/share/doc/render/protocol

### installed

The `installed` option displays all installed ports.

    %% port installed

    The following ports are currently installed:
      aalib @1.4rc5_2 (active)
      apr @1.2.8_0 (active)
      apr-util @1.2.8_2 (active)
      atk @1.18.0_0 (active)

    [ ... trimmed ...]

      wxWidgets @2.8.4_2+darwin_8 (active)
      Xft2 @2.1.7_0 (active)
      xrender @0.9.0_0+darwin_8 (active)
      zlib @1.2.3_1 (active)

### outdated

The `outdated` option checks your installed ports against the MacPorts repository to see if updated Portfiles have been released since your ports were installed.

    %% port outdated

    apr                            1.2.8_0 < 1.2.9_0
    autoconf                       2.61_0 < 2.61_1
    gimp                           2.2.14_0 < 2.2.16_0
    libtool                        1.5.22_0 < 1.5.24_0
    pkgconfig                      0.21_0 < 0.22_0

### upgrade

The `upgrade` option upgrades installed ports and their dependencies when a `Portfile` in the repository has been updated after a port was installed.

    %% port upgrade gnome

If you wish not to upgrade a port's dependencies, use the `-n` switch.

    %% port -n upgrade gnome

If you'd like to upgrade all outdated ports, use this command.

    %% port upgrade outdated

The `upgrade` option by default does not uninstall an upgraded port —it deactivates it. See section Port Images, and also Destroot and Activate phases in Port Phases. If you wish to uninstall the old version, use the `-u` option.

    %% port -u upgrade vile

### dependents

The `dependents` option reports what ports depend upon a given port, if any. MacPorts learns about dependents during port installation, so uninstalled ports will always report that there are no dependents.

    %% port dependents openssl

    neon depends on openssl
    gnome-vfs depends on openssl
    libdap depends on openssl

### livecheck

The livecheck option checks to see if the application corresponding to a given port has been updated at the developer's download site. It's especially useful for port maintainers, but others may also wish to see if a port has the latest available distribution source. See section Livecheck for more information.

    %% port livecheck rrdtool

    rrdtool seems to have been updated (port version: 1.2.23, new version: 1.3beta1)

If livecheck finds no higher version at the port's download site, it prints nothing. The option `-d` (debug) may be used for detailed livecheck processing information.

### lint

The lint option checks if the Portfile conforms to the MacPorts standards specified in Portfile Development.

If a Portfile validates fine the following message is shown.

    %% port lint chemtool

    --->  Verifying Portfile for chemtool
    --->  0 errors and 0 warnings found.

Otherwise the warnings and errors are listed.

    %% port lint KeyArcher

    --->  Verifying Portfile for KeyArcher
    Warning: Line 2 should be a newline (after RCS tag)
    Warning: Line 5 has trailing whitespace before newline
    Error: Missing required variable: platforms
    --->  1 errors and 2 warnings found.

## Port Variants

Variants are a way for port authors to provide options for a port that may be chosen during the port install. To display the available variants, if any, use this command:

    %% port variants fetchmail

    fetchmail has the variants:
            universal
            ssl: Support secure connections using OpenSSL
            fetchmailconf: Install a graphical configurator
            ntlm: Enable NTLM authentication

Variant descriptions are optional, so you may not see descriptions for all variants.

### Invoking Variants

A variant can only be invoked when a port is installed. After you have determined what variants a given port has, if any, you may install a port using the variant as shown.

    %% port install fetchmail +ssl

Port variant execution may be verified using the `port` command with the verbose switch.

    %% port -v install fetchmail +ssl

When a port is installed using a valid variant and specified correctly, the verbose output will contain:

    DEBUG: Executing variant ssl provides ssl

### Negating Default Variants

For an explanation of default variants see Port Variants. Default variants are optional, and not all ports using variants have them. For ports with default variants, you may install a port without them by negating default variants using "-" as shown.

    %% port install fetchmail -ssl

To verify that you have properly negated a default variant, you may want to use verbose mode. But negated variants are simply not reported in any way by the `port` command, as if they did not exist. You will know you have successfully negated the default variant in the example above if you do not see this line in the verbose output.

    DEBUG: Executing variant ssl provides ssl

## Common Tasks

This section lists common operations you may want to perform when managing a MacPorts installation.

TODO: Add content here.

## Port Binaries

MacPorts can pre-compile ports into binaries so applications need not be compiled when installing on a target system. MacPorts may create two types of binaries: archives and packages.

### Binary Archives

Binary archives can only be used on a target system running MacPorts. Binary archives allow MacPorts utilities to begin installation after the destroot phase and install and activate a port on the target system. Binary archives are created using the `port` command as shown.

    %% port -d archive logrotate

Debug output is shown below.

    --->  Creating logrotate-3.7_0.i386.tgz

    [ ... trimmed ... ]

    DEBUG:
    ./
    ./+COMMENT
    ./+CONTENTS
    ./+DESC
    ./+PORTFILE
    ./+STATE
    ./opt/
    ./opt/local/
    ./opt/local/etc/
    ./opt/local/etc/logrotate.conf
    ./opt/local/man/
    ./opt/local/man/man8/
    ./opt/local/man/man8/logrotate.8
    ./opt/local/sbin/
    ./opt/local/sbin/logrotate
    --->  Archive logrotate-3.7_0.i386.tgz packaged
    DEBUG: Executing archive_finish
    --->  Archive for logrotate 3.7_0 packaged

Binary archive files are placed in `${prefix}/var/macports/packages/`. The archive file type is set in the `macports.conf` file. The default format is .tgz; other options are: tar, tbz, tbz2, tlz, xar, zip, cpgz, cpio.

### Binary Packages

Binary packages are standalone binary installers that are precompiled; they do not require MacPorts on the target system. Binary files created with MacPorts may be either .pkg (Mac OS X Installer Packages), or RPM (RPM Package Manager) format. MacPorts may also process a .pkg package into a Mac OS X .dmg disk image file. You may create binary packages with the `port` command as shown in these examples.

    %% port pkg pstree

You may create a Mac OS X .dmg disk image file as shown.

    %% port dmg pstree

You may compile a port into an RPM file as shown, in order to install it onto a target that has RPM utilities or a full package management system that can install RPMs.

    %% port rpm pstree

All packages are placed in a port's work directory.

### Port Source Packages

Source packages are bundles consisting of a `Portfile`, patches if needed, and any other files required to install the port. Port source packages are mainly used by developers of package management and port submission frameworks. Port source packages may be in either .portpkg (XAR) or .nosrc.rpm (SRPM) format.