argouml-tigris-org.github.io

Web pages for the ArgoUML project.

From the ArgoUML wiki at argouml.tigris.org.
Wiki: Setting up Eclipse 3

If you are running Eclipse 3.2 or later and Subclipse we have prepared a recommended setup configured through the Team Project Set Files For ArgoUML. These are Eclipse .psf files which can be used to automatically check out the project.

The directory structure of an Eclipse check-out of the main source code now mirrors the svn repository structure (since 20 April 2008). For details on the directory structure and layouts, see Source layout. The argouml-core-projectset.psf project set contains a small subset of the full repository. It only contains the files and directories needed to build argouml using Eclipse. It is possible to extend the core project set by importing the argouml-command-line-build.psf file into an existing workspace. This will add the necessary tools to build argouml from the command line; this build can then be run without opening Eclipse. Alternatively, you could achieve the same result by checking-out trunk/ on the command line, and using Eclipse to edit the files (not requiring any .psf files).

For the recommended setup to work we make certain assumption on what modules you have available in your Eclipse. The following are needed:

  • Subclipse
  • Ant
  • JUnit 3
  • PDE Tools

The following is optional and the features will be enabled if available:

  • Checkclipse

Eclipse installation instructions

These instructions are tested on Eclipse 3.3.1.1, downloading Eclipse IDE for Java developers. Note that if you download Eclipse Classic or Eclipse for Java EE Developers, you will not need to install the PDE plugin (PDE is included in those Eclipse packages).

<!> For using the Eclipse Update feature, be sure that you're executing Eclipse with a user with writing privileges on the Eclipse installation folder.

  1. Download and install the latest Java Software Development Kit (JDK) from sun.com: http://java.sun.com/javase/downloads/

  2. Download and install the latest Eclipse IDE for Java Developers: http://www.eclipse.org/downloads/

  3. Download and install Subclipse from within Eclipse, see http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA.

  4. Download and install the PDE tools from within Eclipse (for Eclipse Ganymede (version 3.4) and (maybe) above, see the next listitem):

    1. Help > Software Updates > Find and Install...

    2. Select 'Search for new features to install', click Next.
    3. Select 'The Eclipse Project Updates', click Finish.
    4. Select a nearby mirror if asked.

    5. Select The Eclipse Project > Eclipse SDK Eclipse 3.3.1.1 > Eclipse PDE Plug-in Developer Resources 3.3.2......., Next, Next, Install. Remark MVW: I had to install "Eclipse Plug-in Development Environment", too.

    6. Restart Eclipse.
  5. If you're using Eclipse Ganymede (which is version 3.4) the installation process of PDE Tools is slightly different:

    1. Go to Help -> Software Updates... (if you get this error on Linux "Cannot launch the Update UI...", then enable the classic update in Preferences > General > Capabilities, then follow the previous method).

    2. Go to the tab called "Available software"
    3. Open "Ganymede update site". Open "Java Development Tools". Check the appropriate package (Eclipse Java Development Tools) and click the button "Install". Maybe you need to install the Eclipse Plug-in Development Environment too, I (Shurakai) am not quite sure about that. Anyway, I installed them.
    4. Restart Eclipse
  6. If you're using Eclipse Galileio (3.5) it looks like this:

    1. Go to Help -> Install New Software.

    2. In the dropdown box, select "The Eclipse Project Updates".
    3. Check PDE/API Tools Environment and go through with the installation including the restart of Eclipse.

  7. Download and install Checkstyle 4.4 from within Eclipse, see http://eclipse-cs.sourceforge.net/. (The ArgoUML configuration for checkstyle is not yet updated to Checkstyle 5.0).

  8. Ant and JUnit3 are included in the above.

  9. If you are planning to develop ArgoEclipse you also need to download the Albireo library, see http://wiki.eclipse.org/Albireo_Installation.

If any of these instructions don't work or could be improved in some way, please ask on the developer mailing list or update this page.

Basic ideas of the set up

Here are the ideas governing the layout of the recommended Eclipse set up.

  • Argouml in its own workspace
  • To some extent the ArgoUML projects rely on the workspace-specific settings. If no workspace-specific settings are relied on this is not important.
  • Prefer project-specific settings to workspace-specific settings (compiler, JRE, style).
  • The workspace-specific settings are not saved automatically in the repository so using them would be error-prone.
  • Compile time dependencies are set up using the PDE Tools. Projects containing java code are Plugin-projects.
  • Run time dependencies are set up in the Configurations.
  • Configurations saved in the project where they "belong".
  • Use as many of the build tools as possible from their Eclipse distributions.
  • Installing tools is always complicated and a risk in the project. On the other hand, maintaining our own set of tools is also complicated. As Eclipse delivers an infrastructure where the installation of tools is simple the strain on every ArgoUML developer is small and the Eclipse integration project of the tool project will deal with all OS and platform issues.
  • Eclipse also has an infrastructure for handling tools that are configured but missing so developers forgetting to install one or several tools can still do basic things.

