*vim-java-ant.html*

Ant
***


Running
=======

For those that use Vim as an editor and ant as a build tool, is is
common to set your Vim 'makeprg' option to execute ant so that you may
navigate compilation errors via Vim's quickfix functionality.

Eclim utilizes this same paradigm to provide users with ant execution
functionality from any file without any of the setup required by Vim.

*:Ant*

Eclim provides the following command:

:Ant [<target> ...]

which performs the following steps:

- Saves any previous 'makeprg' and 'errorformat' option settings so
  that you can define your own settings for the :make command.
- Sets 'makeprg' to execute ant with the -find option so that it
  will search for your build.xml file in the current directory or in a
  parent directory.
- Sets 'errorformat' to recognize the following errors:
  - javac errors.
  - javadoc errors.
  - jasper jsp compilattion errors.
  - junit errors / failures.
  - cactus errors / failures.
- Executes :make.
- Restores your previous 'makeprg' and 'errorformat' option
  settings.
Additionally, if g:EclimMakeLCD (|vim-core-eclim#g:EclimMakeLCD|) is
enabled (which it is by default), then the execution of ant will be
performed from the current buffer's project root directory, ensuring
that ant's build file discovery method is performed from the buffer's
working directory and not your own.

Note: :Ant also supports use of '!' (:Ant!) just like :make does,
  which tells Vim not to jump to the first error if one exists.

The :Ant command also has the added benefit of command completion.

>

   :Ant com<Tab>
   :Ant compile

<


Warning: If your ant file has a lot of imports, then the command
  completion may be slow as Eclipse parses all the imports when
  creating the ant model.  You will notice the same slow behavior when
  using Eclipse directly to perform ant code completion.


Code Completion
===============

Ant code completion uses the standard Vim code completion mechanism
(vim-code_completion) like so:

>

   <ja<Ctrl-X><Ctrl-U>
   <jar de<Ctrl-X><Ctrl-U>
   <jar destfile="${bas<Ctrl-X><Ctrl-U>
   <jar destfile="${basdir
   ...

<


Screenshot of completion in action:

[image]

Warning: If your ant file has a lot of imports, then the code
  completion may be slow as Eclipse parses all the imports when
  creating the ant model.  You will notice the same slow behavior when
  using Eclipse directly.


Validation
==========

When editing an ant xml file eclim will default to validating the file
when it is written.  Any errors will be added to the current window's
location list (:help location-list) and their corresponding line
number noted via Vim's sign functionality.

Currently the Eclipse ant file validation isn't as robust as one might
hope.  It doesn't validate that element attributes are correct, that
child elements are valid, etc., but it does perform the following:

- If a default target is specified, validate that it exists and that
  the target dependencies exist.
- Check for missing dependencies.
- Check for circular dependencies.
Eclim also combines the above validation with xml validation
(vim-xml-index#xml-validation) to validate that the ant file is well
formed.

If you do not want your ant files validated automatically when saved,
you can set the |g:EclimAntValidate| variable described in the
configuration section below.

*:Validate_ant*

Whether or not auto validation has been enabled, eclim also exposes
the command :Validate to manually execute the validation of the ant
file.

*:AntDoc*


Documentation Lookup
====================

When editing an ant build file eclim defines a command named :AntDoc
which will attempt to lookup and open in your configured browser
(|vim-core-eclim#g:EclimBrowser|) the documentation for the element
under the cursor or, if supplied, the element passed to it.

This command will only lookup element names, not attribute names or
values.

By default this plugin is configured to find all the standard ant
tasks, types, etc, as well as those defined by the antcontrib
(http://ant-contrib.sourceforge.net) project.

*:AntUserDoc*

If you have other tasks that you wish to add to this plugin, you can
do so by defining the global variable g:EclimAntUserDocs. The value of
this variable is expected to be a map of element names to the url
where the documentation for that element can be found.  The url also
supports a substitution variable, <element> which will be substituted
with the lower case version of the element name.

The following is an example which adds the tasks from the apache
cactus project.

>

   let s:cactus =
     \ 'http://jakarta.apache.org/cactus/integration/ant/task_<element>.html'
   let g:EclimAntUserDocs = {
       \  'cactifywar'     : s:cactus,
       \  'cactifyear'     : s:cactus,
       \  'cactus'         : s:cactus,
       \  'runservertests' : s:cactus,
       \  'webxmlmerge'    : s:cactus,
     \ }

<



Configuration
=============

Vim Settings (vim-settings)

*g:EclimAntCompilerAdditionalErrorFormat*

- g:EclimAntCompilerAdditionalErrorFormat (Default: '') - Since
  there are many more ant tasks beyond javac, javadoc, etc., eclim
  provides this variable as a means to add error format information
  for any additional ant tasks that you may be using.
  Example: Adding support for xslt

  >
     let g:EclimAntCompilerAdditionalErrorFormat =
       \ '\%A%.%#[xslt]\ Loading\ stylesheet\ %f,' .
       \ '\%Z%.%#[xslt]\ %.%#:%l:%c:\ %m,'

  <

  Note: The xslt task is a bit flaky when it comes to reporting the
    file name on errors, so the above format will catch successful
    runs as well.  If anyone has a better solution, please submit it.

*g:EclimAntErrorsEnabled*

- g:EclimAntErrorsEnabled (Default: 0) - When non-zero, build file
  error messages will be added to vim's quickfix if encountered during
  :Ant invocations.  Disabled by default because it's difficult to
  distinguish between actual issues with the build file (invalid
  property, task, etc.) and build failure messages which occur under
  normal usage (junit task failed due to test failure, javac failures
  due to compile error, etc.) leading to false positives.
*g:EclimAntValidate*

- g:EclimAntValidate (Default: 1) - If set to 0, disables ant xml
  validation when saving the file.

Suggested Mappings
==================

Here are some mappings for the ant funtionality provided by eclim.  To
make use of these mappings, simply create a ftplugin file for ant and
place your mappings there (:help ftplugin-name).

- Lookup and open the documentation for the ant element under the
  cursor with <enter>.
  >
     noremap <silent> <buffer> <cr> :AntDoc<cr>

  <

vim:ft=eclimhelp