Development: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 that some Moodle developers like to use. Other (more) popular choices are vim and emacs.

However, Eclipse 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.

This article started off as a brain-dump by Tim Hunt. Since then, several other people have worked through it and made corrections, so the information here should be pretty accurate.

Prerequisites

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

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

Installing Eclipse

Go to http://www.eclipse.org/downloads/. Click on the link corresponding to your operating system where it says Eclipse Classic. 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, unzip 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 launch 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 "Use this as the default and do not ask 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 probably 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.

Note, there is now also another PHP editor for Eclipse. The update URL ishttp://download.eclipse.org/tools/pdt/updates/. I am just trying it--Tim Hunt 11:39, 7 November 2007 (CST)

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 Europa Discovery Site (or possibly Callisto Discovery Site.

Then click Finish.

It goes off sees what updates are available 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 (from your newly created PHPEclipse Update Site) and all the Web Standard Tools (WST) (usually under Callisto Discovery Site --> Web and J2EE Development).

Next, and very importantly, you must click the Select Required button which should resolve dependencies and remove the warning message you are probably worrying about. 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 architecture 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 ... (Eclipse menu on Mac OS X).

The Eclipse preferences are immense, 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 (I would hate to edit code an anything except Andale Mono), 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, if it is not already there, 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 them 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 Appearance tab, check Show line numbers to display line numbers in the left margin (optional). NOTE.- When you are editing a PHP file, you could left-click in the left margin and tick the Show Line Numbers line in the contextual menu. However, this toggle only applies to plain text files, not to HTML or PHP files. The only place where you can toggle line numbers on/off for such files is in the PHP/Appearance menu.

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 and Remove trailing spaces on editor save. 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

print_object(${word_selection}${cursor}); // DONOTCOMMIT

You can do other useful things with templates too. Here are two more I use:

debugging("'${word_selection}${cursor}'"); // DONOTCOMMIT

$$string['${word_selection}${cursor}'] = '.';

That is, a simple debug message with a stack trace, and a new language string.

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 using the GUI. You will have to edit one of the Eclipse config files by hand. So

Note down the path to your Eclipse profile. On Windows it will be something like C:/Documents and settings/XXXX/workspace, and on Unixy systems something like ~/workspace.
Close Eclipse.
Open the file net.sourceforge.phpeclipse.ui.prefs that is in the directory (your workspace)/.metadata/.plugins/org.eclipse.core.runtime/.settings in a text editor.
Look for a line in the file that starts _php_include_paths= If it is not there, add it at the end.
Change this line to say _php_include_paths=.
Run Eclipse again.

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 on what people used to do when the CVS was at Sourceforge. However, If you follow the Sourceforge instructions now you will spend a good deal of time trying to add a public key to your sourceforge profile to no purpose; the key generated is for cvs.moodle.org, NOT, sourceforge, and you add it via the Update My Developer Information tab on the moodle developers page at http://moodle.org/mod/cvsadmin/view.php?id=7134. Once you have uploaded your public key you can then try to fgure out how to make Eclipse use this keyset.

The rest of the ones in this section are personal preferences, but I recommend 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 -> 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.

Checking out the Moodle code

From the File menu, choose New -> Project ..., then click Next >.

In the wizard that pops up, choose CVS -> Projects from CVS, then click Next >.

Select Create a new repository location, then click Next >.

Fill in

For anonymous CVS access use

Host: XX.cvs.moodle.org

where XX.cvs.moodle.org is one of these mirrors

Repository path: /cvsroot/moodle
User: anonymous
Password: (leave blank)
Connection type: pserver

Host: cvs.moodle.org
Repository path: /cvsroot/moodle
User: (your Moodle CVS username)
Password: (if you set up the SSH2 key thing in preferences, leave this blank, otherwise, type in your Moodle CVS password.)
Connection type: extssh

(CVS experts, if you are confused by that last one, know it is an Eclipse-specific thing.) Then click Next >.

On the next screen of the Wizard, choose Use an existing module. Wait a moment, then select moodle from the list. Click Next >.

On the next screen, make sure the option Check out as a project configured using the New Project Wizard is selected, then click Next >.

Click Refresh Tags, then choose the branch you want. For now leave it set to HEAD.

Click Finish.

Now you will find yourself back at the start of the New Project Wizard. This is because of the option you chose three paragraphs ago. This time you should select PHP -> PHP Project, then click Next >.

Make up a project name. moodle would be sensible.

Click Finish, and wait while all the moodle files are checked out of CVS.

Once it has finished, it will probably ask you if you want to switch to the PHP perspective. Answer Yes.

If you also need another branch (1.6, 1.7, 1.8, ...) repeat all the other steps with a few changes:

This time you can choose Use an existing repository location instead of typing all the sourceforge CVS details again.
Select the appropriate branch. If you don't see the branch you want, see this Troubleshooting tip.
Use a different project name (e.g. moodle16, moodle17, etc.).

Let your development web server know where your files are

Either by editing you web server's config files, or using a symbolic link. Make sure your webserver can see your new working set of files at a sensible URL, so you can test the code you are working on.

Quick tour of some cool features, and remaining configuration changes

I find the default workbench setup is pretty good. Here is a quick guide to some of the bits.

Navigator

To the left is the Navigator. This is a tree view of all your files. If you double-click on a file, it opens in the editor in the middle. Try opening course/lib.php now. You will notice that it comes up nicely syntax-hightlighted.

Error highlighting

In the middle of the file, just type any old text, for example "I like Eclipse". Obviously, this is not valid PHP syntax, and Eclipse will notice this, and put a red underline under it. Also, by the scrollbar is a ruler with a red mark in it to show the error.

You will see some yellow marks lower down the ruler. There are warnings. Click on one, and you will be taken to where that warning is in the file. Hover your mouse over the warning, and you will get a tooltip explaining what the problem might be.

Save the edited file. (Don't worry that it is broken, we'll clean up the mess later.) Notice that a red error marker is added to the file in the navigator, so you can see that there is a problem. Also, error markers are added to the course folder, and the whole project, so you could see there was an error even if the navigator tree was collapsed.

You will probably find lots of warnings that the config.php file can't be found. In the navigator, find the file config-dist.php. Do Copy then Paste and choose to call the new file config.php. Edit this new config.php as normal. You should fine that most of the include file warnings have gone now.

Notice also that there is another marker on each file icon. A little yellow cylinder on most files, but a white-on-brown star on the one you have edited. This is telling you the CVS status of each file. The brown stars are changes you have made but not checked in yet.

Outline

Over to the right is the Outline view. This shows a list of functions and classes defined in this file. By default, they are listed in the same order as in the file, but if you click on the az toolbar button, they are sorted into alphabetical order.

Click on the function name add_course_module in the Outline. You will see that the editor scrolls to the definition of that function.

Code navigation

In that function, hover the mouse pointer over the function name insert_record. After a while, the documentation for that function will appear in a big tooltip.

Hold down CTRL, move the mouse pointer over the function name insert_record, then click. Eclipse should load dmllib.php, and scroll you to where this function is defined.

In the main Eclipse toolbar, there are forward and back arrows like in a web browser. Click back now to get back to course/lib.php.

Open resource

From the Navigate menu, choose Open Resource.... In the dialog that pops up, start typing a filename for instance type moodlel. In the box in the middle of the dialog, you will see it list all the files in the project whose names start that way. At the bottom is a box which lists the different folders that contain a file with that name. This can be a very quick way of opening files with fairly unique names like moodlelib.php, without having to click through the levels of the navigator tree. Of course, it is not so useful for an index.php file! Click OK now to open moodlelib.php. (It would actually work if you just did CTRL + Shift + R, moodlel, Enter.)

Multi-file search

Scroll down moodlelib a little bit, and double click on the name of the constant MOODLE_INTERNAL where it is defined, so that the text is selected. Then, from the Search menu, choose Search.... Notice that the Containing text box has already been filled in for you with the text you just selected. Of course you can just type text into this box without selecting it first. Notice that you can do regular expression searches, but leave that turned off for now. In the File name patterns box type *.css, *.html, *.inc, *.js, *.php, *.xml. (This is the most useful general setting for working on moodle. Eclipse will remember this setting, so you only have to enter it once.) Click Search.

The search results will appear in a new view underneath the editor. That view has a toolbar with yellow up and down arrows. Click the down arrow a few times and it will take you to the first few matches in the code, opening the relevant files as necessary.

Synchronize view

I think this is my favorite feature. From the Window menu, select Show View -> Other.... In the dialog that pops up, select Team -> Synchronize, then click OK.

This opens the Synchronize view below the editor. The view has a toolbar. Click on the first toolbar button, which pops up the Synchronize wizard.

On the first screen, there will probably only be one option: CVS. Make sure that is selected, then click Next >.

Under Scope, choose Workspace, then click Finish.

Wait while it talks to the CVS server. After a while, you will see that the Synchronize view lists course/lib.php, and something called .project.... That is, it is listing just the files you have edited, but not checked in yet.

.project is something that belongs to Eclipse that we don't care about. So select it and bring up the context menu, and choose Add to .cvsignore.... In the dialog that pops up, choose the top option, then click OK. Then you will find the Synchronize view shows you a .cvsignore file that you aren't interested in, so add that to .cvsignore too!

If you double-click on course/lib.php here, you will see that it opens the compare editor, which is a nice graphical display of the changes in this file.

If you select a file or files here, then bring up the context menu, you will see the option to Commit... the changes. (But don't do that now!). This is the easiest way to commit things in Eclipse.

However, our changes were rubbish, so we want to undo them. So open the context menu again, and choose Override and Update. This checks a clean copy of the file out of CVS, removing our changes.

Note that the easiest way to do an ordinary CVS Update is to select the top-level project-folder in the Navigator view on the left, open the context menu, and choose Team -> Update.

That's all the really important features. I sure you can learn everything else on your own. An you could always read the built in help!

Creating a patch

In the synchronise view, right click on an item (file or folder) and choose Create Patch.... Or in the navigator, right click on an item and choose Team -> Create Patch....

This brings up a two-page wizard. On the first page you can select where you want the patch made. For small patches it can be useful to create them on the clipboard, but normally you will want to save them in a file.

On the second page, you can set some options, but normally you don't need to change the defaults which are Unified diff format, and Patch root set to Workspace. Well, sometimes it is helpful to change the second one to Project but it is not important.

There is a corresponding apply patch wizard that you can use to apply a patch to a project.

Switching to another branch or version

Suppose you have been using a check-out of HEAD from CVS, and then as the 1.9 release approaches, the MOODLE_19_STABLE branch is created, and you want to start following that instead.

Right click on the moodle project in the navigator view, and select Team -> Switch to Another Branch or Version ....
choose the second radio button: Select the tag from the following list.
If the branch you want is not in the Matching tags box, see Resetting the branch information below.
Select the branch you want and click Finish.

Troubleshooting

Some tips on how to solve common problems that may crop up.

Resetting the branch information

Every now and then, Eclipse may lose information on the branch tags it knows about. Hitting refresh tags may fix it, but if not, try the following:

Bring up the tag dialogue (example using "Team / Switch to Another Branch or Version").
Click on Configure tags ... (not Refresh tags).
Select config-dist.php in the top left box (if this is a Moodle checkout).
Click Add Checked tags.
Click OK.
Then you will have all tags.

(thanks to Tim Hunt)

Error loading php files after Ubuntu 7.04 Install

A java issue with Ubuntu 7.04 may cause an error when you attempt to load php pages. Refer to: http://www.plog4u.org/index.php/Using_PHPEclipse_:_Installation_:_Installing_PHPEclipse for details about how to fix this in Ubuntu 7.04.

After upgrading from Ubuntu 7.04 to 7.10, I had to go in and re-edit the /etc/eclipse/java_home file in order to get the CVS functions to work and be able to open PHP files. When I tried to do a CVS update I initially received an error about org.eclipse.team.internal.ccvs.ui.wizards.CheckoutWizard). Everything seemed to work again after reapplying the fix for the aforementioned 7.04 java issue.

Documentation