Skip to main content
Jump to: navigation, search

Difference between revisions of "Eclipse Oomph Authoring"

Line 86: Line 86:
 
If a variable is declared without a value a prompt dialog is displayed early in the execution process. The user can enter the missing variable values, which are then stored as variable tasks in the User scope (see above). These stored variable tasks are restricted to the scope that originally declared the variable. At execution time these User-scoped variable tasks override the respective variable tasks that you have declared in your project model.
 
If a variable is declared without a value a prompt dialog is displayed early in the execution process. The user can enter the missing variable values, which are then stored as variable tasks in the User scope (see above). These stored variable tasks are restricted to the scope that originally declared the variable. At execution time these User-scoped variable tasks override the respective variable tasks that you have declared in your project model.
  
'''Important''': Prompted values of variables that are declared with the type PASSWORD are not stored in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup} but rather in an Equinox Secure Storage node. The setup framework ensures that they are never shown in the user interface.
+
'''Important''': Prompted values of variables that are declared with the type PASSWORD are not stored in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup</tt> but rather in an Equinox Secure Storage node. The setup framework ensures that they are never shown in the user interface.
  
 
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:
 
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:
  
 
   ${''variable-name''}
 
   ${''variable-name''}
 +
 +
 +
In addition to the variables that are declared by VariableTasks you can refer to all:
 +
 +
* Attributes of setup tasks with a defined ID. The reference syntax is ${''task-ID''.''attribute-name''}.
 +
* System properties as returned by <tt>System.getProperties()</tt>.
 +
* Environment variables as returned by <tt>System.getenv()</tt>.
 +
* Predefined variables as determined by the setup engine from the user input to the installer.
 +
 +
 +
The following variables are predefined by the setup engine:
 +
 +
{| class="wikitable"
 +
| '''scope.installation.name''' || The value of the <em>name</em> attribute of the current installation scope.
 +
|-
 +
| '''scope.installation.label''' || The value of the <em>label</em> attribute of the current installation scope.
 +
|-
 +
| '''scope.installation.description''' || The value of the <em>description</em> attribute of the current installation scope.
 +
|-
 +
| '''scope.workspace.name''' || The value of the <em>name</em> attribute of the current workspace scope.
 +
|-
 +
| '''scope.workspace.label''' || The value of the <em>label</em> attribute of the current workspace scope.
 +
|-
 +
| '''scope.workspace.description''' || The value of the <em>description</em> attribute of the current workspace scope.
 +
|-
 +
| '''scope.user.name''' || The value of the <em>name</em> attribute of the current user scope.
 +
|-
 +
| '''scope.user.label''' || The value of the <em>label</em> attribute of the current user scope.
 +
|-
 +
| '''scope.user.description''' || The value of the <em>description</em> attribute of the current user scope.
 +
|-
 +
| '''scope.product.catalog.name''' || The value of the <em>name</em> attribute of the current product catalog scope.
 +
|-
 +
| '''scope.product.catalog.label''' || The value of the <em>label</em> attribute of the current product catalog scope.
 +
|-
 +
| '''scope.product.catalog.description''' || The value of the <em>description</em> attribute of the current product catalog scope.
 +
|-
 +
| '''scope.product.name''' || The value of the <em>name</em> attribute of the current product scope.
 +
|-
 +
| '''scope.product.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product scope and its parent scopes.
 +
|-
 +
| '''scope.product.label''' || The value of the <em>label</em> attribute of the current product scope.
 +
|-
 +
| '''scope.product.description''' || The value of the <em>description</em> attribute of the current product scope.
 +
|-
 +
| '''scope.product.version.name''' || The value of the <em>name</em> attribute of the current product version scope.
 +
|-
 +
| '''scope.product.version.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product version scope and its parent scopes.
 +
|-
 +
| '''scope.product.version.label''' || The value of the <em>label</em> attribute of the current product version scope.
 +
|-
 +
| '''scope.product.version.description''' || The value of the <em>description</em> attribute of the current installation scope.
 +
|-
 +
| '''scope.project.catalog.name''' || The value of the <em>name</em> attribute of the current project catalog scope.
 +
|-
 +
| '''scope.project.catalog.label''' || The value of the <em>label</em> attribute of the current project catalog scope.
 +
|-
 +
| '''scope.project.catalog.description''' || The value of the <em>description</em> attribute of the current project catalog scope.
 +
|-
 +
| '''scope.project.name''' || The value of the <em>name</em> attribute of the current project scope.
 +
|-
 +
| '''scope.project.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current project scope and its parent scopes.
 +
|-
 +
| '''scope.project.label''' || The value of the <em>name</em> attribute of the current project scope.
 +
|-
 +
| '''scope.project.description''' || The value of the <em>name</em> attribute of the current project scope.
 +
|-
 +
| '''scope.project.stream.name''' || The value of the <em>name</em> attribute of the current stream scope.
 +
|-
 +
| '''scope.project.stream.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current stream scope and its parent scopes.
 +
|-
 +
| '''scope.project.stream.label''' || The value of the <em>label</em> attribute of the current stream scope.
 +
|-
 +
| '''scope.project.stream.description''' || The value of the <em>description</em> attribute of the current stream scope.
 +
|}
 +
  
 
