Skip to content

Information for Developers

Jump to bottom
Andreas edited this page Oct 20, 2023 · 47 revisions

Project/Module Structure

Umlet is available as Swing Standalone application, Eclipse Plugin, VSCode Plugin and Web Application. It is a multi-module maven project with the following modules:

  • umlet-elements: the shared code which mostly consists of element implementations
  • umlet-res: resources of UMLet which should be placed on top level instead of within jars (e.g., to let the user change the palettes without unzipping jars)
  • umlet-gwt: the shared code for the web version of UMLet and the VSCode plugin
  • umlet-web: the web version of Umlet (www.umletino.com)
  • umlet-vscode: the Umlet VSCode (Visual Studio Code) Plugin (more infos in umlet-vscode/README-dev.md)
  • umlet-standalone: the Swing Standalone UMLet endpoint
  • umlet-swing: the Swing specific UMLet code which is shared by the Eclipse Plugin and Standalone UMLet
  • umlet-eclipse-plugin: the eclipse plugin project which is built with tycho. The maven build makes sure everything is set up exactly as PDE/Tycho expect it.
  • umlet-eclipse-plugin-deps: a helper module for the eclipse plugin which is required for the tycho interaction
  • umlet-eclipse-p2: builds an Eclipse P2 repository to provide the eclise plugin as an update site.

If you're only interested in one platform, you can ignore unused modules.

  • UMLetino needs: umlet-elements, umlet-gwt, umlet-web
  • UMLet VSCode Plugin needs: umlet-elements, umlet-gwt, umlet-vscode
  • UMLet Standalone needs: umlet-elements, umlet-swing, umlet-standalone
  • UMLet Eclipse Plugin needs: umlet-elements, umlet-swing, umlet-eclipse-plugin, umlet-eclipse-plugin-deps, umlet-eclipse-p2 (only if you need to build an update site)

Setting up the Umlet Dev-Environment

Please note, that we typically cannot provide individual help on setting up the project, but if you execute the following steps, you should get Umlet to compile.

Building Umlet via Commandline

