DevelopmentSetUp

TCLethbridge edited this page Jan 20, 2017 · 43 revisions
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 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 Php5 Installed. 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.

Windows Installation:

This will run through simple steps for installing the prerequisites for development:

  1. Install Oracle JDK8 Download
  2. Install Chocolatey
  3. 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.

  4. Adjust your environment variables (chocolatey may have done some of these for you already):
    1. 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
    2. 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 65 may be different)

Mac OSX

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.

  1. Install Homebrew
  2. Run:

    brew tap caskroom/cask
    brew update 
    brew install php ant ruby
    brew cask install java

Linux

For Ubuntu-based distributions:

  1. Run:

    sudo add-apt-repository ppa:webupd8team/java
    sudo apt-get update
    sudo apt-get install ant git php5-common php5-cli ruby-rvm oracle-java8-installer
    
    rvm use 2.2

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

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)

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

  • 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 2 and 6 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.

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.

Step 2d: Setting up local UmpleOnline (Optional)

You may 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

Before digging into an issue, to 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 JDK1.8 folder.

echo $JAVA_HOME

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

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 1.8 on Mac OSX

Check your Java version

  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