You can also extend variable references that evaluate to file system paths by adding a forward slash notation of the nested path '''before''' the closing brace. The advantage is that the full resulting path is formatted in the OS-specific form, e.g.:
 
You can also extend variable references that evaluate to file system paths by adding a forward slash notation of the nested path '''before''' the closing brace. The advantage is that the full resulting path is formatted in the OS-specific form, e.g.:
  
 
   ${installation.location/git/myproject} evaluates to C:\develop\my.project\master\git\myproject on Windows
 
   ${installation.location/git/myproject} evaluates to C:\develop\my.project\master\git\myproject on Windows
 +
  
 
After the path extension part you can add filter calls with pipe symbols. Multiple filters can be chained. Example:
 
After the path extension part you can add filter calls with pipe symbols. Multiple filters can be chained. Example:
  
 
   ${installation.location|uri}/git/myproject evaluates to file:/C:/develop/git/my.project/master/git/myproject
 
   ${installation.location|uri}/git/myproject evaluates to file:/C:/develop/git/my.project/master/git/myproject
 +
  
 
The following filters are currently available:
 
The following filters are currently available:
  
{|
+
{| class="wikitable"
 
| '''file''' || Converts a file: URI to an OS-specific file system path.
 
| '''file''' || Converts a file: URI to an OS-specific file system path.
 
|-
 
|-
Line 136: Line 214:
 
|}
 
|}
  
The following variables are predefined by the setup engine:
 
  
* All system properties as returned by System.getProperties()
+
When looking for declared variables that you can use in your model also have a look at the Outline view that displays variables from the outer scopes. For example the current [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.projects.setup Project Catalog] file for Eclipse.org projects contains declarations for some useful variables:
* All environment variables as returned by System.getenv()
+
* '''setup.state.dir''' --> ${user.home/.eclipse/org.eclipse.emf.cdo.releng.setup}
+
* '''setup.p2.agent.dir''' --> ${user.home/.p2}
+
* '''setup.p2.pool.dir''' --> ${setup.p2.agent.dir/pool}
+
* '''setup.install.dir''' --> the root install folder as entered by the user
+
* '''setup.project.dir''' --> ${setup.install.dir/''project-name''}
+
* '''setup.branch.dir''' --> ${setup.project.dir/''branch-name''}
+
* '''setup.eclipse.dir''' --> ${setup.branch.dir/eclipse}
+
* '''setup.project.name''' --> ''project-name''
+
* '''setup.project.label''' --> ''project-label''
+
* '''setup.branch.name''' --> ''branch-name''
+
* '''setup.branch.label''' --> ''project-label'' + " " + ''branch-name''
+
 
