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):
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:
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
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
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
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
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.