Setting up Eclipse

Eclipse is an IDE originally designed for Java, but now with plugins for many languages, including PHP. It has lots of very powerful features, and it is the editor of choice for most of the OU Moodle developers, and a number of other people in the community.

However, it is not the easiest program in the world to get started with, so I'm going to take you through it step by step. These instructions assume Eclipse 3.2, the current version at the time of writing. It should not change much between releases.

Warning

This is just a brain-dump, and since I already have Eclipse installed on all my computers I have not been able to test all the the steps. I would be very grateful if some people could try these instructions and make the necessary corrections.Tim Hunt 21:32, 12 August 2006 (WST)

Prerequisites

Eclipse is written in Java, so I would recommend getting the latest Java runtime environment from http://java.com/ for maximum speed and reliability.

Also, Eclipse is quite big, so I recomment lots of memory in your computer. I have used it on all of Windows, MacOS X and Linux with 1GB of memory, and that is plenty.

Installing Eclipse

Go to http://www.eclipse.org/downloads/. Click on the link where it says Download now: Eclipse SDK 3.2 It should have automatically detected which platform you are using. Choose a Mirror, and wait for the ~100MB download.

You will notice that what you have got is a zip file (unless your system automatically decompresses it for you).

On Windows, upzip it into C:\Program Files (all the files go into an Eclipse folder there). Then look in the Eclipse folder and drag Eclipse.exe to the Start menu/Desktop/Quicklaunch bar to make a shortcut for starting it.

On MacOS, unzip and copy the Eclipse folder into Applications. Go into the Eclipse folder and drag the Eclipse app to the Dock for ease of launching.

On Linux, unzip somewhere suitable, and make an easy way to launch it.

The first time you run Eclipse

The first time you lauch Eclipse it does a bit of setup stuff, for instance, it create a workspace. This is where it stores the things you are working on. The default location is sensible on all platforms, so use that.

For some reason, every time you start Eclipse, it asks you which workspace you want to use. I have never seen the need to have more than one, so I recommend turning on the checkbox that says "Don't ask me this again".

Another thing that happens the first time you run Eclipse is that you arrive at a welcome screen. This has links to various bits of help, which you can read if you like, but you probaly don't need to if you are following these instructions. So find the button on the welcome page that closes it and gets you to the main Eclipse screen.

Installing the necessary plugins

By default, Eclipse comes with the Java tools. For everything else you will need to install some plugins.

If you are sitting behind a web proxy, from the Window menu choose Preferences .... Choose Install/Update from the tree view on the left, and enter the proxy information in the boxes on the right. If you aren't behind a proxy, ignore this step.

From the Help menu choose Software Updates -> Find and Install.

On the first screen of the wizard, make sure that "Search for new features to install" is selected, then click Next >.

The next screen is a list of upgrade sites to check. You need to add one to the list, so click the New Remote Site ... Button.

In the pop-up dialog, give the remote site a name like PHPeclipse update site; set the URL to http://phpeclipse.sourceforge.net/update/releases/; then click OK.

Back in the wizard, turn on just two things in the box "Sites to include in search":

• Your newly created 'Phpeclipse update site; and
• the one called Callisto Discovery Site.

Then click Finish.

It goes off sees what updates are avaiable at those sites. As it does so, it may occasionally pop up a dialog asking you to choose a mirror. Each time, select a sensible one.

Eventually, you get to a new wizard for selecting and installing the updates you want. The ones you want (you may have to search the tree structure) are, PHPeclipse and all the Web Standard Tools (WST) ones.

Next, and very importantly, you must click the Select Required button. Then you can click the Next > button.

Read and agree to all the license agreements. Then click Next >.

Click Finish, and wait for the plugins to download.

Once the downloads have finished, a warning will pop-up telling you that all the plugins you downloaded are not digitally signed. The Eclipse Foundation build digital signing of plugins into their archetecture as a security measure, and then did not sign any of their own plugins! Anyway, click the Install All button.

Finally, a Window will pop up asking you to restart Eclipse. Do so.

Setting the preferences for Moodle development

Now go to the Window menu, and choose Preferences ....

The Eclipse preferences are emense, with a tree view on the left, which selects which screen to display on the right. Don't panic, we'll guide you through it.

General settings

If you have strong feelings about fonts, choose General -> Appearance -> Colors and Fonts from the tree on the left. Then on the right look under Basic and change Text Font. All the other editor font settings will inherit from this, so this is probably the only one you have to change.

Under "General -> Content Types', select PHP Source File, and add "*.html" to the box at the bottom.

Under '"General -> Editors -> File Associations, add "*.php" to the top box. With "*.php" selected in the top box, make sure "PHP Editor" is set to default in the bottom box. With "*.html" selected in the top box, select "PHP Editor" in the bottom box and click the "Default" button to change it, because in Moodle, most HTML files actually contain PHP code.

If you use a web proxy, enter the details under '"Internet -> Proxy Settings. (Yes, I know you have entered the somewhere else before. Now you have to enter them again here. I don't know why. You just do.)

PHP Settings

These are all hidden under the PHPeclipse Web Development bit of the tree.

Under PHPeclipse Web Development -> Browser Preview Defaults, turn off both checkboxes.

Under PHPeclipse Web Development -> PHP, on the Appearance tab, set "Displayed tab width" to 4.

Under PHPeclipse Web Development -> PHP, on the Typing tab, turn off all the options except "Pasting for correct indentation", "Insert spaces for tab" and "Close PHPdocs and comments". It would be nice to turn on more of these options, but most of the rest don't work very well.

Under PHPeclipse Web Development -> PHP -> Formatter, on the New Lines tab, turn on Clear all blank lines.

Under PHPeclipse Web Development -> PHP -> Formatter, on the Style tab, turn off Indentation is represented by a tab.

Under PHPeclipse Web Development -> PHP -> Templates, I like to define a new template to help with debugging:

Name

dump

Description

Dump a PHP variable

Pattern

echo '<pre>'; //DONOTCOMMIT

print_r(${cursor}); echo '';

You can do other useful things with templates too.

There is a really stupid bug. Under PHPeclipse Web Development -> Project Defaults, you would like to add "." to the Include Paths, but you can't. There is a page on the web with instructions for working round this (basically, you have to edit one of the config files by hand), but I can't find it now.

CVS Settings

These are all hidden under the Team bit of the tree.

Under Team -> CVS -> SSH2 Connection Method, you can set up a public/private key pair. If you do this, you won't have to keep typing your Sourceforge password when doing CVS operations. See http://sourceforge.net/docs/F02/ for the instructions of what you have to do at the Sourceforge end to make this work. That should make it clear what you have to do in Eclipse.

The rest of the ones in this section are personal preferences, but I recomment them because the default settings are very irritating.

Under Team, set "Perspectives" to None.

Under Team -> CVS -> Annotate set "Use Quick Diff annotate mode for local file annotations" to Yes, and Open perspective after a 'Show Annotations' operation" to No.

Under Team -> CVS -> Console", turn on "Show CVS console automatically when command is run".

Under Team -> CVS -> Label Decorations, switch to the Icon Decorations tab and turn on all the settings, and then on the Text Decorations tab change both "File Decoration" and "Folder Decoration" to be just {name}.

Web and XML settings

Foreach XXX in CSS, HTML, Javascript, XML:

Under Web and XML -> XXX Files ->XXX Source, choose Indent using spaces and indentation size 4.