vim-android.txt

*vim-android.txt*   For Vim version 7.3 or NeoVim   Last change: 2019 Jun 20

Author:         Horacio Sanson
Licence:        Vim licence, see |license|
Homepage:       https://github.com/hsanson/vim-android
Version:        1.6.1

==============================================================================
Contents                                   *vim-android* *vim-android-contents*

         1. Intro ........................... |vim-android-intro|
              Supported Features              |vim-android-features|
              Known Issues                    |vim-android-issues|
         2. Requirements .................... |vim-android-requirements|
         3. Installation .................... |vim-android-installation|
         4. Usage ........................... |vim-android-usage|
              Commands ...................... |vim-android-commands|
              Key mappings .................. |vim-android-keys|
              Omnicompletion ................ |vim-android-omnicomplete|
              Status Line.................... |vim-android-statusline|
                Airline Status Line.......... |vim-android-airline|
                LightLine Status Line........ |vim-android-lightline|
              Troubleshooting ............... |vim-android-troubleshooting|
         5. ALE Integration ................. |vim-android-ale|
         6. Configuration ................... |vim-android-configuration|
         7. Todo ............................ |vim-android-todo|
         8. Credits ......................... |vim-android-credits|

==============================================================================
1. Intro                                                      *vim-android-intro*

vim-android is a plugin that facilitates the development of Gradle and Android
applications within vim. When editing a java, kotlin or xml file this plugin
tries to find gradle.build file in the current directory and if found it
configures a set of variables and commands that allows easier development for
Gradle projects. If the gradle.build file contains the android gradle plugin
then Android specific commands are also configured.

------------------------------------------------------------------------------
SUPPORTED FEATURES                                         *vim-android-features*

The following features are supported by vim-android:

  - Auto-detection of Gradle and Android projects when opening a Java, kotlin or
    XML file. For this the plugin uses findfile function that searches from the
    current buffer path backwards until it finds a build.gradle file for the
    project.
  - Custom gradle vim task that invokes gradle directly with any arguments
    passed to the command.
  - Custom errorformat that captures java errors, linter errors, test errors,
    aapt errors and displays them in the loclist window. This
    requires that gradle be invoked with the vim init file loaded.
  - Updates the CLASSPATH environment variable to include paths for your
    current project, external libs, external lib-projects and the current
    target Android SDK jars. This allows auto-completion of Java code using
    other plugins.
  - Updates the SRCPATH environment variable to include source paths for the
    current project and dependencies if available. This allows debuggers like
    vebugger to follow source code during step debugging.
  - Generates .classpath file that works with Android projects.
  - Adds useful commands to compile and install your application APK into
    your emulator/devices.
  - Improved XML omnicompletion for Android resource and manifest XML files.
  - Takes advantage of neovim async functions to perfom long running tasks in
    the background (e.g. GradleSync)
  - Integration with ALE for linter and auto-completion support.

------------------------------------------------------------------------------
Known Issues                                                *vim-android-issues*

  - The first time an android java or xml file is opened we create a list of
    dependencies for the project and a cache with all the packages found in the
    gradle home folder. This process can be extremely slow depending on the
    number of dependencies the project has and the number of packages cached in
    your gradle home. When running in neovim with async functions these tasks do
    not block the interface but all Gradle and Android commands won't be
    available until the tasks complete in the background.

  - To get full support of AAPT errors in the loclist window of vim it is
    recommended that you use the android gradle plugin version 1.3.0 or newer.
    Previous versions of the android gradle plugin fail to show correctly the
    absolute path of the XML files that have errors making it difficult to jump
    to the problem files directly within vim.

        https://code.google.com/p/android/issues/detail?id=57513
        https://code.google.com/p/android/issues/detail?id=174778


==============================================================================
2. Requirements                                        *vim-android-requirements*

