<?xml version="1.0"?>

<!--
 !   TTOOLS build file
 !
 !   This file describes how to build and install TTOOLS
 !   from a source and binary release. TTOOLS is an application
 !   package, i.e. provides user-level commands and interfaces, as
 !   well as an optional programming API.
 !
 !   The main targets are:
 !
 !      build            -> compiles the source code
 !      clean            -> cleans up build and dist products
 !      deinstall        -> undo the install target
 !      dist             -> creates the local binary distribution
 !      export           -> creates the full distribution archives
 !      export-runonly   -> creates the runonly distribution archives
 !      export-source    -> creates the source distribution archives
 !      install          -> installs the distribution
 !      install-runonly  -> installs a runonly distribution
 !      jars             -> creates the package jar file(s)
 !      javadocs         -> creates the package API documentation
 !      javadoc-sources  -> make source files for release API documention
 !      test             -> runs JUnit test cases
 !
 !   Targets specific to TTOOLS:
 !      plot2-examples   -> writes example plot images
 !      build-standalone -> builds stilts.jar
 !      docs-pdf         -> builds sun256.pdf
 !
 !   Authors:
 !      Peter W. Draper (17-SEP-2002)
 !
 !   Version:
 !      $Id$
 !
 !-->

<project name="Build file for TTOOLS" default="build" basedir=".">
  <!-- Properties will also be set for all environment variables
   !   (PATH becomes "env.PATH"), generally not a good
   !   idea as names are OS dependent -->
  <property environment="env"/>

  <!--
   !  =================
   !  Global Properties
   !  =================
   !-->

  <!-- Directory for the Starlink installation (usually /star/java)-->
  <property name="star.dir" value="/usr/share/java"/>

  <!-- Directory to install into (install target, usually /star/java)-->
  <property name="star.install" value="${star.dir}"/>

  <!-- Directory that contains the Starlink jar tree -->
  <property name="star.jar.dir" value="${star.dir}"/>

  <!-- Directory that contains the locally built sources (usually
   !   /star/java/source for full distribution) -->
  <property name="star.build.dir" value="${basedir}/../"/>

  <!-- Directory that any archives should be placed into. The local
   !   directory by default -->
  <property name="star.archive.dir" value="${basedir}"/>

  <!-- URL and package-list for linking against full Java docs -->
  <property name="javaapi.url" value="https://docs.oracle.com/javase/8/docs/api/"/>
  <property name="javaapi.lis" value="${star.build.dir}/src/docs/javaapi/"/>

  <!--
   !  ================
   !  Local Properties
   !  ================
   !-->

  <!-- Define the package name and current versions -->
  <property name="Name" value="Starjava TTOOLS"/>
  <property name="name" value="starlink-ttools"/>
  <property name="version" value="3.5.2"/>

  <!-- The Java package name -->
  <property name="package.name" value="uk.ac.starlink.ttools"/>

  <!-- Compilation options -->
  <property name="debug" value="true"/>
  <property name="deprecation" value="true"/>
  <property name="optimize" value="true"/>
  <property name="source.version" value="1.8"/>

  <!-- Extra task options, if any -->
  <property name="chmod.fail" value="false"/>

  <!-- JUnit test options -->
  <property name="junit.fork" value="true"/>
  <property name="junit.filtertrace" value="on"/>
  <property name="junit.summary" value="no"/>
  <property name="junit.assertions" value="-enableassertions"/>

  <!-- Local directory and remote URL containing example plot data files.
   !   Note you can override these using system properties -
   !   it may be a good idea to reset plot2.figdata.dir to some
   !   external directory if you have multiple starjava builds. -->
  <property name="plot2.figdata.dir"
            value="${basedir}/plot2data/"/>
  <property name="plot2.figdata.url"
            value="http://www.starlink.ac.uk/stilts/plot2data/"/>

  <!-- Directory containing the package source -->
  <property name="src.dir" value="${basedir}/src"/>

  <!-- Directory containing the java source (top of the namespace)-->
  <property name="java.dir" value="${src.dir}/main"/>

  <!-- Directory containing miscellaneous docs -->
  <property name="src.docs" value="${src.dir}/docs"/>
  <property name="src.docs.examp" value="${src.docs}/examp"/>
  <property name="user.doc" value="sun256"/>
  <property name="coverimage" value="ttools2.png"/>
  <property name="xdoc.etc" value="${src.dir}/etc/xdoc"/>

  <!-- Directory containing any script required to execute or setup package-->
  <property name="script.dir" value="${src.dir}/script"/>

  <!-- Directory containing any third-party jars that should be
   !   distributed (normally these would belong in a proper package)-->
  <property name="src.jars.dir" value="${src.dir}/lib"/>

  <!-- Directory containing any JNI source code -->
  <property name="src.jni.dir" value="${src.dir}/jni"/>

  <!-- Directory containing files downloaded at build time. -->
  <property name="src.downloads.dir" value="${src.dir}/downloads"/>

  <!-- Directories for JUnit test cases and related files -->
  <property name="tests.dir" value="${src.dir}/testcases"/>
  <property name="tests.etc.dir" value="${src.dir}/etc/testcases"/>

  <!-- File types that should not be passed through a filterchain when
   !   copying -->
  <property name="unfiltered.files"
            value="**/*.gif,**/*.jpg,**/*.jpeg,**/*.ico,**/*.png,**/*.eps*"/>

  <!-- Directories to receive the various build components -->
  <property name="build.dir" value="${basedir}/build"/>
  <property name="build.classes" value="${build.dir}/classes"/>
  <property name="build.javadocs" value="${build.dir}/javadocs"/>
  <property name="build.docs" value="${build.dir}/docs"/>
  <property name="build.java" value="${build.dir}/java"/>
  <property name="build.etc" value="${build.dir}/etc"/>
  <property name="build.tests" value="${build.dir}/testcases"/>
  <property name="build.tests.javadocs" value="${build.dir}/javadocs.test/"/>

  <!-- Distribution directories, these are created in the current
   !   directory, unless dist.dir is redefined. Files that will be
   !   installed under a package name prefixed directory should be
   !   placed in the ".pkg" variants. Note some build components may
   !   be placed directly here for efficiency-->
  <property name="dist.dir" value="${basedir}"/>
  <property name="dist.bin" value="${dist.dir}/bin"/>
  <property name="dist.lib" value="${dist.dir}/lib"/>
  <property name="dist.src" value="${dist.dir}/src"/>
  <property name="dist.docs" value="${dist.dir}/docs"/>
  <property name="dist.etc" value="${dist.dir}/etc"/>

  <property name="dist.bin.pkg" value="${dist.bin}"/>
  <property name="dist.lib.pkg" value="${dist.lib}/${name}"/>
  <property name="dist.docs.pkg" value="${dist.docs}/${name}"/>
  <property name="dist.etc.pkg" value="${dist.etc}/${name}"/>
  <property name="dist.javadocs" value="${dist.docs}/${name}/javadocs"/>

  <!-- Version for zipped/tarred export files. -->
  <property name="dist.version" value="${name}-${version}"/>

  <!-- File for logging the files that are copied by the install target -->
  <property name="install.log" value=".${name}.install"/>
  <property name="install.overwrite" value="true"/>

  <!-- Local webstart properties. Note this needs a local keystore,
   !   assumed to be called keystore in $star.build.dir, .. by
   !   default. -->
  <property name="webstart.codebase"
           value="http://starlink.jach.hawaii.edu/starjava/lib"/>
  <property name="webstart.alias" value="Starlink-UK"/>
  <property name="webstart.keystore" value="${star.build.dir}/keystore"/>
  <property name="webstart.keypass" value="Vroomfondel"/>
  <property name="webstart.storepass" value="Majikthise"/>
  <property name="webstart.starlink_logo" value="starlink_logo_med.gif"/>
  <property name="home.page" value="http://www.starlink.ac.uk/${name}"/>

  <!-- Doclet base class used for generating XML and HTML user-facing docs
   !   from classes in uk.ac.starlink.ttools.func.
   !   At Java 8, SunDoclet, based on com.sun.doclet API is required.
   !   The com.sun.doclet API is deprecated at Java 9 and withdrawn at Java 17; 
   !   from Java 9, JdkDoclet, based on jdk.doclet.javadoc API can be used
   !   instead. -->
  <condition property="jdk.isv8">
    <contains string="${java.specification.version}" substring="1.8"/>
  </condition>
  <condition property="jel.doclet"
             value="uk.ac.starlink.ttools.build.SunDoclet"
             else="uk.ac.starlink.ttools.build.JdkDoclet">
    <isset property="jdk.isv8"/>
  </condition>
  <condition property="src.excludes"
             value="uk/ac/starlink/ttools/build/JdkDoclet.java"
             else="uk/ac/starlink/ttools/build/SunDoclet.java">
    <isset property="jdk.isv8"/>
  </condition>

  <!--
   !   =========
   !   CLASSPATH
   !   =========
   !-->

  <!-- Installed jar files.
   !
   !   Name all the installed jar files of other packages that we depend on.
   !
   !   When compiling under Java 1.4 these will be used to produce a full
   !   classpath that is equivalent to that generated when these are
   !   referenced as optional bundled packages by the JVM.
   !   When compiling under Java 1.5 (and probably later) this is just
   !   a simple path of these jar files, as the expansion to a full optional
   !   bundled package classpath is performed by the compiler
   !
   !   What that all means is that the manifest classpaths of these jar files
   !   are honoured, the plain compiler pre Java 1.5 didn't do that. When Java
   !   1.4 is no longer used the extclasspath type can be replaced by a simple
   !   path.
   !-->
  <path id="installed.classpath">
    <pathelement location="${star.jar.dir}/starlink-util.jar"/>
    <pathelement location="${star.jar.dir}/starlink-table.jar"/>
    <pathelement location="${star.jar.dir}/starlink-tjoin.jar"/>
    <pathelement location="${star.jar.dir}/starlink-fits.jar"/>
    <pathelement location="${star.jar.dir}/starlink-votable.jar"/>
    <pathelement location="${star.jar.dir}/starlink-pal.jar"/>
    <pathelement location="${star.jar.dir}/starlink-registry.jar"/>
    <pathelement location="${star.jar.dir}/starlink-vo.jar"/>
    <pathelement location="${star.jar.dir}/starlink-task.jar"/>
    <pathelement location="${star.jar.dir}/starlink-tfcat.jar"/>
    <pathelement location="${star.jar.dir}/starlink-dpac.jar"/>
    <pathelement location="${star.jar.dir}/jel.jar"/>
    <pathelement location="${star.jar.dir}/adql.jar"/>
    <pathelement location="${star.jar.dir}/jsamp.jar"/>
    <pathelement location="${star.jar.dir}/fits.jar"/>
    <pathelement location="${star.jar.dir}/cds.moc.jar"/>
    <pathelement location="${star.jar.dir}/eag-healpix.jar"/>
    <pathelement location="${star.jar.dir}/skyview.jar"/>
    <pathelement location="${star.jar.dir}/itext.jar"/>
    <pathelement location="${star.jar.dir}/net.sourceforge.jlibeps.jar"/>
    <pathelement location="${star.jar.dir}/jlatexmath.jar"/>
    <pathelement location="${star.jar.dir}/jide-oss.jar"/>
    <pathelement location="${star.jar.dir}/json.jar"/>
    <pathelement location="${star.jar.dir}/commons-io.jar"/>
    <pathelement location="${star.jar.dir}/org.jfree.svg.jar"/>
    <pathelement location="${star.jar.dir}/servlet-api.jar"/>
    <pathelement location="/usr/lib/jvm/default-java/lib/tools.jar"/>
  </path>

  <path id="jar.classpath">
    <pathelement location="${dist.lib.pkg}/starlink-util.jar"/>
    <pathelement location="${dist.lib.pkg}/starlink-table.jar"/>
    <pathelement location="${dist.lib.pkg}/starlink-tjoin.jar"/>
    <pathelement location="${dist.lib.pkg}/starlink-fits.jar"/>
    <pathelement location="${dist.lib.pkg}/starlink-votable.jar"/>
    <pathelement location="${dist.lib.pkg}/starlink-pal.jar"/>
    <pathelement location="${dist.lib.pkg}/starlink-registry.jar"/>
    <pathelement location="${dist.lib.pkg}/starlink-vo.jar"/>
    <pathelement location="${dist.lib.pkg}/starlink-task.jar"/>
    <pathelement location="${dist.lib.pkg}/starlink-tfcat.jar"/>
    <pathelement location="${dist.lib.pkg}/starlink-topcat.jar"/>
    <pathelement location="${dist.lib.pkg}/starlink-dpac.jar"/>
    <pathelement location="${dist.lib.pkg}/jel.jar"/>
    <pathelement location="${dist.lib.pkg}/adql.jar"/>
    <pathelement location="${dist.lib.pkg}/jsamp.jar"/>
    <pathelement location="${dist.lib.pkg}/fits.jar"/>
    <pathelement location="${dist.lib.pkg}/cds.moc.jar"/>
    <pathelement location="${dist.lib.pkg}/eag-healpix.jar"/>
    <pathelement location="${dist.lib.pkg}/skyview.jar"/>
    <pathelement location="${dist.lib.pkg}/itext.jar"/>
    <pathelement location="${dist.lib.pkg}/net.sourceforge.jlibeps.jar"/>
    <pathelement location="${dist.lib.pkg}/jlatexmath.jar"/>
    <pathelement location="${dist.lib.pkg}/jide-oss.jar"/>
    <pathelement location="${dist.lib.pkg}/json.jar"/>
    <pathelement location="${dist.lib.pkg}/commons-io.jar"/>
    <pathelement location="${dist.lib.pkg}/org.jfree.svg.jar"/>
    <pathelement location="${dist.lib.pkg}/servlet-api.jar"/>
  </path>

  <!-- Local build system jar files.
   !
   !   Name all the jar files of other packages that we depend on, which have
   !   not been installed (should be same packages as in installed.classpath).
   !-->
  <path id="built.jarpath"/>

  <!-- Find all local third party jars files.
   !
   !   Normally these will be kept in their own third party package, but may
   !   be kept here temporarily, say if there are version conflicts that
   !   cannot be addressed. They are installed with the package jar files and
   !   should be entered into the main jar file manifest.
   !-->
  <mkdir dir="${src.jars.dir}"/>
  <path id="package.jars">
     <fileset dir="${src.jars.dir}">
        <include name="*.jar"/>
     </fileset>
  </path>

  <!-- Create the local build system CLASSPATH.
   !
   !   Create the classpath used when building this package as part of a full
   !   build system without any dependency on any installed or external jar
   !   files.
   !
   !   Classes compiled in the local build tree will be in the "build/classes"
   !   part of each package. Third party packages, have do not have any source
   !   code, just jar files, will have their jar files in their "dist"
   !   directories (usually lib/{package_name}).
   !
   !   So the full built classpath is created by constructing a path
   !   consisting of:
   !
   !      - all third party jar files in this package
   !      - all build/classes directories in the local build system (these
   !        will have the most recent class files)
   !      - all jar files named in built.jarpath, i.e. named local build
   !        system jar files (these can be normal packages in the "dist" state
   !        or third party packages)
   !      - all jar files in the "dist" directories of all packages in the
   !        local build system (these are necessary to make sure that the jar
   !        files in the previous part have their dependencies fulfilled,
   !        without having them all installed)
   !-->
  <path id="built.classpath">

    <!-- Third party jars held by this package -->
    <path refid="package.jars"/>

    <!-- All classes in the local build system -->
    <dirset dir="${star.build.dir}">
      <include name="*/build/classes"/>
    </dirset>

    <!-- Directly dependent jars in the local build system -->
    <path refid="built.jarpath"/>

    <!-- All "dist" jar files to make sure everything is resolved, including
     !   relative URLs of the local packages, without installation -->
    <fileset dir="${star.build.dir}">
      <include name="*/lib/*/*.jar"/>
    </fileset>

  </path>

  <!-- User-defined CLASSPATH.
   !
   !   This is set by the property "extra.class.path" (which can be defined
   !   locally using say -Dextra.class.path=$CLASSPATH on the command line
   !   or by setting the property in either of the properties files.-->
  <property name="extra.class.path" value=""/>
  <path id="local.classpath" path="${extra.class.path}"/>

  <!-- Create the full CLASSPATH used during compilation.
   !
   !   This is created from the user-defined classpath, followed by the
   !   classpath for building against the local system, followed by the
   !   classpath for building against an installed system.
   !-->
  <path id="classpath">
     <path refid="local.classpath"/>
     <path refid="built.classpath"/>
     <path refid="installed.classpath"/>
  </path>

  <!-- Create the JUnit tests CLASSPATH.
   !
   !   Note that in addition to the build/classes and build/tests directory
   !   we also add tests.dir and tests.etc.dir so that resources may be
   !   located there. The full classpath is also used.
   !-->
 <path id="tests-classpath">
    <pathelement location="${star.jar.dir}/junit.jar"/>
    <pathelement location="${star.jar.dir}/healpix.jar"/>
    <pathelement location="${star.jar.dir}/jython.jar"/>
    <pathelement location="${build.classes}"/>
    <pathelement location="${build.tests}"/>
    <pathelement location="${tests.dir}"/>
    <pathelement location="${tests.etc.dir}"/>
    <pathelement location="${build.etc}"/>
    <path refid="classpath"/>
    <pathelement location="${star.jar.dir}/${name}.jar"/>
  </path>

  <!-- Turn this path into a string which is passed to the tests -->
  <property name="tests-classpath.value" refid="tests-classpath"/>

  <!--
   !    ============
   !    Library path
   !    ============
   !    Used by test targets for locating native libraries.
   !-->
  <path id="tests-libpath.id">
    <pathelement path="${java.library.path}"/>
    <pathelement location="${star.jar.dir}/${os.arch}"/>
  </path>
  <property name="tests-libpath" refid="tests-libpath.id"/>

  <!--
   !    =========================================
   !    Check availability of direct dependencies
   !    =========================================
   !
   !    Minimalist check of the required dependencies so that the build will
   !    not proceed if some basic dependencies are not present on the
   !    classpath. Optional components could also be checked here.
   !-->
  <target name="check_packages"
          unless="runonly.install">

    <!-- UTIL -->
    <available property="util.present"
               classpathref="classpath"
               classname="uk.ac.starlink.util.DataSource"/>
    <fail message="No UTIL available" unless="util.present"/>

    <!-- TABLE -->
    <available property="table.present"
               classpathref="classpath"
               classname="uk.ac.starlink.table.StarTable"/>
    <fail message="No TABLE available" unless="table.present"/>

    <!-- Need JUnit for testcases, not essential -->
    <available property="junit.present"
               classpathref="classpath"
               classname="junit.framework.TestCase"/>

  </target>

  <!--
   !   =================
   !   Prepare the build
   !   =================
   !
   !  Do any jobs that are required before any other target can proceed.
   !-->
  <target name="prepare">

    <tstamp>
      <format property="year" pattern="yyyy"/>
    </tstamp>

    <!-- This is a filterchain that can be used to copy-edit files
     !   that require the package version, current date and/or time -->
    <filterchain id="filters">
      <replacetokens>
        <token key="VERSION" value="${version}"/>
        <token key="DATE" value="${TODAY}"/>
        <token key="TIME" value="${TSTAMP}"/>
      </replacetokens>
    </filterchain>

  </target>


  <!--
   !   ==============
   !   Build the code
   !   ==============
   !
   !  The results of the compilation are placed in the build.classes
   !  directory. Other files that are also needed in the classes tree
   !  (i.e. resources like images and property files) should also be
   !  copied into place here.
   !-->
  <target name="build"
          depends="prepare, check_packages"
          unless="runonly.install"
          description="-> compiles the source code">

    <mkdir dir="${build.classes}"/>
    <javac srcdir="${java.dir}"
           destdir="${build.classes}"
           debug="${debug}"
           deprecation="${deprecation}"
           encoding="cp1252"
           includeantruntime="false"
           optimize="${optimize}">
      <compilerarg value="-Xlint:all,-path,-serial"/>

      <classpath refid="classpath"/>

      <!-- Exclude any files in the source tree that should not be
       !   compiled -->
      <include name="**/*.java"/>
      <exclude name="${src.excludes}"/>
      <exclude name="uk/ac/starlink/ttools/cone/HtmTiling.java"/>
      <exclude name="uk/ac/starlink/ttools/task/StiltsServer.java"/>
      <exclude name="uk/ac/starlink/ttools/server/*.java"/>
      <exclude name="uk/ac/starlink/ttools/mode/PlasticMode.java"/>
    </javac>

    <!-- Copy extra files that should live with packages classes
     !   (i.e. are discovered using "getResource()"). -->
    <copy todir="${build.classes}">
      <fileset dir="${src.dir}/resources"/>
    </copy>

    <!-- Write the package version number to a file. -->
    <echo file="${build.classes}/uk/ac/starlink/ttools/stilts.version"
          message="${version}"/>

    <!-- Local third party jars, if any. Copy straight into
     !   distribution directories to save on unnecessary copies and to
     !   make these available for resolution by other locally built
     !   packages that are using this one -->
    <mkdir dir="${dist.lib.pkg}"/>
    <copy todir="${dist.lib.pkg}">
       <fileset dir="${src.jars.dir}"/>
    </copy>

    <!-- Additional built resources. -->
    <java classname="uk.ac.starlink.ttools.build.Plot2Example"
          output="${build.classes}/uk/ac/starlink/ttools/server/ex-plots.html"
          failonerror="yes"
          logerror="yes">
      <sysproperty key="java.awt.headless" value="true"/>
      <classpath refid="classpath"/>
      <arg value="-mode"/> <arg value="plotserv"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.Plot2Example"
          output="${build.classes}/uk/ac/starlink/ttools/server/basic-plots.html"
          failonerror="yes"
          logerror="yes">
      <sysproperty key="java.awt.headless" value="true"/>
      <classpath refid="classpath"/>
      <arg value="-mode"/> <arg value="plotserv_basic"/>
      <arg value="layer-label"/>
      <arg value="skysim"/>
      <arg value="clifford"/>
      <arg value="rampe"/>
      <arg value="layer-function"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.Plot2Example"
          output="${build.classes}/uk/ac/starlink/ttools/server/basic-plots.ipynb"
          failonerror="yes"
          logerror="yes">
      <sysproperty key="java.awt.headless" value="true"/>
      <classpath refid="classpath"/>
      <arg value="-mode"/> <arg value="ipynb_basic"/>
      <arg value="layer-label"/>
      <arg value="skysim"/>
      <arg value="clifford"/>
      <arg value="rampe"/>
      <arg value="layer-function"/>
    </java>

    <!-- Call target to do time-consuming build of additional components;
     !   first check that they are not already in place. -->
    <condition property="extras.built">
      <and>
        <uptodate targetfile="${build.javadocs}/uk/ac/starlink/ttools/func">
          <srcfiles dir="${java.dir}/uk/ac/starlink/ttools/func"/>
        </uptodate>
        <uptodate targetfile="${build.etc}/stilts.py">
          <srcfiles dir="${java.dir}"/>
        </uptodate>
      </and>
    </condition>
    <antcall target="build-extras"/>

  </target>

  <!-- Sub-target to perform time-consuming build of additional components
   !   in build phase; unless attribute allows it to be skipped. -->
  <target name="build-extras" unless="extras.built">

    <!-- Construct HTML documentation for JEL-accessible classes. -->
    <mkdir dir="${build.javadocs}"/>
    <javadoc doclet="${jel.doclet}$Html"
             docletpathref="classpath"
             failonerror="true"
             public="true"
             additionalparam="-headings"
             destdir="${build.javadocs}"
             sourcepath="${java.dir}"
             packagenames="uk.ac.starlink.ttools.func"
             classpathref="classpath"
             encoding="cp1252"/>

    <!-- Write and compile JyStilts module source code. -->
    <echo message="Generating stilts.py"/>
    <mkdir dir="${build.etc}"/>
    <java classname="uk.ac.starlink.ttools.build.JyStilts"
          output="${build.etc}/stilts.py"
          failonerror="yes"
          fork="true"
          logerror="yes">
      <classpath refid="classpath"/>
      <sysproperty key="java.awt.headless" value="true"/>
    </java>

    <!-- Write LaTeX fonts resource list. -->
    <echo message="Assembling list of LaTeX fonts"/>
    <mkdir dir="${build.classes}/uk/ac/starlink/ttools/plot2"/>
    <java classname="uk.ac.starlink.ttools.plot.ExternalFontMapper"
          output="${build.classes}/uk/ac/starlink/ttools/plot2/latex_fonts.txt"
          failonerror="yes"
          fork="true"
          logerror="yes">
      <classpath refid="classpath"/>
      <sysproperty key="java.awt.headless" value="true"/>
      <arg value="${star.jar.dir}/jlatexmath.jar"/>
    </java>
  </target>

  <target name="build-standalone" depends="install">

    <!-- Build temporary zip file containing things not in the input jars
     !   which ought to be included in the standalone jars. -->
    <exec outputproperty="gitversion"
          logerror="true"
          executable="${star.dir}/bin/gitversion"/>
    <echo message="${gitversion}"
          file="${build.classes}/uk/ac/starlink/ttools/revision-string"/>
    <zip destfile="${dist.lib.pkg}/stilts-version.zip">
      <fileset dir="${build.classes}"
               includes="uk/ac/starlink/ttools/revision-string"/>
    </zip>
    <delete file="${build.classes}/uk/ac/starlink/ttools/revision-string"/>

    <java classname="uk.ac.starlink.util.SuperJar" failonerror="yes">
      <sysproperty key="java.awt.headless" value="true"/>
      <classpath refid="classpath"/>
      <arg value="-oj"/><arg value="${dist.lib.pkg}/stilts.jar"/>
      <arg value="-oz"/><arg value="${dist.lib.pkg}/stilts_jars.zip"/>
      <arg value="-xjar"/><arg value="junit.jar"/>
      <arg value="-xjar"/><arg value="topcat.jar"/>
      <arg value="-xjar"/><arg value="org.mortbay.jmx.jar"/>
      <arg value="-xjar"/><arg value="jasper-combined.jar"/>
      <arg value="-xjar"/><arg value="parquet-mr-stil.jar"/>
      <arg value="-xent"/><arg value="*"/>
      <arg value="-xent"/><arg value="META-INF/*"/>
      <arg value="-xent"/><arg value="META-INF/maven/"/>
      <arg value="-file"/><arg value="${star.bin}/stilts"/>
      <arg value="-file"/><arg value="${star.etc.pkg}/stilts.py"/>
      <arg value="-file"/><arg value="${src.docs}/LICENSE.txt"/>
      <arg value="-file"/>
          <arg value="${build.classes}/uk/ac/starlink/ttools/stilts.version"/>
      <arg value="${star.lib.pkg}/stilts-app.jar"/>
      <arg value="${dist.lib.pkg}/stilts-version.zip"/>
    </java>
    <delete file="${dist.lib.pkg}/stilts-version.zip"/>
  </target>

  <!--
   !   ============================
   !   Create the package jar files
   !   ============================
   !
   !  Creates a jar file from the build.classes directory tree. If
   !  jars of sub-components are also required these should be also
   !  created here. Note this requires a manifest file that defines the
   !  jars that we directly depend on (using relative URLs) on and
   !  defines the application entrance point. The jar files should be
   !  placed directly in the distribution directories.
   !-->
  <target name="jars"
          depends="build"
          unless="runonly.install"
          description="-> creates the package jar file(s)">

    <!-- Create the library jar file, ttools.jar.
     !   This excludes any GPL-encumbered parts. -->
    <mkdir dir="${dist.lib.pkg}"/>
    <manifestclasspath property="jar.class.path"
                       jarfile="${dist.lib.pkg}/${name}.jar">
      <classpath refid="jar.classpath" />
    </manifestclasspath>
    <jar destfile="${dist.lib.pkg}/${name}.jar">
      <fileset dir="${build.classes}"
               excludes="uk/ac/starlink/ttools/gpl/*
                         uk/ac/starlink/ttools/gpl"/>
      <fileset dir="${build.javadocs}"/>
      <fileset dir="${build.etc}"/>
      <manifest>
        <attribute name="Built-By" value="${user.name}"/>
        <attribute name="Class-Path" value="${jar.class.path}"/>
        <attribute name="Main-Class" value="uk.ac.starlink.ttools.Stilts"/>
      </manifest>
    </jar>

    <!-- Create a jar file consisting of just the GPL-encumbered parts. -->
    <mkdir dir="${dist.lib.pkg}"/>
    <jar destfile="${dist.lib.pkg}/${name}-gpl.jar">
      <fileset dir="${build.classes}"
               includes="uk/ac/starlink/ttools/gpl/*"/>
      <manifest> 
        <attribute name="Built-By" value="${user.name}"/>
      </manifest>
    </jar>

    <!-- Also create a jar file which can be used to invoke the STILTS 
     !   application.  As well as a Main-Class, this wants a reference
     !   to the TOPCAT jar file, so that tpipe's topcat output mode can
     !   start up TOPCAT when required.  If you try to put topcat.jar
     !   in the Class-Path entry of the ttools.jar file, it causes part
     !   of the build (or at least the test) to blow up with recursive
     !   classpath trouble, so this jar file contains nothing but a
     !   manifest. -->
    <jar destfile="${dist.lib.pkg}/stilts-app.jar" excludes="**">
      <manifest> 
        <attribute name="Built-By" value="${user.name}"/>
        <attribute name="Class-Path" value="${name}.jar ../topcat/topcat.jar"/>
        <attribute name="Main-Class" value="uk.ac.starlink.ttools.Stilts"/>
      </manifest>
    </jar>

  </target>

  <!--
   !   ========================================
   !   Make package JNLP file for Java webstart
   !   ========================================
   !
   ! The webstart setup for an application requires that it have two
   ! JNLP files. One to describe it as an application and one as a component.
   ! The component form is required if another application wants to use
   ! this application, either directly (by embedding) or just as a
   ! dependency (for contact via webservices). These two functions cannot be
   ! performed in the same two JNLP files.
   !-->
  <target name="webstart"
          description="-> create webstart descriptor files">

    <!-- Create a webstart JNLP file for this application as a component, 
     !   so that may be used by other applications. This goes into "dist.lib".
     !-->
     <jnlp toFile="${dist.lib}/${name}.jnlp" href="${name}.jnlp"
          codebase="${webstart.codebase}">

      <information>
         <title>TTOOLS - auxiliary table manipulation utilities</title>
         <vendor>Starlink UK</vendor>
         <homepage href="${home.page}"/>
         <icon href="${webstart.starlink_logo}"/>
         <description>Starlink TTOOLS - Webstart edition</description>
         <offline_allowed/>
       </information>

       <security>
          <all_permissions/>
       </security>

       <resources>
         <j2se version="1.8+"/>

         <!-- All jar files of this application -->
         <fileset dir="${dist.lib}" includes="**/*.jar **/*.zip"
                  excludes="**/stilts.jar **/stilts-app.jar
                            **/stilts_jars.zip"/>

         <!-- Components that this component depends on (non applications
          !   named in the application jar file class-path). -->
         <extension name="TABLE" href="table.jnlp"/>
         <extension name="TJOIN" href="tjoin.jnlp"/>
         <extension name="FITS" href="fits.jnlp"/>
         <extension name="MIRAGE" href="mirage.jnlp"/>
         <extension name="VOTABLE" href="votable.jnlp"/>
         <extension name="TASK" href="task.jnlp"/>
         <extension name="VO" href="vo.jnlp"/>
         <extension name="PAL" href="pal.jnlp"/>
         <extension name="PLASTIC" href="plastic.jnlp"/>
       </resources>

       <!-- This is a component -->
       <component_desc/>
     </jnlp>

  </target>

  <!--
   !   =================================
   !   Configures the local distribution
   !   =================================
   !
   !  Completes the creation of the local distribution into the
   !  directory "dist.dir" (usually the current directory).
   !  Installations and exports are based on the state of this
   !  distribution, so it must be performed before installation or
   !  export. If the "runonly.install" parameter is set then this
   !  target is skipped (needed for releases that do not have
   !  source). Much of the work of getting the distribution
   !  directories into the correct state is performed by the dependency
   !  targets.
   !-->
  <target name="dist"
          depends="build,jars,javadocs,docs,webstart,download"
          unless="runonly.install"
          description="-> configures the local binary distribution">

    <!-- Make sure all the distribution directories exist -->
    <mkdir dir="${dist.dir}"/>
    <mkdir dir="${dist.bin.pkg}"/>
    <mkdir dir="${dist.lib.pkg}"/>
    <mkdir dir="${dist.docs.pkg}"/>
    <mkdir dir="${dist.etc.pkg}"/>

    <!-- Copy any startup scripts etc. -->
    <copy todir="${dist.bin.pkg}">
      <fileset dir="${script.dir}" excludes="*.template"/>
    </copy>

    <!-- Copy extra documentation, note doesn't include javadocs these
     !   are generated from the source-->
    <copy todir="${dist.docs.pkg}">
      <fileset dir="${build.docs}"
               includes="${user.doc}/* *.pdf README.* LICENSE.txt"/>
    </copy>

    <!-- Copy extra files. -->
    <copy todir="${dist.etc.pkg}">
      <fileset dir="${build.etc}"/>
    </copy>
    <copy todir="${dist.lib.pkg}">
      <fileset dir="${src.downloads.dir}">
        <include name="*.jar"/>
      </fileset>
    </copy>

    <!-- Set permissions on contents of distribution directories -->
    <chmod perm="ugo+rx" dir="${dist.dir}" type="dir" includes="**"
           failonerror="${chmod.fail}" maxparallel="50"/>
    <chmod perm="ugo+r" dir="${dist.dir}" type="file" includes="**"
           failonerror="${chmod.fail}" maxparallel="50"/>
    <chmod perm="ugo+x" type="file" failonerror="${chmod.fail}"
           maxparallel="50">
       <fileset dir="${dist.bin}"/>
    </chmod>

  </target>

  <!--
   !   ========================
   !   Create the full releases
   !   ========================
   !
   !  Creates the full "zip", "tar" and "bzip" archives of the
   !  products of the "dist" target and the source directory.
   !  The archives are designed to be unpacked such that the resultant
   !  directory layout can be either used as a local distribution, or
   !  installed into a Starlink tree (installation requires the
   !  Starlink modified version of ANT, use as a local distribution
   !  may need special handling of the extension path). This version
   !  can also be used to rebuild the package from source.
   !
   !  The archive names are ${dist.version}.<ext>.
   !-->
  <target name="export"
          description="-> creates the full distribution archives">

    <antcall target="create_archives">
      <param name="source.required" value="true"/>
      <param name="binary.required" value="true"/>
      <param name="archive.name" value="${dist.version}"/>
    </antcall>

  </target>

  <!--
   !   ==========================
   !   Create the source releases
   !   ==========================
   !
   !  Creates the source only "zip", "tar" and "bzip" archives.
   !  These can be used to rebuild the package (requires the Starlink
   !  modified version of ANT).
   !
   !  The archive names are ${dist.version}-src.<ext>.
   !-->
  <target name="export-source"
          description="-> creates the source distribution archives">

     <antcall target="create_archives">
      <param name="source.required" value="true"/>
      <param name="archive.name" value="${dist.version}-src"/>
    </antcall>

  </target>

  <!--
   !   ===========================
   !   Create the runonly releases
   !   ===========================
   !
   !  Creates the runonly "zip", "tar" and "bzip" archives of the
   !  products of the "dist" target. The archives are designed to be
   !  unpacked such that the resultant directory layout can be either
   !  used as a local distribution, or installed into a Starlink tree
   !  (installation requires the Starlink modified version of ANT).
   !
   !  The archive names are ${dist.version}-bin.<ext>.
   !-->
  <target name="export-runonly"
          description="-> creates the runonly distribution archives">

     <antcall target="create_archives">
      <param name="binary.required" value="true"/>
      <param name="archive.name" value="${dist.version}-bin"/>
    </antcall>

  </target>

  <!--
   ! Create release archives of the various types required. Use this
   ! by an <antcall> and set the property "archive.name" to define what
   ! name to use for the outfile files. The archives are written into
   ! the directory ${star.archive.dir} (the local directory by default).
   !
   ! If the property "binary.required" is set then the files needed
   ! for a run-only release are included and if "source.required" is
   ! defined the source code is also included.
   !-->
  <target name="create_archives"
          depends="dist">

    <mkdir dir="${star.archive.dir}"/>

    <zip destfile="${star.archive.dir}/${archive.name}.zip">

      <!-- All releases have the documentation and build file -->
      <zipfileset dir="${dist.docs}" prefix="${name}/docs"/>
      <zipfileset dir="${dist.dir}" includes="build.xml" prefix="${name}"/>

      <zipfileset dir="${dist.bin}" prefix="${name}/bin">
        <include name="**" if="binary.required"/>
      </zipfileset>
      <zipfileset dir="${dist.lib}" prefix="${name}/lib">
        <include name="**" if="binary.required"/>
      </zipfileset>
      <zipfileset dir="${dist.etc}" prefix="${name}/etc">
        <include name="**" if="binary.required"/>
      </zipfileset>

      <zipfileset dir="${src.dir}" prefix="${name}/src">
        <include name="**" if="source.required"/>

        <!-- Exclude local development support from distribution-->
        <exclude name="local/**" if="source.required"/>
      </zipfileset>

    </zip>

    <!-- Note: creating a tar file with empty directories doesn't
     !   work, so the directory structure may be incomplete -->
    <tar longfile="gnu" destfile="${archive.name}.tar">

      <!-- All releases have the documentation and build file -->
      <tarfileset dir="${dist.docs}" prefix="${name}/docs"/>
      <tarfileset dir="${dist.dir}" prefix="${name}">
        <include name="build.xml"/>
      </tarfileset>

      <tarfileset dir="${dist.bin}" prefix="${name}/bin">
        <include name="**" if="binary.required"/>
      </tarfileset>
      <tarfileset dir="${dist.lib}" prefix="${name}/lib">
        <include name="**" if="binary.required"/>
      </tarfileset>
      <tarfileset dir="${dist.etc}" prefix="${name}/etc">
        <include name="**" if="binary.required"/>
      </tarfileset>

      <tarfileset dir="${src.dir}" prefix="${name}/src">
        <include name="**" if="source.required"/>
        <exclude name="local/**" if="source.required"/>
      </tarfileset>

    </tar>

    <gzip zipfile="${star.archive.dir}/${archive.name}.tar.gz"
          src="${archive.name}.tar"/>
    <bzip2 zipfile="${star.archive.dir}/${archive.name}.tar.bz2"
           src="${archive.name}.tar"/>
    <delete file="${archive.name}.tar"/>

  </target>

  <!--
   !   ============================================
   !   Cleans up build and distribution directories
   !   ============================================
   !-->
  <target name="clean"
          description="-> cleans up build and dist products">

    <delete dir="${build.dir}"/>
    <delete dir="${dist.bin}"/>
    <delete dir="${dist.lib}"/>
    <delete dir="${dist.docs}"/>
    <delete dir="${dist.etc}"/>

  </target>

  <!--
   !   ================================
   !   Install into the "Starlink" tree
   !   ================================
   !
   ! Installs the "dist" target products into another set of
   ! directories.
   !
   ! An installed system is potentially "undoable" as the copied names
   ! and package-specific directories are logged to "${install.log}".
   !-->
  <target name="install"
          depends="dist"
          description="-> installs distribution">

    <!-- Installation based directories (based on "star.install")-->
    <property name="star.bin" value="${star.install}/bin"/>
    <property name="star.lib" value="${star.install}/lib"/>
    <property name="star.etc" value="${star.install}/etc"/>
    <property name="star.docs" value="${star.install}/docs"/>
    <property name="star.bin.pkg" value="${star.bin}"/>
    <property name="star.lib.pkg" value="${star.lib}/${name}"/>
    <property name="star.etc.pkg" value="${star.etc}/${name}"/>
    <property name="star.docs.pkg" value="${star.docs}/${name}"/>
    <mkdir dir="${star.install}"/>
    <mkdir dir="${star.bin.pkg}"/>
    <mkdir dir="${star.lib.pkg}"/>
    <mkdir dir="${star.etc.pkg}"/>
    <mkdir dir="${star.docs.pkg}"/>

    <loggedcopy todir="${star.bin}"
                logfile="${install.log}"
                overwrite="${install.overwrite}"
                logfileAppend="false">
      <fileset dir="${dist.bin}"/>
    </loggedcopy>

    <chmod perm="ugo+rx" failonerror="${chmod.fail}">
      <fileset dir="${star.bin}">
        <present targetdir="${dist.bin}" present="both"/>
      </fileset>
    </chmod>

    <loggedcopy todir="${star.lib}"
                logfile="${install.log}"
                overwrite="${install.overwrite}"
                logfileAppend="true">
      <fileset dir="${dist.lib}">
        <include name="**/*.jnlp"/>
        <include name="**/*.jar"/>
        <include name="**/*.zip"/>
      </fileset>
    </loggedcopy>
    <echo file="${install.log}" append="true">${star.lib.pkg}
</echo>

    <loggedcopy todir="${star.etc}"
                logfile="${install.log}"
                overwrite="${install.overwrite}"
                logfileAppend="true">
      <fileset dir="${dist.etc}"/>
    </loggedcopy>
    <echo file="${install.log}" append="true">${star.etc.pkg}
</echo>

    <loggedcopy todir="${star.docs}"
                logfile="${install.log}"
                overwrite="${install.overwrite}"
                logfileAppend="true">
      <fileset dir="${dist.docs}" excludes="${unfiltered.files}"/>
      <filterchain refid="filters"/>
    </loggedcopy>

    <loggedcopy todir="${star.docs}" filtering="false"
                logfile="${install.log}"
                overwrite="${install.overwrite}"
                logfileAppend="true">
      <fileset dir="${dist.docs}" includes="${unfiltered.files}"/>
    </loggedcopy>
    <echo file="${install.log}" append="true">${star.docs.pkg}
</echo>

  </target>

  <!--
   !   ========================================
   !   Install runonly into the "Starlink" tree
   !   ========================================
   !
   ! Do an install using only the contents of a binary release (a
   ! source-free runonly system).
   !-->
  <target name="install-runonly"
          description="-> install a runonly distribution into Starlink tree">

     <!-- Make sure that the expected file structure exists, some
          of these files can be missing if originally empty -->
     <mkdir dir="${dist.dir}"/>
     <mkdir dir="${dist.bin.pkg}"/>
     <mkdir dir="${dist.lib.pkg}"/>
     <mkdir dir="${dist.docs.pkg}"/>
     <mkdir dir="${dist.etc.pkg}"/>

     <!-- Do normal install, but with many targets switched off-->
     <antcall target="install">
      <param name="runonly.install" value="true"/>
      <param name="javadoc.notrequired" value="true"/>
    </antcall>

  </target>

  <!--
   !   ===================================
   !   De-install from the "Starlink" tree
   !   ===================================
   !
   ! Uses the content of the "${install.log}" to remove the files
   !  that were copied into place by the install target. If this fails
   !  then hopefully the log file will not be deleted!
   !-->
 <target name="deinstall"
          description="-> undo the install target">

    <available file="${install.log}" property="install.log.present"/>

    <antcall target="real_deinstall"/>

  </target>

  <!-- Real deinstall target. Only activated if "install.log.present"
   !   is defined -->
  <target name="real_deinstall"
          if="install.log.present">

    <loadfile property="files" srcFile="${install.log}"/>
    <listdelete>
      <filelist dir="/" files="${files}"/>
    </listdelete>

    <delete file="${install.log}"/>

  </target>

  <!--
   !   =============================
   !   Creates the API documentation
   !   =============================
   !
   !  Create documentation from the Java sources. Additional
   !  documentation is kept in the ${src.docs} directory.
   !-->
  <target name="javadocs"
          depends="prepare,javadoc_check"
          unless="javadoc.notrequired"
          description="-> creates the API documentation">

    <mkdir dir="${dist.javadocs}"/>
    <javadoc useexternalfile="yes"
             destdir="${dist.javadocs}"
             author="true"
             version="true"
             locale="en"
             windowtitle="${Name} API"
             doctitle="${Name}"
             defaultexcludes="yes"
             source="${source.version}"
             failonerror="yes"
             classpathref="classpath">
      <arg value="-Xdoclint:all,-missing"/>
      <arg value="-quiet"/>

      <!-- Get a list of directories that name all the potential
       !   java packages -->
      <fileset dir="${java.dir}" defaultexcludes="yes">
         <include name="**/*.java"/>
         <exclude name="uk/ac/starlink/ttools/build"/>
	 <exclude name="uk/ac/starlink/ttools/cone/HtmTiling.java"/>
	 <exclude name="uk/ac/starlink/ttools/task/StiltsServer.java"/>
	 <exclude name="uk/ac/starlink/ttools/server/*.java"/>
	 <exclude name="uk/ac/starlink/ttools/mode/PlasticMode.java"/>
      </fileset>

      <!-- Link to the full Java API at SUNs website -->
      <link offline="true" href="${javaapi.url}"
            packagelistLoc="${javaapi.lis}"/>

      <!-- Cope with custom tags. -->
      <tag name="example" 
           description="Examples:"
           scope="methods, fields"
           enabled="true"/>

      <group title="${Name} API" packages="${package.name}*"/>

      <bottom><![CDATA[<i>Copyright &#169; ${year} Central Laboratory of the Research Councils. All Rights Reserved.<i>]]></bottom>
    </javadoc>

  </target>

  <!-- This checks if the javadocs are up to date with respect to the
   !   java source, if so then the "javadoc.notrequired" variable is
   !   set true. Note this is check is not performed if
   !   javadoc.notrequired is already set (by .properties) -->
  <target name="javadoc_check"
          unless="javadoc.notrequired">

    <uptodate property="javadoc.notrequired"
              targetfile="${dist.javadocs}/packages.html">
        <srcfiles dir= "${java.dir}" includes="**/*.java"/>
    </uptodate>

  </target>

  <!--
   !   =================================================
   !   Creates additional documentation from XML sources
   !   =================================================
   !
   !   The XML user document is downconverted to single- 
   !   and multiple-file HTML versions in the docs directory.
   !-->
  <target name="docs"
          depends="build, docs_check"
          unless="docs.notrequired"
          description="-> creates the user documentation">

    <!-- Make destination directory for built files. -->
    <mkdir dir="${build.docs}"/>

    <!-- Copy required source files there. -->
    <copy todir="${build.docs}">
      <fileset dir="${src.docs}" includes="${user.doc}.xml"/>
      <fileset dir="${xdoc.etc}" includes="docs.dtd"/>
      <fileset dir="${src.docs}" includes="README.* LICENSE.txt"/>
      <fileset dir="${src.docs.examp}" includes="*.xml"/>
    </copy>
    <copy todir="${build.docs}/${user.doc}">
      <fileset dir="${src.docs.examp}"
               includesfile="${src.docs.examp}/plot-example-files.txt"/>
      <fileset dir="${src.docs.examp}"
               includesfile="${src.docs.examp}/plot2-figs.lis"/>
    </copy>

    <!-- Construct XML documentation for the JEL-accessible classes.
     !   This is built using Javadoc, and forms part of the user document. -->
    <javadoc doclet="${jel.doclet}$Xml"
             docletpathref="classpath"
             failonerror="true"
             public="true"
             additionalparam="-o ${build.docs}/jel-javadocs.xml"
             sourcepath="${java.dir}"
             packagenames="uk.ac.starlink.ttools.func"
             classpathref="classpath"
             source="${source.version}"/>

    <!-- Write an XML file containing usage output for some actual
     !   command invocations. -->
    <java classname="uk.ac.starlink.ttools.build.OutputCapture"
          failonerror="yes"
          fork="no"
          output="${build.docs}/stilts-usage.xml"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
      <arg value="uk.ac.starlink.ttools.Stilts"/>
      <arg value="-help"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.OutputCapture"
          failonerror="yes"
          fork="no"
          output="${build.docs}/tcopy-usage.xml"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
      <arg value="uk.ac.starlink.ttools.Stilts"/>
      <arg value="tcopy"/>
      <arg value="help"/>
    </java>
    <!-- fork="yes" required below else ant confuses JAXP -->
    <java classname="uk.ac.starlink.ttools.build.OutputCapture"
          failonerror="yes"
          fork="yes"
          output="${build.docs}/tcopy-in-usage.xml"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
      <arg value="uk.ac.starlink.ttools.Stilts"/>
      <arg value="tcopy"/>
      <arg value="help=in"/>
    </java>

    <!-- Write XML files containing per-task usage information
     !   for inclusion in the user document. -->
    <java classname="uk.ac.starlink.ttools.build.PurposeWriter"
          failonerror="yes"
          output="${build.docs}/purpose-defs.xml"
          logerror="yes"
          fork="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.UsageWriter"
          failonerror="yes"
          fork="yes"
          dir="${build.docs}"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.LayersWriter"
          failonerror="yes"
          fork="yes"
          dir="${build.docs}"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.FilterDoc"
          failonerror="yes"
          output="${build.docs}/filter-docs.xml"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.ModeDoc"
          failonerror="yes"
          output="${build.docs}/mode-docs.xml"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.PaintModeDoc"
          failonerror="yes"
          output="${build.docs}/paintmode-docs.xml"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.LayerTypeDoc"
          failonerror="yes"
          fork="yes"
          output="${build.docs}/layertype-docs.xml"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.ShapeModeDoc"
          failonerror="yes"
          fork="yes"
          output="${build.docs}/shapemode-docs.xml"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.MiscDoc"
          failonerror="yes"
          fork="yes"
          dir="${build.docs}"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.SchemeDoc"
          output="${build.docs}/scheme-docs.xml"
          failonerror="yes"
          fork="no"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
      <arg value="-stil"/>
      <arg value="-stilts"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.HandlerDoc"
          failonerror="yes"
          fork="yes"
          dir="${build.docs}"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
      <arg value="-files"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.ShaderLegend"
          output="${build.docs}/${user.doc}/colormaps-abs.svg"
          failonerror="yes"
          fork="yes"
          dir="${build.docs}"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
      <arg value="-ncol"/>
      <arg value="3"/>
      <arg value="-abs"/>
    </java>
    <java classname="uk.ac.starlink.ttools.build.ShaderLegend"
          output="${build.docs}/${user.doc}/colormaps-noabs.svg"
          failonerror="yes"
          fork="yes"
          dir="${build.docs}"
          logerror="yes"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
      <arg value="-ncol"/>
      <arg value="3"/>
      <arg value="-noabs"/>
    </java>

    <!-- Write XML files containing MatchEngine usage information
     !   for inclusion in the user document. -->
    <java classname="uk.ac.starlink.ttools.build.MatcherUsage"
          failonerror="yes"
          fork="yes"
          dir="${build.docs}"
          classpathref="classpath">
      <sysproperty key="java.awt.headless" value="true"/>
      <arg value="sky"/>
      <arg value="skyerr"/>
      <arg value="skyellipse"/>
      <arg value="sky3d"/>
      <arg value="exact"/>
      <arg value="1d"/>
      <arg value="2d"/>
      <arg value="2d_anisotropic"/>
      <arg value="2d_cuboid"/>
      <arg value="2d_err"/>
      <arg value="2d_ellipse"/>
      <arg value="sky+1d"/>
    </java>

    <!-- Copy miscellaneous XML -->
    <copy todir="${build.docs}">
      <fileset dir="${star.build.dir}/votable/src/docs"
               includes="fits-plus.xml"/>
      <fileset dir="${star.build.dir}/fits/src/docs"
               includes="fits-wide.xml"/>
    </copy>

    <!-- Transform the user document XML to a single HTML document. -->
    <mkdir dir="${build.docs}/${user.doc}"/>
    <copy todir="${build.docs}/${user.doc}">
      <fileset dir="${src.docs}" includes="${coverimage}"/>
      <fileset dir="${xdoc.etc}" includes="sun-style.css"/>
    </copy>
    <xslt in="${build.docs}/${user.doc}.xml"
          out="${build.docs}/${user.doc}/${user.doc}.html"
          style="${xdoc.etc}/toHTML1.xslt">
      <param name="VERSION" expression="${version}"/>
      <param name="BASEDIR" expression="${build.docs}/${user.doc}"/>
      <param name="COVERIMAGE" expression="${coverimage}"/>
      <param name="CSS_HREF" expression="sun-style.css"/>
    </xslt>

    <!-- Transform the user document to a multi-page HTML document. -->
  </target>

  <!--
   !   =================================================
   !   Create user document in PDF form from XML sources
   !   =================================================
   !
   !   The XML document is downconverted to PDF via xsl-fo using Fop.
   !
   !   This process is, for reasons I haven't tried very hard to
   !   understand, somewhat slow and also problematic
   !   in that it fails in headless mode when trying to render SVGs.
   !   Given that, and the fact that the PDF user document is rather
   !   a special-interest item, this target is no longer invoked as
   !   part of the normal install target.  If the PDF user document
   !   is required, this target must be invoked explicitly.
   !-->
  <target name="docs-pdf"
          depends="docs"
          description="-> creates the user documentation in PDF form">

    <!-- Transform the user document XML to a PDF document via XSL-FO. -->
    <xslt in="${build.docs}/${user.doc}.xml"
          out="${build.docs}/${user.doc}/${user.doc}.2.html"
          classpath="/usr/share/java/Saxon-HE.jar"
          style="${xdoc.etc}/toHTML.xslt">
      <param name="VERSION" expression="${version}"/>
      <param name="BASEDIR" expression="${build.docs}/${user.doc}"/>
      <param name="FIGDIR" expression="${build.docs}/${user.doc}"/>
      <param name="COVERIMAGE" expression="${coverimage}"/>
      <param name="CSS_HREF" expression="sun-style.css"/>
    </xslt>
  </target>

  <!-- Checks whether the docs build is up to date. -->
  <target name="docs_check" unless="docs.notrequired">
    <uptodate property="docs.notrequired"
              srcfile="${src.docs}/${user.doc}.xml"
              targetfile="${build.docs}/${user.doc}/${user.doc}.html"/>
  </target>

  <!--
   !   =======================
   !   Generates example plots
   !   =======================
   !
   !   This target is not called by any of the standard targets, but may
   !   be invoked by hand to write example plot graphics output files
   !   into the source tree.
   !
   !   These plots are not generated as part of the standard build process
   !   because (a) they are somewhat time-consuming to produce and
   !   (b) they require large binary data input files that ought not to be
   !   checked into the source archive.  But this target should be executed
   !   by hand from time to time (including before a release) when
   !   plotting code might have changed.  The example plots should be
   !   pixel-to-pixel equal unless some plotting behaviour has changed,
   !   i.e. running this target should not generated modified output,
   !   so any discrepancies between old and new graphic output revealed
   !   by this target should be understood before committing modified
   !   versions.
   !-->
  <target name="plot2-examples"
          description="-> generate example graphics for plot2 commands"
          depends="build,plot2-figdata">
    <echo message="Writing plot2 example files to ${src.docs.examp}"/>
    <echo message="Input data from ${plot2.figdata.dir}"/>
    <java classpathref="classpath"
          classname="uk.ac.starlink.ttools.build.Plot2Example"
          failonerror="yes"
          fork="yes">
      <jvmarg value="-enableassertions"/>
      <arg value="-dataDir"/>
      <arg value="${plot2.figdata.dir}"/>
      <arg value="-outDir"/>
      <arg value="${src.docs.examp}"/>
      <arg value="-mode"/>
      <arg value="png"/>
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
  </target>

  <!--
   !  This does the same as plot2-examples but forces (most of) the plotting
   !  execution to be done in parallel - in most cases it's done sequentially
   !  by default because the example plots are non-huge.
   !  This may produce slightly different results for some,
   !  but (unless there is a problem) not most of the plot examples.
   !-->
  <target name="plot2-examples-par"
        description="-> generate example graphics for plot2 commands (parallel)"
          depends="build,plot2-figdata">
    <echo message="Writing plot2 example files to ${src.docs.examp}"/>
    <echo message="Input data from ${plot2.figdata.dir}"/>
    <java classpathref="classpath"
          classname="uk.ac.starlink.ttools.build.Plot2Example"
          failonerror="yes"
          fork="yes">
      <arg value="-forceParallel"/>
      <arg value="-dataDir"/>
      <arg value="${plot2.figdata.dir}"/>
      <arg value="-outDir"/>
      <arg value="${src.docs.examp}"/>
      <arg value="-mode"/>
      <arg value="png"/>
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
  </target>

  <!--
   !   =====================================
   !   Acquires data files for example plots
   !   =====================================
   !
   !   Copies missing data files required for generating plot2 example
   !   graphics from an external URL to a local directory.
   !-->
  <target name="plot2-figdata"
          depends="build">
    <mkdir dir="${plot2.figdata.dir}"/>
    <java classpathref="classpath"
          classname="uk.ac.starlink.ttools.build.Plot2Example"
          failonerror="yes"
          fork="yes">
      <sysproperty key="java.awt.headless" value="true"/>
      <arg value="-dataDir"/>
      <arg value="${plot2.figdata.dir}"/>
      <arg value="-dataUrl"/>
      <arg value="${plot2.figdata.url}"/>
      <arg value="-mode"/>
      <arg value="copydata"/>
    </java>
  </target>

  <!--
   !   ===================================
   !   Generates example plots (old-style)
   !   ===================================
   !
   !   This target is not called by any of the standard targets, but may
   !   be invoked by hand to write example plot files and associated
   !   descriptions into the source tree.  This approach may be changed
   !   at a later date, but for now it's more convenient than generating
   !   these plots at build time, since (a) the plotting is somewhat
   !   time-consuming and (b) some input datasets are large (not ideal for 
   !   checking into source archive).
   !
   !   These examples refer to the old-style plotting framework,
   !   so are more or less obsolete.
   !-->
  <target name="plot-examples"
          description="-> generate example old-style plots (obsolete)"
          depends="build">
    <echo message="Writing plot example files to source dir ${src.docs.examp}"/>
    <java classpathref="classpath"
          dir="${src.docs.examp}"
          classname="uk.ac.starlink.ttools.build.PlotExample"
          failonerror="yes"
          fork="yes">
      <sysproperty key="java.awt.headless" value="true"/>
    </java>
  </target>


  <!--
   !   =========================================
   !   Makes the API java source files available
   !   =========================================
   !
   !  The full API documentation is created from all the various
   !  packages (of which this package is just one). This target makes
   !  the source code that should be used in the full public API
   !  available in a special part of the build tree so that it can be
   !  automatically discovered. This method works around two potential
   !  problems, not all source code the in src/main directories should be
   !  in the API docs, and it's not possible to make this distinction
   !  easily outside this package (cannot pass out a fileset), plus
   !  some code is generated, so cannot be located by scanning the
   !  src/main tree. When javadocs can be generated incrementally this
   !  arrangement should be reworked to generate whatever is needed as
   !  part of the javadocs target.
   !
   !  Application packages should only make public those parts of
   !  their internal APIs that they are prepared to support. Consider
   !  adding such code to proper class libraries (such as util).
   !-->
  <target name="javadoc-sources"
          description="-> make source files for release API documention">

    <mkdir dir="${build.java}"/>

    <!-- Copy and/or generate the source to be included when creating
     !   the full Starlink API javadocs-->
    <copy todir="${build.java}">
      <fileset dir="${java.dir}" defaultexcludes="yes">
          <exclude name="**/README"/>
      </fileset>
    </copy>

  </target>

  <!--
   !   =================
   !   Compile testcases
   !   =================
   !-->
  <target name="compile-tests"
          depends="build"
          if="junit.present">

    <mkdir dir="${build.tests}"/>

    <javac srcdir="${tests.dir}"
           destdir="${build.tests}"
           debug="${debug}"
           encoding="cp1252"
           includeantruntime="false"
           deprecation="${deprecation}" >

      <classpath refid="tests-classpath"/>

      <exclude name="uk/ac/starlink/ttools/task/TableMatch1Test.java"/>
      <exclude name="uk/ac/starlink/ttools/mode/ReflectionTest.java"/>
      <exclude name="uk/ac/starlink/ttools/DocTest.java"/>
    </javac>

  </target>

  <!--
   !   ==============================
   !   Download external dependencies
   !   ==============================
   !-->
  <property name="jython.lib" value="jython-standalone-2.7.2.jar"/>
  <target name="download">
    <condition property="downloads.present">
      <and>
        <available file="${src.downloads.dir}/${jython.lib}"/>
      </and>
    </condition>
    <antcall target="do-downloads"/>
    <checksum file="${src.downloads.dir}/${jython.lib}" algorithm="MD5"/>
  </target>
  <target name="do-downloads" unless="downloads.present">
    <get src="https://repo1.maven.org/maven2/org/python/jython-standalone/2.7.2/${jython.lib}"
         dest="${src.downloads.dir}/${jython.lib}"/>
  </target>

  <!--
   !   ============
   !   Run testcase
   !   ============
   !-->
  <target name="test"
          depends="run-tests"
          description="-> run JUnit tests"/>

  <target name="run-tests"
          depends="compile-tests"
          if="junit.present">

    <junit printsummary="${junit.summary}" haltonfailure="yes"
           filtertrace="${junit.filtertrace}"
           fork="${junit.fork}">

      <classpath refid="tests-classpath"/>

      <jvmarg value="${junit.assertions}"/>

      <sysproperty key="build.tests" value="${build.tests}"/>
      <sysproperty key="tests-classpath.value"
                   value="${tests-classpath.value}"/>
      <sysproperty key="java.library.path" value="${tests-libpath}"/>
      <sysproperty key="java.awt.headless" value="${java.awt.headless}"/>
      <sysproperty key="tests.withnet" value="${tests.withnet}"/>
      <sysproperty key="basedir" value="${basedir}"/>
      <sysproperty key="xdoc.etc" value="${xdoc.etc}"/>
      <sysproperty key="plot2.figdata.dir" value="${plot2.figdata.dir}"/>
      <sysproperty key="python.cachedir" value="${build.dir}/tmp"/>
      <sysproperty key="python.path" value="/usr/lib/site-python:/usr/share/jython/Lib"/>

      <formatter type="brief" usefile="false"/>

      <batchtest>
        <fileset dir="${tests.dir}">
          <include name="**/*Test.java"/>
          <exclude name="**/net_tests/*"/>
          <exclude name="uk/ac/starlink/ttools/task/TableMatch1Test.java"/>
          <exclude name="uk/ac/starlink/ttools/mode/ReflectionTest.java"/>
          <exclude name="uk/ac/starlink/ttools/DocTest.java"/>
        </fileset>
      </batchtest>

    </junit>

  </target>

  <!--
   !   =================
   !   Run network tests
   !   =================
   !-->
  <target name="run-net-tests"
          depends="compile-tests"
          if="junit.present"
          description="-> run network-dependent JUnit tests">
    <junit printsummary="${junit.summary}" haltonfailure="yes"
           filtertrace="${junit.filtertrace}"
           fork="${junit.fork}">
      <classpath refid="tests-classpath"/>
      <jvmarg value="${junit.assertions}"/>
      <sysproperty key="java.awt.headless" value="${java.awt.headless}"/>
      <formatter type="brief" usefile="false"/>
      <batchtest>
        <fileset dir="${tests.dir}">
          <include name="**/net_tests/*Test.java"/>
        </fileset>
      </batchtest>
    </junit>
  </target>

  <target name="run-single-test"
          if="testcase"
          depends="compile-tests"
          description="-> runs the single unit test defined in the testcase property">

    <junit printsummary="${junit.summary}"
          haltonfailure="yes"
          fork="${junit.fork}"
          filtertrace="${junit.filtertrace}">

      <sysproperty key="hdx.home" value="${hdx.home}"/>
      <sysproperty key="build.tests" value="${build.tests}"/>
      <sysproperty key="tests-classpath.value"
                   value="${tests-classpath.value}"/>
      <sysproperty key="java.library.path" value="${tests-libpath}"/>
      <sysproperty key="java.awt.headless" value="${java.awt.headless}"/>
      <sysproperty key="tests.withnet" value="${tests.withnet}"/>
      <sysproperty key="basedir" value="${basedir}"/>
      <sysproperty key="xdoc.etc" value="${xdoc.etc}"/>
      <sysproperty key="plot2.figdata.dir" value="${plot2.figdata.dir}"/>

      <classpath refid="tests-classpath"/>
      <jvmarg value="${junit.assertions}"/>
      <formatter type="plain" usefile="false"/>
      <test name="${testcase}"/>

    </junit>

  </target>

  <!--
   ! Get a DTD for this build file. Documentation suggests may be incomplete!
   !
   ! Use:
   !
   !    <!DOCTYPE project PUBLIC "-//ANT//DTD project//EN" "./project.dtd">
   !
   ! at head of document to include.
   !-->
  <target name="dtd">
     <antstructure output="project.dtd"/>
  </target>

</project>