Skip to content

DevelopmentSetUp

Jump to bottom
TCLethbridge edited this page Feb 27, 2023 · 67 revisions

General

Developers

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:

  1. Install Chocolatey if you do not have it.

  2. Install JDK11 or later if not already installed. This can be Oracle jdk or openjdk using choco

  3. 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.

  4. Adjust your environment variables (chocolatey may have done some of these for you already):

  5. Add the following to your PATH variable: * C:\Ruby22\bin or C:\tools\ruby\ruby23\bin if you're using Ruby 2.3 * C:\tools\php * C:\ProgramData\chocolatey\lib\ant

  6. Create the JAVA_HOME and set it to be the location of your JDK installation, likely C:\Program Files\Java\jdk1.8.0_65\ (the version number will be different, e.g. 11.something)

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

  1. 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

  2. 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.

  1. 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 $@

  2. 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.

  1. 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".

  1. 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, select Configure -> Add Ivy Dependency Management Add Ivy Dependency Management

  • Right click the project again, select Build Path -> Add Libraries...

    • Choose IvyDE Managed Dependencies Select Add Libraries...
    • Click Next, this displays the Ivy configuration dialog Configure Ivy Dialog
    • Using the "File System..." button for the Ivy File, select build/ivy.xml
    • For "Configurations," select the following: Ivy Configurations
    • 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

  • 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:

    1. cruise.umple/src-gen-umpletl
    2. cruise.umple/src-gen-umple
    3. 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