TWiki Developer Environment

Automates build process, including installer generation, for Pugins, Add-ons and Contrib modules.

Summary of Contents

Build & Install Modules

The Build.pm module can be used by developers to create a really simple build process for your plugin, addon or contrib module. The advantage of using this module is that it dictates a standard build procedure for plugins, so you won't get file names wrong or get the list of files in the plugin topic wrong either.

The module also automatically generates an installer script that manages dependencies in the user installation.

Development Model

The build module assumes:

• that you are not developing your plugin in a live TWiki installation (which is usually a really bad idea), but are instead doing the sensible thing and developing in a separate directory tree, usually - but not always - an SVN checkout area.
• that your module follows the standards for plugins and contribs i.e. that it
  1. has a topic in the data/TWiki directory
  2. has a perl module in the lib/TWiki/Plugins or lib/TWiki/Contrib directory
  3. has a sub-directory alongside the perl module that contains the extra .pm files specific to the module

The idea is that your module is built using a perl script build.pl that is kept in the module-specific subdirectory (3). This build script is like a Makefile. It has several targets that can be used to perform different stages of the development cycle. By default these targets are:

build	check that everything is perl
test	run unit tests
installer	Build an install/uninstall script for use by end-users
install	install on local installation defined by $TWIKI_HOME
uninstall	uninstall from local installation defined by $TWIKI_HOME
pod	build POD documentation
release	build, pod and package a release zip
upload	build, pod, package and upload to twiki.org
manifest	print a best-guess draft MANIFEST file
history	Updates the plugin/contrib topic with the history extracted from Subversion. See #HistoryTarget for more information.

The default target is test.

The module is designed so that most common behaviour is catered for. It is also easy to override any of the default targets in your build.pl and add extra behaviours.

The result of the 'release' target is a ZIP file, that will contain the following:

1. All the files listed in the MANIFEST
2. A generated documentation topic
3. An install/uninstall script, that is run after the module is unzipped

This zip file can be generated and subsequently uploaded to twiki.org, or you can simply use the upload target directly.

The easiest way to start using the module is to copy the build.pl file from lib/TWiki/Contrib/BuildContrib/build.pl into your own plugin or contrib, in the corresponding place i.e. copy it to lib/TWiki/Plugins/MyPlugin/build.pl or lib/TWiki/Contrib/MyContrib/build.pl. Then edit the file, and change as appropriate (it should be fairly obvious what you have to do). Then type

• perl build.pl manifest

This should inspect the directory structure and write a best-guess MANIFEST file.

Notes

• This is a build module for use by developers, not an install module for end users. When a release is built, an installer/uninstaller script is automatically generated that is packaged with the release. This simple script is the only part of the build system visible to end users
• This topic and all the embedded POD documentation are generated using this build module.
• The build environment does not assume the use of SVN, though it is highly recommended.
• The test target assumes you are using Test::Unit. Build.pm has only been tested on Linux, but should work with cygwin OK.

Install support

The installer script shipped with the package is very simple. By default all it does is to check the dependencies you list, and if necessary download and install any missing TWiki and CPAN modules. Other dependencies are simply checked. In Dakar and later releases, TWiki topics shipped with the module are automatically merged into any existing local copies, ensuring histories are preserved.

If you want your installer to do anything else - for example, optionally install submodules shipped with the module - then you will need to write a POSTINSTALL script. A good example of a POSTINSTALL can be found in the SVN tree for TWiki:Plugins/WysiwygPlugin.

Test Fixtures

The are a number of test fixtures in the repository that can be used for testing plugins with Test::Unit. The fixtures replace the TWiki::Func, TWiki::Store and TWiki modules, allowing a stand-alone unit test suite to be built for the plugin. The easiest way to use the fixtures is to copy the tests from an existing plugin that uses them - for example, Comment Plugin, Action Tracker Plugin, Web DAV Plugin or Form Query Plugin - and modify the tests appropriately for your plugin.

The fixtures do not replace all of the TWiki core functionality, just those pieces used by the plugins. If you find a piece is missing, and you need it, please feel free to extend the fixtures on condition that you check your improvements back in.

Support scripts

conformance_analyser.pl is a perl script that analyses the conformance of plugins to the API and packaging standards. It is driven from the zips downloadable from twiki.org.

Detailed Documentation

%$POD%

Settings

• Name of the perl package
  • Set STUB = %$STUB%
• One line description:
  • Set SHORTDESCRIPTION = Automate build process for Pugins, Add-ons and Contrib modules

Installation Instructions

You are strongly recommended to use this Contrib to help split your code development away from your live TWiki environment, as described above.

• Download the ZIP file from the Plugin web (see below)
• Unzip BuildContrib.zip in your development ($TWIKI_DEV) directory. Content:

  File:	Description:

%$MANIFEST%

• Optionally, run BuildContrib_installer.pl to automatically check and install other TWiki modules that this module depends on. You can also do this step manually.
• Alternatively, manually make sure the dependencies listed in the table below are resolved. %$DEPENDENCIES%

