The instructions below describe how to set up your environment if you want to contribute changes to the Umple project. Many people work on Umple using Eclipse, others use command line tools and plain text editors. You will need to use the command line for some steps.
This page discusses the technical setup. You will also need to understand the processes and best practices required to contribute properly to Umple
Step 1: Set up and install prerequisites needed for building Umple
Before starting, you need to ensure that on your machine (Windows, Mac or Linux) you have Java 8, Apache Ant, Ruby and Php7 Installed (php5 also works). If you have a choice, we suggest using Mac or Linux as your platform as most developers find working with Umple using Unix commands easier than working with Windows. Optionally you might want to install Eclipse.
This will run through simple steps for installing the prerequisites for development:
Install Oracle JDK8 Download
Run the following scripts in an Administrative PowerShell (each should be run individually):
choco install ant git choco install ruby choco install php
Note: The above will install the latest versions of ruby and php. It is possible that the latest versions will result in emergent problems due to Umple using deprecated features. For Ruby Umple is known to work on --version=2.0.0 and --version=2.2.3 For Php Umple is known to work on --version=5.5.26 and --version=5.5.34 --version=5.6.17
You will be asked to "accept running of scripts," agree.
Adjust your environment variables (chocolatey may have done some of these for you already):
Add the following to your
C:\tools\ruby\ruby23\binif you're using Ruby 2.3 *
JAVA_HOMEand set it to be the location of your JDK installation, likely
65may be different)
You have several options to obtain Java, php, ant and Ruby. Homebrew, below, can install them all and is probably the simplest approach. Before following the instructions below, see what you already have installed. Java can be installed directly by downloading the latest jdk from Oracle. Php is already installed with the latest MacOS so you do not normally need to install it separately.
brew tap caskroom/cask brew update brew install php ant ruby brew cask install java
Note: You can also install Java directly from Oracle. It is suggested that you install the latest version of Java, which gets updated every couple of months.
** Apple Silicon machines (mac M1)
You need to install php and ruby using Homebrew. However, Some JDKs may generate errors when doing full build due to "core dumps". Azul open JDK is working fine and can be downloaded from https://www.azul.com/downloads. We tested Umple using Azul openJdk version "16.0.1" (date 2021-04-20).
Alternatively, you can use the docker image, which is based on arm64 Ubuntu 20. It can be pulled from here. The docker image is very fast (it takes around 5 min).
For Ubuntu-based distributions:
For Java, the jdk is going to be downloaded as you download the ant tool.
sudo apt-get update sudo apt install openjdk-11-jdk sudo apt-get install ant git php sudo apt-get install rvm sudo apt-get install ruby sudo apt-get install csh
Note: The above will install the latest versions of ruby and php. It is possible that the latest versions will result in emergent problems due to Umple using deprecated features. For Ruby, Umple is known to work on --version=2.0.0 up to at least 2.7 . For Php, Umple is known to work on --version=5.5.26 up to at least 7,4. For jdk, Umple is known to work on --version=8. The shell "csh" is useful when you want to use the commands in dev-tools. For example, while you are in dev-tools, we can enter "csh bumple".
Step 2b: Set up your Umple git repository
Option 1: Command line download: Create a directory where you want the Umple code to reside, cd to that directory and check out the Umple code from the Github repository. Make sure there is no space in the pathname. A suggestion is to issue the following command directly in your home directory, which would create a new directory called 'umple' there. You could also put it somewhere else and create a symbolic link in your home directory called 'umple' that points to the other place.
git clone https://github.com/umple/umple.git
Option 2: Github Desktop: Alternatively go to https://github.com/umple/umple and select the 'Open in Desktop' option. If you do this, you will be prompted to install Github Desktop if you do not yet have it installed. Then your repository will be downloaded into the location where Github Desktop installs its repositories.
Do not download a Zip file from Github; that would just get the code, not a full repository.
Step 2c. Do a series of command-line builds as follows:
Run the following in the 'build' directory in the trunk
ant -Dmyenv=local bootstrap, this installs Ivy and Ant contrib. This is only required once ever (however, it is idempotent and causes no problems with more invocations). This should take a minute.
ant -Dmyenv=local -f build.umple.xml first-build-- this gets the Umple compiler used to compile Umple itself, which is obtained from the most recent successful push to git and built by http://cc.umple.org, and stored at http://dl.umple.org . You only need to do this the first time you compile, and then to grab the latest release. This should take about 1.5 minutes on a fast machine.
ant -Dmyenv=local-- This is called a 'full build' and uses the compiler you most previously downloaded. From now on, you normally just do this when you want to compile and test fully. This will take between 6 and 10 minutes depending on the power of your machine (and could take longer as the number of tests in Umple increases). It is also possible to do simpler compiles. See the CheatSheet. If the build takes excessive time, see the Troubleshooting section below.
If this fails trying to load "junit" what may be actually missing is ant-junit.jar. Probably only an issue not building under eclipse.
On Windows replace 'local' above with 'wlocal', so
See the instructions at the end entitled 'Command Line building of Umple using Ant' for more command line options, if you plan to regularly using the command line.
Note for Eclipse users: once you have followed the instructions below to get Umple setup for development in Eclipse, you can (optionally) configure Ant as an External Tool in Eclipse. Doing so allows you to trigger a full build from inside Eclipse, without opening a terminal and typing in commands. See this page for how to set this up.
Step 2d: Setting up local UmpleOnline (Not needed for those just working on the compiler, but still useful)
You will likely want to set up a local version of Umple Online so you can test your changes to UmpleOnline, and also test your compiler changes manually]
Step 2e: Getting going with development
You might want to add the 'dev-tools' directory to your path, to give you access to certain wu
Also remember to read and understand the process to follow to contribute to Umple
Once you have got your environment set up, you can create create pull requests to change Umple.
If you want to do development using command line tools, you are now done. But if you want to use Eclipse, then continue).
Step 3: Setting up Eclipse (Optional)
Ignore this section if you don't want to use Eclipse initially.
Step 3a. Set up to run Umple in Eclipse
If you want to use Eclipse, follow the instructions on the page Install Eclipse Plugin
Step 3b: Additional Eclipse Dependencies needed
- As your workspace for Eclipse, choose the trunk of your checked-out working copy of Umple. Using the Working Copy directory as your Eclipse workspace is not mandatory, but will simplify some steps.
- Install the IvyDE plugin
- Open the Eclipse preferences, Window -> Preferences, select "Ivy -> Settings"
- For the "Ivy settings path," select
build/ivysettings.xmlvia the "File System..." button
- Close the dialogs
When you declare a directory to be your workspace, Eclipse places a hidden file there called
.metadata to keep track of various Eclipse properties.
Step 3c: Create a new java project called cruise.umple as follows:
Eclipse instructions are out of date, please update as available
This will be the first of several projects pointing to your checked-out code.
Select New / Java Project...
Enter the Project name:
cruise.umple(If you have followed the directions above and are using the Working Copy directory as your workspace, then leave 'Use default location' checked, otherwise uncheck the "Use default location" and point the location to the correct directory.)
Right click the
Configure -> Add Ivy Dependency Management
Right click the project again, select
Build Path -> Add Libraries...
IvyDE Managed Dependencies
Next, this displays the Ivy configuration dialog
- Using the "File System..." button for the Ivy File, select
- For "Configurations," select the following:
- Close the dialog
Step 3d: Additional projects in Eclipse
Next, you need to add other subdirectories of the umple trunk as projects. You can repeat the above process or do the following. At the very least you need to add cruise.umple.nebula.
Right click on the cruise.umple project
Select Import / General / Existing Projects Into Workspace
Browse for your working copy directory (as soon as you do this, it should select your Working Copy directory)
De-select projects that you have no involvement with. The most important ones you will need are cruise.umple.nebula. Ensure any other projects in which your are planning to work remain selected. Press Finish.
Right click the cruise.umple project and choose 'Build Path -> Configure Build Path'
Go to the "Projects" Tab and add the project cruise.umple.nebula, as well as any other cruise.umple* project.
Go to the "Source" Tab and make sure that ONLY the following source folders are listed:
- cruise.umple/test Remove the other folders by selecting the undesired folder and then clicking on the "Remove" button. Note that this will not physically delete the folders or their content, we are just marking those folders as normal folders instead of source folders.
Remain in the same "Source" Tab, select the first folder "cruise.umple/src-gen-umpletl", expand it and verify that there are no excluded folders. Do the same but this time for the "cruise.umple/src-gen-umple" folder.
Go to the "Order and Export" tab and move the "JRE System Library" to the top of the list. Then press OK.
Click on the "OK" button to exit the properties page.
At this point, your "cruise.umple" project should show no errors in eclipse.
Step 3e: Building and testing in Eclipse
Clean and build your project (Project menu / Clean)
Use the Umple plug-in to generate all .ump source files. You do this by compiling this file: cruise.umple/src/Master.ump. First, open the file in Eclipse (double-click it), then click the Umple icon in the toolbar at the top left corner of the main Eclipse view.
Since the above regenerates many files externally, refresh your projects. Select the projects and Press F5 or right click and select Refresh.
Run all the tests in Umple to make sure they are passing as follows:
Run tab -> Run configurations -> Junit
Name: AllTest (you can name this test anything)
Run all tests in the selected project, package, or folder: cruise.umple
Set Test Runner: junit 4
The source code must compile at this point and the projects shouldn't have error markers.
Troubleshooting failed junit tests in Eclipse
If you just ran the junit tests from the cruise.umple project, and everything is failing (or some things are failing) try the following:
- Run a full build (from the command line, see below for this)
- Refresh Eclipse Projects (F5). This is important, as when you run a build it changes the Umple version and Eclipse doesn't automatically reflect this. Since the version is different the tests will fail.
Description of Umple Eclipse Projects
There are at least Seven core Eclipse projects you may want/need to work on.
cruise.umple // core, depends on Umple-Java,PhP,Ruby.
This is the core Umple project. This project includes all Umple core files, such as the Grammar, the parser, the compiler, and all test files.
cruise.umple.nebula This project is used for code generation.
cruise.umple.eclipse Project that has been replaced by cruise.umple.xtext.ui.
cruise.umple.xtext Not currently used. Project that contains all code for the parser, lexer and the code generated by the Xtext workflow (not UI).
cruise.umple.xtext.ui Not currently used. Project that contains all UI code for the Umple Editor and Umple Actions.
UmpleOnline Our PHP Web Application that brings you umple on the Web.
UmpleToJava The template project for Java code generation.
UmpleToPhP The template project for PHP code generation.
UmpleToRuby The template project for Ruby code generation.
Note: Master.ump file is the root file that calls all files that is needed for Umple to build.
Extra Details of Step Command Line building of Umple using Ant
General Notes About Ant
Umple developers use ant scripts to build the system. We frequently run these from the command line, although they can be run within Eclipse. See the next section if you need to install ant on your system.
The Ant scripts are found in the ./build directory. build.umple.xml is the central file. Open it up and you will see the targets that you can choose to build.
Note: On some environment setups you may find that running ant fails to do with taskdef's, to get around this ensure that you have the appropriate files in your ant lib directory:
If you installed ant using Homebrew on Mac OSX, the default ant directory will be:
In here you will want "ant-contrib-1.0b3.jar" which can be acquired by a quick web search from various places.:
Untar the file:
tar -zxvf ant-contrib-1.0b3-bin.tar.gz
For convenience the extracted directory was moved to home, if you do not you will have to change the command for which you copy from later on.
Now you need to move this to the ant lib directory, so first ensure you are in that directory:
And now copy it over (you need to be superuser):
sudo cp ~/ant-contrib/ant-contrib-1.0b3.jar .
Note: The above command is assuming you moved the extracted tar file into your home directory.
Bootstrap / Resetting Umple Generated Code (src-gen-umple)
We no longer commit the generated code within the repository (remember Umple is written in itself and generates Java). Because of this, you need to bootstrap your environment and compile those into your system.
ant -Dmyenv=local -f build.umple.xml first-build
For more details, the first-build uses the target resetUmpleSelf, which will build the system against ./lib/umple.jar; whereas the ant tasks below are built on the newly minted version which is stored (but not version controlled) in ./dist/umple.jar (and the target is umpleSelf). Both can be used interchangeable
(a small lie, as you might add new features that Umple then takes advantage of).
To quickly compile and build, but skip the tests temporarily:
ant -Dmyenv=local -f build.umple.xml umpleSelf compile packageMainJar
or to build all jar files, including the ones used in UmpleOnline
ant -Dmyenv=local -f build.umple.xml umpleSelf compile packageJars
If the above fails, check that JAVA_HOME is set to your JDK1.8 folder.
To set it, figure out where your JDK1.8 folder is
/usr/libexec/java_home -v 1.8
Set this in your ~/.bashrc (if you are using bash, otherwise the correct rc file for your shell), restart your terminal, and try a quick build again
export JAVA_HOME="/Library/Java/JavaVirtualMachines/jdk1.7.0_25.jdk/Contents/Home" PATH=$JAVA_HOME/bin:$PATH
After a quick build that is successful, then you can run the tests
ant -Dmyenv=local -f build.umple.xml template.test
Search for the word 'fail' Don't rely on the phrase 'BUILD SUCCESSFUL'.
If you get test errors, you will find an analysis of test results in
If you want to do a complete build simply do this:
Those in the Windows environment should use the following command due to issues with Rake:
Once again, don't rely on BUILD SUCCESSFUL. Search for the word 'fail'
The above will not copy the jars to your local UmpleOnline. If you want to do that, then do the following
ant -DshouldPackageUmpleOnline=true -Dmyenv=local -f build.umple.xml packageUmpleonline
If a full build takes more than about 7 minutes on a modern (post 2013) machine, especially on MacOS
Try to do the full build using
ant -Dmyenv=local -Donline=false
Also try disconnecting from the network if it gets stuck doing template.test and/orbefore issuing the above command. There seems to be a problem on some wifi networks where DNS queries done in every test take excessive time.
Upgrading to Java 1.8 on Mac OSX
Check your Java version
If you don't have at least 1.8 then please upgrade by downloading the JDK from the Oracle site
Obtaining Ant on Windows machines
You can download Ant for windows from: http://ant.apache.org/bindownload.cgi
After you have dowloaded the file, extract the contents into a folder. NOTE: the simpler the path the easier it will be for later steps for example C:\ANT.
Right click on My Computer -> Properties ->Advanced tab ->Enviornment Variables button
- Under the System Variables click NEW
- varibale name: ANT_HOME
- variable value: C:\ANT (or which ever path you set in the earlier step)
- click OK
- Under System Variables find PATH in the Variable column
- Add ;%ANT_HOME%\bin; at the end of Variable value
- click OK to finish
Open up the start menu and click Run -> open: cmd In the Command prompt type ant -version and enter
if the test result looks something like Apache Ant version 1.7.1 compiled on June 27 2008 then ANT is working correctly
- Now that ANT is working, download the ant-contrib file from the downloads page. Extract it and move the ant-contrib .jar file inside into the "lib" folder of ANT.
Problem: when you run the command ant -version and you get the error "Unable to locate tools.jar..."
Solution: Locate where you intially downloaded the JDK and JRE. Once you have located both of the folders go into the JDK folder and search for tools.jar (It will likely be in the lib folder) Once you have found the tools.jar file copy it and paste it in the lib folder for the JRE and rpeat the last step in Checking ANT