YOUR FIRST INSTALL

Your directory structure should look like this (note that "C:\eclipse" can be

anything you want - I personally use C:\mazz\eclipse for example):

C:\eclipse\eclipse   (this is where the base install lives)

C:\eclipse\ext       (this is where your plugins ("extensions") live)

C:\eclipse\ws        (this is where Eclipse's .metadata workspace data lives)

C:\eclipse\projects  (this is where you can put your projects (optional))

C:\eclipse\config    (this is where you put exported preferences (optional))

The first time you install Eclipse, unzip it into "C:\eclipse" - this puts your base install into C:\eclipse\eclipse.

Now create a special directory called "links" under C:\eclipse\eclipse.  In

that C:\eclipse\eclipse\links directory, create a file called "main.link".  The

contents of "main.link" is a single line pointing to the full path to your "ext"

directory.  Example (IMPORTANT: you need to escape the backslashes):

path=C:\eclipse\ext

Now when you want to install/download plugins, the Install/Update manager will

give you the option to install it in your ext directory.  This allows all of

your personal plugins to remain external to the Eclipse install directory.

Keeping your own plugins external to the Eclipse installation makes upgrading

easier.  If you already have plugins that you want to install manually now,

create a "C:\eclipse\ext\eclipse\plugins" directory and put your plugins in

there (this is analogous to Eclipse's own "plugins" directory).

One other nice thing about Eclipse is the ability to have multiple extensions

directories.  I personally have several - one specifically for JBoss Eclipse IDE, one

for my test plugins (ones that I just want to try out but aren't sure I want to keep;

things like beta-quality plugins for example), and one for my "main" plugins that I

plan on keeping.  So, under my "links" directory, I have a "main.link" file

pointing to my "C:\eclipse\ext\main" extensions directory, I have a "test.link" file

pointing to my "C:\eclipse\ext\test" extensions directory and I have a "jbosside.link" file

pointing to my "C:\eclipse\ext\jbosside" extensions directory.  When I pull down a

new JBoss Eclipse IDE version, I tell Eclipse to install it in that jbosside extensions

directory.  If I pull down a beta plugin that I want to test, I tell Eclipse to install it

in my "test" extensions directory.  Note that I can then disable one or more extensions

directories (and thus disable the plugins in those directories) by simply removing the

corresponding .link file.  When I want to re-enable them, I put the .link file back.

If you only ever want to use a single workspace, you can start Eclipse like

this (ignoring any -vmargs or other parameters you might want to pass in):

C:\eclipse\eclipse\eclipse.exe -data C:\eclipse\ws

If you want to have multiple workspaces and switch between them, create your

workspace directories under this "ws" directory - these directories are where

Eclipse will place its .metadata directories:

C:\eclipse\ws\jboss-4.0

C:\eclipse\ws\jboss-head

C:\eclipse\ws\sandbox

Now just create shortcuts for each workspace.  Eclipse allows you to switch

workspaces from the tool, this just allows you to start up Eclipse in any

specific workspace you want:

C:\eclipse\eclipse\eclipse.exe -data C:\eclipse\ws\jboss-4.0

C:\eclipse\eclipse\eclipse.exe -data C:\eclipse\ws\jboss-head

C:\eclipse\eclipse\eclipse.exe -data C:\eclipse\ws\sandbox

As a side note, I like to pass in "-vmargs -Xmx512m" to bump up my JVM max

memory.

Now, the install directory where Eclipse is (e.g. c:\eclipse\eclipse) has no

customizations that will be lost when you upgrade.

You may place all of your projects in "C:\eclipse\projects", just as a

convienence.  I like to have my projects localized to a central location.  You

can have your projects anywhere you like.  However, I avoid putting my projects

in the actual workspace directories (C:\eclipse\ws and below) because Eclipse

gets funny when you put projects under subdirectories of its workspace (e.g.

C:\eclipse\ws\jboss-head\aop).  If you only put projects directly under your

workspace directory (e.g. C:\eclipse\ws), that is OK and is how Eclipse is

really designed.

Once you get Eclipse's preferences configured the way you like, you should

export all of your preferences (in 3.0, Windows->Preferences has an "Export..."

feature - in 3.1, File->Export has a "Preferences" option).  In addition, I also

export the individual preferences when applicable (Templates have an Export

capability as well as the Code Formatter).

Place your preferences file(s) under "C:\eclipse\config".  There is nothing

special about this directory's location or name, its just a location I use to

store my preferences files.

You are now installed and have separate workspaces available and both

workspaces and plugins are independent of the Eclipse install.

UPGRADING YOUR ECLIPSE

Now you are running happily along developing in Eclipse.  Once a new version

comes out, there are very few steps to perform to upgrade, and they go very

quick.

First, download the new Eclipse .zip install file.

Then make a copy of your C:\eclipse\eclipse\links directory and delete the

entire C:\eclipse\eclipse directory, in effect removing your old Eclipse

install.  I like to delete the old install to ensure that no old (and possibly

incompatible) files are still hanging around.

Now unzip the new version back in that C:\eclipse\eclipse (remember, unzip to

the C:\eclipse directory - the install .zip will install a "eclipse" directory

as its base directory).

Now copy back your "links" directory - giving you back your original "C:\eclipse\eclipse\links\main.link" file (and any others you have).

You now have a full and clean install of the new version.

Start it up and you will notice that your plugins are still intact and loaded.

Even your workspaces are back to normal - all your projects should be intact.

The last step is to import your preferences to get back your original

configuration.  For Eclipse 3.0, go to Windows->Preferences and select the preferences file that

you stored in C:\eclipse\config and "Import..." them.  For 3.1, go to File->Import

and select "Preferences" then select your preferences file. Note that naturally some

preferences won't be compatible or used in the new version - Eclipse will pop

up a dialog box informing you of this should it occur and will tell you what it

is doing.

Note that you must import your preferences in each of your workspaces

(preferences are stored in the workspaces' .metadata directories and hence each

workspace has its own set of preferences).

That's it.  You've upgraded in less than 5 minutes.

See CustomizingEclipse