The following requirements have to be met in order to be able to use vim-android:

  - Vim 7.3 or a recent build of Neovim. This plugin may also work with previous
    versions but I have only tested Vim 7.3 and Neovim.
  - Android SDK installed and with the platform-tools directory set in your
    PATH environment variable.
    - Android gradle plugin 1.3.0 or newer recommended.
    - Android build tools 22.0.1 or newer recommended.
  - Gradle 2.2+ in your PATH or gradle wrapper script.

==============================================================================
3. Installation                                        *vim-android-installation*

It is recommended that you use a package manager like Pathogen or Vundle to
install this plugin. In the case of Vundle all you have to do is add this
line to your vimrc:
>
       Bundle 'hsanson/vim-android'
<
and then inside vim run the |:BundleInstall| command.

==============================================================================
4. Usage                                                      *vim-android-usage*

Before using this plugin you must tell it where you have the android SDK
installed. There are two ways to do this: you can set the ANDROID_HOME
environment variable to the absolute path of the android SDK or you can set
it to the global variable g:android_sdk_path in your vimrc file.

When you open a Java, Kotlin or XML file this plugin looks for a build.gradle
file starting from the location of the current open buffer upwards until your
HOME directory. If it is found this plugin activates and enables several
commands that faciliate working on Android projects and exports environment
variables that can be used by other plugins for omnicomplete and debugging.

Optionally you may also set |g:gradle_path| to tell the plugin where to look
for the gradle binaries. Check the options documentation below for more
details on these and other options.

------------------------------------------------------------------------------
COMMANDS                                                   *vim-android-commands*

:GradleSync
    Synchronizes the vim-android environment with that of the gradle.build
    file. This is run automatically when opening a buffer with a java, kotlin
    or xml file inside a gradle or android project. You should execute this
    command every time you make changes to your build.gradle file.

:GradleInfo
    Displays the output of the last command executed by the plugin. Useful
    for figuring out why something may not be working properly.

:Gradle <options>
    Invokes gradle passing the <options> verbatim. Any gradle options
    available via command line can be used using this command (e.g. :Gradle
    build).

:GradleGenClassPathFile
    Manually generate the .classpath file with all gradle dependencies and
    sources. This .classpath file is read by some tools like Eclipse JDT
    language server for lsp features.

    Note that this command is affected by |g:gradle_gen_classpath_file|
    configuration.

    After generating the .classpath file you may want to run |GradleSync| to
    update the language servers (Eclipse JDT) configurations. If after this
    you get unknown references it may be necessary to restart the language
    server itself.

    Warning: for now this command only works for Android projects. For non
    Android projects this command has no effect.

:Android <options>
    This is an alias to the Gradle command.

:AndroidInstall <mode>                                   *:AndroidDebugInstall*
    Build and installs the application in <mode> mode. In the case that you
    have several emulators running and/or several devices connected then this
    command will present you a list of emulators/devices so you can choose to
    which one the APK should be installed to. If there are not apk files
    build this command fails with an error. Current version of gradle can also
    install the APK on all connected devices so invoking :Gradle installDebug
    or :Gradle installRelease should have the same effect if you have a recent
    enough version of the android gradle plugin.

:AndroidUninstall                                           *:AndroidUninstall*
    This command allows to uninstall the application. If you have several
    emulators running and/or several devices connected, then this command will
    prompt you with a list of emulators/devices so you can choose from which one
    the app should be uninstalled. Current version of gradle can also uninstall
    the APKs from all connected devices so invoking :Gradle uninstallAll should
    have the same effect as long as you have a recent version of android gradle
    plugin.

:AndroidDevices                                               *:AndroidDevices*
    Lists all android devices connected and all running emulators.

:AndroidEmulator                                             *:AndroidEmulator*
    Allows to start defined avd emulators within vim.

------------------------------------------------------------------------------
KEY MAPPINGS                                                  *vim-android-keys*

By default the vim-android plugin has no mappings and all functionality is
accessed using the commands |vim-android-commands| but this does not impede
you from creating your own mappings.

