add description to -post-jar utility target

162ce088 · Brutzman, Don · b75d134b · 162ce088
Commit 162ce088 authored 8 months ago by Brutzman, Don
--- a/examples/build.xml
+++ b/examples/build.xml
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- You may freely edit this file. See commented blocks below for -->
 <!-- some examples of how to customize the build. -->
 <!-- (If you delete it and reopen the project it will be recreated.) -->
 <!-- By default, only the Clean and Build commands use this build script. -->
 <!-- Commands such as Run, Debug, and Test only use this build script if -->
 <!-- the Compile on Save feature is turned off for the project. -->
 <!-- You can turn off the Compile on Save (or Deploy on Save) setting -->
 <!-- in the project's Project Properties dialog box.-->
 <!--
  Copyright (c) 1995-2024 held by the author(s).  All rights reserved.
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer
      in the documentation and/or other materials provided with the
      distribution.
    * Neither the names of the Naval Postgraduate School (NPS)
      Modeling Virtual Environments and Simulation (MOVES) Institute
      (https://www.nps.edu and https://www.MovesInstitute.org)
      nor the names of its contributors may be used to endorse or
      promote products derived from this software without specific
      prior written permission.
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.
 -->
 <project name="MV3500 examples" default="default" basedir=".">
    <description>Builds, tests, and runs the project Networked Graphics MV3500 examples.</description>
    <import file="nbproject/build-impl.xml"/>
    <!-- TODO target to test all examples as quick unit test -->
    <target name="test.examples">
        <!-- invoke single-process tests first -->
        <!-- invoke    two-process tests next, perhaps following patterns in opendis7-java -->
    </target>
    <target name="clean.all.pduLogs">
        <ant dir="pduLog" antfile="build.xml" target="clean.all.pduLogs"/>
    </target>
    <!--
-    There exist several targets which are by default empty and which can be 
+    There exist several targets which are by default empty and which can be
-    used for execution of your tasks. These targets are usually executed 
+    used for execution of your tasks. These targets are usually executed
-    before and after some main targets. They are: 
+    before and after some main targets. They are:
      -pre-init:                 called before initialization of project properties
      -post-init:                called after initialization of project properties
      -pre-compile:              called before javac compilation
      -post-compile:             called after javac compilation
      -pre-compile-single:       called before javac compilation of single file
      -post-compile-single:      called after javac compilation of single file
      -pre-compile-test:         called before javac compilation of JUnit tests
      -post-compile-test:        called after javac compilation of JUnit tests
      -pre-compile-test-single:  called before javac compilation of single JUnit test
      -post-compile-test-single: called after javac compilation of single JUunit test
      -pre-jar:                  called before JAR building
      -post-jar:                 called after JAR building
      -post-clean:               called after cleaning build products
    (Targets beginning with '-' are not intended to be called on their own.)
    Example of inserting an obfuscator after compilation could look like this:
        <target name="-post-compile">
            <obfuscate>
                <fileset dir="${build.classes.dir}"/>
            </obfuscate>
        </target>
-    For list of available properties check the imported 
+    For list of available properties check the imported
-    nbproject/build-impl.xml file. 
+    nbproject/build-impl.xml file.
    Another way to customize the build is by overriding existing main targets.
-    The targets of interest are: 
+    The targets of interest are:
      -init-macrodef-javac:     defines macro for javac compilation
      -init-macrodef-junit:     defines macro for junit execution
      -init-macrodef-debug:     defines macro for class debugging
      -init-macrodef-java:      defines macro for class execution
      -do-jar:                  JAR building
-      run:                      execution of project 
+      run:                      execution of project
      -javadoc-build:           Javadoc generation
      test-report:              JUnit report generation
    An example of overriding the target for project execution could look like this:
        <target name="run" depends="Networked_Graphics_MV3500_examples-impl.jar">
            <exec dir="bin" executable="launcher.exe">
                <arg file="${dist.jar}"/>
            </exec>
        </target>
-    Notice that the overridden target depends on the jar target and not only on 
+    Notice that the overridden target depends on the jar target and not only on
-    the compile target as the regular run target does. Again, for a list of available 
+    the compile target as the regular run target does. Again, for a list of available
    properties which you can use, check the target you are overriding in the
-    nbproject/build-impl.xml file. 
+    nbproject/build-impl.xml file.
    -->
    <target name="view.examples.javadoc.local" depends="javadoc"
            description="view local MV3500 assignments javadoc in web browser (via Netbeans only)">
        <!-- no online javadoc -->
        <echo message="dist/javadoc/index.html"/>
        <nbbrowse file="dist/javadoc/index.html"/>
    </target>
    <target name="view.examples.gitlab" description="view gitlab MV3500 examples in web browser (via Netbeans only)">
        <echo message="https://gitlab.nps.edu/Savage/NetworkedGraphicsMV3500/tree/master/examples"/>
        <nbbrowse url="https://gitlab.nps.edu/Savage/NetworkedGraphicsMV3500/tree/master/examples"/>
    </target>
    <target name="view.opendis7.javadoc" description="view opendis7 javadoc documentation in web browser (via Netbeans only)">
        <echo message="https://savage.nps.edu/opendis7-java/javadoc"/>
        <nbbrowse url="https://savage.nps.edu/opendis7-java/javadoc"/>
    </target>
    <!-- ensure backwards compatibility of produced jar to specified version of Java, though project itself may be higher -->
    <!-- <property name="java.source"                 value="21"/>LTS -->
    <!-- <property name="java.target"                 value="21"/>LTS -->
    <!-- <property name="java.release"                value="21"/>LTS --><!-- simpler, less verbose than -source -target -->
    <property name="dist.javadoc.dir"            value="dist/javadoc"/>
    <property name="javadoc.additionalparam" value=""/>
    <property name="javadoc.author"          value="Don Brutzman brutzman@nps.edu"/>
    <property name="javadoc.dir"             value="${dist.javadoc.dir}"/>
    <property name="javadoc.encoding"        value="ISO-8859-1"/>
    <property name="javadoc.copyright"       value="Copyright &amp;#169; 1995-2024 held by the authors, &lt;a href='https://www.nps.edu'&gt;Naval Postgraduate School (NPS)&lt;/a&gt; under an &lt;a href='../license.html'&gt;open-source license&lt;/a&gt; and free for any use. &lt;a href='mailto:brutzman@nps.edu?subject=opendis7-java%20feedback'&gt;Feedback&lt;/a&gt; is welcome."/>
    <property name="javadoc.noindex"         value="false"/>
    <property name="javadoc.nonavbar"        value="false"/>
    <property name="javadoc.notree"          value="false"/>
    <property name="javadoc.private"         value="false"/>
 <!--<property name="javadoc.source"          value="${java.source}"/>-->
    <property name="javadoc.splitindex"      value="true"/>
    <property name="javadoc.breakiterator"   value="true"/>
    <property name="javadoc.use"             value="true"/><!-- Create class and package usage pages -->
    <property name="javadoc.version"         value="true"/>
    <property name="javadoc.windowtitle"     value="MV3500 Distributed Simulation Examples Javadoc"/>
    <property name="javadoc.doctitle"        value="${javadoc.windowtitle}"/>
    <!-- build.impl <javadoc additionalparam="-J-Dfile.encoding=${file.encoding} ${javadoc.additionalparam}" author="${javadoc.author}" charset="UTF-8" destdir="${dist.javadoc.dir}" docencoding="UTF-8" encoding="${javadoc.encoding.used}" failonerror="true" noindex="${javadoc.noindex}" nonavbar="${javadoc.nonavbar}" notree="${javadoc.notree}" private="${javadoc.private}" source="${javac.source}" splitindex="${javadoc.splitindex}" use="${javadoc.use}" useexternalfile="true" version="${javadoc.version}" windowtitle="${javadoc.windowtitle}"> -->
    <target name="javadoc.custom" depends="clean,compile" description="Customized javadoc">
        <echo message="$javac.classpath=${javac.classpath}"/>
-        <copy file="images/OpenDisSurferDude.png" todir="${javadoc.dir}"/> 
+        <copy file="images/OpenDisSurferDude.png" todir="${javadoc.dir}"/>
        <javadoc     destdir="${javadoc.dir}"
                     author="${javadoc.author}"
                     bottom="${javadoc.copyright}"
                     breakiterator="${javadoc.breakiterator}"
                     classpath="${x3djsail.stylesheets.dir}/${jsai.full.archive.jar.name};${run.test.classpath}"
                     Encoding="${javadoc.encoding}"
                     Doctitle="${javadoc.doctitle}"
                     Header="${javadoc.doctitle}"
                     maxmemory="4096m"
                     noindex="${javadoc.noindex}"
                     nonavbar="${javadoc.nonavbar}"
                     notree="${javadoc.notree}"
                     Overview="src/overview.html"
                     Private="${javadoc.private}"
                     Splitindex="${javadoc.splitindex}"
-                     Use="${javadoc.use}" 
+                     Use="${javadoc.use}"
                     useexternalfile="yes"
                     verbose="true"
                     version="${javadoc.version}"
                     windowtitle="${javadoc.windowtitle}">
                <!-- source="${java.source}" -->
            <classpath>
                <pathelement location="../lib/opendis7-full.jar"/>
                <pathelement location="../lib/open-dis_4.16.jar"/>
                <pathelement location="../lib/dis-enums-1.3.jar"/>
                <pathelement location="../lib/simkit.jar"/>
            </classpath>
            <fileset dir="." defaultexcludes="yes">
                <include name="src/**/*.java"/>
            </fileset>
        </javadoc>
        <antcall target="view.javadoc.local"/>
    </target>
    <target name="view.javadoc.local" description="view local package javadoc in web browser (Netbeans only)">
        <echo message="view local javadoc in ${dist.javadoc.dir} subdirectory"/>
        <nbbrowse file="${dist.javadoc.dir}/index.html" />
        <!-- TODO implementation-independent approach if possible, but note that other Ant approaches usually have to be customized for each OS. -->
    </target>
    <target name="view.javadoc.online" description="view online package javadoc in web browser (Netbeans only)">
        <echo message="TODO DEPLOY - view online javadoc in dist/javadoc subdirectory"/>
        <nbbrowse url="https://savage.nps.edu/opendis7-java/javadoc" />
        <!-- TODO implementation-independent approach if possible, but note that other Ant approaches usually have to be customized for each OS. -->
    </target>
    <target name="run.opendis.helper" depends="jar" description="Test run our OpenDisHelper">
        <java classpath="${viskit.proj.lib.dir}/${dist.name}.jar" classname="${opendis.helper}" fork="true">
            <classpath path="${file.reference.simkit.jar}"/>
            <classpath path="${file.reference.opendis7-full.jar}"/>
        </java>
    </target>
-    <target name="-post-jar">
+    <target name="-post-jar" description="compiles all classes into a single utility jar for MV3500 course use of viskit">
        <copy todir="${viskit.proj.lib.dir}">
            <fileset dir="${dist.dir}">
                <include name="${dist.name}.jar"/>
            </fileset>
        </copy>
    </target>
 </project>