.. Copyright (C) 2005 - 2014 Eric Van Dewoestine
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
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** [ ...]
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 :ref:`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.
.. code-block:: vim
:Ant com
: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
:doc:`Vim code completion mechanism ` like so:
::
` 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 :ref:`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
:ref:`configured browser ` 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_ 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,
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.
.. code-block:: vim
let s:cactus =
\ 'http://jakarta.apache.org/cactus/integration/ant/task_.html'
let g:EclimAntUserDocs = {
\ 'cactifywar' : s:cactus,
\ 'cactifyear' : s:cactus,
\ 'cactus' : s:cactus,
\ 'runservertests' : s:cactus,
\ 'webxmlmerge' : s:cactus,
\ }
Configuration
-------------
:doc:`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
.. code-block:: vim
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
.
.. code-block:: vim
noremap :AntDoc
.. _antcontrib: http://ant-contrib.sourceforge.net