TWiki on FreeBSD
Porting TWiki includes two challenges (among others) - modularity and upgradability.
Modularity
With a short www/twiki/bsd.twiki.mk it was easy to break TWiki distribution into a core package (www/twiki) and a number of modules (www/twiki-*). An infrastructure for further TWiki extensions is under development, but is ready for use as is.
Almost every TWiki extension is available from svn.twiki.org through anonymous access.
To create a new extension port, you can cd to www/twiki and execute make make-port name=PatternSkin:12345. A basic skeleton will be created in www/twiki-PatternSkin, svn will checkout revision 12345 of the extension, make a distfiles, put it in your _DISTDIR, generate Makefile, distinfo, pkg-descr and pkg-plist. Naturally, manual tuning is needed in most cases. cd to www/twiki-PatternSkin and run make twdep to see what other extensions and perl modules may be needed. The resulting lines can be pasted into the new Makefile.
An example extension port - www/twiki-TinyMCEPlugin:
PORTNAME= TinyMCEPlugin
SVNREV= 16650
COMMENT= TinyMCE WYSIWYG editor integration
TWDEP= BehaviourContrib>=15357 WysiwygPlugin>=16650
.include "${.CURDIR}/../twiki/bsd.twiki.mk"
.include <bsd.port.mk>TWDEP is translated into RUN_DEPENDS by bsd.twiki.mk. By default PORTVERSION is 0.0.SVNREV.
To update an extension you need to tweak SVNREV and then run make clean make-dist, move the new distfile from WRKDIR to _DISTDIR and run make makesum create-plist twdep. Verify dependencies have not changed, publish the distfile - and you're set.
Unbundling default extensions
The main TWiki 4.2.0 distfiles comes bundled with about 20 default extensions. Unfortunately, there's no easy way to unbundle them and building a customized distfile from SVN is more tricky than it can seem. As a temporary, but effective enough method, we scan all www/twiki-*/pkg-plist and remove all files referenced there from the bundle at post-extract. It really only takes a few seconds.
Alternatives
TWiki extensions can be upgraded via the configure script, but it poses security and administrative issues.
Upgrading TWiki
TWiki is one of those webapps, which are fully flat-file-based (with an RCS clutch). Using it often includes editing lots of files by hand. To avoid loosing information at every upgrade, the following scheme is used:
- twiki is installed into TWDIR, which is in PREFIX/share/twiki
- at post-install, files are copied from ther to WWWDIR in a non-overwriting fashion
- at pre-deinstall, files in WWWDIR are compared to the originals and removed only if there are no differences
The disadvantage of doing it this way is that hard drive space is wasted. The advantages are obvious. The user can always run diff -ru TWDIR WWWDIR to see the tweaks he made, or how the new version differs from what he's got. Debian went a similar way, but they keep the TWDIR stuff gzipped and limit it to the data parts.
Manual steps
Manual steps usually include merging the changes you made to your older TWiki installation through straightforward editing and lower level hacking and tuning:
- create diffs between vanilla distribution files and whatever you have
- upgrade twiki port
- inspect conflicting files
- back up the conflicting files that you have
- overwrite them with the new distribution files
- apply patches, adjusting as needed
None of these steps (except for the actual non-overwriting upgrade) has been automated. An approach similar to the mergemaster tool can be taken, but right now it all has to be done manually. Cracking this problem may show a way for dealing with text-based configuration and data files in other ports. Other systems, like Debian and Gentoo, have their solutions already in place.