This section contains practical guidelines for creating Portfiles that install smoothly and provide consistency between ports. The following sections are on the TODO list.
Portfiles may be thought of as a table of keys and values in two columns separated by spaces (not tabs), so you should set your editor to use soft tabs, which are tabs emulated by spaces. By default, the top line of all Portfiles should use a modeline that defines soft tabs for the vim and emacs editors as shown.
# -*- coding: utf-8; mode: tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:fenc=utf-8:ft=tcl:et:sw=4:ts=4:sts=4
The left column should consist of single words, and will be separated from the more complex right side by spaces in multiples of four. Variable assignments and variant declarations are exceptions, and may be considered a single word on the left side, with a single space between words.
set libver "8.5"
variant mysql5 { ... }Frequently multiple items are necessary in the second column. For
example, to set multiple source download locations, multiple
master_sites must be defined. Unless the second column
items are few and short you should place each additional item on a new
line and separate lines with a backslash. Indent the lines after the
first line to make it clear the items are second column values and also
to emphasize the unity of the block.
destroot.keepdirs ${destroot}${prefix}/var/run \
${destroot}${prefix}/var/log \
${destroot}${prefix}/var/cache/mrtgTODO: Set variables so changing paths may be done in one place; use them anytime it makes updates simpler: distname ${name}-src-${version}
If there is the need to replace a port with another port or a
renaming is necessary for some reason, the port should be marked as
replaced_by.
As an illustration of a typical workflow the port “skrooge-devel” shall be taken. This port had been used for testing new versions of skrooge, but it turned out to have become unnecessary due to the fact that skrooge's developers currently prefer a distribution via port “skrooge” instead.
At the end of this section the use of the obsolete PortGroup is suggested as an even shorter approach to the below described workflow.
Skrooge's original devel port file looked like this:
# -*- coding: utf-8; mode: tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4; truncate-lines: t -*- vim:fenc=utf-8:et:sw=4:ts=4:sts=4
# $Id$
PortSystem 1.0
PortGroup kde4 1.1
fetch.type svn
svn.url svn://anonsvn.kde.org/home/kde/trunk/extragear/office/skrooge
svn.revision 1215845
name skrooge-devel
version 0.8.0-${svn.revision}
categories kde finance
maintainers mk pixilla openmaintainer
description Skrooge
long_description Personal finance management tool for KDE4, with the aim of being highly intuitive, while \
providing powerful functions such as reporting (including graphics), persistent \
Undo/Redo, encryption, and much more...
conflicts skrooge
platforms darwin
license GPL-3
homepage http://skrooge.org
master_sites http://skrooge.org/files/
livecheck.type none
distname skrooge
depends_lib-append port:kdelibs4 \
port:libofx \
port:qca-ossl \
port:kdebase4-runtime \
port:oxygen-iconsThe following steps have to be taken to ensure a smooth transition
for a MacPorts user updating his local installation using
sudo port upgrade:
add the line replaced_by foo where foo is the
port this one is replaced by; when a user upgrades this port,
MacPorts will instead install the replacement port
replaced_by skrooge
increase the version, revision, or epoch, so that users who
have this port installed will get notice in port
outdated that they should upgrade it and trigger the above
process
revision 1
clear distfiles (have a line reading only
distfiles) so that no distfile is downloaded for this
stub port
distfiles
delete master_sites since there aren't any distfiles to download
disable livecheck
livecheck.type none
add a pre-configure block with a ui_error and
return -code error explaining to users who try to
install this port that the port has been replaced
pre-configure {
ui_error "Please do not install this port since it has been replaced by 'skrooge'."
return -code error
}With above modifications the port file eventually looks like this:
# -*- coding: utf-8; mode: tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4; truncate-lines: t -*- vim:fenc=utf-8:et:sw=4:ts=4:sts=4
# $Id$
PortSystem 1.0
name skrooge-devel
svn.revision 1215845
version 0.8.0-${svn.revision}
revision 1
replaced_by skrooge
categories kde finance
maintainers mk pixilla openmaintainer
description Skrooge
long_description Personal finance management tool for KDE4, with the aim of being highly intuitive, while \
providing powerful functions such as reporting (including graphics), persistent \
Undo/Redo, encryption, and much more...
platforms darwin
license GPL-3
homepage http://skrooge.org
livecheck.type none
pre-configure {
ui_error "Please do not install this port since it has been replaced by 'skrooge'."
return -code error
}
distfilesA user upgrading ports will experience the following for port “skrooge-devel”:
%%sudo port upgrade skrooge-devel
---> skrooge-devel is replaced by skrooge ---> Computing dependencies for skrooge ---> Fetching skrooge ---> Verifying checksum(s) for skrooge ---> Extracting skrooge ---> Configuring skrooge ---> Building skrooge ---> Staging skrooge into destroot ---> Deactivating skrooge-devel @0.8.0-1215845_0 ---> Cleaning skrooge-devel ---> Computing dependencies for skrooge ---> Installing skrooge @0.8.0.6_0 ---> Activating skrooge @0.8.0.6_0 ########################################################## # Don't forget that dbus needs to be started as the local # user (not with sudo) before any KDE programs will launch # To start it run the following command: # launchctl load /Library/LaunchAgents/org.freedesktop.dbus-session.plist ########################################################## ###################################################### # Programs will not start until you run the command # 'sudo chown -R $USER ~/Library/Preferences/KDE' # replacing $USER with your username. ###################################################### ---> Cleaning skrooge
In case a user actually tries to install the obsolete port “skrooge-devel” it would be pointed out by an error message that this is impossible now:
%%sudo port install skrooge-devel
---> Fetching skrooge-devel ---> Verifying checksum(s) for skrooge-devel ---> Extracting skrooge-devel ---> Configuring skrooge-devel Error: Please do not install this port since it has been replaced by 'skrooge'. Error: Target org.macports.configure returned: Log for skrooge-devel is at: /opt/local/var/macports/logs/_opt_local_var_macports_sources_rsync.macports.org_release_ports_kde_skrooge-devel/main.log Error: Status 1 encountered during processing. To report a bug, see <http://guide.macports.org/#project.tickets>
Using the PortGroup obsolete makes the task described in the previous subsection much easier:
# -*- coding: utf-8; mode: tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4; truncate-lines: t -*- vim:fenc=utf-8:et:sw=4:ts=4:sts=4
# $Id$
PortSystem 1.0
replaced_by skrooge
PortGroup obsolete 1.0
name skrooge-devel
svn.revision 1215845
version 0.8.0-${svn.revision}
revision 2The PortGroup defines a number of reasonable defaults for a port that is only
there to inform users that they should uninstall it and install something else
instead. You might want to override some of the defaults though. For details have
a look at the PortGroup's source code in
${prefix}/var/macports/sources/rsync.macports.org/release/ports/_resources/port1.0/group/obsolete-1.0.tcl.
If a port has to be removed from MacPorts one should consider the hints concerning replacing it by some alternative port given above. If there is no replacement for it, insert a pre-configure block as described there to alert the user about why the port is not allowed for installation anymore.
It is recommended to wait about a year before the port directory is actually being removed from MacPorts' Subversion repository.