Joomla Ant build files

From Joomla! Documentation

Revision as of 09:20, 10 August 2012 by E-builds (Talk | contribs)


When software projects become large its is often helpful for developers to create build or make file that assists the developer to quickly "compile" new code. Although designed for Java the Apache Ant system can be used to create build files for Joomla developers, it is especially useful because it is installed by default in Eclipse, which is an IDE often used by Joomla! extension developers. Creating an Ant build file for your projects will greatly expedite the following frequent tasks.

Common tasks that can be scripted by an Ant build file

  1. Creating accurate xml manifest file lists
  2. Generating new Joomla install archives
  3. Updating development/debug server files
  4. Uploading new archives to release sites

Installing Ant

Ant is high portable software and can be installed on most systems. Please follow the instructions on the Apache Ant homepage. As mentioned previously if you are working in Eclipse Ant is installed by default.

For those who have Eclipse PDT Ganymede without ANT, should download the Java Development Tools (JDT) plugin. The JDT plugin could be downloaded by clicking Help > Software Updates > Ganymede Update Site > Java Development > Eclipse Java Development Tool and then Install button at right hand. Once its downloaded, restart Eclipse and then verify if ANT is properly installed by clicking Window > Preferences. If you see ANT (under General), it means ANT is successfully installed over Eclipse.

If Eclipse complain something like "No grammar constraints (DTD or XML schema) detected for the document.", then you will need to add minimal DTD. For example; <!DOCTYPE project> reference

Example Build File

<?xml version="1.0" encoding="UTF-8"?>
<project name="uncleocho" default="build" basedir=".">
	<description>Ant Build File for Joomla by Evan Fillman (mole84)</description>
	<!-- load variables from config file -->
	<property name="cfg.configFile" location="antconfig.txt" />
	<loadproperties srcfile="${cfg.configFile}" />
	<!--config file values
	<!-- auto values but should be checked -->
	<property name="cfg.comName" value="com_${}" />
	<property name="cfg.comDir" value="${basedir}/${cfg.versionDir}/${cfg.comName}" />
	<property name="cfg.buildVersionDir" value="${cfg.buildDir}/${cfg.versionDir}" />
	<property name="cfg.adminFilesDir" location="${cfg.comDir}/admin" />
	<property name="cfg.siteFilesDir" location="${cfg.comDir}/site" />
	<property name="cfg.extensionsDir" location="${cfg.adminFilesDir}/extensions" />
	<target name="build" depends="clean, init, build_component, info" />
	<target name="init" description="creates nessecary directory to build with">
		<mkdir dir="${cfg.buildVersionDir}" />
		<mkdir dir="${cfg.buildVersionDir}/plugins" />
		<mkdir dir="${cfg.buildVersionDir}/modules" />
		<mkdir dir="${cfg.buildVersionDir}/components" />
		<mkdir dir="${cfg.extensionsDir}" />
	<target name="build_component" depends="update_extensions" description="packages the finaly component file">
		<zip destfile="${cfg.buildVersionDir}/components/${cfg.comName}.zip" basedir="${cfg.comDir}" />
	<target name="build_plugins" description="packages any plugins">
		<!-- add all plugin directories here -->
		<zip destfile="${cfg.buildVersionDir}/plugins/" basedir="${cfg.versionDir}/plg_uncleocho" />
	<target name="build_modules" description="packages any modules">
		<!-- add all module directories here -->
		<zip destfile="${cfg.buildVersionDir}/modules/" basedir="${cfg.versionDir}/mod_uncleocho" />
	<target name="build_debug" description="builds any debug plugins or code">
		<zip destfile="${cfg.buildVersionDir}/plugins/" basedir="${cfg.versionDir}/billets_plugin_toolbox" />
		<zip destfile="${cfg.buildVersionDir}/plugins/" basedir="${cfg.versionDir}/billets_plugin_debug" />
	<target name="update_extensions" depends="build_plugins, build_modules" description="copies fresh builds of plugins and extensions to the admin/extensions folder">
		<copy todir="${cfg.extensionsDir}" overwrite="true">
			<fileset dir="${cfg.buildVersionDir}/plugins" />
		<copy todir="${cfg.extensionsDir}" overwrite="true">
			<fileset dir="${cfg.buildVersionDir}/modules" />
	<target name="info" description="prints information">
		<echo message="Project:			${}" />
			<format property="buildtime" pattern="yyyy-MM-dd'T'HH:mm:ss" />
		<echo message="Buildtime:	${buildtime}" />
	<target name="clean" description="Destroys all generated files and dirs.">
		<delete dir="${cfg.buildVersionDir}" />
		<delete dir="packages" />
		<delete dir="${cfg.extensionsDir}" />
		<delete file="${cfg.xmlfile}" />
	<target name="update_localhost" depends="info" description="attemps to update files on localhost server with files from working directory">
		<copy todir="${cfg.localhostRoot}/administrator/components/${cfg.comName}" overwrite="true">
			<fileset dir="${cfg.adminFilesDir}" />
		<copy todir="${cfg.localhostRoot}/components/${cfg.comName}" overwrite="true">
			<fileset dir="${cfg.siteFilesDir}" />
	<target name="upload" description="attempts to upload build file to ftp server">
		<fileset id="ftp.upload.fileset" dir="${cfg.buildVersionDir}/components">
			<include name="*.zip" />
		<echo>FTP target is ${ftp.server}</echo>
		<ftp server="${ftp.server}" userid="${ftp.user}" password="${ftp.password}" action="put" remotedir="${ftp.dir}">
			<fileset refid="ftp.upload.fileset" />
	<target name="build_xml" description="builds an xml listing of all the files in the working copy">
		<fileset id="site" dir="${cfg.siteFilesDir}" />
		<echo message="${line.separator}&lt;files folder=&quot;site&quot;&gt;${line.separator}&lt;filename&gt;" file="${cfg.xmlfile}" append="false" />
		<echo-fileset filesetref="site" />
		<echo message="&lt;/filename&gt;${line.separator}&lt;/files&gt;${line.separator}" file="${cfg.xmlfile}" append="true" />
		<fileset id="admin" dir="${cfg.adminFilesDir}" />
		<echo message="${line.separator}&lt;files folder=&quot;admin&quot;&gt;${line.separator}&lt;filename&gt;" file="${cfg.xmlfile}" append="true" />
		<echo-fileset filesetref="admin" />
		<echo message="&lt;/filename&gt;${line.separator}&lt;/files&gt;${line.separator}" file="${cfg.xmlfile}" append="true" />
		<replace file="${cfg.xmlfile}" token="${cfg.siteFilesDir}/" value="" />
		<replace file="${cfg.xmlfile}" token="${cfg.adminFilesDir}/" value="" />
	<macrodef name="echo-fileset" description="creates a printable directory listing">
		<attribute name="filesetref" />
			<pathconvert pathsep="&lt;/filename&gt;${line.separator}&lt;filename&gt;" property="@{filesetref}.echopath">
					<fileset refid="@{filesetref}" />
			<echo message="${@{filesetref}.echopath}" file="${cfg.xmlfile}" append="true" />

Config File to Accompany Build File