# Eclipse tips/tricks/HOWTOs

$Id: eclipse.txt 1902 2008-11-02 15:50:35Z mjs $

## 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 map to local file paths)--it'll try to guess later, and the guesses are pretty good.  (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).

## 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 */