+
When looking for declared variables that you can use in your model also have a look at the Outline view that displays variables from the outer scopes. For example the current main [http://git.eclipse.org/c/cdo/cdo.git/tree/plugins/org.eclipse.emf.cdo.releng.setup/Configuration.setup configuration] file for Eclipse.org projects contains declarations for some useful variables:
+
  
 
* '''jre.1.4.location''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}
 
* '''jre.1.4.location''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}
Line 165: Line 228:
 
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson
 
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson
  
The advantage of having these variables be declared in a project-independent scope is that their prompted values will be stored in the Preferences scope without a project restriction. Hence users will not be required to enter these values more than once even when they install additional environments. Of course they can be edited in the Preferences model at any time.
+
 
 +
The advantage of having these variables be declared in a project-independent scope is that their prompted values will be stored in the User scope without a project restriction. Hence users will not be required to enter these values more than once even when they install additional environments. Of course they can be edited in the User model at any time.
  
 
The recommended form of variable names is the dot-separated notation. Note that it is typically not possible to define environment variables with dots in their name. If you want to define variables in your process/system environment use underscores instead of the dots; you can still refer to them via dot-notation in your models.
 
The recommended form of variable names is the dot-separated notation. Note that it is typically not possible to define environment variables with dots in their name. If you want to define variables in your process/system environment use underscores instead of the dots; you can still refer to them via dot-notation in your models.
 +
  
 
== Frequently Asked Questions ==
 
== Frequently Asked Questions ==

Revision as of 07:55, 20 June 2015

Warning2.png
Outdated content
A complete author's guide is currently under construction (help center documentation). The wikis are quite outdated, see this forum thread for more information. A link will be published here when it is ready.


What is Oomph?

Please read Eclipse Installer.


Getting Started

For now here are some easy steps for creating a new setup model for your project:

  1. Download and install the Eclipse Installer as outlined in Eclipse Installer.
  2. Make sure that the Oomph setup SDK is installed in your IDE. Either:
    1. That's already the case because your IDE is a Mars M5 or later Eclipse Package, or
    2. Start the installer and install an IDE of your choice (select on the first installer page), or
    3. Use p2 to install "Oomph Setup SDK" from http://download.eclipse.org/oomph/updates/latest.
  3. Create a new "Project Setup Model" file in any existing workspace project:
    New-wizard.png New-wizard-2.png New-wizard-3.png
  4. Open the resulting setup file with Oomph's Setup Editor:
    Setup-edit.png
  5. Add setup tasks to your project and/or to your project streams:
    Setup-edit2.png
  6. Configure the tasks in the Properties view. Note that there are "Expert" properties available:
    Setup-edit3.png
  7. The Outline view displays a preview of the executable model with resolved variables:
    Setup-edit4.png
  8. To test/execute your new setup model:
    1. Start the installer (see step 1) and, if necessary, switch to the Advanced Mode via the dialog menu.
    2. Pick any product on page 1 and click the Next button to proceed to page 2.
    3. Drag and drop your .setup file onto one of the top-level catalogs (Eclipse.org or Github.com) in the projects tree. Your project will appear as a subproject of the special <User> project.
    4. Double-click your project to add it to the table at te bottom of the page. There you can select a project stream in the Stream column. Press the Next button to proceed to the Variables page.
    5. Fill in the empty fields and press the Next button to proceed to the Confirmation page.
    6. Click Finish to start the installation process. The installer will first bootstrap a new IDE and then launch it to complete the installation at startup time.
  9. Chances are that your first model contains errors. Always turn on live validation in the Setup editor to get early feedback. If the installation fails early and the new IDE doesn't come up go back to step 6. If the IDE comes up but the initial configuration fails continue with step 10.
  10. In the new IDE (whether the initial configuration was successful or not) open your model file from the main menu, Navigate → Open Setup → Branch.png. Find the problems and fix them. Then start the setup process from within this IDE via the main menu, Help → Update.png Perform Setup Tasks…. This "manual trigger" will pop up a confirmation dialog before starting the setup process so that you can review what tasks are scheduled for execution.