For example you can map a function key (e.g. F5) to compile your project in
debug mode using:

>
  nmap <F5> <ESC>:Gradle assembleDebug<CR>
<

this way anytime you press the <F5> key it will build and install your
Android application.

Every time you modify the build.gradle file by adding or removing dependencies
it is a good idea to run the GradleSync command so the dependencies get loaded
into vim-android. If you are using NeoVim and have async |g:gradle_async|
enabled you may prefer to set an autocommand so this happens automatically.
For this simply add the following to your vim configuration:

>
  au BufWrite build.gradle call gradle#sync()
<

------------------------------------------------------------------------------
ANDROID OMNI-COMPLETION                              *vim-android-omnicomplete*

This plugin by itself does not provide omni-completion of Android classes
and/or methods. It is highly recommended to install ALE
(https://github.com/w0rp/ale) with the `eclipselsp` or `javalsp` LSP linter to get
this functionality.


------------------------------------------------------------------------------
STATUS LINE                                             *vim-android-statusline*

This plugin provides some methods that return strings indiciating the plugin
status.

Function |lightline#gradle#running()| returns |g:gradle_glyph_building|
followed with the number of running gradle jobs. If no jobs are currently
running then an empty string is returned.

Function |lightline#gradle#project()| returns |g:gradle_glyph_android| if the
current project is an android project, |g:gradle_glyph_gradle| if the
current project is a gradle project, or an empty string otherwise.

Function |lightline#gradle#errors()| returns |g:gradle_glyph_errors| followed
by the number of errors currently listed in the loclist.

Function |lightline#gradle#warnings()| returns |g:gradle_glyph_warnings| followed
by the number of warnings currently listed in the loclist.


                                                 *g:gradle_glyph_gradle*
g:gradle_glyph_gradle~
Default: "G"
>
        let g:gradle_glyph_gradle = 'U+e73a'
<
                                                 *g:gradle_glyph_android*
g:gradle_glyph_android~
Default: "A"
>
        let g:gradle_glyph_android = 'U+f17b'
<
                                                   *g:gradle_glyph_error*
g:gradle_glyph_error~
Default: "E"
>
        let g:android_airline_error_glyph = 'U+f06a'
<
                                                 *g:gradle_glyph_warning*
g:gradle_glyph_warning~
Default: "W"
>
        let g:gradle_glyph_warning = 'U+f071'
<
                                                 *g:gradle_glyph_building*
g:gradle_glyph_building~
Default: "B"
>
        let g:gradle_glyph_building... = 'U+f253'
<
Note: To use the examples above you must have a powerline enabled font. You
can use a program such as fontmatrix to browse the glyphs available in your
font and find the HEX representation. Once you know the HEX representation of
the glyph you can copy/paste it or input it by pressing <Ctrl+v> followed by
'u' and the HEX code in insert mode.

------------------------------------------------------------------------------
AIRLINE STATUS LINE                                      *vim-android-airline*

To show the gradle/android status line in Airline you can add the following to
your vim configuration to create airline gradle parts:
>
   call airline#parts#define_function(
       \ 'gradle-running',
       \ 'lightline#gradle#running'
       \)

   call airline#parts#define_function(
       \ 'gradle-errors',
       \ 'lightline#gradle#errors'
       \)

   call airline#parts#define_function(
       \ 'gradle-warnings',
       \ 'lightline#gradle#warnings'
       \)

   call airline#parts#define_function(
       \ 'gradle-project',
       \ 'lightline#gradle#project'
       \)
<
Then you can add the parts to any airline section you want:
>
   let g:airline_section_x= airline#section#create_right([
     \ 'filetype',
     \ 'gradle-running',
     \ 'gradle-errors',
     \ 'gradle-warnings'
     \])
<

Refer to airline documentation for details on how parts and sections are
defined and used.

------------------------------------------------------------------------------
LIGHTLINE STATUS LINE                                    *vim-android-lightline*

To show the gradle/android status line in Lightline you can add the following
to your vim configuration:

