Note 1: the token string must not contain the separators chars (@).
Note 2: Either token and value attributes must be provided, or only the
-filterfile attribute.
Parameters
| includeAntRuntime | whether to include the Ant run-time libraries;
- defaults to no. |
+ defaults to No | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| longfile | -Controls how long paths are handled. Allowable - values are "gnu" and "truncate" | -No | +Determines how long files (>100 chars) are to be + handled. Allowable values are "truncate", "fail", + "warn", "omil" and "gnu". Default is + "warn". + | No | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| includes | diff --git a/docs/manual/Integration/VAJAntTool.html b/docs/manual/Integration/VAJAntTool.html index 071c6796f..f64cbeb6f 100644 --- a/docs/manual/Integration/VAJAntTool.html +++ b/docs/manual/Integration/VAJAntTool.html @@ -3,133 +3,619 @@ -
| VAJLoad + |
+ loads specified versions into the workspace + |
+
| VAJExport + |
+ exports specified packages into the file system + |
+
| VAJImport + |
+ imports specified files into the workspace + |
+
+
VAJLoad
+Description:
+Loads a specified VAJ project version into the workspace.
+ +Parameters
+none
+ +Parameters specified as nested elements
+vajproject
+| Attribute | +Description | +Required | +
| name | +name of the VAJ project to load into the workspace | +yes | +
| version | +name of the requested version | +yes | +
Example
++<vajload> + <vajproject name="My Testcases" version="1.7beta" /> + <vajproject name="JUnit" version="3.2" /> +</vajload> ++ +
+
VAJExport
+ +Description:
+Exports Java source files, class files and/or resources from the workspace +to the file system. Exports can be specified by giving the VAJ project +name and package name(s). This works very similar to +FileSets.
+ +Parameters
+| Attribute | +Description | +Required | +
| destdir | +location to store the exported files | +yes | +
| exportSources | +export source files (default: "yes") | +no | +
| exportResources | +export resource files (default: "yes") | +no | +
| exportClasses | +export class files (default: "no") | +no | +
| exportDebugInfo | +include debug info in exported + class files (default: "no") | +no | +
| defaultexcludes | +use default excludes when exporting (default: "yes") + | no | +
Parameters specified as nested elements
+ +include
+specifies the packages to include into the export + +| Attribute | +Description | +Required | +
| name | +name of the VAJ project and package to export. + The first element of the name must be the project name, + then the package name elements separated by '/'. |
+ yes | +
exclude
+specifies the packages to exclude from the export+ +
| Attribute | +Description | +Required | +
| name | +name of the VAJ project/package not to export | +yes | +
Example
+
+<vajexport destdir="${src.dir}" exportResources="no">
+ <include name="MyProject/**"/>
+ <exclude name="MyProject/test/**"/>
+</vajexport>
+
+This example exports all packages in the VAJ project 'MyProject', except
+packages starting with 'test'.
++
VAJImport
+ +Description:
+Imports Java source files, class files and/or resources from the file +system into VAJ. These imports can be specified with a fileset.
+Parameters
+| Attribute | +Description | +Required | +
| vajProject | +imported files are added to this VAJ project | +yes | +
| importSources | +export source files (default: "yes") | +no | +
| importResources | +export resource files (default: "yes") | +no | +
| importClasses | +export class files (default: "no") | +no | +
Parameters specified as nested elements
+ +fileset
+A FileSet specifies the files to import. + +Example
+
+<vajimport project="Test" importClasses="true">
+ <fileset dir="${import.dir}">
+ <include name="com/sample/**/*.class"/>
+ <exclude name="com/sample/test/**"/>
+ </fileset>
+</vajimport>
+
+This example imports all class files in the directory ${import.dir}/com/sample
+excluding those in the subdirectory test+ +
+
A sample build file
+This is a sample build file which builds a zip file useful for distribution +of the VAJ plugin. The build file exports a specific version of Ant, compiles +it, extracts necessary helper classes and zips everything together. This +is useful as complete example as well as to deploy Ant in a team where all +developers use VAJ. The resulting zip file must be unzipped in +<VAJInstallDir>\ide\tools\org-apache-tools-ant. +For more information see the installation section.+
+
+<?xml version="1.0"?>
+<!-- ======================================================================= -->
+<!-- Builds a binary distribution of the VAJ Ant Plugin -->
+<!-- ======================================================================= -->
+<project name="anttool" default="buildall" basedir="c:\temp\anttool">
+
+ <property name="src.dir" value="${basedir}/src"/>
+ <property name="zip.dir" value="${basedir}/dist"/>
+ <property name="build.classes" value="${basedir}/classes"/>
+
+ <!-- location of the unzipped Ant source distribution -->
+ <property name="antdistribution.dir" value="u:\ant-1.3beta1"/>
+
+ <!-- VAJ install dir -->
+ <property name="vaj.dir" value="C:\IBMVJava2"/>
+
+ <path id="classpath">
+ <pathelement location="${src.dir}"/>
+ <pathelement location="${vaj.dir}\IDE\project_resources\IBM IDE Utility class libraries" />
+ <pathelement location="${build.classes}"/>
+ </path>
+
+
+ <!-- =================================================================== -->
+ <!-- Load Projects into Workspace -->
+ <!-- =================================================================== -->
+ <target name="load" description="load projects">
+ <vajload>
+ <project name="Ant" version="1.3"/>
+ <project name="Apache Oro RegExp" version="2.0.1"/>
+ </vajload>
+ </target>
+
+
+ <!-- =================================================================== -->
+ <!-- Creates the build dirs -->
+ <!-- =================================================================== -->
+ <target name="preparedirs">
+ <mkdir dir="${basedir}"/>
+ <mkdir dir="${src.dir}"/>
+ <mkdir dir="${zip.dir}"/>
+ <mkdir dir="${build.classes}"/>
+ </target>
+
+
+ <!-- =================================================================== -->
+ <!-- Export from VA -->
+ <!-- =================================================================== -->
+ <target name="export" depends="preparedirs" description="export projects">
+ <mkdir dir="${src.dir}"/>
+ <!-- Export all Ant sources except optional tasks and the Oro sources -->
+ <vajexport destdir="${src.dir}">
+ <include name="Ant/**"/>
+ <exclude name="Ant/**/optional/**"/>
+ <exclude name="Ant/org/apache/tools/ant/gui/**"/>
+ <include name="Apache Oro*/**"/>
+ </vajexport>
+ <!-- Export selected optional tasks -->
+ <vajexport destdir="${src.dir}">
+ <include name="Ant/org/apache/tools/ant/taskdefs/optional/ide/**"/>
+ </vajexport>
+ </target>
+
+ <!-- =================================================================== -->
+ <!-- Unzip necessary libraries -->
+ <!-- =================================================================== -->
+ <target name="expand">
+ <mkdir dir="${build.classes}"/>
+ <unzip src="${antdistribution.dir}\lib\parser.jar"
+ dest="${build.classes}"
+ />
+ <unzip src="${antdistribution.dir}\lib\jaxp.jar"
+ dest="${build.classes}"
+ />
+ <delete dir="${build.classes}\META-INF" />
+ </target>
+
+ <!-- =================================================================== -->
+ <!-- Compile the source code -->
+ <!-- =================================================================== -->
+ <target name="compile" depends="expand" description="compile java sources">
+ <mkdir dir="${build.classes}"/>
+ <javac srcdir="${src.dir}"
+ destdir="${build.classes}"
+ debug="on"
+ deprecation="off"
+ optimize="on" >
+ <classpath refid="classpath" />
+ <include name="org/apache/**"/>
+ <exclude name="**/JakartaRegexpMatcher.java"/>
+ </javac>
+ </target>
+
+ <!-- =================================================================== -->
+ <!-- Copy resources and zip everything together -->
+ <!-- =================================================================== -->
+ <target name="zip" depends="compile" description="creates zip distribution">
+ <copy todir="${build.classes}">
+ <fileset dir="${src.dir}">
+ <include name="org/apache/**"/>
+ <exclude name="**/*.java"/>
+ </fileset>
+ </copy>
+ <mkdir dir="${build.classes}/doc"/>
+ <copy todir="${build.classes}/doc" overwrite="yes">
+ <fileset dir="${antdistribution.dir}/docs">
+ <include name="VAJAnttool.html, toolmenu.gif, anttool1.gif"/>
+ </fileset>
+ </copy>
+ <copy file="${antdistribution.dir}/src/main/org/apache/tools/ant/taskdefs/optional/ide/default.ini" todir="${build.classes}" overwrite="yes"/>
+ <mkdir dir="${zip.dir}"/>
+ <zip basedir="${build.classes}" zipfile="${zip.dir}/anttool.zip" />
+ </target>
+
+ <!-- =================================================================== -->
+ <!-- Cleans source and class dirs -->
+ <!-- =================================================================== -->
+ <target name="clean" depends="preparedirs" description="removes all files from src and build tree">
+ <delete>
+ <fileset dir="${src.dir}"/>
+ </delete>
+ <delete>
+ <fileset dir="${build.classes}"/>
+ </delete>
+ <delete>
+ <fileset dir="${zip.dir}"/>
+ </delete>
+ </target>
+
+ <!-- =================================================================== -->
+ <!-- Cleans the build dir, loads required project versions, exports, -->
+ <!-- compiles and zips the Plugin -->
+ <!-- =================================================================== -->
+ <target name="buildall" depends="clean, load, export, zip" description="build all">
+ </target>
+</project>
+
+
++
The Plugin
+The tasks are usable within VAJ by running the +org.apache.tools.ant.Main class, but this is +quite inconvenient. Therefore a small GUI is +provided which allows selecting a build file +and executing its targets. This Plugin is accessible +from the VAJ Tools menu (see Usage). +Installation
-At the moment the installation has it's rough edges. If something described -below doesn't work for You, it's probably not Your fault but incomplete/wrong -instructions. In this case, please contact one of the -authors.-We assume C:\IBMVJava as VAJ install directory. -If you have installed it elsewhere, adapt the paths below. Execute following -steps to get the PlugIn up and running: +At the moment the installation has it's rough edges. If something +described below doesn't work for You, it's probably not Your fault +but incomplete/wrong instructions. In this case, please contact one +of the authors. +We assume C:\IBMVJava as VAJ install +directory. If You have installed it elsewhere, adapt the pathes below. +Execute following steps to get the PlugIn up and running:
-
-
- import the Ant sources into VAJ. +
- install the Visual Age IDE Tools (via File->Quick Start-> + Add feature->'IBM IDE Utility class libraries' +
- import an appropriate XML parser to VAJ (we use Xerces 1.2.0 and are - happy with it). Unfortunately the XML parser delivered with VAJ (in the - project 'IBM XML Parser for Java') doesn't work with Ant. You have to - remove that project (temporarily) from the workspace before importing - another XML implementation. + happy with it). Unfortunately the XML parser delivered with VAJ (in + the project 'IBM XML Parser for Java') doesn't work with Ant. You have to + remove that project (temporarily) from the workspace before importing another + XML implementation. + + +
- import the Ant sources into VAJ.
- Create the directory - C:\IBMVJava\ide\tools\org-apache-tools-ant. + C:\IBMVJava\ide\tools\org-apache-tools-ant. +
- export the Ant and XML parser class files into this directory. Be sure - to select class files and resources. Sources don't have to be exported. - Some optional tasks have errors and can't be exported when You don't have - the necessary packages in Your workspace (e.g. junit task, ejbc task). - If You need this tasks either import these packages into VAJ, too, - or copy the .class files directly from the binary distribution -
- copy default.ini (in - jakarta-ant\src\...\taskdefs\optional\ide) - to - C:\IBMVJava\ide\tools\org-apache-tools-ant\default.ini. -
- if you want to access this help from the Workbench, create the - directory - C:\IBMVJava\ide\tools\org-apache-tools-ant\doc and copy the files - VAJAntTool.html, - toolmenu.gif and - anttool1.gif to it. + to select class files and resources. Sources don't have to be exported. + Some optional tasks have errors and can't be exported when You + don't have the necessary packages in Your workspace (e.g. junit + task, ejbc task). If You need this tasks either import these packages + into VAJ, too, or copy the .class files directly from the binary + distribution. + +
- copy default.ini (in + jakarta-ant\src\...\taskdefs\optional\ide) to + C:\IBMVJava\ide\tools\org-apache-tools-ant\default.ini. + +
- if you want to access this help from the Workbench, create the + directory C:\IBMVJava\ide\tools\org-apache-tools-ant\doc + and copy the files VAJAntTool.html, + toolmenu.gif and + anttool1.gif to it. +
- VAJ has to be restarted to recognize the new tool.
- Now if You open the context menu of a project, You should see the entry - 'Ant Build' in the Tools submenu (see Usage). + 'Ant Build' in the Tools submenu (see Usage). +
- Make sure the tool works as expected. Now You can remove Ant and the - imported XML parser from Your workspace (and optionally add the IBM parser - again). + imported XML parser from Your workspace (and optionally add the + IBM parser again). +
Usage
-Being sure the tool is installed correctly and your Ant build file is -configured, it is really easy to use.-Go to your Workbench, select the project you want to deploy and open -its context menu. In the submenu Tools you should find the new -entry Ant Build. Click it to start the tool! -
-
-
+Go to your Workbench, select the project you want to deploy and +open its context menu. In the submenu Tools you should find +the new entry Ant Build. Klick it to start the tool! + +
- A menubar with some options described later
- The name of your selected VAJ project -
- An entry field for the Ant XML buildfile with a browse [...] button. The - full qualified filename, including the directory is needed here. -
- A list with tasks specified in the buildfile. Until your first save of - the build info (described later), this list will be empty. When loading a - build file by the Reload Project button, this list is filled with - all tasks which have a description attribute. The task you select in this - list will be executed when pressing the Execute Task button. +
- An entry field for the Ant XML buildfile with a browse [...] button. + The full qualified filename, including the directory is needed here. + +
- A list with tasks specified in the buildfile. Until your first save + of the build info (described later), this list will be empty. When + loading a build file by the Reload Project button, this list + is filled with all tasks which have a description attribute. The + task you select in this list will be executed when pressing the + Execute Task button. +
- A pulldown box for specifying the log level.
- Three buttons. Two of them I have already described and the third one - is just the Close button to exit our small tool! + is just the Close button to exit our small tool! +
-If you have closed the log window accidentally, it can be reopened with -the Log item in the File menu, and if you want to know who -developed this, just select About in the Help menu. -
+After you have set up your buildprocess you might find it useful +to save the data you've just entered, so we implemented an option to +save it to the repository into your selected project. Make sure that you +have an open edition of your project before selecting +Save BuildInfo To Repository from the File menu. +Now your information is saved to this edition of your project and will +be loaded automatically the next time you start Ant Build.
+If you have closed the log window accidentally, it can be reopened +with the Log item in the File menu, and if you want to +know who developed this, just select About in the Help menu.
Frequently Asked Questions
-F: I want to load, export and build more then one Visual Age project to
-one jar! How to?
-A: The VA tasks are able to load and export several Projects all at
-once. You can choose whatever project you like for storing the tool
-information, it doesn't really matter.
Q: I want to load, export and build more then one Visual Age project
+to one jar! How to?
+A: The VA tasks are able to load and export several Projects all
+at once. You can choose whatever project you like for storing the tool
+information, it doesn't really matter
+
Q: When I load my build file, the list of targets is empty. Why?
+A: You need to add the optional "description" parameter to the targets You
+want to come up in the list. Then reload the build file in the "ant build"
+tool. We chose to display only targets with description to allow the build
+file developer to distinguish between targets for end users and helper targets.
+
Q: Is there a sample build file available?
+A: Now You can find an example in this manual
+
Q: Why does it export my entire workspace when I've already implicitly
+selected a project when starting the Tool?
+A: This selection does not carry into the buildfile you are using. Set the
+Project name at the beginning of the "includes" parameter.
+
Q: When I import Ant into my Workspace, I get Problems reported. Can I
+ignore them?
+A: It depends on the problems reported, and what you want to do with Ant.
+Problems you can't ignore:
+
-
+
- Classes from javax.xml.parser missing - install a compatible parser + (see installation) + +
- Classes from com.ibm.ivj.util missing - install the Visual Age IDE + Utility feature (see installation). + +
Q: Why is the task name vajload when the class is called VAJLoadProjects?
+A: At the moment this task can load only project versions. This is reflected
+by the class name. It may be extended to load package and class versions,
+too, and we didn't want to let these extensions affect the build files. Therefore
+we chose the more general name vajload as task name.
+
Q: I want to use the same buildfile both within Visual Age and from the
+command line using my regular Ant environment. What do I need to be aware
+of?
+A: The three Visual Age Tasks won't work when executing Ant from the command
+line.
+
Q: How do I control the import/export of sourcefiles, compiled files and
+project resources explicity?
+A: Via the Boolean values exportClasses (default false) exportSources (default
+true) and exportResources (default true). In some situations, Resources are
+not exported correctly without this being explicity set.
+
+
Known Problems
+-
+
- Exporting a package containing just resources doesn't work. This is + a VAJ Tool API bug. Workaround: create a dummy class and set 'exportSources' + to false. + +
+
VisualAge for Java Versions
-This tool integration has been tested with versions 3.02 and 3.5 of VisualAge -for Java. It should run with the 2.x Versions, too, but we didn't try. -The graphical user interface is build with AWT so it is JDK independent -by now!+This tool integration has been tested with versions 3.02 and 3.5 +of VisualAge for Java. It should run with the 2.x Versions, too, but +we didn't try. The graphical user interface is build with AWT so it is +JDK independent by now. +
+ +
History
+| 1.0 | +2000/09/11 | +Initial Version | +
| 1.1 | +2001/02/14 | +Added Task documentation and more FAQs (thanks to + Richard Bourke for the FAQ additions) + | +
-
Copyright © 2000 Apache Software Foundation. -All rights Reserved.