Checking out through Eclipse

This instruction is for downloading the ArgoUML source through Eclipse.

Eclipse uses Team Project Set (.psf) files to automatically control the check-out from the SVN repository.

Do the following.

  1. Go to the Team Project Set files download page: Team Project Set Files For ArgoUML

    1. On Windows systems (quicker way):
      1. Copy the link location of argouml-core-projectset.psf (copy shortcut/copy link location).
      2. Open Eclipse

      3. File > Import... > Team Project Set > Next.

      4. File name: click 'Browse...'

      5. Right-click > paste, or <ctrl>-v. Press <enter>. After a short delay, the filename updates with the .psf that's just been downloaded.

      6. Click Finish.
      b. On any other system:
      1. Download the argouml-core-projectset.psf Team Project Set file and save it somewhere.
      2. Open Eclipse

      3. File > Import... > Team Project Set > Next.

      4. File name: click 'Browse...'

      5. Navigate to the .psf file you just saved and press <enter>.

      6. Click Finish.
    Now everything is automatic even though it takes a while. What happens is:
    1. Files are downloaded from the Tigris SVN server and put into Eclipse projects.

      It is around 45MiB that is downloaded so beware if you are on a slow connection. If you do this for the ArgoEclipse psf file, more than 300MiB are downloaded. During downloading, Eclipse is asking you multiple times for your Tigris account name and password; once per Eclipse project. It may look like the password is refused, but it is not - just be patient and type your name and password again.

    2. The projects are built. First things that are special for ArgoUML, generated Java code, are created by Eclipse calling ant, then Eclipse kicks in and compiles the Java code.
    3. Eclipse finds the Configurations that are also checked out.

    If this doesn't work, try to select Project => Clean... and clean the projects that were not built properly. If it's always wrong (may be argouml-core-model-mdr with Indigo), run the "clean" ant's target from "build.xml".

  3. Verify that you can start ArgoUML from the debugger within Eclipse. You can do this by clicking on the little down-arrow close to the Debug icon in the tool bar, selecting Debug... or Run..., and finding ArgoUML in the list (under Java Application).

Eclipse to help with the ArgoUML coding style

Note: With the change to project specific settings this need not be done by every developer.

This instruction is to set up Eclipse to work according to the ArgoUML Coding standards. If this is not done correctly you will most likely find that you will have to do a lot of manual edits every time Eclipse has touched the code. You have your tool working against you instead of for you.

The instructions here are for these settings to affect your Eclipse Workspace. If you have other projects in the same Eclipse Workspace you would probably want this for only the ArgoUML projects and that is possible although not explained here. We suggest you to consider having ArgoUML work in an Eclipse Workspace separate from your other projects.