let g:lightline = {
  \ 'active': {
  \    'left': [ ['gradle_project'] ],
  \    'right': [ ['gradle_running'], ['gradle_errors'], ['gradle_warnings'] ]
  \ },
  \ 'component_expand': {
  \    'gradle_errors': 'lightline#gradle#errors',
  \    'gradle_warnings': 'lightline#gradle#warnings',
  \    'gradle_running': 'lightline#gradle#running',
  \    'gradle_project': 'lightline#gradle#project'
  \ },
  \ 'component_type': {
  \    'gradle_errors': 'error',
  \    'gradle_warnings': 'warning',
  \    'gradle_running': 'left',
  \    'gradle_project': 'left'
  \ }
  \ }

Read the Lightline documentation for details on how this configuration works and
adapt to your own usage.

------------------------------------------------------------------------------
TROUBLESHOOTING                                    *vim-android-troubleshooting*

Using neovim *health* feature you can check your environment setup running the
CheckHealth command:
>
        :checkhealth gradle
<
==============================================================================
5. ALE Integration                                             *vim-android-ale*

This plugin full potential is achieved when used in combination with the
ALE (https://github.com/w0rp/ale) plugin. When this plugin is installed and
configured we get additional features:

 - ALE with eclipselsp (jdtls) or javalsp linter gets support for
   linting, auto-completing, import, and go to definition of Android
   dependencies.
 - ALE gains a new `android` linter available for xml, java, kotlin, and
   groovy files. You need to add `android` to these file types in your
   |g:ale_linters| configuration.
 - vim-android benefits from all linters/fixers available in ALE like
   checkstyle, google_format, etc.
 - vim-android benefits from ALE auto-completion for java/kotlin files.

Example configuration for best ALE/vim-android combination:
>
    let g:gradle_loclist_show = 0
    let g:gradle_show_signs = 0

    let g:ale_linters = {
     \ 'xml': ['android'],
     \ 'groovy': ['android'],
     \ 'java': ['android', 'checkstyle', 'eclipselsp'],
     \ 'kotlin': ['android', 'ktlint', 'languageserver']
     \ }
<
Refer to ALE documentation for installation and configuration details of each
linter.

Both ALE and vim-android modify the loclist and buffer signs conflicting with
each other. Is recommended to set both |g:gradle_loclist_show| and
|g:gradle_show_signs| variables to 0 and let ALE take care of handling them.


==============================================================================
6. Configuration                                     *vim-android-configuration*

                                                            *g:android_sdk_path*
g:android_sdk_path~
Default: $ANDROID_HOME

This option must specify the location of your Android SDK installation.

Example:
>
        let g:android_sdk_path = '/opt/adroid-sdk'
<
                                                                  *g:gradle_bin*
g:gradle_bin~
Default: Gradle Wrapper

By default this plugin tries to use gradle wrapper script (e.g. gradlew) to
build the project unless this variable is set. If set then the plugin uses this
gradle binary to build all project. If this variable is not set and the
project does not have a gradle wrapper script, then the binary is searched
inside the GRADLE_HOME and PATH environment variables. See |g:gradle_path| for
a way to customize this behaviour.

Example:
>
    let g:gradle_bin=/opt/gradle/bin/gradle
<
                                                          *g:gradle_sync_on_load*
g:gradle_sync_on_load~
Default: 1

This plugin runs gradle#sync() the first time a java, kotlin, or xml file of a
project is open. This behavior can be disabled by setting this variable to 0.

                                                                 *g:gradle_path*
g:gradle_path~
Default: GRADLE_HOME

When the project has no gradle wrapper script and |g:gradle_bin| is not
defined, then this project tries to search for the gradle binary inside
GRADLE_HOME and PATH environment variables. If your gradle installation
is in a non-standard location you can change the search path by setting
this g:gradle_path variable:

Example:
>
    let g:gradle_path=/opt/gradle
<
The above will cause the plugin to search for the gradle binary in the
/bin directory within /opt/gradle folder.

                                                                *g:gradle_daemon*
g:gradle_daemon~
Default: 1

If this variable is 1 then gradle will be executed with the daemon option on.
This greatly improves the speed of builds and is recommended to let it
enabled. If for some reason you prefer to not run gradle in daemon mode then
set this variable to 0.

Example:
>
    let g:gradle_daemon=0
<

                                                            *g:android_adb_tool*
g:android_adb_tool~
Default: ${g:android_sdk_path}/tools/adb

This plugin relies heavily on the Android ADB tool to query devices/emulators
and to install the APK files. By default this tool is found inside the
Android SDK so you do not need to set this variable but if for some reason in
you installation the ADB tool is located in a different path you can
explicitly tell the plugin where to find it using this variable.

Example:
>
        let g:android_adb_tool=/path/to/tool/adb
<

                                                           *g:android_aapt_tool*
g:android_aapt_tool~
Default: ${g:android_sdk_path}/build-tools/{latest-version}/aapt2

Some functions such as AndroidLaunch require the aapt2 binary. By default this
plugin looks for the latest version of build tools installed inside the
android SDK path.

Example:
>
        let g:android_aapt_tool=/path/to/tool/aapt2
<

                                                        *g:gradle_loclist_show*
g:gradle_loclist_show~
Default: 0

Setting this variable will cause the plugin to open the loclist automatically
if there are any errors present. Since this may conflict with other plugins
that also modify the loclist (e.g. ALE) this is disabled by default.

Example:
>
        let g:gradle_loclist_show=1
<
                                                              *g:gradle_async*
g:gradle_async~
Default: 1

If you are running NeoVim then this plugin will execute gradle tasks in the
background using NeoVim job functions. If for some reason you need to disable
this functionality you can do so by setting this variable to zero.

Example:
>
        let g:gradle_async=0
<
                                                        *g:gradle_set_classpath*
g:gradle_set_classpath~
Default: 1

This plugin will automatically set the CLASSPATH and SRCPATH environment
variables after gradle sync task completes. But there are other plugins (e.g.
javacomplete2) that also set these environment variables. To avoid conflict
you can disable this feature by setting this configuration variable to 0. In
this case this plugin will not touch the CLASSPATH and SRCPATH environment
variables.

Example:
>
        let g:gradle_set_classpath=0
<
                                                   *g:gradle_gen_classpath_file*
g:gradle_gen_classpath_file~
Default: 1

This plugin will automatically generate a .classpath file with dependencies
after gradle sync task completes for Android projects. This file is required
for some language servers (e.g. Eclipse JDT) to figure out dependencies for
auto completion, auto import, and other useful functions. If you prefer to not
generate this file then set this configuration variable to 0.

Note that the .classpath file is generated only for Android projects. For
non-Android projects this configuration has no effect.

Example:
>
        let g:gradle_gen_classpath_file=0
<
                                                        *g:gradle_show_signs*
g:gradle_show_signs~
Default: 1 (0 if ALE is present)

This variable determines if the plugin should display vim signs marking
errors and warnings. To avoid conflict with ALE, this is disabled by default
if the ALE plugin is also installed and loaded.

Example:
>
        let g:gradle_show_signs=0
<
==============================================================================
7. Todo                                                       *vim-android-todo*

  - Project creation commands.

==============================================================================
8. Credits                                                 *vim-android-credits*

Contributors:

 - Donnie West (https://github.com/DonnieWest)
 - Grim Kriegor (https://github.com/GrimKriegor)

Ideas stolen from:

 - https://github.com/bpowell/vim-android
 - https://github.com/mgarriott/vim-android
 - http://flukus.github.io/2015/07/03/2015_07_03-Vim-errorformat-Demystified/

Recommended :

 - https://github.com/w0rp/ale

==============================================================================
 vim: tw=78 ts=8 sw=4 sts=4 et ft=help