Dreaded_X/dotfiles
1
0
Fork 0
Code Issues 3 Pull Requests Packages Projects Releases Wiki Activity

Installed eclim + remved autocomplete plugins

Browse Source
This commit is contained in:
Dreaded_X
2014-08-31 22:16:01 +02:00
parent 9b88b794a1
commit ce98650c57
226 changed files with 32126 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
vim/bundle/eclim/doc/development/architecture.txt Normal file
View File

@@ -0,0 +1,38 @@
*development-architecture*
Architecture
************
The eclim architecture is pretty straight forward. Commands issued by
a user in vim are relayed via nailgun
(http://www.martiansoftware.com/nailgun/) to the running eclim daemon
and the proper command implementation is then located and executed.
Here is a diagram showing the sequence in a bit more detail:
[diagram]
The commands which are executed on the eclimd side are also fairly
simple. They accept an object containing the command line parameters
passed into the eclim invocation and then return an object (String,
Collection, etc) which is converted to a json response. Below is a
simple class diagram showing the hierarchy of a couple typical
commands.
[diagram]
Another important aspect of eclim's architecture is support for
plugins. Plugins for eclim are bundled as eclipse plugins with their
auto start attribute set to false. When the eclim daemon starts it
will locate and load any eclipse plugin with an 'org.eclim.' prefix.
When a plugin is loaded, eclim will locate the plugin's required
resources provider and invoke its initialize method which will then
inject its resources (messages, command options, etc) into eclim and
register any new commands.
Here is graphical representation of this process:
[diagram]
vim:ft=eclimhelp

242
vim/bundle/eclim/doc/development/commands.txt Normal file
View File

@@ -0,0 +1,242 @@
*development-commands*
Commands
********
For each eclipse feature that is exposed in eclim, there is a
corresponding command on the daemon which handles calling the
appropriate eclipse APIs and returning a result back to the client.
This page will walk you through creating a simple command to
familiarize you with the process.
Creating a Command
==================
Commands are simple classes which extend AbstractCommand and are
registered using the @Command annotation. They then define an execute
method which can return any object that can be serialized
appropriately using gson (http://code.google.com/p/google-gson/).
Here is an example of a trivial command which returns a map of the
arguments it was supplied, with the supplied project and file paths
converted to absolute paths and the file byte offset converted to a
character offset (eclim's vim function eclim#util#GetOffset() returns
the offset in bytes since getting a character offset in vim with multi
byte characters is less reliable, but most eclipse APIs expect
character offsets):
Note: Eclim's source code is grouped by bundles (org.eclim,
org.eclim.core, etc), each of which has java directory containing
the java source code for that bundle.
>
package org.eclim.plugin.core.command.sample;
import java.util.HashMap;
import org.eclim.annotation.Command;
import org.eclim.command.CommandLine;
import org.eclim.command.Options;
import org.eclim.plugin.core.command.AbstractCommand;
import org.eclim.plugin.core.util.ProjectUtils;
import org.eclipse.core.resources.IProject;
@Command(
name = "echo",
options =
"REQUIRED p project ARG," +
"REQUIRED f file ARG," +
"REQUIRED o offset ARG," +
"OPTIONAL e encoding ARG"
)
public class EchoCommand
extends AbstractCommand
{
@Override
public Object execute(CommandLine commandLine)
throws Exception
{
String projectName = commandLine.getValue(Options.PROJECT_OPTION);
String file = commandLine.getValue(Options.FILE_OPTION);
IProject project = ProjectUtils.getProject(projectName);
// translates client supplied byte offset to a character offset using the
// 'project', 'file', 'offset', and 'encoding' command line args.
int offset = getOffset(commandLine);
HashMap<String,Object> result = new HashMap<String,Object>();
result.put("project", ProjectUtils.getPath(project));
result.put("file", ProjectUtils.getFilePath(project, file));
result.put("offset", offset);
if (commandLine.hasOption(Options.ENCODING_OPTION)){
result.put("encoding", commandLine.getValue(Options.ENCODING_OPTION));
}
return result;
}
}
<
When registering the command with the @Command annotation, you give it
a name and a comma separated list of options. Each option consists of
4 parts in the form of:
>
REQUIRED|OPTIONAL s longname ARG|NOARG|ANY
<
Where each part is defined as:
1. REQUIRED or OPTIONAL
2. a single letter short name for the option
3. a long name for the option
4. whether the option requires an argument, no argument, or can
have any number of additional arguments. In the case of ANY, you
should only have one option with that value and when running the
command from the command line, that option should be supplied last.
That should give you the basics on what's involved with creating a new
command, but the biggest hurdle for creating most commands is locating
and deciphering the eclipse API calls that are necessary to implement
the feature you want. Unfortunately most of the eclipse code that
you'll need to hook into will most likely have little to no
documentation so you're going to have to dig through the eclipse code.
Eclim does provide a couple ant tasks to at least help you to quickly
extract any docs or source code found in your eclipse install:
- eclipse.doc: This target will extract any doc jars from your
eclipse install to a 'doc' directory in your eclipse home (or user
local eclipse home).
- eclipse.src: This target will extract any src jars from your
eclipse install to a 'src' directory in your eclipse home (or user
local eclipse home). If you download the sdk version of eclipse then
the jdt and all the core eclipse source will be available. Some
other plugins provide sdk versions which include the source code and
this target can extract those as well, but some plugins don't seem
to have this option when installing via eclipse's update manager
(and may not include the source when installed from a system package
manager). For those you can often download a zip version of their
update site which should include source bundles. Once you've
extracted that file, you can tell this target to extract source
bundles from a specified directory. Here is an example of extracting
the source from an unpacked dltk update site:
>
$ ant -Dsrc.dir=/home/ervandew/downloads/dltk-core-5.0.0/plugins eclipse.src
<
Running a Command
=================
Once you've created your command you then need to compile the code
using eclim's ant build file. After you've done that you can then
start eclimd and execute your command from the command line to test
it:
>
$ eclim -pretty -command echo -p eclim -f org.eclim.core/plugin.properties -o 42 -e utf-8
<
Note: As you are developing your commands, you can avoid restarting
eclimd after every change by using eclim's reload command which will
reload all of eclim's plugin bundles with the exception of
org.eclim.core (so unfortunately it won't help with our example
above if we put that command in the org.eclim.core bundle):>
$ eclim -command reload
<
Adding to Vim
=============
Continuing with our echo command example, we can add the command to
vim by first defining a new vim command in
org.eclim.core/vim/eclim/plugin/eclim.vim:
Note: If the command should only be available for a specific file
type, then you'd put it in a vim/eclim/ftplugin/somefiltetype.vim
file instead.
>
command EclimEcho :call eclim#echo#Echo()
<
Now that we've created the command, we then need to define our
eclim#echo#Echo() function accordingly in
org.eclim.core/vim/eclim/autoload/eclim/echo.vim:
>
" Script Variables {{{
let s:echo_command =
\ '-command echo -p "<project>" -f "<file>" ' .
\ '-o <offset> -e <encoding>'
" }}}
function! eclim#echo#Echo() " {{{
if !eclim#project#util#IsCurrentFileInProject(0)
return
endif
let project = eclim#project#util#GetCurrentProjectName()
let file = eclim#project#util#GetProjectRelativeFilePath()
let command = s:echo_command
let command = substitute(command, '<project>', project, '')
let command = substitute(command, '<file>', file, '')
let command = substitute(command, '<offset>', eclim#util#GetOffset(), '')
let command = substitute(command, '<encoding>', eclim#util#GetEncoding(), '')
let response = eclim#Execute(command)
" if we didn't get back a dict as expected, then there was probably a
" failure in the command, which eclim#Execute will handle alerting the user
" to.
if type(response) != g:DICT_TYPE
return
endif
" simply print the response for the user.
call eclim#util#Echo(string(response))
endfunction " }}}
<
And that's all there is to it. After re-building eclim, restarting
eclimd, and restarting vim, you can now execute the command :EclimEcho
to see the response printed in vim.
Now that you know the basics, you can explore the many existing eclim
commands found in the eclim source code to see detailed examples of
how to access various eclipse features to expose them for use in vim
or the editor of your choice.
You should also take a look at the eclim Plugins
(|development-plugins|) documentation which documents how to create a
new eclim plugin, including information on adding new eclim settings,
managing the plugin's dependencies through its META-INF/MANIFEST.MF,
etc.
vim:ft=eclimhelp

268
vim/bundle/eclim/doc/development/gettingstarted.txt Normal file
View File

@@ -0,0 +1,268 @@
*development-gettingstarted*
Developers Guide
****************
This guide is intended for those who wish to contribute to eclim by
fixing bugs or adding new functionality.
Checking out the code and building it.
======================================
1. Check out the code:
----------------------
>
$ git clone git://github.com/ervandew/eclim.git
<
Note: If you are still using Eclipse 3.7 (Indigo) you will need to
checkout the eclim indigo branch before attempting to build eclim:>
$ cd eclim
$ git checkout indigo
<
2. Build eclim:
---------------
>
$ cd eclim
$ ant -Declipse.home=/your/eclipse/home/dir
<
Note: If your eclipse home path contains a space, be sure to quote
it:>
> ant "-Declipse.home=C:/Program Files/eclipse"
<
This will build and deploy eclim to your eclipse and vim directories.
Note: If your vimfiles directory is not located at the default
location for your OS, then you can specify the location using the
"vim.files" property:>
$ ant -Dvim.files=<your vimfiles dir>
<
When the build starts, it will first examine your eclipse installation
to find what eclipse plugins are available. It will then use that list
to determine which eclim features/plugins should be built and will
output a list like the one below showing what will be built vs what
will be skipped:
>
[echo] ${eclipse}: /opt/eclipse
[echo] # Skipping org.eclim.adt, missing com.android.ide.eclipse.adt
[echo] # Skipping org.eclim.dltk, missing org.eclipse.dltk.core
[echo] # Skipping org.eclim.dltkruby, missing org.eclipse.dltk.ruby
[echo] # Skipping org.eclim.pdt, missing org.eclipse.php
[echo] Plugins:
[echo] org.eclim.cdt
[echo] org.eclim.jdt
[echo] org.eclim.pydev
[echo] org.eclim.sdt
[echo] org.eclim.wst
<
In this case we can see that four eclim plugins will be skipped along
with the eclipse feature that would be required to build those
plugins. If you see an eclipse feature in that list that you know you
have, it may be the case that you installed it as a regular user, so
that feature was installed in your user local eclipse directory. In
that case you will need to notify the build of that directory so it
can examine it as well (just replace the <version> portion below with
the actual version found in your ~/.eclipse directory):
>
$ ant \
-Declipse.home=/opt/eclipse \
-Declipse.local=$HOME/.eclipse/org.eclipse.platform_<version>
<
If you don't want to supply the eclipse home directory, or any other
properties, on the command line every time you build eclim, you can
create a user.properties file at the eclim source root and put all
your properties in there:
>
$ vim user.properties
eclipse.home=/opt/eclipse
vim.files=${user.home}/.vim/bundle/eclim
<
Note: The eclim vim help files, used by the :EclimHelp
(|vim-core-eclim#:EclimHelp|) command, are not built by default. To
build these you first need to install sphinx
(http://sphinx-doc.org), then run the following command:>
$ ant vimdocs
<
This target also supports the vim.files property if you want the
docs deployed to a directory other than the default location.
*coding-style*
Coding Style
============
When contributing code please try to adhere to the coding style of
similar code so that eclim's source can retain consistency throughout.
For java code, eclim includes a checkstyle configuration which can be
run against the whole project:
>
$ ant checkstyle
<
or against the current java file from within vim:
>
:Checkstyle
<
*development-patches*
Developing / Submitting Patches
===============================
The preferred means of developing and submitting patches is to use a
github fork. Github provides a nice guide to forking
(http://help.github.com/forking/) which should get you started.
Although using a github fork is preferred, you can of course still
submit patches via email using git's format-patch command:
>
$ git format-patch -M origin/master
<
Running the above command will generate a series of patch files which
can be submitted to the eclim development group
(http://groups.google.com/group/eclim-dev).
Building the eclim installer
============================
It should be rare that someone should need to build the eclim
installer, but should the need arise here are the instructions for
doing so.
To build the installer you first need a couple external tools
installed:
- sphinx (http://sphinx-doc.org): Sphinx is used to build the eclim
documentation which is included in the installer.
Eclim also uses a custom sphinx theme which is included in eclim as
a git submodule. So before you can build the installer you will need
to initialize the submodule:
>
$ git submodule init
$ git submodule update
<
- graphviz (http://www.graphviz.org/): The docs include a few uml
diagrams which are generated using plantuml
(http://plantuml.sourceforge.net/) (included in the eclim source
tree) which in turn requires graphviz (http://www.graphviz.org/).
- formic (http://github.com/ervandew/formic): The eclim installer
has been developed using the formic framework, and requires it to
build the installer distributables. Formic doesn't currently have
an official release, so you'll need to check out the source code:
>
$ git clone git://github.com/ervandew/formic.git
<
After checking out the code, you'll need to build the formic
distribution:
>
$ cd formic
$ ant dist
<
Then extract the formic tar to the location of your choice
>
$ tar -zxvf build/dist/formic-0.2.0.tar.gz -C /location/of/your/choice
<
Once you have installed the above dependencies, you can then build the
eclim installer with the following command.
>
$ ant -Dformic.home=/your/formic/install/dir dist
<
In lieu of supplying the formic home on the command line, you can
instead put it in a user.properties file at the eclim source root:
>
$ vim user.properties
formic.home=/your/formic/install/dir
<
What's Next
===========
Now that you're familiar with the basics of building and patching
eclim, the next step is to familiarize yourself with the eclim
architecture and to review the detailed docs on how new features are
added.
All of that and more can be found in the eclim development docs
(|development-index|).
vim:ft=eclimhelp

21
vim/bundle/eclim/doc/development/index.txt Normal file
View File

@@ -0,0 +1,21 @@
*development-index*
Development Docs
****************
Developers Guide (|development-gettingstarted|)
Architecture (|development-architecture|)
Explains the underlying architecture that eclim utilizes including
an overview of the call sequence from vim to eclipse.
Commands (|development-commands|)
Details the process of adding a new command to vim which calls to a
corresponding implementation in eclipse.
Plugins (|development-plugins|)
Details the process of adding a new plugin to eclim.
... More To Come
vim:ft=eclimhelp

226
vim/bundle/eclim/doc/development/plugins.txt Normal file
View File

@@ -0,0 +1,226 @@
*development-plugins*
Plugins
*******
Note: This guide is a work in progress. If in the process of writing
a new plugin you find anything here that is unclear or missing,
please don't hesitate to post to the eclim-dev
(http://groups.google.com/group/eclim-dev) mailing list with
questions, suggestions, etc.
To allow eclim to support different languages, eclim is broken up into
eclipse plugins, each of which depend on a corresponding eclipse
feature which provides support for that language. When you install or
build eclim, it will examine your eclipse install to determine which
features are available and will add the corresponding eclim plugins to
expose those features. This page documents the core aspects of what
goes into the creation of a new eclim plugin.
Bootstrapping the plugin artifacts
==================================
Eclim includes a set of templates to help you bootstrap a new plugin.
To utilize them you can run the following ant target:
>
$ ant plugin.create
<
You will be prompted to enter a name for this plugin along with some
guidelines on choosing an appropriate name.
Once you've chosen a name, the plugin's directory structure will be
created and populated with bare bones version of the required
artifacts. Eclim's build.xml file will also be updated to include a
target to the new plugin's unit test target.
Updating the initial artifacts
==============================
After you've bootstrapped your plugin, you can now start updating the
generated artifacts:
build_<plugin_name>.gant
------------------------
The first file you'll need to modify is a gant file for your plugin.
The main eclim build.gant script will load this file during the build
process to determine what the plugin's eclipse dependency is, so it
knows whether it can be built against the target eclipse install. So
the first thing we need to do is to fill in that information by
updating the feature_<plugin_name> variable with the name of the
eclipse feature that this plugin depends on. For example, the eclim
jdt plugin has this set to 'org.eclipse.jdt'. The build script will
look in the features directory of your eclipse install (including the
dropins and your user local eclipse dir if set), to find this feature,
so the value you set, must be found in one of those locations (the
version suffixes will be removed from the features in order to match
it against the value you've set).
You'll also notice that there is a unit test target in the gant file.
You can ignore that for now.
META-INF/MANIFEST.MF
--------------------
The next file to note is the plugin's META-INF/MANIFEST.MF. This is
the file that eclipse will use to determine how to load the bundle and
what to include in its classpath. The only part of this file that you
should edit is the Require-Bundle: section. This is a comma separated
list of bundles (or plugins) which this bundle depends on. When this
bundle is loaded only those bundles listed here will be available in
the classpath. So when you start running commands you've written
later, if you receive a ClassNotFoundException, that is likely due to
the bundle containing that class not being listed in your plugin's
Require-Bundle: list. At this point you probably don't know yet what
bundles you need to add to this list. When you start writing commands
for your plugin, you'll have to find out which bundles contain the
classes imported from the eclipse plugin you are integrating with, and
you'll need to add those bundles accordingly.
It's also worth noting that eclim provides a custom classpath
container which scans the manifest of each eclim plugin and loads the
required bundles of each into the classpath. So when adding new
bundles, if you want validation, search, code completion, etc to work
with classes from those new bundles, you'll have to restart the eclim
daemon. While restarting can be annoying, this is generally better
than having to add/remove entries from the .classpath file or worrying
about one user having different bundle version numbers from another.
PluginResources.java
--------------------
At this point you'll typically need to start customizing your plugin's
org.eclim.<name>/java/org/eclim/plugin/<name>/PluginResources.java
file. Here is where you will map a short alias to the project nature,
or natures, of the plugin you are integrating with, register a project
manager for initializing project's for this plugin, register any
plugin settings that users can configure, etc. You'll be doing all
this inside of the initialize method which has been generated for you.
Project Nature
~~~~~~~~~~~~~~
You'll first need to find out where the plugin's nature id is defined.
Here are some examples that should give you an idea of where to look:
- jdt: org.eclipse.jdt.core.JavaCore.NATURE_ID
- cdt:
- org.eclipse.cdt.core.CProjectNature.CNATURE_ID
- org.eclipse.cdt.core.CCProjectNature.CC_NATURE_ID
- dltkruby: org.eclipse.dltk.ruby.core.RubyNature.NATURE_ID
- adt: com.android.ide.eclipse.adt.AdtConstants.NATURE_DEFAULT
One way to find it is to open up the .project file in a project
containing the nature, locate the fully qualified name in the
<natures> section, then grep the plugin's code for that name.
Once you have the reference to the nature id, you can then create a
public static variable called NATURE:
>
public static final String NATURE = SomeClass.NATURE_ID;
<
You'll be using this constant as the key to register features for
project containing this nature, but first we'll register a short alias
for this nature since the actual nature id tends to be long and
unstandardized, and we don't want users to have to type it out when
creating projects from eclim:
>
ProjectNatureFactory.addNature("shortname", NATURE);
<
Project Manager
~~~~~~~~~~~~~~~
The next thing you'll probably need to do is to create a project
manager for your project
(org.eclim.<name>/java/org/eclim/plugin/<name>/project/SomeProjectManager.java).
The project manager is responsible for performing any post create,
update, delete, or refresh logic required for projects of this nature.
This logic can include things such as creating an initial
classpath/buildpath, validate the classpath/buildpath on update,
forcing a full update of the search index on refresh, or any number of
other things.
Overriding the create method will almost certainly be necessary, but
the logic you'll need here varies widely. Finding what you'll need is
a matter of digging through the parent plugin's source code, typically
looking for the project creation wizard class, to see what it does to
create a project of this nature and later comparing the created
artifacts from your code against those of a project created from the
eclipse gui. This can be a difficult hurdle to get past for someone
doing this the first time, so please don't be shy about asking for
help on the eclim-dev (http://groups.google.com/group/eclim-dev)
mailing list.
Eclim does provide a couple ant tasks to at least help you to quickly
extract any docs and source code found in your eclipse install:
- eclipse.doc: This target will extract any doc jars from your
eclipse install to a 'doc' directory in your eclipse home (or user
local eclipse home).
- eclipse.src: This target will extract any src jars from your
eclipse install to a 'src' directory in your eclipse home (or user
local eclipse home). If you download the sdk version of eclipse then
the jdt and all the core eclipse source will be available. Some
other plugins provide sdk versions which include the source code and
this target can extract those as well, but some plugins don't seem
to have this option when installing via eclipse's update manager
(and may not include the source when installed from a system package
manager). For those you can often download a zip version of their
update site which should include source bundles. Once you've
extracted that file, you can tell this target to extract source
bundles from a specified directory. Here is an example of extracting
the source from an unpacked dltk update site:
>
$ ant -Dsrc.dir=/home/ervandew/downloads/dltk-core-5.0.0/plugins eclipse.src
<
Once you've created your project manager, you then map it to your
plugin's nature inside of your PluginResources.initialize method like
so:
>
ProjectManagement.addProjectManager(NATURE, new SomeProjectManager());
<
Project Settings
~~~~~~~~~~~~~~~~
At this point you should have the minimum of what is needed for a new
plugin. Hopefully you can now create new projects with your plugin's
defined nature. The next step would be to start adding commands
(|development-commands|) to provide validation, code completion, etc.
The remaining items in this list are not required to continue. They
provide you with the ability to setup your own preferences or to
expose the parent plugin's defined preferences inside of vim. When
you've come to the point that you need to work with preferences, then
feel free to come back here and continue reading.
To Be Continued...
vim:ft=eclimhelp