Code conventions

  1. Select in the menu Window => Preferences.

  2. Then select Java => Code Style => Formatter.

  3. For Eclipse 3.2 and later you do: Select Java Conventions [built-in].
    • For Eclipse 3.1 you do: Select Import and give the file eclipse/eclipse-argo-formatter.xml located in the argouml-core-tools project that you just checked out.

      This takes care of the Java Conventions [built-in] Tab width bug (https://bugs.eclipse.org/bugs/show_bug.cgi?id=104765).

  4. Press OK.

This will give you Code Conventions exactly like the Sun Coding Style that we use in the ArgoUML project.

New file templates

  1. Select in the menu Window => Preferences.

  2. Then select Java => Code Style => Code Templates.

  3. Select Import and give the file EclipseWorkspace/argouml-core-tools/eclipse/eclipse-argo-codetemplates.xml located in the argouml-core-tools project that you just checked out.

  4. Press OK.

This will set up templates to be used when using the Eclipse functions for creating files, functions, types and Javadoc...

Eclipse to automatically find problems in the code

Note: With the change to project specific settings this need not be done by every developer.

This instruction is to set up Eclipse to automatically find what, in the ArgoUML project, could be considered problems in the code.

You can apply these individually depending on what level of help you need in your coding. I (Linus Tolke) recommend that you set them all on the Warning level. This makes them visible for you. You can then decide to fix them or not depending on how you feel about the code you are working with.

The instructions on where to find the different settings are for Eclipse 3.2. If you use Eclipse 3.1 you might need to search through the tabs to find where the setting is since they were reorganized for Eclipse 3.2.

  • Compiler compliance level.

After ArgoUML v0.33.1:

  • The Complier level : "1.6" (nothing to do).

Before ArgoUML v0.33.1:

  • See in the menu Window => Preferences. Then select Java => Compiler. At the right hand side set Compiler compliance level: 5.0. Check Use default compliance settings. In the ArgoUML project we have decided to keep source compliance to Java5 (See Section 3.3.1, “Choice of JRE: ArgoUML will support any JRE compatible with a Sun specification of any JRE from Sun that has not begun the Sun End of Life (EOL) process. ”). This setting enables Eclipse to tell you where some Java6 features have crept in.

  • Find forgotten and incorrect Javadoc comments.

    In the menu select Window => Preferences. Then select Java => Compiler => Javadoc. Suggested settings for these tabs (Only things diverting from the Eclipse defaults are listed):

    • Javadoc => Malformed Javadoc comments: Warning, Private, Check all "Report...".

    • Javadoc => Missing Javadoc tags: Warning, Private, check Check overriding and implementing methods.

    • Javadoc => Missing Javadoc comments: Warning, Protected, uncheck Check overriding and implementing methods.

    These problems (except missing Javadoc comments) are also found by Checkstyle so if you are running Checkclipse (See Section 2.9.6, “Settings for Checkclipse”) put this in Ignore instead.
  • Code that hides other code.

    In the menu select Window => Preferences. Then select Java => Compiler => Error/Warnings. Suggested settings for these tabs (Only things diverting from the Eclipse defaults are listed):

    • Potential programming problems => Serializable class without serialVersionUID: Ignore We don't use serialization in the ArgoUML project anyway.

    • Potential programming problems => Possible accidental boolean assignment: Warning.

    • Name shadowing and conflicts => Field declaration hides another field or variable: Warning.

    • Name shadowing and conflicts => Local variable declaration hides another field or variable: Warning, check Include constructor or setter method parameters.

  • Find Code that shall be removed.

    In the menu select Window => Preferences. Then select Java => Compiler => Error/Warnings. Suggested settings for these tabs (Only things diverting from the Eclipse defaults are listed):

    • Unnecessary code => Local variable is never read: Warning. (This is default in Eclipse 3.3.)

    • Unnecessary code => Parameter is never read: Warning. uncheck Ignore parameters documented with '@param' tag.

    • Unnecessary code => Unused or unread private members: Warning. (This is reformulated and default in Eclipse 3.3.)

    • Unnecessary code => Unnecessary semicolon: Warning.

    • Unnecessary code => Unnecessary cast or 'instanceof' operation: Warning.

    • Unnecessary code => Unnecessary declaration of thrown checked exception: Warning.

Settings for Checkclipse

CategoryFix: This description needs to be updated!

Checkclipse is a plug in for Eclipse which needs to be installed separately. It enables style checking according the rules set for the ArgoUML project.

Get the latest Checkclipse kit from SourceForge as described at http://eclipse-cs.sourceforge.net/downloads.html. (Checkstyle is bundled with Checkclipse so it's not necessary to install it separately, but the web site is http://checkstyle.sourceforge.net/ for reference.)

Most ArgoUML projects in Eclipse have their Checkclipse settings predefined which should be found as soon as you install Checkclipse, but if you need to set them up by hand, use the following instructions. These instructions are for Checkclipse 2.1.

In the Java perspective, in the Package Explorer select the project argouml-app. Then, in the menu, select Project => Properties, select Checkclipse (appears only if Checkclipse is correctly installed) and then fill the fields like this:

  • Enable Checkstyle - Checked.
  • Set Project Classloader - Checked.
  • Checkstyle Configuration File: /argouml-core-tools/checkstyle/checkstyle_argouml.xml in the argouml-core-tools project.
  • Checkstyle Properties File: /argouml-core-tools/checkstyle/checkstyle.properties in the argouml-core-tools project.

Leave the rest of the fields at their default (empty). The File Filters are defined on an additional preferences tab rather than in a separate file as in earlier versions of Checkclipse. If this isn't populated with the saved values from SVN you can add individual files to the exclude list as you encounter them, but generally any machine generated source file (JavaLexer, JavaRecognizer, etc) should be excluded from the checks.

Running JUnit test cases from within Eclipse

Most of the JUnit test cases belong to the argouml-core-tests Eclipse project. The argouml-core-tests Eclipse project has its compile time dependencies set up to include the things needed to compile the test cases. This means that it is possible to compile the test cases and nobody will create tests that use the insides of some subsystem that is supposed to be hidden.

The Model subsystem is separated in two parts:

  • The interfaces and some bootstrap code in the argouml-core-model Eclipse project.
  • The MDR implementation in the argouml-core-model-mdr Eclipse project.

There is also for test purposes a partly implemented Mock implementation of the model subsystem in the org.argouml.model.MockModelImplementation-class for the purpose of testing the interfaces and the bootstrap code but it requires the test cases to be written especially for that.

The tests are never to be compiled against the MDR-implementation but against the interfaces. This means that the MDR-implementation is not included in the project dependencies.

When it comes to running the tests, most of the tests require the Model subsystem working to succeed. To run the application with a working Model subsystem, a working implementation is needed so the tests require the MDR-implementation.

The simplest way to solve this is to:

  1. Create the test (by right-clicking on any of the test classes and select Run as JUnit Test or Debug as JUnit Test).

    The test fails with a java.lang.ExceptionInInitializerError on the first reference to Model. If it doesn't then the perhaps the test case doesn't use the Model.

  2. Select Debug... or Run... to get the configuration editing box. It has remembered the test case and it is selected.
  3. Add the argouml-core-model-mdr to the class path. Classpath tab, Select User Entries, Add Projects, Check argouml-core-model-mdr, make sure Add exported entries of selected projects and Add required projects of selected projects are checked, Press OK, Press Debug or Run. Eclipse will remember these changes to that configuration but you will have to do it all over again once for each new test case.

Running all JUnit test cases from within Eclipse

The description so far describes how to do this for a single test case at the time. If you want to run all test cases in one go from within Eclipse it is also possible. We have not prepared that for three reasons:

  • Some of the tests fail when run in this way. The guess (Linus July 2006) is that this depends on the fact that Eclipse doesn't start each test in its own JVM and some of the tests relies on a fresh environment (empty models...). Let's hope that an upcoming version of Eclipse includes a function to allow us to specify that the tests are to be run each in its own JVM. Another cause might be that the tests rely on certain other files being in specified places that the Eclipse set up doesn't provide.
  • Maintaining the Configuration. Since we have an Eclipse setup with a mismatch between the compile time dependencies and the run time dependencies this Configuration contains references to specific jar-files. This means a maintenance problem whenever changing version of a dependency.
  • Selection of tests. In the project we keep all tests in the same tree, whether they are working or not. We distinguish between test classes with names starting with "Test", "GUITest", and neither of them. The ones starting with "Test" or "GUITest" are official tests that should be working. All others are tests that are never run automatically. They are perhaps used for other purposes. In Eclipse, there is no way to specify this so the description below will run all tests.

    Such a test is the DoAllTests-test suite that runs all tests so tests risk to be run twice.

If you want to test this, this is what you do:

  • Right-click on the project argouml-core-tests.
  • On the multilevel pop-up that opens, select Run As... JUnit Test or Debug As... JUnit Test.
  • A Configuration is created on that project with the Run all tests in the selected project, package or source folder: checked and the configuration is started/launched.
  • Stop the running Configuration. The newly Configuration has the same problem as every single test above with the model subsystem so it won't work.
  • Press Debug... or Run... to open the Configuration editor. The newly created Configuration argouml-core-test is selected.
  • Add the argouml-core-model-mdr project to the class path. This is done by:
    • selecting the Classpath tab,
    • selecting argouml-core-tests under User Entries,
    • clicking Add projects, and
    • selecting the argouml-core-model-mdr project and press OK.
  • Run all the tests by pressing Debug or Run.

How to work with the modules

The Eclipse set up is prepared to handle work with some ArgoUML subprojects too in the same way. To work on these, or having them enabled in the workspace to spot incompatible changes you do the following:

  • Set the workspace default file for ant to tools/eclipse/eclipse-ant.properties.

    Window => Preferences, Ant -> Runtime Properties and add a Global property file ${workspace_loc:/argouml-core-tools/eclipse/eclipse-ant.properties}.

  • Import from the argouml-modules-projectset.psf files.

CategoryFix: We no longer recommend the workspace-settings but use project settings so each developer need not supply those themselves.

CategoryFromCookbook

Setting up Eclipse 3 (last edited 2014-11-24 18:11:31 -0700 by elbedd)