Skip to content

Contributing to Geppetto

Jump to bottom Edit New page
hlindberg edited this page Jul 19, 2012 · 25 revisions

NOTE: this page is a work in progress...

Now with instructions for Setting up for Geppetto 3.0 (and later) using Eclipse Juno.

Installation of Basic Tools

All instructions listed here assumes that you have an Eclipse IDE. Once you have that installed, you can update it to include other software. It's easy. Just choose Help in the top menu and then Install New Software.

Install Eclipse

You can install the Eclipse IDE from http://www.eclipse.org/downloads/. Choose the package that best suit your needs. Choose version Eclipse Classic 4.2 if you are uncertain.

## Install Git support ###If you are installing using Eclipse 4.2 Juno Install support for Git by selecting Help > Install New Software. Select "Contact all update sites". You find _EGit_ under the category _Collaboraton_. If you have no special requirements, just select _EGit_.

If you are installing using Eclipse 3.7 Indigo

Install Eclipse Git Team Provider found in the p2 site http://download.eclipse.org/egit/updates. It should already be available among the known p2 sites, and it just needs to be enabled. If not, just add it.

Restart Eclipse when prompted to do so.

## Install Buckminster The Eclipse Buckminster project is used to configure the Eclipse workspace and target platform for building Geppetto. To install Buckminster, enable the p2 site `http://download.eclipse.org/tools/buckminster/updates-4.2` in Available Software Sites (or add if not already included), and install the following:

