Getting Started

Vitruv in a Nutshell

The most general steps to setup Vitruv for developing or using it are as follows. For detailed instructions, please read the information in the sections below.

1. Download an Eclipse 2022-12 release (preferably the Modeling Tools).
2. Install Xtext from the Eclipse Marketplace.
3. Install features required for your use case from the Vitruv nightly update site.
4. If you want to develop for Vitruv, import only projects of plug-ins that you want to modify from the Vitruv GitHub repositories. Otherwise, create or import the projects you want to develop using Vitruv.
5. Make sure that Eclipse is configured to use a Java JDK instead of Java JRE.

To get an overview of the repositories, their intents and dependencies, take a look at the organization readme.

Environment Setup

In either way you want to use Vitruv (be it for developing Vitruv or for using it), you first need to install a current Eclipse. So download and run the 2022-12 release of Eclipse, preferably the Eclipse Modeling Tools. Then, install Xtext from the Eclipse Marketplace.

You should then install the required features from our nightly update site and import those plug-ins you potentially want to add or modify (in case you want to develop Vitruv and not only use it) into your workspace.

General Setup for Developing and/or Using Vitruv

• Install the required features from our (nightly) update site:
  1. Open your Eclipse and go to Help -> Install new software and search for our nightly update site: https://vitruv-tools.github.io/updatesite/nightly/aggregated
  2. Select the features you need, e.g., only the framework, the consistency specification DSLs or even certain domains or applications that have been developed for Vitruv
  3. For further information on the features you may need, see Selecting Required Plug-ins
  4. You do not need to install any additional dependencies when installing Vitruv from our updatesite. All required tools and metamodels for the domains and applications are installed automatically.

Developing Vitruv

In case you want to develop Vitruv, clone the GitHub repository and import only the projects of the plug-ins that you want to modify or extend, see Workspace Setup. (If an Eclipse plug-in is installed / added to the target platform and opened as a project in the workspace, Eclipse automatically replaces the installed version with the workspace version.) Be aware that code needs to be generated for several of the projects, which can most easily be achieved by performing a Maven build as explained in Workspace Setup.

Using Vitruv

In case you only want to use Vitruv, you can develop your projects with Vitruv, e.g., using the Vitruv wizard that is available via an icon in the toolbar.

Manual Setup

If you do not install the Vitruv features from our update site or provide them in a target platform, you need to install some required Eclipse Plug-ins manually before downloading and using the code from GitHub:

• All features under SDQ Commons (except the MDSD Profiles Commons), Active Xtend Annotations, and Demo Metamodels from our SDQ Update Site
• Optional Eclipse Plug-ins, depending on which metamodels you want to define or use consistency specifications for. For details about the applications and their dependencies, see Applications.

However: This manual installation is not recommended. Better define a target platform with the Vitruv features that automatically resolved these dependencies.

Selecting Required Plug-ins

Vitruv consists of several plug-ins, separated into different categories.

There are three categories of user that require different plug-ins to be imported to their workspace:

• Vitruv Framework Developers
  • Developers of the framework should checkout and import the complete set of plug-ins, which are the one contained in the framework and the ones in domains and applications repositories.
  • Changes in the framework may affect a plug-in that is built on the framework.
  • Plug-in projects that are not affected, not needed and/or for which dependencies are missing can be closed in the workspace.
• Vitruv Application Developers
  • An application developer defines consistency specifications between metamodels.
  • Required plug-ins are the framework and the DSLs and the DSLs runtime extensions, as well as the domains projects for the metamodels to define consistency for and the application projects for the metamodel pair to keep consistent.
• Vitruv Application Users
  • An application user uses already defined applications to build a virtual metamodel that uses the consistency specifications to keep models consistent.
  • Required plug-ins are the framework, the domain projects and the applications projects for the involved metamodels (DSLs are not required). They are best installed from the update site.

Workspace Setup

Setup the workspace with the code from GitHub, for framework development at least the Vitruv-Change and the Vitruv projects, for DSLs development also the Vitruv-DSLs. To get the source code of the Vitruv framework:

1. Clone the Vitruv repository and import projects from it

   • Right click in the Eclipse Package Explorer view: Import -> Git -> Projects from Git
   • Import only those projects of the plug-ins that you want to modify or extend
     • You can set the scope of the wizard to the folder "bundles" or one of its subfolders in the "Working Tree" to only obtain relevant import suggestions
     • Select as few projects from the list as necessary. (To modify the reactions language, for example, you would only import projects named tools.vitruv.dsls.reactions.* in the dsls subfolder of the bundles folder.)

2. Our continuous integration is based on Maven Tycho and GitHub Actions. You need to run a Maven build after importing the sources, especially to generate the artifacts of the consistency preservation languages. To avoid incompatibilities of Maven versions, we provide a Maven wrapper (command mvnw) in the repository to always use a version of Maven tested with Vitruv.

   1. Navigate with the console to the Vitruv framework (e.g. cd ./git/Vitruv/)
   2. Run ./mvnw clean verify(in case of build failures try ./mvnw clean verify -U)
   • Alternatively, you can run the MWE2 workflows within the projects to build the metamodel code and the languages in Eclipse and let Eclipse build the projects, but this sometimes causes issues due to missing folders, so starting a Maven build is the more reliable option.

3. In case there are still build failures within Eclipse, refresh the projects (select and press F5) and potentially clean them (Project -> Clean) and build them anew. In some cases, it may be necessary to delete all errors in the errors view by hand. For further information on potential problems, see Fixing Common IDE Failures.

Workspace Configuration

Ensure that your workspace is configured properly for Vitruv. If it is not, you will usually face compile errors. A proper configuration especially concerns the workspace encoding, which must be set to UTF-8 (especially important for windows users), and a proper Java compiler compliance level, which should be set to 17.

Encoding

• Open the preferences window: Window -> Preferences
• Open the page General -> Workspace and select enconding in the box Text file encoding

Compliance level

• Open the preferences window: Window -> Preferences
• Open the page Java -> Compiler and select 17 in the dropdown menu for the Compiler compliance level

Miscellaneous

Fixing Common IDE Failures

• Ensure that all artifacts (metamodels, languages etc.) have been generated, in the easiest case by running the Maven build
• Ensure that all resources are present in Eclipse by performing a refresh (F5)
• Rebuild all projects by cleaning them and performing a rebuild (Project -> Clean)
• In case problems remain, try to manually delete all errors in the Eclipse Errors view and clean and rebuild the projects again.

Installing from (Nightly) Update Sites

• Open Help -> Install new software
• Input the update site (URL) in the search field
• Select the required features from the list
• Finish the wizard, accepting potential requests