<!-- DrJava Documentation Build Script -->
<!-- This build script is based on the template located at "trunk/misc/build-template.xml"
in the DrJava Subversion repository. In general, changes made to the script should be
reflected in the template as well. -->
<project name="docs" default="help">
<property name="readable-project-name" value="DrJava Documentation" />
<property name="svn-repository" value="https://svn.sourceforge.net/svnroot/drjava" />
<property environment="env" />
<property name="docbook-xsl-home" value="${env.DOCBOOK_XSL_HOME}" />
<!-- By default, clean can fail -->
<property name="clean-can-fail" value="yes" />
<!-- By default, don't append anything extra to the tag -->
<property name="tag-append" value="" />
<!-- Don't use or inherit the CLASSPATH environment variable for anything -->
<property name="build.sysclasspath" value="ignore" />
<fileset id="libs" dir="lib" includes="*.jar" /> <!-- Only include jars that are at the top level (not in buildlib) -->
<!-- ***********
Help Target
*********** -->
<target name="help" description="Print general build script information">
<echo message="--------------------------------------------------------------------" />
<echo message="${readable-project-name} Build Scripts" />
<echo message="--------------------------------------------------------------------" />
<echo message="Type 'ant -projecthelp' or 'ant -p' to see the list of targets." />
<echo message="" />
<echo message="For this build file to function properly, the following environment " />
<echo message="variables should be defined:" />
<echo message="DOCBOOK_XSL_HOME: Location of the DocBook XSL style sheets" />
<echo message="PATH: 'xsltproc' must be available; 'svn' needs to refer to the" />
<echo message=" Subversion client executable" />
<echo message="" />
<echo message="Ant may also require ANT_HOME to be set. Note that the value of " />
<echo message="CLASSPATH will be ignored -- classes on the system classpath will " />
<echo message="not be visible during the build process." />
</target>
<!-- ************
Build Target
************ -->
<target name="build" depends="doc-html, jar"
description="Shortcut for 'doc-html' and 'jar'">
</target>
<!-- ***********
Jar Targets
*********** -->
<target name="jar" depends="doc-html, resolve-version-tag"
description="Create the jar file with distributed docs (generating html docs first)">
<jar jarfile="${ant.project.name}.jar">
<manifest>
<attribute name="Built-By" value="${user.name}" />
<attribute name="Build-Version" value="${version-tag}" />
</manifest>
<zipfileset dir="docs" prefix="edu/rice/cs/drjava/docs" includes="user/**" />
<zipfileset dir="docs" prefix="edu/rice/cs/drjava/docs" includes="quickstart/**" />
<zipfileset dir="docs" prefix="edu/rice/cs/drjava/docs" includes="javaapi/**" />
</jar>
</target>
<!-- *********************
Documentation Targets
********************* -->
<target name="doc" depends="doc-html, doc-pdf" description="Shortcut for 'doc-html' and 'doc-pdf'">
</target>
<target name="doc-html" description="Generate all html documentation">
<echo message="Creating html documentation" />
<antcall target="generate-html">
<param name="docbook-dir" value="user" />
<param name="docbook-srcfile" value="userdoc" />
</antcall>
<antcall target="generate-html">
<param name="docbook-dir" value="quickstart" />
<param name="docbook-srcfile" value="quickstart" />
</antcall>
<antcall target="generate-html">
<param name="docbook-dir" value="developer" />
<param name="docbook-srcfile" value="devdoc" />
</antcall>
<antcall target="copy-resources" />
</target>
<target name="doc-pdf" description="Generate all pdf documentation">
<echo message="Creating pdf documentation" />
<antcall target="generate-pdf">
<param name="docbook-dir" value="user" />
<param name="docbook-srcfile" value="userdoc" />
</antcall>
<antcall target="generate-pdf">
<param name="docbook-dir" value="quickstart" />
<param name="docbook-srcfile" value="quickstart" />
</antcall>
<antcall target="generate-pdf">
<param name="docbook-dir" value="developer" />
<param name="docbook-srcfile" value="devdoc" />
</antcall>
</target>
<target name="doc-user" description="Generate user documentation (html and pdf)">
<echo message="Creating user documentation" />
<antcall target="generate-html">
<param name="docbook-dir" value="user" />
<param name="docbook-srcfile" value="userdoc" />
</antcall>
<antcall target="generate-pdf">
<param name="docbook-dir" value="user" />
<param name="docbook-srcfile" value="userdoc" />
</antcall>
<antcall target="copy-resources" />
</target>
<target name="doc-quickstart" description="Generate quickstart documentation (html and pdf)">
<echo message="Creating user documentation" />
<antcall target="generate-html">
<param name="docbook-dir" value="quickstart" />
<param name="docbook-srcfile" value="quickstart" />
</antcall>
<antcall target="generate-pdf">
<param name="docbook-dir" value="quickstart" />
<param name="docbook-srcfile" value="quickstart" />
</antcall>
<antcall target="copy-resources" />
</target>
<target name="doc-developer" description="Generate developer documentation (html and pdf)">
<echo message="Creating user documentation" />
<antcall target="generate-html">
<param name="docbook-dir" value="developer" />
<param name="docbook-srcfile" value="devdoc" />
</antcall>
<antcall target="generate-pdf">
<param name="docbook-dir" value="developer" />
<param name="docbook-srcfile" value="devdoc" />
</antcall>
<antcall target="copy-resources" />
</target>
<target name="generate-html" depends="assert-docbook-xsl-exists">
<mkdir dir="docs/${docbook-dir}" />
<exec executable="xsltproc" failonerror="yes" dir="src/${docbook-dir}">
<arg value="--stringparam" />
<!-- ignore image scaling in HTML to avoid bug
[ drjava-Bugs-2892129 ] Squished Images in Included Documentation
according to
http://www.sagehill.net/docbookxsl/ImageSizing.html#DiffImageSizes
and
http://www.sagehill.net/docbookxsl/Parameters.html#ParameterSyntax -->
<arg value="ignore.image.scaling" />
<arg value="1" />
<arg value="-o" />
<arg value="../../docs/${docbook-dir}/" />
<arg file="${docbook-xsl-home}/html/chunk.xsl" />
<arg file="src/${docbook-dir}/${docbook-srcfile}.docbook" />
</exec>
<!-- This should work and be platform-independent, but I can't get it to generate good output:
the built-in Java API version fails; xalan works but the index.html page is blank (no TOC)
<xslt style="${docbook-xsl-home}/html/chunk.xsl"
destdir="docs/${docbook-dir}" basedir="src/${docbook-dir}" includes="${docbook-srcfile}" />
-->
</target>
<target name="generate-pdf" depends="assert-docbook-xsl-exists">
<taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop">
<classpath>
<fileset dir="lib/buildlib">
<include name="*.jar"/>
</fileset>
</classpath>
</taskdef>
<mkdir dir="fo" />
<mkdir dir="docs" />
<exec executable="xsltproc" failonerror="yes" dir="src/${docbook-dir}">
<arg value="-o" />
<arg value="../../fo/${docbook-srcfile}.fo" />
<arg file="${docbook-xsl-home}/fo/docbook.xsl" />
<arg file="src/${docbook-dir}/${docbook-srcfile}.docbook" />
</exec>
<fop fofile="fo/${docbook-srcfile}.fo" outfile="docs/${docbook-srcfile}.pdf"
basedir="src/${docbook-dir}" />
</target>
<target name="copy-resources">
<copy todir="docs">
<fileset dir="src">
<include name="**/LICENSE" />
<include name="**/README" />
<include name="**/*.gif" />
<include name="**/*.png" />
<include name="**/*.jpg" />
<include name="**/*.jpeg" />
<include name="**/*.properties" />
<include name="**/*.html" />
<!-- Additional resource files should be listed here -->
</fileset>
</copy>
</target>
<!-- *************
Clean Targets
************* -->
<target name="clean" depends="clean-intermediate, clean-products"
description="Remove all build products; the result should match the intended Subversion contents">
</target>
<target name="clean-intermediate" unless="skip-clean">
<echo message="Deleting all intermediate build products" />
<delete dir="fo" failonerror="${clean-can-fail}" />
<delete includeemptydirs="true" failonerror="${clean-can-fail}">
<fileset dir="${basedir}" defaultexcludes="no">
<!-- We could get rid of backups, but "update" ignores them, so they're okay.
(doesn't work if defaultexcludes is "yes") -->
<!-- <include name="**/*~" /> -->
<!-- Get rid of pesky OS helper files (doesn't work if defaultexcludes is "yes") -->
<include name="**/.DS_Store" />
<include name="**/Thumbs.db" />
<!-- Additional files to delete may be listed here -->
</fileset>
</delete>
</target>
<target name="clean-products" unless="skip-clean">
<echo message="Deleting all final build products" />
<delete dir="docs" failonerror="${clean-can-fail}" />
<delete includeemptydirs="true" failonerror="${clean-can-fail}">
<fileset dir="${basedir}" defaultexcludes="no">
<include name="*.jar" />
<include name="*.zip" />
<include name="*.tar.gz" />
<include name="${ant.project.name}-*" />
</fileset>
</delete>
</target>
<!-- ******************
Subversion Targets
****************** -->
<target name="update" depends="clean" description="Reconcile source with the Subversion archive">
<echo message="Running Subversion update" />
<exec executable="svn" failonerror="yes">
<arg value="update" />
</exec>
<exec executable="svn" failonerror="yes">
<arg value="status" />
</exec>
</target>
<target name="commit" depends="update, build"
description="Commit source to the Subversion archive (after building)">
<antcall target="clean-intermediate"> <!-- Clean up after the latest build -->
<param name="clean-can-fail" value="no" />
</antcall>
<exec executable="svn" failonerror="yes">
<arg value="status" />
</exec>
<input message="Please enter a log message for the commit: "
addproperty="svn-commit-message" />
<echo message="Running Subversion commit" />
<exec executable="svn" failonerror="yes">
<arg value="commit" />
<arg value="-m" />
<arg value="${svn-commit-message}" />
</exec>
</target>
<target name="tag" depends="update, resolve-version-tag"
description="Copy the working copy to a new Subversion tag (after updating)">
<echo message="Creating a new Subversion tag with name ${version-tag}"/>
<exec executable="svn" failonerror="yes">
<arg value="copy" />
<arg value="${basedir}" />
<arg value="${svn-repository}/tags/${version-tag}" />
<arg value="-m" />
<arg value="Created tag ${version-tag}" />
</exec>
</target>
<target name="branch" depends="update"
description="Copy the working copy to a new Subversion branch (after updating)">
<echo message="This will create a new branch from your working copy. If there are changes " />
<echo message="in your copy that have not been committed, you may want to do so first, " />
<echo message="so that there's a clear branch point for merging later." />
<input message="Enter a name for the new branch: "
addproperty="svn-branch-name" />
<echo message="Creating a new Subversion branch ${svn-branch-name}" />
<exec executable="svn" failonerror="yes">
<arg value="copy" />
<arg value="${basedir}" />
<arg value="${svn-repository}/branches/${svn-branch-name}" />
<arg value="-m" />
<arg value="Created branch ${svn-branch-name}" />
</exec>
</target>
<!-- ***************
Release Targets
*************** -->
<target name="release-stable" description="Generate all release files tagged with 'stable'">
<antcall target="release">
<param name="tag-append" value="-stable" />
</antcall>
</target>
<target name="release-beta" description="Generate all release files tagged with 'beta'">
<antcall target="release">
<param name="tag-append" value="-beta" />
</antcall>
</target>
<target name="release"
depends="update, build, tag, jar-app, src-zip"
description="Generate all release files (after building)">
<delete dir="${version-tag}" />
</target>
<target name="jar-app" depends="assert-jar-exists, resolve-version-tag">
<echo message="Creating ${version-tag}.jar" />
<copy file="${ant.project.name}.jar" tofile="${version-tag}.jar" />
</target>
<target name="src-zip" depends="resolve-version-tag">
<echo message="Creating ${version-tag}-src.zip" />
<exec executable="svn" failonerror="yes">
<arg value="export" />
<arg value="${svn-repository}/tags/${version-tag}" />
<arg value="${version-tag}/src" />
</exec>
<zip destfile="${version-tag}-src.zip">
<zipfileset dir="${version-tag}/src" prefix="${version-tag}/src" />
</zip>
</target>
<!-- ********************************
Misc Occasionally-Useful Targets
******************************** -->
<patternset id="exclude-binaries">
<exclude name="**/*.jar" />
<exclude name="**/*.class" />
<exclude name="**/DrJava" />
<exclude name="**/*.png" />
<exclude name="**/*.icns" />
<exclude name="**/*.gif" />
<exclude name="**/*.jpg" />
<exclude name="**/*.jpeg" />
<!-- Additional binary types may be added here -->
</patternset>
<!-- Run a batch find-and-replace on all text files in the project.
Assumes the properties "find" and "replace" have been defined
(e.g. "ant -Dfind=foo -Dreplace=bar find-and-replace"). -->
<target name="find-and-replace">
<replace dir="${basedir}" token="${find}" value="${replace}" summary="yes">
<patternset refid="exclude-binaries" />
</replace>
</target>
<!-- Standardize all newline character sequences. Subversion takes care of this
automatically, but sometimes files crop up with the wrong sequence.
Use "svn status" after running this to see which files were fixed. -->
<target name="fix-newlines" description="Standardize newline character sequences in all text files">
<!-- If we're in Windows, use \r\n -->
<condition property="newline-code" value="crlf">
<os family="windows" />
</condition>
<!-- Otherwise, use \n -->
<property name="newline-code" value="lf" />
<fixcrlf srcdir="${basedir}" eol="${newline-code}" fixlast="no">
<patternset refid="exclude-binaries" />
</fixcrlf>
</target>
<!-- ***************************
Property-resolution Targets
*************************** -->
<target name="assert-docbook-xsl-exists">
<available property="docbook-xsl-exists" file="${docbook-xsl-home}/html/chunk.xsl" />
<fail message="${docbook-xsl-home}/html/chunk.xsl does not exist" unless="docbook-xsl-exists" />
</target>
<target name="assert-jar-exists">
<available property="jar-exists" file="${ant.project.name}.jar" />
<fail message="Can't find ${ant.project.name}.jar" unless="jar-exists" />
</target>
<target name="resolve-version-tag">
<!-- Get a timestamp based on GMT, rather than local time -->
<tstamp>
<format property="DSTAMP" pattern="yyyyMMdd" timezone="GMT" />
<format property="TSTAMP" pattern="HHmm" timezone="GMT" />
<format property="TODAY" pattern="MMMM dd yyyy" timezone="GMT" />
</tstamp>
<property name="version-tag"
value="${ant.project.name}${tag-append}-${DSTAMP}-${TSTAMP}" />
</target>
<!-- Sets "already-generated" if "generate-file" is more recent than "generate-sourcefile";
otherwise, the out-of-date target file is deleted (if it exists). Note that, since
properties can only be set once, this should happen underneath an "antcall". -->
<target name="check-generate-file-from-file">
<dependset>
<srcfilelist dir="${basedir}" files="${generate-sourcefile}" />
<targetfilelist dir="${basedir}" files="${generate-file}" />
</dependset>
<available file="${generate-file}" property="already-generated" />
</target>
<!-- Sets "already-generated" if "generate-file" is more recent than everything in
"generate-sourcedir"; otherwise, the out-of-date target file is deleted (if it exists).
Note that, since properties can only be set once, this should happen underneath an "antcall". -->
<target name="check-generate-file-from-dir">
<dependset>
<srcfileset dir="${generate-sourcedir}" />
<targetfilelist dir="${basedir}" files="${generate-file}" />
</dependset>
<available file="${generate-file}" property="already-generated" />
</target>
<!-- Sets "already-generated" if "generate-dir" was created (or modified) more recently
than "generate-sourcefile". Note that, since properties can only be set once, this
should happen underneath an "antcall". -->
<target name="check-generate-dir-from-file">
<uptodate property="already-generated" targetfile="${generate-dir}" srcfile="${generate-sourcefile}" />
</target>
<!-- Sets "already-generated" if "generate-dir" was created (or modified) more recently
than everything in "generate-sourcedir". Note that, since properties can only be
set once, this should happen underneath an "antcall". -->
<target name="check-generate-dir-from-dir">
<!-- Unfortunately, a bug in uptodate prevents this from working properly,
so we just have to equate *existence* with being up to date.
<uptodate property="already-generated" targetfile="${generate-dir}" >
<srcfiles dir="${generate-sourcedir}" />
</uptodate>
-->
<available file="${generate-dir}" property="already-generated" />
</target>
</project>
