Overview

This document describes how to check out the ArchStudio (and constituent) code from GitHub and build ArchStudio from source.

Casual ArchStudio users or those evaluating the technology should probably just download and install the latest pre-built release. However, ArchStudio developers - those who are interested in developing new ArchStudio components, making changes to ArchStudio itself, or those interested in having bleeding-edge updates to ArchStudio before they go into official release - should check out the ArchStudio source code and build the environment from source.

The Source Code Environment

ArchStudio is built in and for the Eclipse development environment. Because it uses plug-ins in Eclipse to auto generate code, it must be developed in the Eclipse environment.

If you are just interested in browsing the source without checking it out, you can browse the raw source on GitHub.

What You'll Need

You will need the following installed on your machine:

• Java SE 8 SDK*, and
• Eclipse 4.5* or later.

* ArchStudio can also be compiled and run using Java SE 7 and Eclipse 4.3 or 4.4. However, it is not, by default, configured in this way. To user either of these alternatives, a few minor modifications must be made to Eclipse after checkout. These are discussed below, in Using a Different Java Virtual Machine.

Within Eclipse, you will need to install the following features:

• ArchStudio (follow the instructions, here),
• Collaboration / Eclipse Git Team Provider,
• General Purpose Tools / Xtext Complete SDK*,
• Modeling / EMF - Eclipse Modeling Framework - SDK*, and
• Modeling / XSD - XML Schema Definition SDK*.

* These components should be installed automatically when you install ArchStudio in Eclipse. However, if you run into compile errors, try installing them manually.

Installing the above Eclipse features is similar to installing ArchStudio itself, as described here. However, for the "Work with:" field select "--All Available Sites--". Then navigate to and select each feature listed above.

Checking Out Source Code

Once you have the tools above installed and running, you can check out the ArchStudio source code. ArchStudio is composed of a number of different plug-ins, each of which contributes a part to the environment.

To check out the code perform the following steps:

1. Switch to the Git perspective by going to Window | Perspective | Open Perspective | Other... | Select "Git" | Hit OK.
2. Select "Clone a Git Repository".
3. In the Source Git Repository dialog box that pops up, enter the following for the URI field: https://github.com/isr-uci-edu/ArchStudio5.git.
4. Click Next to go to Branch Selection page.
5. Ensure that "master" is selected.
6. Click Next again to go to the Local Destination page.
7. Select "Import all existing projects after clone finishes".
8. Click Finish.

The checkout may take several minutes. After it is completed, you will want to return to the Plug-in perspective. To do this:

1. Switch to the Plug-in perspective by going to Window | Perspective | Open Perspective | Other... | Select "Plug-in Development" | Hit OK.

After completing the steps above, you should have the Eclipse environment populated with the many plug-ins used to develop ArchStudio. All plug-ins should compile without errors except for the org.archstudio.releng(.*) plug-ins. These plug-ins are used for building and deploying ArchStudio headlessly. You can safely close them; they are not required for developing ArchStudio.

Common Problems

Running Eclipse 4.5

If you get an error running Eclipse having to do with the Java virtual machine not being available, run eclipse using the "-vm" option to indicate the path to the java executable you installed. For instance, if you installed Java 8u45 SDK on a Mac, you would use the following command:

eclipse -vm /Library/Java/JavaVirtualMachines/jdk1.8.0_45.jdk/Contents/Home/bin/java

Using a Different Java Virtual Machine

You may elect to use a different version of Java or Eclipse, or your system may only have a specific version installed. In such situations you may encounter one or more of the following errors:

• The "Debug" or "Run" buttons are disabled when trying to start ArchStudio (see below).
• ArchStudio starts but immediately exits.
• A java.lang.UnsupportedClassVersionError exception is thrown when starting or running ArchStudio.

These errors indicate that the version of Java being used to compile ArchStudio is different from the version of Java being used to run ArchStudio. To remedy this:

1. Register your Java installation with Eclipse. Go to Eclipse Preferences | Java / Installed JREs, and add it if it is not already listed.
2. Set the execution environment to point to your Java installation. Go to Eclipse Preferences | Java / Installed JREs / Execution Environments, and select your Java installation for the appropriate execution environment. For example, if you were to install Java 7u79 SDK, you would select the "JavaSE-1.7" execution environment and check the "Java SE 7 [1.7.0_79]" compatible JRE entry.
3. Set the Java compiler compliance level. Go to Eclipse Preferences | Java / Compiler, and set the compiler compliance level match your Java installation. For example, if you were to install Java 7u79 SDK, you would select a compiler compliance level of 1.7.
4. Set the execution environment for the ArchStudio launch configuration (used below). Go to Run | Debug Configurations... | Eclipse Application / ArchStudio, and on the Main tab, under Java Runtime Environment, select the execution environment that you configured above.

After configuring the Eclipse Java settings, you will need to do a clean and rebuild, as described below.

Clean and Rebuild ArchStudio

At times Eclipse will report compile errors even though none really exist and all projects are checked out. To remedy this, clean and rebuild ArchStudion by doing the following:

1. Go to Project | Clean...
2. Select "Clean all projects".
3. Hit OK.

You may have to repeat this step twice.

Running ArchStudio

From within Eclipse, you can run the version of ArchStudio that you checked out using the ArchStudio launch configuration. To do so, perform the following:

1. Go to Run | Debug Configurations...
2. Select Eclipse Applications / ArchStudio.
3. Click Debug.
4. (If "Debug" is disable, look at Using a Different Java Virtual Machine, above.)
5. (You may get a dialog box asking if Eclipse may accept incoming network connections. If so, click "Allow" in order for the Eclipse debugger to interact with ArchStudio.)

Now that you have a running version of ArchStudio, take a look at getting started with an architecture.

Contributing to ArchStudio

If you are looking for a way to contribute to ArchStudio, take a look at the open issues. In particular, some issues are marked as help wanted to indicate that they are good candidates for others to contribute a solution. If you discover an issue, please file a bug at the same location. Finally, if you add functionality that you'd like to have incorporated back into ArchStudio, contact us.

Contact Us

If you have questions not answered by this website, please feel free to contact the software architectures group at UC Irvine through the ArchStudio developer's (mailman protected) email list at: archstudio-dev [@] uci [.] edu. (Note: You must subscribe to the mail list before you can post to it.)