build.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- 
  NOTICE: Copyright (c) 2017-2023 by the Music Encoding Initiative (MEI) Board (formerly known as "MEI Council").

  Licensed under the Educational Community License, Version 2.0 (the "License"); you may
  not use this file except in compliance with the License. You may obtain a copy of the License
  at https://opensource.org/licenses/ECL-2.0.
  
  Unless required by applicable law or agreed to in writing, software distributed under the
  License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
  OF ANY KIND, either express or implied. See the License for the specific language
  governing permissions and limitations under the License.
  
  This is a derivative work based on earlier versions of the schema © 2001-2006 Perry Roland
  and the Rector and Visitors of the University of Virginia; licensed under the Educational
  Community License version 1.0.
  
  CONTACT: info@music-encoding.org
-->
<project name="music-encoding" default="dist" xmlns:if="ant:if" xmlns:unless="ant:unless">
    <property environment="env">
        <!-- set environment variable -->
    </property>
    <property name="version" value="dev"/>
    <!-- in XSLT version = att.meiversion defaultVal -->
    <property name="github.sha" value="">
        <!-- string    external    The current GitHub sha -->
    </property>
    <property name="github.event_name" value="github.event_name">
        <!--string    external    The name of the event that triggered the workflow run. e.g.: push, pull_request; cf. https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows -->
    </property>
    <property name="github.ref" value="">
        <!-- string    external    The branch or tag ref that triggered the workflow run. For branches this in the format refs/heads/<branch_name>, and for tags it is refs/tags/<tag_name> -->
    </property>
    <loadresource property="github.ref-type" quiet="true">
        <string value="${github.ref}"/>
        <filterchain>
            <tokenfilter>
                <replaceregex pattern="([^\/]+\/)([^\/]+)(\/[^\/]+)" replace="\2"/>
            </tokenfilter>
        </filterchain>
    </loadresource>
    <loadresource property="github.ref-name" quiet="true">
        <string value="${github.ref}"/>
        <filterchain>
            <tokenfilter>
                <replaceregex pattern="([^\/]+\/)+" replace=""/>
            </tokenfilter>
        </filterchain>
    </loadresource>
    <loadresource property="windir" quiet="true">
        <string value="${basedir}"/>
        <filterchain>
            <tokenfilter>
                <replaceregex pattern="\\" replace="/"/>
            </tokenfilter>
        </filterchain>
    </loadresource>
    <condition property="basedir.cross_platform" value="${basedir}" else="file:/${windir}">
        <not>
            <os family="windows"/>
        </not>
    </condition>
    <property name="meiversion.latest" value="5.0"/>
    <property name="meiversion.next" value="5.1-dev"/>
    <property name="dir.build" value="build"/>
    <property name="canonicalized.file" value="mei-source_canonicalized_v"/>
    <property name="canonicalized.source.path" value="${dir.build}/${canonicalized.file}${meiversion.next}.xml"/>
    <property name="canonicalized.source.path.cross_platform" value="${basedir.cross_platform}/${canonicalized.source.path}"/>
    <property name="dir.dist" value="dist"/>
    <property name="dir.dist.guidelines" value="${dir.dist}/guidelines/web"/>
    <property name="dir.dist.schemata" location="${dir.dist}/schemata/"/>
    <property name="dir.lib" value="lib"/>
    <property name="dir.lib.saxon" value="${dir.lib}/saxon"/>
    <property name="dir.lib.xerces" value="${dir.lib}/xerces"/>
    <property name="saxon.download.version" value="SaxonHE11-5"/>
    <property name="saxon.jar.file" value="saxon-he-11.5.jar"/>
    <property name="xerces.version" value="25.1.0.1"/>
    <property name="xerces.jar.file" value="oxygen-patched-xerces-${xerces.version}.jar"/>
    <property name="oxygen.basic.utilites.jar.file" value="oxygen-basic-utilities-${xerces.version}.jar"/>
    <condition property="verbose" value="true" else="false">
        <contains string="${sun.java.command}" substring="-v" />
    </condition>

    <target name="help">
        <antcall target="echo-mei"/>
        <echo>================================================</echo>
        <echo>= Welcome to the MEI music-encoding ant-script! =</echo>
        <echo>================================================</echo>
        <echo/>
        <echo>This is the default build target with some usage information.</echo>
        <echo>You can also call this via 'ant help'</echo>
        <echo/>
        <echo>To build distribution of canonicalized source, compiled ODDs and customization RNGs run the default target `dist` by executing:</echo>
        <echo>ant dist</echo>
        <echo>OR just</echo>
        <echo>ant</echo>
        <echo/>
        <echo>run 'ant -projecthelp' or 'ant -p' to get more information on the available build targets.</echo>
        <echo/>
        <echo>The following buildproperties are configured in your environment:</echo>
        <echo/>
        <antcall target="echo-properties"/>
    </target>

    <target name="clean" description="Deletes the following directories: `build`, `dist` and `temp`.">
        <delete dir="build"/>
        <delete dir="dist"/>
        <delete dir="temp"/>
    </target>

    <target name="echo-classpath" description="Echos the mei.classpath." depends="init-mei-classpath">
        <echo message="${ant.refid:mei.classpath}"></echo>
    </target>

    <target name="echo-mei">
      <loadfile srcfile="source/assets/images/meilogo_ascii_100.txt" property="mei"/>
        <echo message="${mei}"/>
    </target>

    <target name="echo-properties" description="Echos all ant properties.">
        <echoproperties/>
    </target>

    <target name="get-local-git-sha" description="Retrieves the local git sha.">
        <exec executable="git" outputproperty="github.sha.local">
            <arg value="describe"/>
            <arg value="--match=NeVeRmAtCh"/>
            <arg value="--always"/>
            <arg value="--abbrev"/>
            <arg value="--dirty"/>
        </exec>
        <echo>Local github.sha: ${github.sha.local}</echo>
    </target>

    <target name="get-local-git-branch" description="Retrieves the current git branch via commandline.">
        <exec executable="git" outputproperty="github.branch.local">
            <arg value="branch"/>
            <arg value="--show-current"/>
        </exec>
        <echo>Local github.branch: ${github.branch.local}</echo>
    </target>

    <target name="reset" description="Resets the build environment. Same as `clean`, but additionaly deletes the `lib` directory with the Saxon and Xerces jar files.">
        <delete dir="lib"/>
        <antcall target="clean"/>
    </target>
    
    <target name="init" description="Initializes the build environment, i.e., checks if saxon and xerces are available, and if not, downloads jar files for Saxon, Xerces and adds them to the lib folder. Checks if prince is available.">
        <!-- check if xerces is available -->
        <condition property="xerces-available">
            <or>
                <available file="${dir.lib.xerces}/${xerces.jar.file}"/>
                <available classname="org.apache.xerces.jaxp.SAXParserFactoryImpl"/>
            </or>
        </condition>
        <echo if:set="xerces-available" message="xerces available: ${xerces-available}"/>
        <echo unless:set="xerces-available" message="xerces available: false"/>
        <!-- check if saxon is available -->
        <condition property="saxon-available">
            <or>
                <available file="${dir.lib.saxon}/${saxon.jar.file}"/>
                <available classname="net.sf.saxon.Transform"/>
            </or>
        </condition>
        <echo if:set="saxon-available" message="saxon available: ${saxon-available}"/>
        <echo unless:set="saxon-available" message="saxon available: false"/>
        <!-- check for prince -->
        <condition property="prince-available">
            <available file="prince" filepath="${env.PATH}" />
        </condition>
        <echo if:set="prince-available" message="prince available: ${prince-available}"/>
        <echo unless:set="prince-available" message="prince available: false"/>

        <antcall target="saxon-prepare" unless:true="${saxon-available}"/>
        <antcall target="xerces-download" unless:true="${xerces-available}"/>

        <echo>initialized</echo>
    </target>

    <target name="init-mei-classpath" description="Initializes the mei.classpath, which is essential for the schema generation, by prepending the jar files contained in the lib directory to the java classpath. Will be called automatically if needed." depends="init">
        <path id="mei.classpath">
            <fileset dir="lib" erroronmissingdir="false">
                <include name="**/*.jar" />
            </fileset>
            <pathelement path="${java.class.path}"/>
        </path>
        <echo>mei.classpath set</echo>
    </target>

    <target name="saxon-download" unless="${saxon-available}">
        <mkdir dir="temp"/>
        <get src="https://github.com/Saxonica/Saxon-HE/releases/download/${saxon.download.version}/${saxon.download.version}J.zip" dest="temp/download"/>
        <!-- TODO check for newer releases-->
    </target>

    <target name="saxon-prepare" depends="saxon-unzip" unless="${saxon-available}">
        <delete dir="temp/"/>
    </target>

    <target name="saxon-unzip" depends="saxon-download" unless="${saxon-available}">
        <mkdir dir="${dir.lib.saxon}"/>
        <unzip src="temp/download" overwrite="true" dest="${dir.lib.saxon}"/>
    </target>

    <target name="xerces-download" unless="${xerces-available}">
        <mkdir dir="${dir.lib.xerces}"/>
        <get src="https://www.oxygenxml.com/maven/com/oxygenxml/oxygen-patched-xerces/${xerces.version}/${xerces.jar.file}" dest="${dir.lib.xerces}"/>
        <get src="https://www.oxygenxml.com/maven/com/oxygenxml/oxygen-basic-utilities/${xerces.version}/${oxygen.basic.utilites.jar.file}" dest="${dir.lib.xerces}"/>
    </target>

    <target name="canonicalize-source" description="Creates a canonicalized version of the mei-source.xml, i.e., resolves xincludes and puts result in build/mei-source_canonicalized. This target will be triggered before all `build-...` targets." depends="init-mei-classpath" >
        <echo unless:set="canonicalize-source.done">canonicalizing source...</echo>
        <java unless:set="canonicalize-source.done" classname="net.sf.saxon.Transform" classpathref="mei.classpath" failonerror="true" fork="true">
            <arg value="-s:${basedir}/source/mei-source.xml"/>
            <arg value="-xsl:${basedir}/utils/canonicalization/copy.xsl"/>
            <arg value="-o:${canonicalized.source.path}"/>
            <arg value="-xi:on"/>
        </java>
        <property name="canonicalize-source.done" value="true"/>
        <echo>canonicalized source available: ${canonicalize-source.done}</echo>
    </target>

    <target name="build-compiled-odd" description="Builds the compiled ODD of a specific customization submitted as absolute path with -Dcustomization.path input param." depends="canonicalize-source">
        <basename property="odd.basename" file="${customization.path}" suffix=".xml"/>
        <echo>${odd.basename}</echo>
        <ant dir="submodules/Stylesheets/odd/" antfile="build-to.xml" target="go" inheritall="true">
            <property name="inputFile" value="${customization.path}"/>
            <property name="outputFile" value="${dir.dist.schemata}/${odd.basename}_compiled.odd"/>
            <property name="defaultSource" value="${canonicalized.source.path.cross_platform}"/>
            <property name="verbose" value="${verbose}"/>
            <property name="summaryDoc" value="false"/>
            <property name="suppressTEIexamples" value="true"/>
            <reference refid="mei.classpath" torefid="classpath"/>
        </ant>
    </target>
    
    <target name="build-customization-specs" depends="canonicalize-source" description="Builds the specs for a customization submitted as absolute path with -Dcustomization.path input param.">
        <basename property="odd.basename" file="${customization.path}" suffix=".xml"/>
        <echo>${odd.basename}</echo>
        <antcall target="build-compiled-odd">
            <param name="customization.path" value="${customization.path}"></param>
        </antcall>
        <ant dir="submodules/Stylesheets/html5" antfile="build-to.xml" target="odd" inheritall="true">
            <property name="inputFile" value="${dir.dist.schemata}/${odd.basename}_compiled.odd"/>
            <property name="outputFile" value="${dir.dist.schemata}/${odd.basename}_compiled.html"/>
            <property name="verbose" value="${verbose}"/>
            <property name="processODD">true</property>
            <reference refid="mei.classpath" torefid="classpath"/>
        </ant>
    </target>

    <target name="build-rng" description="Builds the RNG schema of a specific customization submitted as absolute path with -Dcustomization.path input param." depends="canonicalize-source">
        <basename property="odd.basename" file="${customization.path}" suffix=".xml"/>
        <echo>building rng ${odd.basename} from ${customization.path}</echo>
        <echo>    source: ${canonicalized.source.path.cross_platform}</echo>
        <echo>    output: ${dir.dist.schemata}/${odd.basename}.rng</echo>
        <ant dir="submodules/Stylesheets/rng/" antfile="build-to.xml" target="dist" inheritall="true" usenativebasedir="true"><!-- check whether nativebasdir is required -->
            <property name="inputFile" value="${customization.path}"/>
            <property name="outputFile" value="${dir.dist.schemata}/${odd.basename}.rng"/>
            <property name="defaultSource" value="${canonicalized.source.path.cross_platform}"/>
            <property name="verbose">true</property>
            <reference refid="mei.classpath" torefid="classpath"/>
            <property name="verbose" value="${verbose}"/>
        </ant>
    </target>

    <target name="build-guidelines-html" description="Builds the HTML version of the MEI guidelines." depends="canonicalize-source" unless="${build-guidelines-html.done}">
        <!-- TODO check dependency try with mei-source.xml -->
        <antcall target="get-local-git-sha" if:blank="${github.sha}"/>
        <antcall target="get-local-git-branch" if:blank="${github.ref}"/>
        <basename property="odd.basename" file="${customization.path}" suffix=".xml"/>
        <echo message="building HTML guidelines for ${odd.basename} from ${customization.path} on branch ${github.branch.local}"/>
        <echo>github.sha: ${github.sha}</echo>
        <echo>github.sha.local: ${github.sha.local}</echo>
        <condition property="hash" value="${github.sha}" else="${github.sha.local}">
            <not>
                <equals arg1="${github.sha}" arg2="" forcestring="true"/>
            </not>
        </condition>
        <condition property="branch" value="${github.ref-name}" else="${github.branch.local}">
            <not>
                <equals arg1="${github.ref}" arg2="" forcestring="true"/>
            </not>
        </condition>
        <antcall target="copy-guidelines-assets"/>
        <java classname="net.sf.saxon.Transform" classpathref="mei.classpath" failonerror="true" fork="true">
            <arg value="-s:${canonicalized.source.path}"/>
            <arg value="-xsl:${basedir}/utils/guidelines_xslt/odd2html.xsl"/>
            <arg value="-xi:on"/>
            <arg value="output.folder=${basedir}/${dir.build}/"/>
            <arg value="hash=${hash}"/>
            <arg value="branch=${branch}"/>
            <arg value="basedir=${basedir.cross_platform}"/>
        </java>
        <antcall target="generate-images"/>
        <antcall target="copy-generated-images"/>
    </target>

    <target name="build-guidelines-pdf" description="Builds the PDF version of the MEI guidelines. (Calls `build-guidelines-html` before execution.)" depends="build-guidelines-html">
        <!-- create output directory for PDF -->
        <mkdir dir="${dir.dist}/guidelines/pdf"/>
        <!-- get HTML input file -->
        <pathconvert property="build.dir.filelist" pathsep="${line.separator}">
            <map from="${basedir}${file.separator}" to=""/>
            <fileset dir="${dir.build}">
                <include name="MEI_Guidelines_*.html"/>
            </fileset>
        </pathconvert>
        <!-- set the prince.input property -->
        <loadresource property="prince.input">
            <string value="${build.dir.filelist}"/>
            <filterchain>
                <headfilter lines="1"/>
            </filterchain>
        </loadresource>
        <!-- set the prince.output.filename and prince.output.path properties -->
        <basename file="${prince.input}" property="prince.output.basename" suffix=".html"/>
        <property name="prince.output.filename" value="${prince.output.basename}.pdf"/>
        <property name="prince.output.path" value="${dir.dist}/guidelines/pdf/${prince.output.filename}"/>
        <!-- run prince to convert HTML guidelines to PDF -->
        <exec executable="prince" failonerror="true">
            <arg prefix="--log=" value="${dir.build}/prince.log"/>
            <arg prefix="--output=" value="${prince.output.path}"/>
            <arg file="${prince.input}"/>
        </exec>
    </target>

    <target name="copy-guidelines-assets">
        <echo message="copying guidelines assets from source to build and dist folders"/>
        <copy todir="${dir.build}/assets">
            <fileset dir="source/assets"/>
        </copy>
        <copy todir="${dir.dist.guidelines}/assets">
            <fileset dir="source/assets"/>
        </copy>
    </target>

    <target name="generate-images" description="Generates SVG images of MEI files in assets/images/GeneratedImages; depends on docker-mei container image." if="${docker}">
        <exec executable="node" dir="${basedir}/../">
            <arg value="index.js"/>
        </exec>
    </target>
    
    <target name="generate-images-py" description="Generates SVG images of MEI files in assets/images/GeneratedImages; depends on python3 with Verovio installed.">
        <exec executable="python3" logerror="true" dir="${basedir}/utils/examples" failifexecutionfails="true" failonerror="true">
            <arg value="generate-examples.py"/>
            <arg value="--clean"/>
            <arg value="--verbose"/>
        </exec>
    </target>

    <target name="copy-generated-images" description="Copies generated images to dist after they're created by running Docker image.">
        <copy todir="${dir.dist.guidelines}/assets/images/GeneratedImages">
            <fileset dir="${dir.build}/assets/images/GeneratedImages">
                <include name="*.svg"/>
            </fileset>
        </copy>
    </target>

    <target name="build-customizations" description="Builds the RNG schemata for all MEI customizations." depends="canonicalize-source">
        <antcall target="build-rng">
            <param name="customization.path" value="${basedir}/customizations/mei-all.xml"/>
        </antcall>
        <antcall target="build-rng">
            <param name="customization.path" value="${basedir}/customizations/mei-all_anyStart.xml"/>
        </antcall>
        <antcall target="build-rng">
            <param name="customization.path" value="${basedir}/customizations/mei-basic.xml"/>
        </antcall>
        <antcall target="build-rng">
            <param name="customization.path" value="${basedir}/customizations/mei-CMN.xml"/>
        </antcall>
        <antcall target="build-rng">
            <param name="customization.path" value="${basedir}/customizations/mei-Mensural.xml"/>
        </antcall>
        <antcall target="build-rng">
            <param name="customization.path" value="${basedir}/customizations/mei-Neumes.xml"/>
        </antcall>
    </target>

    <target name="build-compiled-odds" description="Builds the compiled ODD files for all MEI customizations." depends="canonicalize-source">
        <antcall target="build-compiled-odd">
            <param name="customization.path" value="${basedir}/customizations/mei-all.xml"/>
        </antcall>
        <antcall target="build-compiled-odd">
            <param name="customization.path" value="${basedir}/customizations/mei-all_anyStart.xml"/>
        </antcall>
        <antcall target="build-compiled-odd">
            <param name="customization.path" value="${basedir}/customizations/mei-basic.xml"/>
        </antcall>
        <antcall target="build-compiled-odd">
            <param name="customization.path" value="${basedir}/customizations/mei-CMN.xml"/>
        </antcall>
        <antcall target="build-compiled-odd">
            <param name="customization.path" value="${basedir}/customizations/mei-Mensural.xml"/>
        </antcall>
        <antcall target="build-compiled-odd">
            <param name="customization.path" value="${basedir}/customizations/mei-Neumes.xml"/>
        </antcall>
    </target>

    <target name="compare-versions" description="Compares the canonicalized sources of the MEI dev version with the previous stable version and creates an HTML output; custom versions and output folder can be set via -Dsource, -Dold and -Doutput input params." depends="canonicalize-source">
        <!-- set source file -->
        <property name="source.default" value="${canonicalized.source.path}"/>
        <echo level="verbose">source.default: ${source.default}</echo>
        <echo level="verbose">source user input: ${source}</echo>

        <condition property="source.file" value="${source}" else="${source.default}">
            <isset property="source"/>
        </condition>
        <echo>Using source.file: ${source.file}</echo>

        <!-- set old file to compare with -->
        <property name="old.default" value="${dir.build}/${canonicalized.file}${meiversion.latest}.xml"/>
        <condition property="old.default-available" value="true">
                <available file="${old.default}"/>
        </condition>
        <get src="https://raw.githubusercontent.com/music-encoding/schema/main/${meiversion.latest}/${canonicalized.file}${meiversion.latest}.xml" dest="${old.default}" unless:true="${old.default-available}"/>

        <echo level="verbose">old.default: ${old.default}</echo>
        <echo level="verbose">old user input: ${old}</echo>

        <condition property="old.file" value="${old}" else="${old.default}">
            <isset property="old"/>
        </condition>
        <echo>Using old.file: ${old.file}</echo>

        <!-- check if old.file is available, otherwise fail early -->
        <condition property="old.available" value="true" else="false">
            <available file="${old.file}"/>
        </condition>
        <echo message="old.file available: ${old.available}"></echo>

        <fail unless:true="${old.available}">Unfortunately, the $old.file ${old.file} is not available at the specified location.</fail>

        <!-- set ouput folder -->
        <property name="output.default" value="./utils/compare_versions/"/>
        <echo level="verbose">output.default: ${output.default}</echo>
        <echo level="verbose">output user input: ${output}</echo>

        <condition property="output.folder" value="${output}" else="${output.default}">
            <isset property="output"/>
        </condition>
        <echo>Using output folder: ${output.folder}</echo>

        <!-- compare versions -->
        <java classname="net.sf.saxon.Transform" classpathref="mei.classpath" failonerror="true" fork="true">
            <arg value="-s:${source.file}"/>
            <arg value="-xsl:${basedir}/utils/compare_versions/comparison.xsl"/>
            <arg value="-xi:on"/>
            <arg value="output.folder=${output.folder}"/>
            <arg value="old.version.filename=file:${old.file}"/>
        </java>

        <echo>Comparison done. See ${output.folder}/comparison.html for results.</echo>
    </target>

    <target name="dist" description="Default main target; equivalent to calling ant without any target. Builds all artifacts, i.e., RNG and compiled ODDs of all customizations, guidelines html and PDF." depends="init-mei-classpath, canonicalize-source">
        <classfileset refid="mei.classpath"/>
        <antcall target="echo-mei"/>
        <antcall target="build-customizations"/>
        <antcall target="build-compiled-odds"/>
        <antcall target="build-guidelines-html"/>
        <property name="${build-guidelines-html.done}" value="true"/>
        <antcall target="build-guidelines-pdf" if:true="${prince-available}"/>
    </target>

</project>