Contributing to the Eclipse.org Project Catalog

When you are done authoring your model file (including testing the installation) commit/push it to the master branch of one of your Eclipse Git repositories. Find the plain URL of this file in http://git.eclipse.org/c and submit a bugzilla asking for the inclusion of your model into the main index. Paste the Git plain URL of your model into the bug description.


Understanding the Setup Engine

The setup engine collects the setup tasks that are needed for a particular installation from a number of places called scopes. Some scopes can be nested and nested scopes generally inherit the tasks of their parent scopes.

A setup is fully described by the following local entry scopes:

  • The Installation scope is located in eclipse/configuration/org.eclipse.oomph.setup/installation.setup and contains tasks that are specific to this installation. In addition (and more importantly) the Installation scope points to exactly one Product Version scope (see below) in order to make all tasks (including inherited tasks) of that product version apply to this installation, too.
  • The Workspace scope is located in workspace/.metadata/.plugins/org.eclipse.oomph.setup/workspace.setup and contains tasks that are specific to this workspace. In addition the Workspace scope can optionally point to a number of Stream scopes (see below) in order to make all tasks (including inherited tasks) of those streams apply to this workspace, too.
  • The User scope is located in user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup and contains tasks that are common to all installations and workspaces (unless they're restricted to particular installations or workspaces).

The following additional scope types exist, so they can be referenced by the entry scopes:

  • The Catalog Index is the root scope and contains nested Product Catalogs and Project Catalogs.
  • A Product Catalog contains nested Product scopes and possibly a small number of tasks that are common to all nested scopes. Nested products may be contained directly or be linked in from separate files.
  • A Product contains nested Product Version scopes and possibly some tasks that are common to all nested scopes.
  • A Product Version contains no nested scopes but tasks that are specific to that product version.
  • A Project Catalog contains nested Project scopes and possibly a small number of tasks that are common to all nested scopes. Nested projects may be contained directly or be linked in from separate files.
  • A Project contains nested Stream and/or (Sub-) Project scopes and typically some tasks that are common to all nested scopes.
  • A Stream contains no nested scopes but tasks that are specific to that stream.

The resulting list of tasks is then flattened, that is, compound tasks (folders) are recursively replaced by their contained tasks. Disabled tasks (see the editors context menu) are removed from the list. Tasks that are restricted to scopes that are not chosen for the current installation/workspace are also removed. Tasks that are excluded from the current trigger (one of Bootstrap, Startup or Manual) are also removed.

The remaining list is then partially reordered according to a number of criteria such as task priority (hardcoded), variable references or explicitly authored task requirements (successors and predecessors in the expert properties). If no such criteria apply the tasks are kept in their authored order as much as possible.

Some types of tasks allow only one instance in the list of tasks. For example only one variable task (see below) with a given variable name is allowed to execute. To specify several of them (with the same name) is perfectly okay, but you should notice that the earlier (according to the established order; see above) tasks are replaced/overridden by the later ones. This way, for example, a user can always override such tasks from any high/early scope, e.g., the Project or Stream scope, in his local User scope.

Now variable references in all String attributes of the tasks and their child elements are resolved and replaced by their expanded values. For details see Using Variables below.

Then the engine calls the isNeeded() method on each task in the list and removes those that are not needed (possibly according to the state of the running IDE).

If now the list of needed tasks is not empty a confirmation dialog is displayed and when the user presses Install the perform() method is called on that tasks. The progress of the installation process is then displayed in a progress dialog. The installation can be canceled at any point in time.


Using Variables

Variables play a very important role in the execution process. While a project model can perfectly work without the declaration or use of variables the model is typically more flexible with them. A variable must always be declared with a Variable Task somewhere in the model. It must have a name and can have a value or a default value.

If a variable is declared without a value a prompt dialog is displayed early in the execution process. The user can enter the missing variable values, which are then stored as variable tasks in the User scope (see above). These stored variable tasks are restricted to the scope that originally declared the variable. At execution time these User-scoped variable tasks override the respective variable tasks that you have declared in your project model.

Important: Prompted values of variables that are declared with the type PASSWORD are not stored in user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup but rather in an Equinox Secure Storage node. The setup framework ensures that they are never shown in the user interface.

You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:

  ${variable-name}


In addition to the variables that are declared by VariableTasks you can refer to all:

  • Attributes of setup tasks with a defined ID. The reference syntax is ${task-ID.attribute-name}.
  • System properties as returned by System.getProperties().
  • Environment variables as returned by System.getenv().
  • Predefined variables as determined by the setup engine from the user input to the installer.


The following variables are predefined by the setup engine:

scope.installation.name The value of the name attribute of the current installation scope.
scope.installation.label The value of the label attribute of the current installation scope.
scope.installation.description The value of the description attribute of the current installation scope.
scope.workspace.name The value of the name attribute of the current workspace scope.
scope.workspace.label The value of the label attribute of the current workspace scope.
scope.workspace.description The value of the description attribute of the current workspace scope.
scope.user.name The value of the name attribute of the current user scope.
scope.user.label The value of the label attribute of the current user scope.
scope.user.description The value of the description attribute of the current user scope.
scope.product.catalog.name The value of the name attribute of the current product catalog scope.
scope.product.catalog.label The value of the label attribute of the current product catalog scope.
scope.product.catalog.description The value of the description attribute of the current product catalog scope.
scope.product.name The value of the name attribute of the current product scope.
scope.product.name.qualified The concatenated value of the name attributes of the current product scope and its parent scopes.
scope.product.label The value of the label attribute of the current product scope.
scope.product.description The value of the description attribute of the current product scope.
scope.product.version.name The value of the name attribute of the current product version scope.
scope.product.version.name.qualified The concatenated value of the name attributes of the current product version scope and its parent scopes.
scope.product.version.label The value of the label attribute of the current product version scope.
scope.product.version.description The value of the description attribute of the current installation scope.
scope.project.catalog.name The value of the name attribute of the current project catalog scope.
scope.project.catalog.label The value of the label attribute of the current project catalog scope.
scope.project.catalog.description The value of the description attribute of the current project catalog scope.
scope.project.name The value of the name attribute of the current project scope.
scope.project.name.qualified The concatenated value of the name attributes of the current project scope and its parent scopes.
scope.project.label The value of the name attribute of the current project scope.
scope.project.description The value of the name attribute of the current project scope.
scope.project.stream.name The value of the name attribute of the current stream scope.
scope.project.stream.name.qualified The concatenated value of the name attributes of the current stream scope and its parent scopes.
scope.project.stream.label The value of the label attribute of the current stream scope.
scope.project.stream.description The value of the description attribute of the current stream scope.


You can also extend variable references that evaluate to file system paths by adding a forward slash notation of the nested path before the closing brace. The advantage is that the full resulting path is formatted in the OS-specific form, e.g.:

  ${installation.location/git/myproject} evaluates to C:\develop\my.project\master\git\myproject on Windows


After the path extension part you can add filter calls with pipe symbols. Multiple filters can be chained. Example:

  ${installation.location|uri}/git/myproject evaluates to file:/C:/develop/git/my.project/master/git/myproject


The following filters are currently available:

file Converts a file: URI to an OS-specific file system path.
fileExtension Extracts the file extension from a URI or a file system path.
path Extracts the path segments from a URI.
basePath Removes the last segment from a file system path.
lastSegment Extracts the last segment from a file system path.
uri Converts a file system path to a file: URI.
uriLastSegment Extracts the last path segment from a hierarchical URI or the authority from an opaque URI.
canonical Canonicalizes a file system path.
gitRepository Extracts the name of the repository from a Git URI (excluding a possible .git suffix).
upper Converts all characters of a String value to upper-case.
lower Converts all characters of a String value to lower-case.
cap Capitalizes the first word of a String value.
allCap Capitalizes all words of a String value.
preferenceNode Escapes all forward slashes (/) of a String value, so that the result can be used as a value in preference nodes.
property Escapes all double back slashes (\\) of a String value, so that the result can be used as a value in properties.
username Escapes all "at" symbols (@) of a String value, so that the result can be used in URI that contain a username.


When looking for declared variables that you can use in your model also have a look at the Outline view that displays variables from the outer scopes. For example the current Project Catalog file for Eclipse.org projects contains declarations for some useful variables:

  • jre.1.4.location --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}
  • jre.1.5.location --> The folder containing a 1.5 compatible JDK/JRE for architecture ${os.arch}
  • jre.1.6.location --> The folder containing a 1.6 compatible JDK/JRE for architecture ${os.arch}
  • jre.1.7.location --> The folder containing a 1.7 compatible JDK/JRE for architecture ${os.arch}
  • jre.1.8.location --> The folder containing a 1.8 compatible JDK/JRE for architecture ${os.arch}
  • git.user.id --> The Eclipse user ID for Git/Gerrit commits
  • git.author.name --> The Eclipse author name for Git/Gerrit commits
  • git.author.email --> The Eclipse author email for Git/Gerrit commits
  • eclipse.user.id --> The Eclipse user ID for Bugzilla/Hudson
  • eclipse.user.password --> The Eclipse password for Bugzilla/Hudson


