Building Joomla Extensions with Apache Ant

From Joomla! Documentation

This page will make an effort to provide a both consistent and flexible extensions structure, in addition to give a short explanation on how to use the included ant scripts to build and package extensions.

Extension structure

Component

NOT FINISHED

Module

NOT FINISHED

Plugin

NOT FINISHED

Template

NOT FINISHED

Environment

The build scripts depend on three environment variables, these values can either be set in the environment, you can tell your IDE to set them when running the script or as a last resort, you can edit common.xml and set them manually. Setting them manually is not recommended for projects with multiple participants or testing environments as the paths have to match.

SOURCEDIR

This is the absolute path to the Joomla installation you are testing the extension on

BUILDDIR

This is the path to a temporary directory used to build packages, can be a relative or an absolute path

RELEASEDIR

This is the folder in which to put the packaged extensions when script is invoked with the 'package' target

Build Targets

NOTE: The PREFIX property in the build targets has different meaning depending on the extension type, for plugins it is used to determine the plugin group, and for other types it is used to determine whether the extension is for the site or for the administrator. To make a build target with an admin extension set PREFIX to "administrator"

buildcomponent

The target to build a component takes the component name and prefix, prefix is either empty or "administrator" if we are building a component for the backend

Scripts

build.xml

This file is per project or per extension, whatever the user sees fit, it includes the common.xml file and specifies which extensions to build. You can have one build file per extension or you can use one build file to build many extensions. It is, however, preferable to have one build file for each extension named by the extension, so the build file for a helloworld component would be build_com_helloworld.xml or simply com_helloworld.xml. This is shown in the downloadable example packages.

common.xml

This is where the magic happens, this file contains build targets to build any module, plugin, template or component. You should normally not have to modify this file unless you need to manually set the environment variables or change the overall structure of an extension.

Example workflow

Local svn checkout of your extension repository containing extensions in a structure like the attached example

Run 'ant -f com_helloworld.xml package' which builds the extension in the specified release directory

Install the extension on Joomla test site

Use the test site project to develop the extension and debug it

When changes are made, run 'ant -f com_helloworld.xml build sync' to first build a temporary tree in the specified build folder, then the 'sync' target will synchronize the changes between the build directory and the extension directory in the repository

Inspect the changes and do a svn commit

Now you can either package the extension with the 'package target' or continue development on the test site until a new commit is to be made