config/.vim/eclim/doc/gettingstarted.txt

*gettingstarted*


Getting Started
***************

The first step to getting started with eclim is to install it.  If you
haven't already done so, please see the install guide
(|guides-install|) for instruction on how to install eclim.

If you've already installed eclim, then the next step is to create
your first project after which you can then start writing code and
familiarizing yourself with eclim's features.

First make sure eclimd is running (see the eclimd docs (|eclimd|) if
you are unsure how to start eclimd).


Creating your first project
===========================

Once you've got eclimd running open an instance of vim and create your
project like so (maven users, please see the maven docs for an
alternate method):

>

   :ProjectCreate /path/to/my_project -n java

<


This example creates a project with a java nature (-n java), but the
same method can be used to create a project for other languages by
simply changing the nature accordingly:

>

   :ProjectCreate /path/to/my_c_project -n c
   :ProjectCreate /path/to/my_cpp_project -n c++
   :ProjectCreate /path/to/my_java_project -n java
   :ProjectCreate /path/to/my_php_project -n php
   :ProjectCreate /path/to/my_python_project -n none
   :ProjectCreate /path/to/my_ruby_project -n ruby

<


The only odd ball in the bunch is the creation of the python project
which currently uses the 'none' nature.

The path supplied to the |:ProjectCreate| command will be the path to
the root of your project.  This path may or may not exist.  If it does
not exist it will be created for you.  After you've created your
project, there will be a .project file added to your project's root
along with another file where references to your project's source
directories and any third party libraries your project uses reside.
The name of this file will vary depending on your project's nature,
but in all cases eclim will provide you with commands to manage this
file:

- java - .classpath file (|vim-java-classpath|)

- php, ruby - .buildpath file (|vim-dltk-buildpath|)

- c, c++ - .cproject, managed via the |:CProjectConfigs| command

- python - .ropeproject (see the rope docs (|vim-python-rope|))

Once you've created your project you can use the :ProjectList command
to list the available projects and you should see your newly created
one in the list.

>

   my_project - open   - /path/to/my_project

<


The :ProjectList result is in the form of projectName - (open|closed)
- /project/root/path.  When you create projects, the last path element
will be used for the project name.  If that element contains any
spaces, these will be converted to underscores.


Adding project source directories
=================================

Before you can start writing code, you will first need to create and
register your project's source directories.  If you created your
project from an existing code base, then this step may have been
perform automatically for you, but you should validate the settings to
be sure.

We will use a java project in this example but the steps for other
languages are very similar.  Please see the relevant docs for your
language for more details:

- java (|vim-java-classpath|)

- php and ruby (|vim-dltk-buildpath|)

- c and c++ (|cprojectconfigs|)

- python (|vim-python-rope|)

For the purpose of this example we will assume that you will store
your source files at:

>

   /path/to/my_project/src/java

<


So, given that location, you will need to open the file
/path/to/my_project/.classpath in Vim.

>

   vim /path/to/my_project/.classpath

<


To add the source directory simply execute the following

>

   :NewSrcEntry src/java

<


This will add the necessary entry to the end of your .classpath file.
The contents of this file should now look something like this:

>

   <?xml version="1.0" encoding="UTF-8"?>
   <classpath>
     <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
     <classpathentry kind="output" path="bin"/>
     <classpathentry kind="src" path="src/java"/>
   </classpath>

<


Now that your source directory is setup, you can proceed to edit java
files in that directory and make use of the java functionality
(|vim-java-index|) provided by eclim.

*gettingstarted-coding*


Writing code in your new project
================================

Now that you have a project created, you can start writing code and
utilize the features that eclim provides.

Note: Below we'll walk through a trivial java example, but some of the
  steps apply to all the languages that eclim supports, although the
  command names may differ a bit.  For additional docs on working with
  the language of your choice, please see the relevant section of the
  docs:

     - c/c++ (|vim-c-index|)

     - java (|vim-java-index|)

     - php (|vim-php-index|)

     - python (|vim-python-index|)

     - ruby (|vim-ruby-index|)

     - etc. (|documentation|)

Lets get started writing our first java application using eclim.

1. First, navigate to your new project's source directory (src/java in
   this example) and create any necessary package directories:

   >

      $ cd /path/to/my_project/src/java
      $ mkdir -p org/test/

   <


1. Then start editing your first java source file:

   >

      $ vim org/test/TestMain.java

   <


   >

      package org.test;

      public class TestMain
      {
        public static final void main(String[] args)
        {

        }
      }

   <


1. You can start to use some of the core features now.  For example,
   lets add the following code to the main method so we can test
   eclim's source code validation:

   >
      System.

   <

   Then save the file and note that an error marker is placed in the
   left margin of your file and when the cursor is on that line an
   error message is printed at the bottom of your vim window.  You can
   also run :lopen to view all the errors in the file at once.

2. Now lets try out code completion.  Place your cursor on the '.' of
   'System.' and start insert mode in vim use 'a', then follow the
   example below:

   >

      System.<ctrl-x><ctrl-u>             // starts the completion mode
      System.<ctrl-n>                     // cycle through the completion suggestions
      System.out                          // assuming you chose the 'out' suggestion
      System.out.p<ctrl-x><ctrl-u>        // now start completion again
      System.out.p<ctrl-n>                // hit <ctrl-n> until you get 'println'
      System.out.println(
      System.out.println("Hello World");  // finish up the example code.

   <


1. After saving the file you should have no more validation errors, so
   now we can compile the code and run it like so:

   >

      :Javac
      :Java

   <


   After running the :Java command in vim you should now see your
   output in a new split window.

This only scratches the surface on the number of java features
(|vim-java-index|) that eclim provides, but hopefully this example was
enough to get you started.

*gettingstarted-projectsettings*


Editing your project's settings
===============================

Several of eclim's features are configurable via project settings
which you can modify using the |:ProjectSettings| command.  If your
current Vim window's working directory is at or under the project's
root directory then you can execute the :ProjectSettings with no
arguments, otherwise you will need to supply the project name.

>

   :ProjectSettings projectName

<


After your first time editing your project's settings, a .settings
directory will be created in the project's root directory.  In there
are the project's preferences files.  You should avoid editing these
files directly and stick to using :ProjectSettings to update them.

Note: If you have only one project or many projects that share the same
  settings you can use the |:EclimSettings| command instead to edit
  the global settings.  These global settings will apply to any
  project that has not overridden them with values via
  :ProjectSettings.

*gettingstarted-maven*


Maven Users
===========

Creating your first project with maven can be accomplished using the
same method as any other java project, or you can utilize some of
maven's built in features to get your project started.

1. Run maven's generate archetype to create the project directory and
   samples:

   >

      $ mvn archetype:generate

   <


1. Open an instance of vim and set the necessary eclipse classpath
   variable to point to your maven repos.

   >

      $ vim
      :MvnRepos

   <


1. Run the following command at the root directory of your project to
   generate the necessary eclipse files:

   >

      $ mvn eclipse:eclipse

   <


1. Open an instance of vim and import your project:

   >

      $ vim
      :ProjectImport /path/to/new/project

   <

vim:ft=eclimhelp