The advantage of having these variables be declared in a project-independent scope is that their prompted values will be stored in the User scope without a project restriction. Hence users will not be required to enter these values more than once even when they install additional environments. Of course they can be edited in the User model at any time.

The recommended form of variable names is the dot-separated notation. Note that it is typically not possible to define environment variables with dots in their name. If you want to define variables in your process/system environment use underscores instead of the dots; you can still refer to them via dot-notation in your models.


Frequently Asked Questions

Why didn't the model editor tell me earlier that I've made a silly mistake?

Please enable Live Validation in the editor menu to get early feedback.


Tips and Tricks

Hosting your own index / product catalog

If you want to host your own product catalog, you must provide a URI mapping to the installer to locate the root setup file. Open the oomph.ini file and add an oomph.redirection.<some_id> where some_id is any unique identifier. The root EMF model is an Index and must be stored in the file org.eclipse.setup. Use http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/org.eclipse.setup as a starting point. All of your other setup models can be stored in any file name you desire. You must also copy all of the model files in http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/models/ to your redirection <path>/models/

  • -Doomph.redirection.setups=http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->http://<hostname>/<path>/


Generating PDE Target Definition files (*.target) and their use by Tycho

Oomph can automagically generate a *.target files compatible with the PDE target definition file format (*.target) for you from your *.setup model. This is particularly useful if used in combination with Tycho's support for them, see https://wiki.eclipse.org/Tycho/Target_Platform, as it allows you to maintain p2 Repositories and Requirements in one single place, and have that be used both for workspace set-up and builds.

To generate a *.target file, add an Annotation similar to the example found in Oomph's own setup model (see here http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/Oomph.setup), like so:

     <annotation
         source="http:/www.eclipse.org/oomph/targlets/TargetDefinitionGenerator">
       <detail
           key="location">
         <value>${git.clone.location}/targetdefinition/DesignStudio.target</value>
       </detail>
       <detail
           key="extraUnits">
         <value>org.eclipse.equinox.executable.feature.group</value>
       </detail>
       <detail
           key="includeAllPlatforms">
         <value>false</value>
       </detail>
       <detail
           key="includeSource">
         <value>true</value>
       </detail>
       <detail
           key="generateVersions">
         <value>true</value>
       </detail>
     </annotation>

Note that the *.target file will be updated (or initially generated if first time) each time that Oomph Performs Setup Tasks (and not every time you only "touch" your *.setup model). Any errors encountered while generating the *.target file are reported in the Setup Log as usual.

TODO Document what preferredRepositories, PomModulesUpdater & PomArtifactUpdater do...

Copyright © Eclipse Foundation, Inc. All Rights Reserved.