The master branch and every pull request ist constantly built by Travis CI. Click here to see the latest build result and check the build log. Travis is configures via travis.yml file, where you can see that it is just a simple mvn clean install on the main pom.xml file (-P checks enables additional checks during the build, but it's not required) Therefore the steps to build umlet are simply:

  1. Install JDK8 (future versions may also work, check the travis.yml file for the tested versions). If you don't have a JDK, we suggest to use Temurin from Adoptium.net
  2. Install Git and Apache Maven. NOTE: Maven 3.6.1 cannot be used to build the Eclipse Plugin due to a bug!
  3. Checkout Umlet from GitHub (e.g. by cloning https://github.com/umlet/umlet.git)
  4. Open a command line, cd into the cloned git repository, execute mvn clean install and wait until the build is finished
  5. Only after you have built Umlet this way, I suggest to setup an IDE (otherwise the IDE may be the cause of build related issues)

As mentioned previously, if you are only interested in a specific release variant of Umlet, you can remove modules from pom.xml to speed up the build.

Setting up an IDE

We strongly suggest to use the EclipseIDE, therefore we provide detailed instructions on the setup, but in general you can use any IDE to develop Umlet (as mentioned before the build also works with the command line).

Umlet Setup for EclipseIDE

UMLet uses several generators and does some specific file copies to make the Umlet Eclipse Plugin module work, therefore the following setup steps are necessary to build UMLet:

NOTE: Eclipse 2019-09 (and possibly other versions) ships with Maven 3.6.1 which cannot be used to build the Eclipse Plugin due to a bug. Please use Maven 3.6.0 or 3.6.2

  1. You should use an Eclipse IDE with Maven integration (m2e) and Git integration (EGit).
    1. A good choice is the "Eclipse for RCP and RAP Developers" which comes with m2e and EGit and with the Plug-in Development Environment (PDE) which you need to debug the UMLet Eclipse Plugin. If you do not need to debug the Eclipse plugin, any Eclipse distribution with m2e and EGit will work.
    2. A useful setting is "Window -> Preferences -> Maven -> Hide folders of physically nested modules" to avoid "Open Type" from listing types multiple times
    3. If you see the error "Plugin execution not covered by lifecycle configuration" in the pom.xml files, you should install the appropriate connectors (they are used to tell Eclipse to do something if a Maven-Plugin is executed; e.g. if you use "add-sources" from the build-helper-plugin, you need the connector to tell Eclipse to add the src folder in the Eclipse project settings)
    4. If you want to debug the the GWT version (UMLetino), you can try the GWT Plugin (https://github.com/gwt-plugins/gwt-eclipse-plugin), but usually the umlet-parent/launch/Umletino GWT SuperDev Mode launcher is easier to use (it starts the SuperDevMode using the maven plugin)
  2. Use "Import -> Existing Maven Projects" on the cloned Umlet Git Repository to import the UMLet project and its modules.
  3. If you see compile errors, the cause is probably that some generated sources are missing. To generate those, make an initial maven build (e.g. by calling mvn clean install or using the umlet-parent/launch/mvn clean install.launch)
  4. Select all Umlet modules and press F5 (to be sure that the filesystem is synched with Eclipse)
  5. Select all Umlet modules and press Alt+F5 -> OK to update the Maven Projects with the information from the pom.xml files
  6. If you don't need the Eclipse plugin or the GWT based versions (Umletino/VScode Plugin), uncomment the module entries in the parent-pom.xml and they won't be built (all modules starting with umlet-eclipse- are only used for the Eclipse plugin)
  7. As mentioned before, there are useful Eclipse Launchers in umlet-parent/launch/ which can be used to build, debug, ... Umlet
  8. If you can execute the maven build, but get unexpected Exceptions from javax.swing.* classes when starting the Umlet Standalone GUI from your IDE, maybe you are using a headless Java installation (which is missing necessary GUI classes). Please try another JDK distribution which contains a JRE with Swing classes. You could also try to run a Umlet distribution from www.umlet.com with your JDK package to make sure it contains all necessary classes. Otherwise try a JDK distribution like Temurin as mentioned above.

Other Info

Creating the Umlet.exe

Executables are created using http://launch4j.sourceforge.net Download Launch4J, import the launch4j_project.xml file and you can create updated versions of the executable

The ico and pngs in several sizes can be created from one source image using https://iconverticons.com

Enable logging in compiled Umlet

  1. Copy a log4j.properties file into the Umlet directory (same location as umlet.jar) (sample log4j.properties: https://github.com/umlet/umlet/blob/master/umlet-standalone/src/test/resources/log4j.properties)
  2. start UMLet with the following command: java -Dlog4j.configuration=file:log4j.properties -jar umlet.jar

Releasing Umlet

Steps to make a release build

  1. Update the version with "mvn changeVersion.launch". Enter version as MAJOR.MINOR.BUGFIX (e.g. 15.0.0) (updates pom.xml versions and MANIFEST.MF version in eclipse project)
  2. Afterwards do a maven build with "mvn clean install.launch" (IMPORTANT: step 1 and 2 cannot be combined into one mvn call, otherwise some maven plugins such as tycho would still use the old version)
  3. Check that all pom.xml files and the MANIFEST.MF contain the correct version
  4. Create a new tag which contains the changes; either per command line or with Eclipse EGit the following way:
  5. commit (but do not push!) the changes to the local branch
  6. right mouse click on "umlet-parent" -> Team -> Advanced -> Create Tag ...
  7. enter a name for the tag (in same style as previous version tags) and click "create tag and start push" -> Next -> Finish
  8. Update version of master branch to next MAJOR.MINOR.BUGFIX-SNAPSHOT version (e.g. 15.1.0-SNAPSHOT, must have 3 parts and qualifier) and push it to the master branch

The following tests must be executed before a release (currently manually)

Before every release the following parts of UMLet should be tested:

  • Batch-Start (eg: java -jar umlet.jar -action=convert -format=pdf -filename=palettes/*.uxf -output=.) (there is also an Eclipse launcher in the Baselet project which also uses Headless Mode "-Djava.awt.headless=true" which should also work for batch mode)
  • starting with an uxf file as parameter (e.g. java -jar umlet.jar palettes/Plots.uxf) should open that file
  • Grouping and Selectionhandling of elements
  • Export to pdf and bmp
  • Custom Elements (make sure there are no compile errors)
  • Eclipse Plugin working
Clone this wiki locally