Contrib Info

Authors:	TWiki:Main.CrawfordCurrie
Copyright ©:	2004, Crawford Currie http://www.c-dot.co.uk
License:	GPL
Version:	%$VERSION%
Change History:
8947	Item1718 discovered that svn log doesn't work recursively, so more code required to find changes. Added new inline tokens for various UR Ls. Updated history to 8894.
8894	Item1718 added rel=nofollow to generated links to ~develop
8892	Item1718 Added history target to support extraction of history from SVN logs.
8585	Item1527 Build Contrib: Remember original filedates for pub files
8584	Item1527 Build Contrib: Oops, some (very few) plugins are not Action Tracker Plugin
8583	Item1527 Generated install scripts now really attaches files in pub to topics (means less of these couldn't update history error messages)
8581	Item1527 Build Contrib: Execute topic saves in the TWiki web as T Wiki Admin Group? by default
8365	Item1347 made build.pl tidy up it's mess; and switched buildcontrib over to using push and pop on dirs instead of cd, so we don;t get lost so easily. Oh, and corrected the permissions on the generated viewauth and rdiffauth files
8359	Item1393 For release topic name, removed upper case change of suffix. E.g. 'TWiki-4.0.0-beta6' becomes 'TWikiRelease04x00x00beta06'
8346	Item1393 added final parameter to build.pl (release name) and added processing to derive topic name from release id.
8263	Item663 fixing typos, etc
8217	Item1374 Build Contrib wasn't deleting its temporary files staging area
8216	Item663 fixing formatting/typos
8209	Item1347 changes to support arbitrary release naming, to better support TWiki builds. Should not affect extension builds.
8061	Item1285 Removed TWiki_installer.pl from release package
7531	Item956 skins have their MANIFEST in lib/TWiki/Contrib/...Skin/
7215	Item437 Build.pm reverted - sorry people, it seems this broke the build
7207	Item437 Revised Build Contrib to build MD5s. Crawford - feel free to ditch anything you don't like. (I sent you email about this a couple of days ago). MD5 files are generated for each package and then aggregated during a hands-off install to collect all dependent MD5s into package/DEPS.md5
6827	Item569 added default RELEASE to everything that had a version, and removed a load of dead code that was getting in the way
6791	Item598 removed comment that was getting added to txt files outside data
6759	Item569 computed version numbers for plugins from the repository rev they were built from.
6757	Item559 fixed permissions
6743	Item562 added ability to update VERSIOn number to current repository head
6742	Item561 added a script to build and upload all the plugins, so we can have releases of them from SVN. Presently uploaded to the same topic as the beta releases.
6515	Item432 applied the final polish (I hope) before beta release
6512	Item437 generated md5 sums for packages built using build.pl, and added them to the upload
6504	Item436 incremented vernos of all changed plugins
6470	Item421 polishing up installation, trying to catch gotchas, improving docs
6450	Item143 more apache warnings; and a silly error in comment plugin tests eliminated
6426	Item404 removed CHANGELOG from MANIFEST and added build scripts for all plugins and contribs, so they can be used with the main build.
6369	Item384 As excellent as Antonio's solution is, it breaks all the save script tests and is incompatible with previous releases. Need to fall back on the old 'action' parameter if the new parameters are not available - even though it is really bad news (it blocks the use of 'action' as a form-field name :-(. Also updated the script documentation for Antonio's changes.
6353	Item380 do as the man says; make all $/ local
6240	Item196 Extracted the Manifest File processing from Build.pm to a module that can be used by other Build implementations. Needed for a Command Set of T Wiki Shell Contrib
6092	Item196 more plugin and contrib fixes for develop; mainly just moving tests around and making sure they all pass.
6077	Item243 simplified gendocs to stop it generating ,v files, since Sven is going to solve that. Coorected MANIFEST for source code documents.
6076	Item243 added build scripts for all plugins shipped with T Wiki For Generic Use?
6068	Item244 extracted target_stage and target_archive from target_release to allow me to add functionality to target_stage
6051	Item237 removed requirement to set TWIKI_LIBS for core build
6040	Item237 now supports automatic instantiation of plugins and contribs in the release tree. Install scripts are not run.
6039	Item237 MANIFEST build based on Build Contrib. Very few extensions to Build Contrib were required to do it. Things that are missing are: 1. generation of ,v files 2. packaging up and inclusion of plugins.
6026	Item229 added support for sub-headings in configure. Added support for adding comments to Local Site?.cfg to Build Contrib. Can now create sections in configure for individual plugins.
5960	Item181 new version, supports DEVELOP and Cairo, and adds support for attachments (you can now mail attachments to topics)

Related Topics: T Wiki Preferences

-- TWiki:Main/CrawfordCurrie - %$DATE%
-- TWiki:Main/MartinCleaver - %$DATE%