CheatSheet

The purpose of this page is to list common commands that you may need to issue regularly, but forget. When adding to this page, also make a reference to a document where these may be discussed in more details. Linux/Mac scripts for some of these can be found in the dev-tools directory. We suggest that Linux and Mac users create symbolic links to these to facilitate their work. These scripts will do extra checks, such as ensuring you notice any test failures.

ALL ANT TASKS SHOULD BE RUN FROM build/the dev-tools scripts will do this for you

Gradle : When working on WINDOWS, replace ./gradlew with gradlew.bat

Re-generate files that are saved from build to build

Some files, such as the compiler itself and a few other dependencies are saved from one build to the next. For new projects, or if you want to rebuild your system based on a stable release, then run the "first-build" target. Or, to clean up your umple generated code (i.e. something went horribly wrong, the build crashed in the middle and left things in an unstable setate)

ant -f build.umple.xml first-build

Gradle: ./gradlew firstbuild

Quick Compiles

Use the following to do a quick full compile of your code without testing (never commit anything, however, until a full build is done.). The following can be run using the dev-tools script qfbumple

ant -Dmyenv=local -f build.umple.xml codegen umpleParser rtcpp umpleSelf compile packageJars

Gradle: ./gradlew quickbuild

You can use packageMainJar above (or qbumple) if you only want the command line jar built

Use the following to do a quick run of the unit tests (although not the testbed tests, see below). This is dev-test script tumple

ant -f build.umple.xml template.test

Gradle: ./gradlew test

Use the following to do a quick run of the testbed tests that use the compiler to compile umple examples to java, ruby and PhP and then actually run the PhP.

ant -f build.testbed.xml -Dmyenv=local

Gradle: ./gradlew testbedTests

Use the following to do a quick run testing all the examples in the user manual and umpleonline

ant -Dmyenv=local -f build.exampletests.xml allUserManualAndExampleTests

Gradle: ./gradlew allUserManualAndExampleTests

Use the following to run a full build. This is dev-test script bumple

ant -Dmyenv=local

Gradle: ./gradlew fullbuild

If you have poor Internet connection (or are offline, or find one of the dependencies is offline) you can build without attempting to connect by using:

ant -Donline=false

If you find that the build 'hangs' during template.test because it is trying to download a large dependency repeatedly, then try disconnecting your computer from the Internet to force it to stop trying to connect to the slow resource.

See DevelopmentSetUp

The following is the path to the test results on your local machine BuildingYourProject: dist/qa/cruise.umple/index.html

Test results on the cc server after a PR merge are here: http://qa.umple.org

Use the following to package the User Manual after making changes See the wiki page on this. This is dev-tools script mumple

cd build/
ant -f build.umple.xml packageDocs

Gradle: ./gradlew packageDocs

To update your local copy of umpleonline , run the following. This is dev-tools script pumple

ant -DshouldPackageUmpleOnline=true -f build.umple.xml umpleSelf compile packageMainJar packageUmpleonline

Gradle: ./gradlew packageUmpleonline

Run Tests for a Particular class

To just run a test class without compiling first (e.g. you have compiled, and now want to run a single test)

ant -DshowJunitOutput=true -Djunit=UseGeneratorTest -Dmyenv=local -f build.umple.xml template.test

Gradle: ./gradlew -Pjunit=UseGeneratortest test

To compile the system and then run a single test class

ant -Dmyenv=local -DshowJunitOutput=true -Djunit=UseGeneratorTest -f build.umple.xml codegen umpleParser rtcpp umpleSelf compile packageJars template.test

Gradle: ./gradlew -Pjunit=UseGeneratortest quickbuild test

To run a single test class without compiling (e.g. if you want to modify a test and see if all is OK) and see places that have the word FAILED and nearby lines

ant -Dmyenv=local -DshowJunitOutput=true -Djunit=UmpleParserTest -f build.umple.xml template.test | grep -C4 FAILED

Wherever in these tups it says umpleSelf it means use the version of Umple built locally in dist/umple.jar. If you instead use resetUmpleSelf it will use the last stable release ./lib/umple.jar .

Submitting a Pull Request

Step 1: Make the necessary changes to the code to fix an issue.

Step 2: Bring in any other changes that have been made to the code by others, so you are working with the latest code.

git pull

Step 3: Run a full build, as above.

Step 4: Take a look at the files that Git says you have changed; and 'stage' them for commit

git status
git add WHATEVER

You can repeatedly do the above as needed.

Step 5. Switch to a newly created branch that is describing your change

git checkout -b NEWBRANCH

Step 6. Commit your changes (locally) to this branch

git commit -m 'DESCRIPTION'

Where Description is very short (5-15 words us usually enough).

You can repeatedly do steps 1-4 and step 6 as needed to create more commits for the same pull request.

Step 7. When you are ready to make your changes available to others, push your branch to GitHub

git push --set-upstream origin NEWBRANCH

where NEWBRANCH is the branch name you created in step 5.

Step 8. Create the pull request (PR)

Now on GitHub you will see your branch appear; Github will ask you if you want to create a PR from the branch. You could wait for the continuous integration servers (Travis and Appveyor) to complete a 'branch build' or you could go straight to making a PR from the branch.

If the CI builds fail, determine why. Occasionally it is a problem with the build servers. Sometimes it is your code. If it is your code, then do steps 1-4 and 6. For step 7, just do 'git push'. This will update the PR.

Step 9. Shepherd your PR

Watch the Continuous integration servers to make sure your PR builds. If not, fix it as described above.

Ask others to review your code. Fix as recommended by them.

Finally have someone merge your PR.

When the PR is finally merged, it will build on Travis and AppVeyor, and additionally on cc.umple.org. The latter is important since it publishes the result on UmpleOnline and makes a new umple.jar available for future builds by everybody.

Working with your local UmpleOnline Web Server

Local UmpleOnline web server path (on Mac OS) SettingUpLocalUmpleOnlineWebServer /etc/apache2

Moving jars to local UmpleOnline after a build so you can manually test (UmpleSync.jar and Umple.jar are both needed by UmpleOnline):

ant -DshouldPackageUmpleOnline=true -f build.umple.xml packageUmpleonline

Gradle: ./gradlew deployUmpleonline

Important: Don't commit these files, they should be ignored, but still, don't even try to do it.

Restoring files or a directory you have deleted. Make sure you really want to do this.

git checkout WHATEVER

Reset your working tree

This will reset your working environment back to the most recent version you pulled destroying any changes you have made:

git reset --hard HEAD

To reset a single file:

git checkout HEAD -- path/to/file

To reset to a previous commit:

git reset --hard COMMITISH