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 set of declarations rather than a piece of code. It is best to format the port file is if it were a table consisting of keys and values. In fact, the simplest of ports will only contain a small block of values. Nicely formatted compact tables will result in more values being visible at the same time.
The two columns should be 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"
When items require multiple lines with line continuation, they can be separated from the previous and next items with a blank line. Indent the additional lines to the same column that the right side begins on in the first line.
checksums rmd160 7bbfce4fecc2a8e1ca081169e70c1a298ab1b75a \
sha256 2829fcb7393bac85925090b286b1f9c3cd3fbbf8e7f35796ef4131322509aa53 \
size 1061530Should a key item such as a phase or variant require braces, the opening brace should appear on the same line and the closing brace should be on its own line. The block formed by the braces is indented for visual clearance. Braces merely quoting strings, for example the description of variants, are placed on the same line without line breaks.
variant mysql5 description {Enable support for MySQL 5} {
depends_lib-append port:mysql5
configure.args-replace --without-mysql5 --with-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 -*- vim:fenc=utf-8:ft=tcl:et:sw=4:ts=4:sts=4
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 https://skrooge.org
master_sites https://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
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 -*- vim:fenc=utf-8:ft=tcl:et:sw=4:ts=4:sts=4
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 https://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 <https://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 -*- vim:fenc=utf-8:ft=tcl:et:sw=4:ts=4:sts=4
PortSystem 1.0
PortGroup obsolete 1.0
name skrooge-devel
replaced_by skrooge
svn.revision 1215845
version 0.8.0-${svn.revision}
revision 2
categories kde financeThe 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/macports/release/tarballs/ports/_resources/port1.0/group/obsolete-1.0.tcl.
replaced_by can be specified before or after the PortGroup line.
If a port has to be removed from MacPorts one should consider the hints concerning replacing it by some alternative port given above. It is recommended to wait one year before the port directory is actually removed from the MacPorts ports tree.
If there is no replacement for a port, it can simply be deleted immediately.