View source for Eclipse Oomph Authoring

== What is Oomph? ==

Please read [[Eclipse Oomph Installer]].


== Getting Started ==

A complete author's guide is currently under construction. A link will be published here when it is ready.

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

# Download and install the Eclipse Oomph installer as outlined in [[Eclipse Oomph Installer]].
# Start the installer and install the "CDO Release Engineering" project. The resulting IDE contains the setup/update engine and the needed new wizards and model editors.
# Create a new "Project Setup" file in your releng (or any other) project:<br>[[Image:new-wizard.png]] [[Image:new-wizard-2.png]] [[Image:new-wizard-3.png]]
# Open the resulting setup file with Oomph's EMF model editor:<br>[[Image:setup-edit.png]]
# Add setup tasks to your branches and/or to your project (shared across all branches):<br>[[Image:setup-edit2.png]]
# Configure the tasks in the Properties view. Note that there are "Expert" properties available:<br>[[Image:setup-edit3.png]]
# The Outline view displays a ''preview'' of the executable model with resolved variables:<br>[[Image:setup-edit4.png]]
# To test/execute your new model copy the model file into the root folder of installer (see step 1) (Note: On Mac put your file into Setup.App/Contents/MacOs/). Then restart the installer and you will see your project at the top of the list. Check your branch and press the Install button. The installer will first bootstrap a new IDE and then launch it to complete the installation at startup time.
# Chances are that your first model contains errors (always turn on live validation in the model 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.
# In the new IDE (whether the initial configuration was successful or not) open the model file with the [[Image:branch.png]] button from the main toolbar. Find the problems and fix them. Then start the configuration process '''from within''' this IDE by pressing the [[Image:update.png]] button in the main toolbar. This "manual trigger" will pop up a confimation dialog before starting the configuration process so that you can review what tasks are scheduled for execution.
# When you are done (including testing the installation) commit/push your model file to the master branch of one of your Eclipse Git repositories. Find the ''plain URL'' of this file in [http://git.eclipse.org/c http://git.eclipse.org/c] and [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EMF&component=cdo.releng&version=4.3&bug_severity=enhancement&short_desc=%5BOomph%5D%20Please%20include%20model%20for%20project%20X 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.

'''Hint''': As an alternative to starting with an empty model you can also copy one of existing models:<br>[[Image:example-models.png]]

== 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):

* The '''[http://git.eclipse.org/c/cdo/cdo.git/tree/plugins/org.eclipse.emf.cdo.releng.setup/Configuration.setup Configuration]''' scope is the top level scope with a small number of tasks that apply to all installations. The tasks in this scope are controlled by the Oomph team.
* An '''Eclipse''' scope contains a small number of tasks to install a minimum IDE of a specific Eclipse version. There are several predefined Eclipse scopes nested in the Configuration (see above). All of them are controlled by the Oomph team. The user selects one of them for a particular installation at install time. This can be simulated at authoring time with the view toolbar choices in the Outline (Preview) view of the model editor.
* The '''Project''' scope contains tasks that apply to any installation that is linked to one of your branches (see below). You have full control over these tasks. Press the [[Image:branch.png]] button from the main toolbar to edit them.
* The '''Branch''' scope contains tasks that apply to any installation that is linked to this branch. You have full control over these tasks. The user selects one of them for a particular installation at install time. Press the [[Image:branch.png]] button from the main toolbar to edit them.
* The '''Preferences''' scope contains tasks that apply to any installation (unless they're explicitely restricted to specific higher scopes such as a specific branch or Eclipse version). The user has exclusive control over these tasks. They are stored in the user's home folder: <tt>${user.home}/.eclipse/org.eclipse.emf.cdo.releng.setup/setup-eclipse.xmi</tt>. Press the [[Image:user.png]] button from the main toolbar to edit them.

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 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 explicit (modeled) task requirements. If no such criteria apply the tasks are kept in their modeled 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 branch scope, in his local Preferences 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|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. If it has no 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 Preferences scope (see above). These stored variable tasks are restricted to the scope that originally declared the variable. At execution time these Preferences-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.emf.cdo.releng.setup/setup-eclipse.xmi} 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 attribute of your model. The general syntax is:

   ${''variable-name''}

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.:

   ${setup.branch.dir/git/my.project} evaluates to C:\develop\my.project\master\git\my.project on Windows

After the path extension part you can add filter calls with pipe symbols. Multiple filters can be chained. The filters "uri", "upper", "lower", "cap", "allcap" are currently available. Example:

   ${setup.branch.dir|uri}/git/my.project evaluates to file:/C:/develop/my.project/master/git/my.project

The following variables are predefined by the setup engine:

* All system properties as returned by System.getProperties()
* 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.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 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 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 ==

TBD.