DevelopmentSetUp
Pages 207
General
- Wiki Home
- FAQ Frequently asked questions
- Examples
- Presentations
- PhilosophyAndVision
- Best practices for using Umple
- Publications and theses
- Tutorials
- Installing Eclipse plugin
Developers
- Developer Setup
- UmpleOnline Setup
- Contribution Process
- Architecture
- Cheat sheet
- Umpleonline manual tests
- Planned development
- DraftManualPages
Server maintenance
External
Other
Clone this wiki locally
Introduction
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 VSCode, others use command line tools and plain text editors; some use Eclipse. 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
You need to ensure that on your machine (Windows, Mac or Linux) you have the following installed. Make sure you look at the tips below for each operating system if you need to install these.
- Java 11 or later (all users need this even if they are just using Umple, and not developing it)
- Apache Ant (needed for building by default, although we are moving towards Gradle)
- Ruby (needed for tests of Umple-generated Ruby to pass)
- Python 3 (needed for tests of that language to pass; must be installed as command python not python3)
- Php 7 (needed for UmpleOnline and also for tests of that language)
- TXL (currently requires special instructions, see below). Used to generate Python and for Python tests to pass.
The following are not immediately needed, but would be needed for certain tasks
- Docker (for execution features; not essential initially)
- Gradle
If you have a choice, we suggest using Mac or Linux (Ubuntu recommended) as your platform as most developers find working with Umple using Unix commands easier than working with Windows.
Windows Installation tips:
This will run through simple steps for installing the prerequisites for development:
-
Install Chocolatey if you do not have it.
-
Install JDK11 or later if not already installed. This can be Oracle jdk or openjdk using choco
-
Run the following scripts in an Administrative PowerShell (each should be run individually):
choco install ant git choco install ruby choco install php choco install python
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
PATH
variable: *C:\Ruby22\bin
orC:\tools\ruby\ruby23\bin
if you're using Ruby 2.3 *C:\tools\php
*C:\ProgramData\chocolatey\lib\ant
-
Create the
JAVA_HOME
and set it to be the location of your JDK installation, likelyC:\Program Files\Java\jdk1.8.0_65\
(the version number will be different, e.g. 11.something) -
For TXL, follow the instructions at: [Txl.ca]
Mac OSX tips
You have several options to obtain the needed languages listed earlier. Homebrew, below, can install most of them 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 was once installed with the latest MacOS but is no longer.
-
Install Homebrew following the instructi9ns on the Homebrew page if not already done. Note that if you are transitioning from an Intel to an Apple Silicon Mac, you may need to redo the installation as the executables are put in a different directory
-
Run the following: (the tap cask statements may not be needed)
brew tap caskroom/cask brew update brew install php ant ruby python3 brew cask install java
Note: You can also install Java directly from Oracle or openjdk. It is suggested that you install version 17 of Java. Umple has some problems with version 18 and up, and won't work before version 11.
-
Check to see whether the above installs a command called python. Most likely it instead installs a command called python3, and that running the python command does not yet work. If som do the following: in your bin directory create an executable script that has the lines below to simply result in the python command executing puthon3; then add Users/your-homedir/bin to your path in .zshrc and .bashrc as needed.
#!/bin/bash python3 $@
-
For TXL, follow the instructions at: [Txl.ca] You need version 10.8b (10.8a will not work)
Linux
For Ubuntu-based distributions:
For Java, the jdk is going to be downloaded as you download the ant tool.
- Run:
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".
- For TXL, follow the instructions at: [Txl.ca] You need version 10.8b (10.8a will not work)
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. We suggest you issue the following command directly in your home directory, which would create a new directory called 'umple' there. You could install it elsewhere and make a symbolic link in your home directory called umple to point to the installation location.
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.
If you are not familiar with Git, the following links may be useful: Atlassian Git or Github Guides
Step 2c. Do a series of command-line builds as follows:
Run the following in the 'build' directory in the trunk
-
Run:
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. -
Run
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. -
Run
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.
If you intend to set up a local version of Umple Online: run ant -DshouldPackageUmpleOnline=true -Dmyenv=local -f build.umple.xml packageUmpleonline
-- This will copy the required jars into your local version of Umple Online.
On Windows replace 'local' above with 'wlocal', so
-
ant -Dmyenv=wlocal
-
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.
Note for Windows users: If you recieve an error relating to a missing file named "rake.cmd", please install Ruby --version 2.6 or 2.7 and update your PATH variable to point to the new version.
Step 2d: Setting up local UmpleOnline (Not needed for those just working on the compiler, but still highly recommended)
Click here for instructions for seting up a local version of Umple Online so you can test your changes to UmpleOnline, and also test your compiler changes more easily with many examples]
Step 2e: Getting going with development
You might want to add the 'dev-tools' directory to your path, to give you access to certain commands.
Before digging into an issue, it would be best to at least skim the information about Umple Architecture and particularly UmpleArchitectureTestingView
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.xml
via 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
cruise.umple
project, selectConfigure -> Add Ivy Dependency Management
-
Right click the project again, select
Build Path -> Add Libraries...
- Choose
IvyDE Managed Dependencies
- Click
Next
, this displays the Ivy configuration dialog - Using the "File System..." button for the Ivy File, select
build/ivy.xml
- For "Configurations," select the following:
- Close the dialog
- Choose
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
-
Choose Next
-
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/src-gen-umpletl
- cruise.umple/src-gen-umple
- 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
-
click Run
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:
/usr/share/ant/lib
If you installed ant using Homebrew on Mac OSX, the default ant directory will be:
/usr/local/Cellar/ant
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:
cd /usr/share/ant/lib
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).
Useful Ant Commands. See also CheatSheet.
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 JDK11 folder.
echo $JAVA_HOME
To set it, figure out where your JDK11 folder is
/usr/libexec/java_home -v 11
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
dist/qa/cruise.umple/index.html
If you want to do a complete build simply do this:
ant -Dmyenv=local
Those in the Windows environment should use the following command due to issues with Rake:
ant -Dmyenv=wlocal
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
Troubleshooting
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 11 or higher on Mac OSX
Check your Java version
java -version
If you don't have at least 11 and up to 17 then please upgrade by downloading the JDK from the Oracle site or using brew to get openjdk v11 to 17
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