# Eclipse tips/tricks/HOWTOs



## HOWTO: Install

1. To get the PDT package, download an
"[all-in-one](http://downloads.zend.com/pdt/all-in-one/)" package from Zend.
([More info](http://www.zend.com/en/community/pdt).)

2. (Optional) Install Mylyn via "Search for new features to install".
[Mylyn remote site update URL](http://www.eclipse.org/mylyn/downloads/); it
should look something like:

	http://download.eclipse.org/tools/mylyn/update/e3.3
  
	(Be sure to install the Trac connector.)

3.	(Optional) Install Subclipse ([source](http://subclipse.tigris.org/install.html)).

  Notes:
  
  1. If you use the recommended JavaHL bindings (I think this is the name),
  you need to install the JavaHL libraries (and maybe the command-line
  subversion clients) separately, otherwise you'll get strange "unable to
  load default svn client" errors!
  
      On OS X, these are provided by the `subversion-javahlbindings`
      package, which installs:
  
            /Library/Java/Extensions/libsvnjavahl.jnilib
            /Ports/lib/libsvnjavahl-1.0.0.0.dylib
            /Ports/lib/libsvnjavahl-1.0.dylib
            /Ports/lib/libsvnjavahl-1.a
            /Ports/lib/libsvnjavahl-1.dylib
            /Ports/lib/libsvnjavahl-1.la
            /Ports/lib/svn-javahl/svn-javahl.jar
            /Ports/share/java/svn-javahl.jar
      
      (There may be something equivalent for your architecture.)
      
      You don't need to tell Eclipse or Java where to find these (I guess
      adding to `/Library/Java/Extensions` does it)--just restart Eclipse.
  
  1. You don't need to install anything from the "Integrations" node--these
  need dependencies you probably don't have.

	1. If an eclipse update complains about a org.eclipse.datatools.doc.user
    dependency failing, try installing DTP first via the "Search for new
    features to install" option.  ([more
    info](http://dev.eclipse.org/newslists/news.eclipse.dtp/msg00882.html))

## HOWTO: Enable <tt>emacs</tt> keybindings

Go to Window | Preferences | Workbench | Keys, and set Active
Configuration to "Emacs". Note that the "Content Assist" facility is
remapped from Control-space to Alt-/.

This gets you everything *except* Ctrl-W; to get Ctrl-W working as
well:

Open eclipse/plugins/org.eclipse.ui_2.1.0/plugin.xml, and search
for command="org.eclipse.ui.edit.text.showRulerContextMenu".
You'll eventually find the ctrl-w binding; change it to something
different such as ctrl-!. ([more
info](http://csdl.ics.hawaii.edu/FAQ/Eclipse/eclipse.html))

## HOWTO: Import (checkout) a project from subversion into eclipse

i.e. you want both the "PDT" nature *and* the subversion nature, and you
don't have a working copy yet.  (If you do have a working copy, see
below.)

Do the subversion checkout first; as you're finishing with the wizard
it will ask you how you want the project checked out--choose "Check
out as a project configured using the New Project Wizard".  Choose
"PHP Project" at this point.

## HOWTO: Import an existing eclipse project into eclipse

i.e. a working copy with `.project` file; perhaps a project that's been
"deleted" from Eclipse, but not from disk.

Use File | Import... | Existing Projects into Workspace, then choose the
**parent** directory of the project you want to import as the root
directory.  Select the big "Projects" window, and Eclipse will scan the root
directory for projects to import.  (Note that it may take a long time to
scan the directory.)

Select the project you want to import.  It may take a long while to discover
and add the subversion nature.  (More than 5 minutes.)

## HOWTO: Import a working copy into eclipse

i.e. a directory *without* `.project` file, but *with* `.svn` directories.

Use the File | New PHP Project, and use a project name that expands to a
directory that already exists.  (Ignore all other fields.) Eclipse will
detect that there's already stuff in that directory, and (if it's a working
copy) subclipse will also (eventually) add its annotations.  (If the
annotation aren't being added, click around the project tree a bit and wait
a few minutes.)

## FAQ: Why are my ant builds failing?

(org.apache.catalina.ant.DeployTask cannot be found)

This may be operating under a slightly different classpath than
eclipse. For example, junit stuff may work correctly under
eclipse, but since junit.jar isn't in the default build path of
ant, ant might not be able to build.

What you might have problems with:

junit:

	c:/Program Files/eclipse/plugins/org.junit_3.8.1/junit.jar

tomcat/catalina:

	c:/server/tomcat-5.0.28/server/lib/catalina-ant.jar

(Add them using Window | Preferences | Ant | Runtime.)

## HOWTO: Get Tomcat to automatically reload classes

Add the following fragment to conf/server.xml, just below &lt;Host
name="localhost"...&gt; ([more info](http://jakarta.apache.org/tomcat/tomcat-5.0-doc/config/defaultcontext.html)):

	<DefaultContext reloadable="true">
	  <Loader checkInterval="1"/>
	</DefaultContext>

This should be the only change to Tomcat's configuration that you need
to make--everything else should be configured by the
<tt>web.xml/build.xml/build.properties</tt> in your application's directory.

## TIP: ant buildfiles complain about catalina tasks being missing

Window | Preferences | Ant | Global Entries | Add External Jar

Add catalina-ant.jar from `$CATALINA_HOME/server/lib`.  (Not the ant
JARs in `$CATALINA_HOME/common/lib`!)

## HOWTO: Associate a file extension with a particular content type

(If it's opening in the wrong editor, say.)

Use: General | Editors | File Associations.

You'd think it would be possible to map an extension to a
particular view/syntax highlight using this, but it seems that at
least in some circumstances, you also have to say that a
particular "Content Type" can be mapped to a particular file
extension.

e.g. Setting the default editor of `*.html` to "PHP Editor", but
this doesn't do anything--this will only work once you also set
the "File associations" of the "PHP Content Type" to `*.html`.

If you're trying to change the association of a "locked"
extension, see below.

## HOWTO: Comment region

	Ctrl-/

## HOWTO: View keybindings

	Ctrl-Shift-L

## HOWTO: Install the Xdebug debugger

See [php.html](php.html).

## HOWTO: Use the PDT debugger

i.e. attach to a PHP process on a remote server.

The debugger has an unhealthy focus on individual files, and seems to think that URLs always correspond to files, which confuses things.  What you need to do is:

  1. Select "Open Debug Dialog..." from the "bug" icon in the toolbar.
  
  1. Select "PHP Web Page" and create a new configuration.
  
  1. Add a new server configuration (e.g. `beebo.local`).  You don't need to specify the path mapping (i.e. how remote file paths-on-disk map to local file paths)--if it can't find how one maps to the other later it'll ask you.  (If there's some problem, the "Path on server" is the full path on the server (e.g. `/mnt/hgfs/boom/workspace/beebo`) and the "Path in Workspace" is the local project name (e.g. `/beebo`).)
  
  1. You have to enter something in the "File" field, but the actual file appears to be mostly irrelevant.  It has to exist, and it has to be a PHP file, but that's all.
  
  1. Under "URL", turn off "Auto Generate".  Then, scroll down an make sure that the URL is valid.  (The  (uneditable) hostname part comes from the server configuration--if you need to change it, change it there.)  Also note that because of some bug, changing the "File" inserts slashes into URL, even if "Auto Generate" is turned off.
  
  1. Select the "Debug" button.  This should launch the debug process with a URL like <http://beebo.local/?XDEBUG_SESSION_START=ECLIPSE_DBGP&KEY=12216530166168>.  You can change the web browser that's used via the General | Web Browser preference.  (If using an external web browser on OS X, have `/usr/bin/open` as the "Location", with a "Parameter" like `-a Firefox %URL%`.)
  
  1. If using FastCGI, you may wish to set `-idle-timeout` to a large number, so that it doesn't give up on your PHP process while you're in the middle of debugging a process; at the moment mine reads:
  
        FastCgiConfig -autoupdate -killinterval 3600 -idle-timeout 300

  1. All this assumes that remote debugging is enabled in the Xdebug configuration; check the `php.ini` settings for `xdebug.remote_enable` (should be "On") and `xdebug.remote_host` (should be the IP address of the machine you're connecting from--that is, the IP address of the machine running Eclipse).  If, when you start the debugger from Eclipse, a web browser launches but then appears to hang for a very long time, it's probably because the `xdebug.remote_host` value is incorrectly set.

## FAQ: Why does Xdebug launch Notepad?

(Incorrect Xdebug launch url.)

If, when launching Xdebug, notepad launches and then complains about a
"file" with a name like:

	C:\Documents and Settings\Michael Stillwell\http://ski.ms/simpletest/reservation.html?XDEBUG_SESSION_START=ECLIPSE_DBGP&KEY=119143983189813

not being able to be found, try switching Eclipse's default web
from the internal browser to Firefox.  (You may be able to switch it
back again afterwards.)

## FAQ: Project not recognised as having subversion 

i.e. if the subversion labels/badges and menu items aren't
available.

I don't know how to fix this (other than checking out the project
again).  (Though note that it sometimes takes Eclipse a while to realise that a particular project has a subversion "nature".)  This problem seems to happen less frequently these days.

See also
[How do I manually assign a project Nature or BuildCommand?](http://wiki.eclipse.org/IRC_FAQ#How_do_I_manually_assign_a_project_Nature_or_BuildCommand.3F).

## HOWTO: Revert update manager to asking for a download source

(i.e. if you let it automatically choose the download location, and
now it's trying to pull updates from Bulgaria.)

You may be able to use the "Automatically select mirrors" checkbox on the
"Help | Software Updates | Find and install... | Next" page.

## HOWTO: Release "locked" content types

**Note I'm fairly certain this worked on some version of Eclipse once, but
apparently deleting all the files in the configuration direction except
`config.ini` can lead to problems.  So, if you need to do this, I'd
recommend not deleting anything from the config directory and/or backing
everything up first.**

The locking is done via a the plugin.xml files are scattered through
the plugins directories and plugins/*.jar (zip) files.  To removed a
"locked" file association, you need to find a chunk of XML that looks
something like:

    <content-type id="javaClass" name="%javaClassName" 
        priority="high"				
        file-extensions="class">
        <describer
            class="org.eclipse.core.runtime.content.BinarySignatureDescriber">
            <parameter name="signature" value="CA, FE, BA, BE"/>
        </describer>
    </content-type>

and remove it or comment it out.  Then, go into the configuration
directory and delete everything except the `config.ini` file.  (Might be
possible to delete less, but I haven't figured out exactly what it's
necessary to delete.)

[Some guy's shell script to help find the right plugin.xml](http://divby0.blogspot.com/2007/12/pattern-match-searches-within-multiple.html)

## FAQ: How can I reformat comments?

???

(The "format" command (Shift-Apple-L) reformats source code, and some
comments if editing Java files.  However, it doesn't reformat all comments
(nothing that starts with `//`), and PHP files edited via PDT don't seem to
be reformatted under any circumstances.)

## FAQ: How can I eliminate the "The file has changed on the filesystem.  Do you want to load the changes?" warning?

See "resource is out of sync with the file system", below.

## FAQ: Where's the Preferences menu item gone?

If you're using Zend Studio for Eclipse, for some reason the "Preferences
..." menu doesn't appear immediately after startup--you have to wait for a
few minutes until it appears (!).  (It appears at the same time as the
subversion "nature" becomes available.)

## ERROR: "resource is out of sync with the file system"

You can fix this for a single file by selecting "Refresh" from the file's
context menu.  To automatically refresh (I don't know why it doesn't do this
automatically, like everything else...) enable "Refresh automatically" from
the General | Workspace preferences.

## FAQ: How to make type hint annotations?

Use `@var` followed by the variable name, and then type.  e.g.

    $node = atkNode("user.customer"); /* @var $node atkNode */

## FAQ: How do I insert spaces instead of tabs?

For PDT Eclipse, at least, you need to change this in multiple places:

  1. Set General | Editors | Text Editors | "Insert spaces for tabs."
  1. On PHP | Formatter, change the "Tab policy" to spaces and the
  "Indentation size" to 4.
  1. On Web and XML | JavaScript Files, choose "Indent using spaces." 

## FAQ: Why doesn't subclipse work?

If the subclipse plugin is installed, but doesn't seem to working, try
restarting Eclipse, closing and opening projects and/or waiting a while.
For some reason it often takes quite a while (many minutes) to kick into
action after being installed.

## HOWTO: Configure Eclipse PDT to my preferences

  1. General | Editors | Keys | Choose Emacs scheme
  1. General | Editors | Text Editors | Quick Diff | Pristine SVN Copy
  1. General | Editors | Text Editors | Select Insert spaces for tabs
  1. Install/Update | Automatic Updates | Automatically find new updates
  1. PHP | Code Style | Formatter | Tab policy
  1. PHP | Editor | Code Folding | Disable Enable folding
  1. PHP | Editor | Typing | Disable Automatic closing
  1. PHP | Editor | Tabulators | Enable tab key indents current line
  1. Web | JavaScript | Editor | Folding | Deselect Enable folding
  1. Web | JavaScript | Editor | Typing | Deselect Strings, Parentheses,
  Braces
  1. Web | JavaScript | Code Style | Formatter | Create new profile
     1. Line Wrapping | Function Calls | Arguments | Set Indentation policy
       to Indent by one
     1. Line Wrapping | Expressions | Array initializers | Set Indentation
     policy to Indent by one
     1. Line Wrapping | Expressions | Object initializers | Set Indentation
     policy to Indent by one
     1. Indentation | Set Tab policy to Spaces only
     1. Indentation | Set Indentation size to 2
     1. Indentation | Set Tab size to 2
  1. Web | JavaScript | Validator | Enable JavaScript semantic validation (?)
  1. Team | SVN | Menu Icons | Choose TortoiseSVN
  
## FAQ: Why does "open declaration"/"code assist" not work?

It's probably because that project's "Build Path" or "Include Path" is
incorrectly configured.  (Eclipse will sometimes take it upon itself to
configure these automatically, and will sometimes do a poor job.)

The Build Path and Include Path together define which directories will be
automatically scanned by Eclipse for the purposes of code assist/code
completion.  For performance reasons, certain directories can be excluded
from scanning, but the way in which this is done is extremely confusing, and
the difference between the two is unclear.

You almost certainly want your Build Path and Include Path to say pretty
much the same thing.  (At one point the manual says: "It is recommended that
the resources on your Build Path match the resources on your Include Path"
and at another "By default, all folders which are one your Build Path will
be included in your Include Path.")

To make "open declaration" work across project (for example, if you have an
external library such as Zend Framework checked out as a separate project,
and you want "open declaration" or code assist to work against Zend
Framework file) then a few things need to be set up:

  1. In your project, the Include Path | Projects configuration screen needs
  to list the Zend project.  You probably want no access rules defined, at
  least until you have completion working.
  1. In the Zend project, the *Build Path* needs to be configured such that
  no directories are excluded.  (i.e. so that all Zend project directories
  are scanned.)
  
I think part of the reason for the difference is that the Include Path is an
Eclipse PDT-specific thing, whilst the Build Path is more general.

(The Build Path is essentially "which files and directories are scanned for
changes" and seems to be able to separately configure which assets are
available for code assist.  The Include Path is (I think) an Eclipse
PDT-specific thing.)

For more information, see the internal Eclipse PDT help:

  * Concepts | PHP Include Path
  * Concepts | PHP Build Path
  * Tasks | Configuring a Project's PHP Build Path
  * Tasks | Configuring a Project's PHP Include Path

## HOWTO: Upgrade Eclipse PDT

The whole Eclipse download/upgrade experience in appalling.  Quite the worst
of any software: compiling and installing Unix tools from the command-line
is much less work.  

Anyway, this is approximately how to upgrade Eclipse PDT, given that full
downloads don't seem to be available from
<http://www.eclipse.org/pdt/downloads/>.

Don't use Help | Check for Updates.  That doesn't seem to do anything.

  1. Go to Help | Install New Software ...
  1. Select "Add ..."
  1. Enter http://download.eclipse.org/tools/pdt/updates/2.0/ as the
  Location and select Okay.  (You can ignore Name.)
  1. In the "Work with" dropdown, select
  http://download.eclipse.org/tools/pdt/updates/2.0/.
  1. Select "Hide items that are already installed."  (I don't know why this
  setting even exists.)
  1. Select "Finish".
  1. Install the updates.
  
See <https://bugs.eclipse.org/bugs/show_bug.cgi?id=280935#c15>.  

## FAQ: Why does "mark occurrences" sometimes stop working?

(i.e. the feature whereby other occurrences of the variable the cursor is on
are highlighted.)