usage introduction user manual This document provides a short guide to the basics of the MacPorts system. The first section provides a short description of the goals of the project and a brief comparison with other systems. Subsequent sections describe how to get, install, and use MacPorts on your own machines. The aim of the MacPorts project is to develop a second- generation system for the building, installation and management of third party software. MacPorts is mainly developed on Mac OS X, however by design it is quite portable and is intended to work on other UNIX-like systems, especially *BSD and hopefully Linux-based systems. MacPorts is probably best described by comparison: It's sort of like the FreeBSD ports collection or Fink in that it automates the process of building third party software for Mac OS X and other operating systems. MacPorts also tracks all dependency information for a given piece of software. In other words, it knows what it needs to build and install and in what order for the piece of software you want to work properly. MacPorts knows how to make, build and install the software to a specific location, meaning that software installed via MacPorts doesn't simply scatter itself all over the system or require user knowledge of dependencies in what order. The FreeBSD Ports Collection is a large set of software packages ported to FreeBSD. The ports collection is also used on the other "free" BSDs. The FreeBSD Ports Collection is based on a large tree of ports where each software has a directory within a category (like mail or graphics). That directory contains the information needed to build the piece of software. MacPorts also uses a directory structure like this, although unlike FreeBSD ports the intention is to avoid requiring a complete copy of the 'Ports Tree' on every user's machine. The FreeBSD Ports Collection is essentially implemented as some very impressive but hairy BSD make(1)'s macros and can be opaque and non-extensible from the perspective of someone looking to extend or refactor parts of the system. Given that makefiles aren't the easiest thing to parse or for non-developers to understand, it is also harder to "mine" the FreeBSD ports collection for data to use for other purposes such as generating documentation indexes or arbitrary front-ends for creating or managing ports. A ports collection can be considered an 'expert system' that knows the sources, dependencies, and other information necessary to *build* a given Open Source project. A package management system relies on similar dependency information, but is focused on safely installing (and de-installing) software. Before MacPorts, most systems did both at once; MacPorts, however, is explicitly designed as a pure ports collection which can use various package management systems. Even discounting some of the limitations of The FreeBSD Ports Collection described above, creating automated build systems is rather more complex than it looks at first glance and there's always room for fresh approaches to the problem. Which is what we have set out to do with MacPorts. There are certainly other systems, some of which have already been mentioned, which have made their own attempts at solving this problem. There will likely be many more such systems in the future since trying to find a single solution which pleases everyone is rather like trying to find a single programming language which pleases everyone - it's more or less impossible. MacPorts is mostly written in Tcl, with some components written in C. Tcl was chosen to allow MacPorts to be readily embedded in other applications (e.g. a Cocoa GUI) and to allow flexible, but easy to read Portfiles. Even though MacPorts is written in Tcl, users do not need to know Tcl in order to use the system or even to add new ports. Port description files, though they are actually full Tcl programs in their own right, are designed to look like a simple list of key/value pairs. MacPorts primary target platforms are Mac OS X 10.4 "Tiger" and Mac OS X 10.3 "Panther" (i. e. Darwin 8.x and 7.x). However, MacPorts should still work on Mac OS X 10.2 "Jaguar", although most ports are no longer tested on Jaguar. MacPorts was previously known to work on various other operating systems such as FreeBSD, NetBSD, OpenBSD, and various Linux distributions, but the MacPorts project is no longer supports them. To install and use MacPorts you must install the Developer tools (gcc, autoconf etc on other platforms, also known as the "Xcode tools" on Mac OS X 10.3 and 10.4.). All the other prerequisites are pre-installed on Mac OS X 10.2 and later. On other platforms you will need to ensure you have installed Tcl (8.3 or later). Currently there are basically two ways to obtain MacPorts. Either download the sources as a tarball or get the binary installer via the downloadable disk image (both available in the download section). If you choose the binary installer, you can skip the next sections. If you want greater control and want to e. g. specify one of the various install-time options, you need to get the sources. If you want to very closely track the latest ports and use the latest experimental features of the port tool, you may want to use svn to check out the sources from our svn repository. To install MacPorts execute the following commands from the macports/base directory. These commands assume that you checked out the macports tree from Subversion or downloaded and extracted the tarball in your home directory. Modify the cd command appropriately if you did otherwise. This will compile and install all the necessary software. In order to install MacPorts on *BSD the default group-ownership must be passed to each make command: make DSTGRP=wheel . It is no longer necessary to edit ${prefix}/etc/macports/sources.conf after installing MacPorts. If you change the location of the mports directory, which was in ~/macports/mports based on the above examples, then you will still need to edit ${prefix}/etc/macports/sources.conf and modify the file:///Users/mike/macports/mports line to reflect the new location. To edit the file you must use a command line text editor like pico or vi. Please note, if you are using Mac OS X 10.2 "Jaguar", then you will need to edit ${prefix}/etc/macports/macports.conf and change: portinstalltype image to: portinstalltype direct You should add /opt/local/bin (or wherever you chose to install MacPorts) to your shell's path. If you are using Mac OS X 10.3 "Panther", Mac OS X 10.4 "Tiger" or a Bourne shell (bash, zsh), add the following line to your ~/.profile: export PATH=$PATH:/opt/local/bin If you are using Mac OS X 10.2 "Jaguar" or a C shell (tcsh), add the following line to your ~/.cshrc: set path=($path /opt/local/bin) These changes will not take effect until you have opened a new shell. If you upgraded your Mac OS X installation from 10.2, you might still have a C shell as login shell. Once you have got this far, you should have a working installation of MacPorts, you have installed the 'port' command (by default this installed as /opt/local/bin/port) and the libraries it needs (in /opt/local/share/macports and /Library/Tcl/macports1.0 by default.) New ports are always being added to the MacPorts mports tree, you should regularly update your tree to get access to new ports, and (hopefully) improved versions of current ports. Currently the simplest way you can update the mports tree is to use the selfupdate feature of port. To start a (rsync based) selfupdate, just issue port sync. Updating your port tool is equally easy to accomplish. If you are using at least version 1.0 of port, port selfupdate will update the sources of port, recompile and install them for you with the same options you installed your current version of port. Updating your MacPorts ports To get the latest Portfiles (the instructions for building ports), you need to update your mports tree via Updating your MacPorts infrastructure To get the latest MacPorts infrastructure (or "base") for building ports, you need to update your base via Using the MacPorts port command is very straight-forward. Most of the time all you need to do is execute a single command to install a port. For example, if you want to install the text editor vile, you would simply type: sudo port install vile That will fetch, build and install vile and anything else it needs to work. All of the examples below use the vile for as an example. You should use whatever port you actually want to install. The port command provides several other 'actions' that can be performed: Searching If you aren't sure the exact name of the port you want, you can use the search option. For example, if you wanted to find out if there was anything called vile in in the ports, you could do: port search 'vile' The search facility uses standard regular expression syntax, so you can also do much more complex searches. Additional Steps: fetch, configure, build, destroot, install You may want to break up the installation of a port into a number of steps. fetch, configure, build, destroot and finally install are all available and perform part of the build or install process. Using the steps individually is not normally needed unless you are developing a new port or trying to diagnose a problem. Cleaning a Port Once the port has been installed, you may want to delete all the intermediate files that MacPorts has created while building the port. To do this, simply use the clean option: port clean vile It is possible to make the clean option remove the distfile, the archive and the work directory. To remove the ports distfile port clean --dist vile To remove a archive created by a port port clean --archive vile To remove the working directory port clean --work vile or port clean vile If you want to do all of the above (remove the distfile and archive, and clean the workdirectory), you can: port clean --all vile Getting Information about a Port You may want to get information about a port, such as a description, its maintainer, and more. You can do this by using the info option: port info vim Listing available Ports You may want a list of all the ports that are available. You can do this two ways, first by using the search option: port search '.+' Or, by using the list option: port list Discovering which ports are installed To determine which ports have been installed, and what their versions are, use: port installed To determine the installed version of a particular port, use: port installed <portname> Discovering which ports are out-of-date To determine which ports are out-of-date (the current Portfile provides a newer version than the installed version of the port) use: port outdated Contents of a Port Once the port has been installed, you might want to check what files are associated with that port. The contents option will list all of the files that were installed by the port: port contents vile Variants and Dependencies Before you install a port, you may want to check what variations of that port are available to use. Variants provide additional configuration options for a port. To see what variations a port has, use the variants option: port variants vile You also may want to see what dependencies a port has. You can use the deps option to check: port deps vile If you want to find out which ports depends on a port you have installed, use: port dependents gettext For more information you should look at the port manpage by entering: man port. Most of the time you won't need to use this command as it is used to build the index of all the available ports, but sometimes the index you have is out of date or innacurate for some reason. When this occurs you will get an error message like 'port search failed: expected integer but got "PortIndex"'. You can fix problem by moving to the mports directory (/Users/mike/macports/mports in our examples) and executing: portindex. This will go through all the available ports in the mport directory and build an index file called PortIndex. Ports are removed using the port command described above, simply execute the command: sudo port uninstall vile You can check if a port is outdated with the following command: port outdated gnome To check if you have any outdated ports: port outdated To upgrade a port execute: sudo port upgrade gnome This will deactivate the old version and install the new, and also install the newer versions of the dependencies of the port. If you would like to upgrade the port, but not the dependencies of the port, you can: sudo port -n upgrade gnome To upgrade all installed ports simply do: sudo port upgrade installed If you dont like that upgrade just deactivates the old version of the port, you can get it to uninstall the old version by using the -u option: sudo port -u upgrade gnome Using force While upgrading you can run into cases when you have to use force (-f). This is especially true if you are upgrading a port that wants to install a file that another port allready has installed, or if you use the -u option to upgrade (and uninstall) a port that could be installed as a dependency. Allways remember to use the -f option with caution. There are a number of common problems so before you report a problem (details on how to report problems follow) check that the problem is described here, or in the FAQ first. This means your PortIndex file is incorrect or potentially corrupted, run the portindex command This means that the port your are trying to install wants to overwrite a file that is installed already. You can : Force activation by using -f like: sudo port -f activate vile remember to take caution when using force. Try to figure out why the conflict occurs and email the port maintainer a fix, or even better submit the fix to Trac. If the you have updated your ports tree, searched the macports-dev@lists.macosforge.org mailling list archives and read the common problems and the FAQ and you still can't find the answer to the problem, you should submit a bug report via Trac. The following section describes in some more detail how to use Trac to submit your port. Project: Make sure you select the MacPorts project. Component: Select "mports" as the component. Assigned to: Please assign updates, bug reports and comments on existing ports to the maintainer. Otherwise, if this is a new port or an RFC, please leave blank URL: You may use this field to point to the port output if it is available online. Summary: Please use this format BUG: portname-1.2.3 for the submission of port installation failures. Description: The description field should contain the following information as per the example given here here.