(Use http://download.eclipse.org/tools/buckminster/updates-3.7 if you are using Indigo (Eclipse 3.7)).

  • Buckminster - Core
  • Buckminster - Git
  • Buckminster - Maven
  • Buckminster - PDE

All other Buckminster features are optional and are not used in the Geppetto build setup. (You do not need to install any Buckminster Source).

Restart Eclipse when prompted to do so.

## Populate the Workspace Buckminster will create a local clone of the Geppetto repository and download all jars needed for the build. All you need to do is:
  1. In Eclipse, open the top menu named File
  2. Choose Import
  3. Expand Buckminster
  4. Select Materialize from Buckminster MSPEC, CQUERY, or BOM and click Next
  5. Paste this URL into the field named Enter URL of ... https://github.com/cloudsmith/geppetto/raw/master/org.cloudsmith.geppetto.releng/geppetto.cquery
  6. Click Load next to the URL.

Buckminster will now resolve the query. This means that it forms a graph of the transitive dependency scope of Geppetto. It usually takes a couple of minutes. Once this is done, click on Finish and everything needed for the build is now downloaded by Buckminster, and you just have to wait for the process to complete.

You should now have a bunch of projects. As your eclipse is setup to build automatically by default, you should after this stage see that everything is built and that there are no error markers in the Eclipse Problem View.

In case there are errors

Typical problems during the above steps are network issues such as timeouts, being behind a restrictive proxy, issues with repository mirrors (you may have been redirected to a slow mirror). If this happens, try again, and if again failing, try a litte later. If issues persist, contact us and we will try to help.

If the build produces lots of errors immediately after materialization, it may be that the Eclipse PDE feature is confused and you may need to activate the TP (target platform) again, or restart Eclipse. You may also want to perform a "Build Clean". If problems persist get in touch with us and we will help you out.

# Building

Basic Build

This is actually a no-op as the default is to build things automatically. Everything should already have been built by Eclipse. But if you turned this off, you need to trigger the Build manually under Project > Build All.

If all you want to do is to run/debug what was built you do not need to perform Building the Geppetto Product, and you can skip to Running and Debugging.

## Building the Geppetto Product The Eclipse workspace build and self hosting will allow you to edit/debug/test the product, but it will not build an installable result. Also, when you are running in self hosted mode, you will not see any issues related to the Geppetto product configuration. If you have made any substantial changes (esp. adding bundles/jars) or modified any of the product related settings, it is recommended to test the installable product itself before submitting patches/pull requests.

The product build will produce a zip file that when unzipped will contain a runnable Geppetto.

To build this simply:

  1. Right click on the project org.cloudsmith.geppetto.releng
  2. Select Buckminster > Invoke Action, in the menu that appears
  3. Click on the Workspace button next to Properties file
  4. Expand the org.cloudsmith.geppetto.releng project and select the geppetto.properties file.
  5. Select one of the product.zip-xxx actions (where xxx is the platform you are working on), or the all.products.zips if you want to build for all platforms.
  6. Press OK

The built zip will appear beneath the directory considered to be the users temp directory:

<tempdir>/buckminster/build/org.cloudsmith.geppetto.releng_2.0.0-buckminster/product.zips

To execute, simply unzip the produced result, and launch geppetto. Make sure it starts ok.

# Running and Debugging The easiest way to run or debug Geppetto is to use one of the launch configurations already provided in the `org.cloudsmith.geppetto.product-feature` project. To do this:
  1. Select Run > Run Configurations... or Run > Debug Configurations... from the menu bar.
  2. Select an appropriate geppetto-<platform> launch configuration under Eclipse Applications, depending on your platform.
  3. Press the Run or Debug button.
# Contributing To contribute your changes back to the Geppetto project, you need to:
  • create a fork of the cloudsmith/geppetto project at github
  • add the fork as a remote git repository in Eclipse
  • commit and push your changes to your fork
  • make a pull request at github

If your work consists of multiple contributions (that can be separately accepted), please make them in separate branches.

For more options regarding git, see Advanced Configuration of Git Repositories.

# Advanced Development Tasks

If you are not planning to work on these tasks, you can stop reading here.

## Semantic Model Development The project `org.cloudsmith.geppetto.pp` contains the definition of the puppet manifest semantic model. In order to make change you need to perform [Installing the Modeling SDK](#install-modeling). The model is found in the `PP.ecore` file, and it has a corresponding diagram `PP.ecorediag`. To work effectively with the model you should also perform [Install Diagram Support](#working-with-diagrams). When making change, you need to regenerate the code; this is done by opening the `PP.genmodel` and performing _Generate Model Code_. Once code has been generated, run _Source > Clean up..._ on the project.

The PPTP files are used for the Puppet Target Platform model, and you work with these the same way.

## Grammar Development The grammar is found in the PP.xtext file. In order to effectively work with the grammar, you need to perform the task [Install Xtext](#install-xtext). When changes have been made you need to perform [Regenerating the Parser](#regenerating-parser). After regeneration has been performed, you may need to change code that has references to grammar rules (these will be flagged as compilation errors), and you may need to adjust the code formatting rules. ## Regenerating the Parser The parser is generated from the PP.xtext file which describes the grammar. This generation is driven by the mwe2 workflow found in the project called `org.cloudsmith.pp.dsl.generator` in the file `src/GeneratePP.mwe2`. In order to run this, you need to have mwe2 installed as described under [Install Xtext](#install-xtext).

To execute the workflow simply:

  1. Right click on the GeneratePP.mwe2 file and select Run as Mwe2 Workflow

Depending on your platform and your Eclipse configuration, the defaults for running the workflow may not give this process enough memory. In this case, add the following settings:

-Xms40m
-Xmx2000m

in the Arguments tab under VM arguments for the Mwe2 Launch configuration named GeneratePP.mwe2.

## Advanced Configuration of Git Repositories If you followed the basic installation instructions above, the execution of the _cquery_ will produce a local clone of the cloudsmith/geppetto repostiory at github, and this clone is located under `${user.home}/git/`.

You may want to create a different configuration if:

  • you are going to be making several contributions and work on them in parallell
  • you want to work with a clone of your fork
  • you want to conveniently collaborate with others in your fork

The easiest is to modify the RMAP file in the releng project and make it reference your fork instead of cloudsmith/geppetto. By running the cquery in a fresh workspace, you will have the same simple setup as the basic setup, but for your fork. Others can get it by just running the query in your repository (the query does not have to be modified).

As in the basic setup, this will give you a local clone per workspace (which you may not want).

If you do not want a local clone in the default location, you need to manually clone the repository to your local filesystem, and then import the projects manually to your workspace. Make sure you import all of the projects from the cloned repo, as the running of the cquery otherwise will create a local clone in the workspace and import the missing projects from this clone. The query will however find all the manually imported projects - so no clone is created under the workspace if all of them are already present. If you make a mistake you will have a somewhat confusing configuration where you may believe that you have pushed changes, but only managed to push from either the clone under the workspace, or from your manually created clone (someplace else in the filesystem), and you will need to keep them both in sync.

# Installing Tools for Advanced Tasks * Optionally perform these tasks: * [Install Modeling SDK](#install-modeling), if you want to modify or regenerate the semantic model * [Install Diagram Support](#working-with-diagrams), if you want to view or modify the semantic model diagrams * [Install XText](#install-xtext), if you want to view or work with the puppet grammar ## Install Eclipse Modeling SDK The Modeling SDK provides editors and code generators for the Geppetto ecore models. You don't need this unless you plan to make changes to the model since all generated code has been checked in to the repository.

If you are installing into Eclipse 4.2 Juno

Go to Help > Install New Software, and select All available sites. Under the category Modeling, select "EMF - Eclipse Module Framework SDK". (Tip: If you read ahead and know about all the things you need from modeling, you can select all of the things at once; i.e. Diagram Support, and Xtext).

If you are installing into Eclipse 3.7 Indigo

It is recommended to install the the org.eclipse.emf.sdk feature from the Eclipse Indigo (3.7) repository (the 3.6 release was called Helios, and the next release, due by end of June 2012, is be named Juno). (Since you will probably also work with editing diagrams, you can install support for diagrams at the same time).

## Install Diagram Support ### If you are installing into Eclipse 4.2 Juno Go to Help > Install New Software, and select _All available sites_. Under the category _Modeling_, select "Ecore Tools SDK".

Continue under "Installing Kieler Layout".

If you are installing into Eclipse 3.7 Indigo

If you want to view or work on the model diagram you should install the org.eclipse.emf.ecoretools.sdk feature from the same repository as for Eclipse Modeling SDK.

NOTE: In Indigo and with Kieler 0.5.0 the result is far from satisfactory !

Installing Kieler Layout

If you are changing anything in the diagram, you probably also want to install a better graph layout manager than what is included by default. We recommend installing the Kieler layout package. To do so add the URL http://rtsys.informatik.uni-kiel.de/~kieler/updatesite/nightly to the Available Software Sites (for < 3.7 drop the nightly at the end). The set of things to install have changed between all Kieler releases - these instructions are for the latest (currently 0.5.0) release.

  • KIELER layout for GMF

Accept the unsigned content (Google Guava, and Kieler bundles are not signed).

If you are installing an older version of Kieler pick these features:

  • Kieler Core
  • Kieler Modeling Core
  • OGDF Library

Before applying layout, you need to:

  • Open an .ecorediag file
  • Open the Kieler Layout View
  • Make sure the tab with the opened diagram is selected (or the Layout view will be empty).
  • Make sure that the "Layout Provider" is set to "Planarization (OGDF)" (select it in the dialog that appears when clicking the "..." button next to "Layout"). (The layout in version < 0.5.0 was called "Mixed-Upward Planarization (OGDF)" and this layout worked much better - awaiting more info from the Kieler project).

To apply layout simply press the button in the menu that Kieler added "Layout the current diagram with Kieler..." (different text in different Kieler versions).

## Install Xtext ### If you are installing into Eclipse 4.2 Juno Go to Help > Install New Software, and select _All available sites_. Under the category _Modeling_, select "Xtext SDK".

If you are installing into Eclipse 3.7 Indigo

The Xtext project provides generation of parsers and lexers, and a framwork for working with models and text. You need to have Xtext installed to enable viewing (with syntax coloring), and editing of the grammar, editing of the generator workflow, and to run the workflow to regenerate the parser.

To install Xtext use a version of Xtext 2.x >= 2011-03-15 and install it from http://download.itemis.com/updates/nightly/ (This is subject to change as Xtext 2.0 is released). Install the following:

  • EMFT MWE2 Language -Nxxxx
  • EMFT MWE2 Runtime -Nxxxx
  • TMF Xtext - Nxxxx
  • Xtext Antlr-2xxxx

Do not select the "Helios" variants as they are for the released Xtext 1.x stream even if you are using an Eclipse 3.6 (Helios).

Add a custom footer
Add a custom sidebar
Clone this wiki locally