utils/jalopy/docs/plugin-ant-usage.html

   1
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.5)
   4  * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, G Barton, M Clamp, S Searle
   5  *
   6  * This file is part of Jalview.
   7  *
   8  * Jalview is free software: you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  18 -->
  19     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  20   <html><head>
  21       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  22    <title>5.3.&nbsp;Usage</title><link rel="stylesheet" href="site.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="manual.html" title="Jalopy User Manual"><link rel="up" href="plugin-ant.html" title="Chapter&nbsp;5.&nbsp;Ant Plug-in task"><link rel="previous" href="plugin-ant-config.html" title="5.2.&nbsp;Configuration"><link rel="next" href="plugin-ant-license.html" title="5.4.&nbsp;License"><link rel="preface" href="dedication.html" title="Dedication"><link rel="preface" href="acknowledge.html" title="Acknowledgements"><link rel="preface" href="introduction.html" title="Introduction"><link rel="part" href="part-core.html" title="Part&nbsp;I.&nbsp;Jalopy core"><link rel="chapter" href="installation.html" title="Chapter&nbsp;1.&nbsp;Installation"><link rel="chapter" href="build.html" title="Chapter&nbsp;2.&nbsp;Building"><link rel="chapter" href="usage.html" title="Chapter&nbsp;3.&nbsp;Usage"><link rel="chapter" href="settings.html" title="Chapter&nbsp;4.&nbsp;Settings"><link rel="part" href="part-plugins.html" title="Part&nbsp;II.&nbsp;Plug-ins"><link rel="chapter" href="plugin-ant.html" title="Chapter&nbsp;5.&nbsp;Ant Plug-in task"><link rel="chapter" href="plugin-console.html" title="Chapter&nbsp;6.&nbsp;Console Application"><link rel="chapter" href="plugin-eclipse.html" title="Chapter&nbsp;7.&nbsp;Eclipse Plug-in"><link rel="chapter" href="plugin-jbuilder.html" title="Chapter&nbsp;8.&nbsp;JBuilder OpenTool"><link rel="chapter" href="plugin-jdev.html" title="Chapter&nbsp;9.&nbsp;JDeveloper Extension"><link rel="chapter" href="plugin-jedit.html" title="Chapter&nbsp;10.&nbsp;jEdit Plug-in"><link rel="chapter" href="plugin-netbeans.html" title="Chapter&nbsp;11.&nbsp;NetBeans/Sun ONE Studio module"><link rel="appendix" href="dependencies.html" title="Appendix&nbsp;A.&nbsp;Library Dependencies"><link rel="appendix" href="license-bsd.html" title="Appendix&nbsp;B.&nbsp;The Jalopy BSD License"><link rel="appendix" href="license-antlr.html" title="Appendix&nbsp;C.&nbsp;ANTLR SOFTWARE RIGHTS"><link rel="appendix" href="license-apache.html" title="Appendix&nbsp;D.&nbsp;The Apache Software License, Version 1.1"><link rel="appendix" href="license-gnu.html" title="Appendix&nbsp;E.&nbsp;GNU GENERAL PUBLIC LICENSE Version 2, June 1991"><link rel="appendix" href="license-gnu-doc.html" title="Appendix&nbsp;F.&nbsp;GNU Free Documentation License Version 1.1, March 2000"><link rel="appendix" href="license-common-public.html" title="Appendix&nbsp;G.&nbsp;Common Public License Version 1.0"><link rel="appendix" href="license-sun-public.html" title="Appendix&nbsp;H.&nbsp;SUN PUBLIC LICENSE Version 1.0"><link rel="index" href="ix01.html" title="Index"><link rel="subsection" href="plugin-ant-usage.html#plugin-ant-usage-example" title="5.3.1.&nbsp;Example">
  23       <meta name="description" content="Jalopy Java Source Code Formatter Beautifier Pretty Printer">
  24       <meta http-equiv="pics-label" content='(pics-1.1 "http://www.icra.org/ratingsv02.html" l gen true for "http://jalopy.sf.net" r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true for "http://jalopy.sf.net" r (n 0 s 0 v 0 l 0))'>
  25     </head><body id="toppage" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table width="700" border="0" cellpadding="0" cellspacing="0" align="left"><tbody><tr><td><table cellpadding="0" cellspacing="0" width="100%" style="border:1px solid #336699"><tbody><tr><td height="16"></td></tr><tr><td bgcolor="#3399cc" height="1"></td></tr><tr style="border:none"><td style="border:none"><table border="0" cellspacing="0" cellpadding="0"><tbody><tr><td class="logo">JALOPY</td><td class="sublogo" valign="bottom">Java Source Code Formatter Beautifier Pretty Printer</td></tr></tbody></table></td></tr><tr><td bgcolor="#3399cc" height="1"></td></tr><tr><td height="10"></td></tr><tr><td bgcolor="#ff8000" height="4"></td></tr><tr><td height="20" bgcolor="#336699" style="color:#ffffff;padding-left:10px"><a href="./index.html" class="navlink">Overview</a> &#149;
  26                     <a href="./download.html" class="navlink">Download</a> &#149;
  27                     <a href="./docs.html" class="navlink">Documentation</a> &#149;
  28                     <a href="./plugins.html" class="navlink">Plug-ins</a> &#149;
  29                     <a href="./links.html" class="navlink">Links</a> &#149;
  30                     <a href="./contact.html" class="navlink">Contact</a></td></tr><tr><td height="1" bgcolor="#ffffff"></td></tr></tbody></table></td></tr><tr valign="top"><td valign="top" bgcolor="#ffffff"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tbody><tr><td height="20" bgcolor="#faebd7" style="padding-left:15px"><a href="./features.html" class="navlink2">Features</a> |
  31                     <a href="./history.html" class="navlink2">History</a> |
  32                     <a href="./manual.html" class="navlink2">Manual</a> |
  33                     <a href="./faq.html" class="navlink2">FAQ</a> |
  34                     <a href="./api/index.html" class="navlink2">Javadoc</a></td></tr><tr><td height="20" bgcolor="#ffffff"></td></tr><tr><td bgcolor="#eeeecc" height="17" align="right" style="font-size:10px;padding-right:3px">
  35                     This page generated: <strong>June 8 2004</strong></td></tr></tbody></table><table border="0" width="100%" cellspacing="0" cellpadding="5"><tr><td><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.3.&nbsp;Usage</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="plugin-ant-config.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;Ant Plug-in task</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="plugin-ant-license.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="plugin-ant-usage"></a>5.3.&nbsp;Usage</h2></div></div><div></div></div><p>
  36 The Jalopy task can take a few parameters to control the runtime behavior of
  37 Jalopy. If omitted, your current preferences settings will be used.
  38 </p><p>
  39 Nested <a href="http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html" target="_top">FileSets</a>
  40 can and should be used to specify the source files and/or directories.
  41 </p><div class="table"><a name="tab-ant-params"></a><p class="title"><b>Table&nbsp;5.1.&nbsp;Jalopy Ant task parameters</b></p><table summary="Jalopy Ant task parameters" cellspacing="0" cellpadding="3" border="0" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col><col><col></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Attribute</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Description</th><th style="border-bottom: 0.5pt solid ; ">Required</th></tr></thead><tbody><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">backup</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Indicates whether backup copies for all file sources should be kept.</td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">classpathrev</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">The classpath to setup the class repository with, given as a <a href="http://jakarta.apache.org/ant/manual/using.html#references" target="_top">reference</a> to a path defined elsewhere. If you want the <a href="imports.html#import-optimization" title="4.3.7.3.&nbsp;Optimize">import optimization feature</a> to work, you have to specify the classpath reference you use to compile your sources here.</td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">convention</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Sets the location to the convention file to use - given either relative to the project's basedir or as an absolute local path or internet address. If omitted, the current settings are used, if available. Otherwise the Jalopy build-in defaults will be used.</td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">destdir</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Sets the destination directory to create/copy all formatting output into. If the given directory does not exist, it will be created. If this attribute is ommitted, all input files will simply be overriden.</td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">encoding</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Sets the encoding that controls how Jalopy interprets text files containing characters beyond the ASCII character set. Defaults to the platform default encoding.</td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">failonerror</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Indicates whether a run should be held if errors occured. Defaults to "true".</td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">file</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Specifies a single source file to format.</td><td style="border-bottom: 0.5pt solid ; ">Yes, if no fileset is specified.</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">fileformat</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Sets the file format of the output files. The file format controls what end of line character is used. Either one of "UNIX", "DOS", MAC", "DEFAULT" or "AUTO" can be used. Defaults to "AUTO" (case insensitive).</td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">force</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Indicates whether the formatting of files should be forced, even if the file is up-to-date.</td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">history</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Specifies the history policy to use. Either one of
  42   "COMMENT", "FILE" or
  43   "NONE" can be used.
  44   </td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">javadoc</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Indicates whether Javadoc related messages should be printed.</td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">loglevel</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Specifies the logging level for message output. Either one of
  45   "ERROR", "WARN", "INFO" or "DEBUG" can be used.</td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr style="border-bottom: 0.5pt solid ; "><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">style</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">DEPRECATED. See <span class="emphasis"><em>convention</em></span></td><td style="border-bottom: 0.5pt solid ; ">No</td></tr><tr><td style="border-right: 0.5pt solid ; ">threads</td><td style="border-right: 0.5pt solid ; ">Specifies the number of processing threads to use. Integer between <tt class="literal">1</tt> - <tt class="literal">8</tt>.
  46   </td><td style="">No</td></tr></tbody></table></div><p></p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="plugin-ant-usage-example"></a>5.3.1.&nbsp;Example</h4></div></div><div></div></div><p>
  47 The following example demonstrates how you can make use of the Jalopy Ant task.
  48 </p><p>
  49 Note that the "format" target depends on the "compile" target.
  50 This way we can be sure that the given classpathref does cover all types used
  51 in your sources (and this is an absolute necessity for the import optimization feature
  52 to work reliable).
  53 </p><div class="example"><a name="ex-ant-build-file"></a><p class="title"><b>Example&nbsp;5.1.&nbsp;Example Ant build file</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
  54 &lt;?xml version="1.0" ?&gt;
  55 &lt;project name="myProject" default="format" basedir="." &gt;
  56
  57   &lt;property name="dir.jalopy" value="/mystuff/jalopy/bin" /&gt;
  58   &lt;property name="dir.lib" value="${basedir}/ext/lib" /&gt;
  59   &lt;property name="dir.compile" value="${basedir}/tmp~/build/classes" /&gt;
  60   &lt;property name="dir.src.java" value="${basedir}/src/java" /&gt;
  61
  62   &lt;!-- ==================================================================== --&gt;
  63   &lt;!-- Defines the Jalopy task                                              --&gt;
  64   &lt;!-- ==================================================================== --&gt;
  65   &lt;taskdef name="jalopy"
  66            classname="de.hunsicker.jalopy.plugin.ant.AntPlugin"&gt;
  67     &lt;!--
  68
  69       we did not copy the needed .jars into the /lib directory of Ant in order
  70       to avoid possible classpath issues, so we have to specify a lookup
  71       classpath here
  72
  73       --&gt;
  74     &lt;classpath&gt;
  75       &lt;fileset dir="${dir.jalopy}"&gt;
  76         &lt;include name="*.jar" /&gt;
  77       &lt;/fileset&gt;
  78     &lt;/classpath&gt;
  79   &lt;/taskdef&gt;
  80
  81
  82   &lt;!-- ==================================================================== --&gt;
  83   &lt;!-- Defines the project classpath                                        --&gt;
  84   &lt;!-- ==================================================================== --&gt;
  85   &lt;path id="project.classpath" &gt;
  86
  87     &lt;!-- our compilation directory --&gt;
  88     &lt;pathelement location="${dir.compile}" /&gt;
  89
  90     &lt;!-- needed 3rd party libraries --&gt;
  91     &lt;fileset dir="${dir.lib}" &gt;
  92       &lt;include name="**/*.jar" /&gt;
  93     &lt;/fileset&gt;
  94   &lt;/path&gt;
  95
  96
  97   &lt;!-- ==================================================================== --&gt;
  98   &lt;!-- Compiles the project sources                                         --&gt;
  99   &lt;!-- ==================================================================== --&gt;
 100   &lt;target name="compile"
 101           depends="init"&gt;
 102     &lt;javac destdir="${dir.compile}"
 103            fork="true"&gt;
 104       &lt;classpath refid="project.classpath" /&gt;
 105       &lt;src path="${dir.src.java}" /&gt;
 106     &lt;/javac&gt;
 107   &lt;/target&gt;
 108
 109
 110   &lt;!-- ==================================================================== --&gt;
 111   &lt;!-- Formats all source files                                             --&gt;
 112   &lt;!-- ==================================================================== --&gt;
 113   &lt;target name="format" depends="compile"&gt;
 114
 115     &lt;!--
 116
 117       Invokes Jalopy as follows:
 118
 119       - All formatted files will have unix fileformat (\n)
 120       - Load your code convention from the given url
 121       - Override the convention to use the file history feature
 122       - Override the convention to use alder32 checksums of files for history testing
 123       - Override the convention to use loglevel "info"
 124       - Override the convention to use 2 threads
 125       - The import optimization feature will work (if enabled in the active
 126         convention), because a classpath reference is specified
 127
 128         Don't forget to setup an include pattern as Jalopy truly expects
 129         valid Java source files as input!
 130
 131       --&gt;
 132     &lt;jalopy fileformat="unix"
 133             convention="http://www.foo.com/myConvention.xml"
 134             history="file"
 135             historymethod="adler32"
 136             loglevel="info"
 137             threads="2"
 138             classpathref="project.classpath"&gt;
 139       &lt;fileset dir="${dir.src.java}"&gt;
 140         &lt;include name="**/*.java" /&gt;
 141       &lt;/fileset&gt;
 142     &lt;/jalopy&gt;
 143   &lt;/target&gt;
 144 &lt;/project&gt;
 145 </pre></td></tr></table></div><p></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plugin-ant-config.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="plugin-ant.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="plugin-ant-license.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.2.&nbsp;Configuration&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.4.&nbsp;License</td></tr></table></div></td></tr></table></td></tr><tr><td bgcolor="#eeeecc" height="17" style="font-size:9px;padding-left:5px"><a href="#toppage">to top</a></td></tr><tr><td height="30"><br></td></tr><tr><td height="3"></td></tr><tr><td bgcolor="#336699" height="1"></td></tr><tr><td height="1"></td></tr><tr><td bgcolor="#336699" height="16"></td></tr><tr><td bgcolor="#ff9966" height="4"></td></tr><tr><td class="footer" align="center" height="15" valign="middle">
 146             Copyright &copy; 2001-2004, <a class="footer" href="./contact.html">Marco Hunsicker</a>. All rights reserved. Hosted by <a href="http://sourceforge.net">SourceForge.net</a></td></tr></tbody></table><img src="http://sourceforge.net/sflogo.php?group_id=45216&amp;type=1" width="1" height="1" border="0" hspace="0" vspace="0" alt=""></body></html>