https://wiki.eclipse.org/api.php?action=feedcontributions&user=Stepper.esc-net.de&feedformat=atomEclipsepedia - User contributions [en]2024-03-19T12:57:00ZUser contributionsMediaWiki 1.26.4https://wiki.eclipse.org/index.php?title=CDO_Source_Installation&diff=447590CDO Source Installation2023-06-24T15:18:51Z<p>Stepper.esc-net.de: </p>
<hr />
<div>To provision the same development environment that the CDO developers use follow these simple steps:<br />
<br />
# Download and start the [[Eclipse Installer]].<br />
# Drag [https://raw.githubusercontent.com/eclipse-cdo/cdo/master/releng/org.eclipse.emf.cdo.releng/CDOConfiguration.setup this link] and drop it on the installer's title area. Alternatively, copy the location of the previous link and apply it to the Eclipse Installer either via the menu in the upper right in simple mode or via the left-most toolbar button to the upper right in advanced mode.<br />
# Review and/or edit the variable values that the installer presents.<br />
# Click the Next/Finish buttons until the installation starts.<br />
<br />
<br />
You can update your development workspace by pulling the latest updates into your CDO Git clone and selecting the '''Perform Setup Tasks...''' action in the '''Help''' menu.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_and_log4j2_vulnerability_(CVE-2021-44228)&diff=444411Eclipse and log4j2 vulnerability (CVE-2021-44228)2021-12-14T06:04:31Z<p>Stepper.esc-net.de: </p>
<hr />
<div>{| class="wikitable"<br />
!Project<br />
!Version<br />
!Status<br />
!Comment<br />
|-<br />
|Passage<br />
| <= 2.2.0<br />
|Vulnerable<br />
| The risk of exposure due to the tooling support in an IDE is negligible. Tools can be updated to the 2.2.1 release and runtimes should be upgraded to the 2.2.1 release. Older versions of Passage also work with log4j >= 2.15. See [https://projects.eclipse.org/projects/technology.passage/downloads Passage Downloads] for site details.<br />
|-<br />
|Eclipse Packaging Project (Eclipse IDE for ...)<br />
|*.*.*<br />
|Not Vulnerable / Vulnerable<br />
|All packages available from [https://www.eclipse.org/downloads/packages/ Eclipse Downloads] are not vulnerable, except for the Eclipse IDE for RCP and RAP Developers which contain Passage. Even for packages containing Passage, the risk of exposure due to the tooling support in an IDE is negligible. Adding the site https://download.eclipse.org/passage/updates/release/2.2.1/ to ''Window &rarr; Preferences &rarr; Install/Update &rarr; Available Sites'' and using ''Help &rarr; Check for Updates'' can be used to upgrade the version of Passage and thereby replace the vulnerable version of log4j2.<br />
|-<br />
|Eclipse Installer<br />
|*.*.*<br />
|Not Vulnerable<br />
|Does not use log4j. The catalogs used by the installer for installing the Eclipse Packaging Project's products are dynamically loaded and have been updated such that installing any version of the Eclipse IDE for RCP and RAP Developers will install Passage 2.2.1 with the repaired version of log4j2, i.e., >= 2.15.<br />
|-<br />
|Eclipse SDK<br />
|*.*.*<br />
|Not Vulnerable<br />
|Eclipse SDK does not use log4j<br />
|-<br />
|JGit<br />
|1.0-5.13.0,6.0.0<br />
|Not Vulnerable<br />
|org.eclipse.jgit.pgm uses log4j 1.2.15<br />
|-<br />
|EGit<br />
|1.0-5.13.0,6.0.0<br />
|Not Vulnerable<br />
|EGit does not use log4j<br />
|-<br />
|Jetty<br />
|*.*.*<br />
|Not Vulnerable<br />
|[https://webtide.com/jetty-log4j2-exploit-cve-2021-44228/ Blog: Jetty & Log4j2 exploit CVE-2021-44228]<br />
|-<br />
|StatET<br />
|*.*.*<br />
|Not Vulnerable<br />
|<br />
|-<br />
|Web Tools Platform<br />
|*.*.*<br />
|Not Vulnerable<br />
|log4j 1.2.15 is used in an unused dependency in a single test plug-in<br />
|-<br />
|Scout Runtime<br />
|10.x - 22.x<br />
|Not Vulnerable<br />
|<br />
|-<br />
|Eclipse Hawk<br />
|*.*.*<br />
|Not Vulnerable<br />
|<br />
|-<br />
|Eclipse Theia<br />
|*.*.*<br />
|Not Vulnerable<br />
|-<br />
|Eclipse Dash<br />
|*.*.*<br />
|Not Vulnerable<br />
|<br />
|-<br />
|Linux Tools<br />
|*.*.*<br />
|Not Vulnerable<br />
|<br />
|-<br />
|Eclipse JKube<br />
|*.*.*<br />
|Not Vulnerable<br />
|Eclipse JKube does not use log4j<br />
|-<br />
|Eclipse Modeling Framework (EMF)<br />
|*.*.*<br />
|Not Vulnerable<br />
| Uses log4j 1.x, but only in Xcore tools bundles, not in any runtime bundles deployed in applications.<br />
|-<br />
|XML Schema Definition (XSD)<br />
|*.*.*<br />
|Not Vulnerable<br />
| Does not use log4j.<br />
|-<br />
|JustJ<br />
|*.*.*<br />
|Not Vulnerable<br />
| Does not use log4j and log4j is not included in the JRE themselves.<br />
|-<br />
|Oomph<br />
|*.*.*<br />
|Not Vulnerable<br />
| Does not use log4j.<br />
|-<br />
|CDO Model Repository<br />
|*.*.*<br />
|Not Vulnerable<br />
| Does not use log4j.<br />
|}</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Oomph_Authoring&diff=441478Eclipse Oomph Authoring2020-11-12T14:00:17Z<p>Stepper.esc-net.de: /* Conditional Tasks */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
== Getting Started ==<br />
<br />
=== What is Oomph? ===<br />
<br />
Please read [[Eclipse Installer]].<br />
<br />
<br />
=== Installing Oomph ===<br />
<br />
# Download and install the Eclipse '''Installer''' as outlined in [[Eclipse Installer]].<br />
# Make sure that the Oomph setup '''SDK''' is installed in your IDE. Either:<br />
## That's already the case because your IDE is a Mars M5 or later Eclipse Package, or<br />
## Start the installer and install an IDE of your choice (select on the first installer page), or<br />
## Use p2 to install "Oomph Setup SDK" from [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest].<br />
<br />
== Creating a Setup Project Model ==<br />
<br />
=== Using the Setup Project Model Wizard ===<br />
<br />
# Create an empty project in your workspace or select a folder in an existing project. You'll create the new "Setup Project Model" in the selected folder.<br />
# Open the New... dialog and select the "Setup Project Model" wizard:<br>[[Image:new-wizard.png]]<br><br />
# Select one of the provided templates (e.g., Eclipse.org, Github.com, or Simple) and adjust the displayed values:<br>[[Image:new-wizard-2.png]]<br><br />
# Some values are automatically derived from your input to fields '''higher up'''.<br />
# Open the Preview>>> to understand the impact of changes to the current field.<br />
<br />
=== Using the Setup Editor ===<br />
<br />
# Open the resulting setup file with Oomph's Setup Editor:<br>[[Image:setup-edit.png]]<br><br />
# Configure the tasks in the Properties view. Note that there are "Expert" properties available.<br />
# Add setup tasks to your project and/or to your project streams and configure them, too.<br />
# The Outline view displays a ''preview'' of the executable model with resolved variables.<br />
<br />
=== Testing the Setup Model ===<br />
<br />
# To test/execute your new setup model:<br />
## Start the installer and, if necessary, switch to the Advanced Mode via the dialog menu.<br />
## Pick any product on page 1 and click the Next button to proceed to page 2.<br />
## Drag and drop your <tt>.setup</tt> file onto one of the top-level catalogs (<tt>Eclipse.org</tt> or <tt>Github.com</tt>) in the projects tree. Your project will appear as a subproject of the special <tt>&lt;User&gt;</tt> project.<br />
## Double-click your project to add it to the table at the 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.<br />
## Fill in the empty fields and press the Next button to proceed to the Confirmation page.<br />
## 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.<br><br />
# 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 [[#Using the Setup Editor|Using the Setup Editor]]. If the IDE comes up but the initial configuration fails continue with step 3.<br />
# In the new IDE (whether the initial configuration was successful or not) open your model file from the main menu, Navigate &rarr; Open Setup &rarr; [[Image:branch.png]]. Find the problems and fix them. Then start the setup process '''from within''' this IDE via the main menu, Help &rarr; [[Image:update.png]] Perform Setup Tasks&hellip;. 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.<br />
<br />
=== Contributing to a Project Catalog ===<br />
<br />
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 http://git.eclipse.org/c] and [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&bug_severity=enhancement&short_desc=Please%20include%20setup%20for%20project%20Xyz 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.<br />
<br />
The same can be done if your project is not an Eclipse project, but hosted on '''GitHub'''. Simply state this fact in the bug description and paste the "raw" content URL to the file instead.<br />
<br />
== Understanding the Setup Engine ==<br />
<br />
=== Understanding Setup Tasks and Scopes ===<br />
<br />
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:<br />
<br />
* The '''Installation''' scope is located in <tt>eclipse/configuration/org.eclipse.oomph.setup/installation.setup</tt> 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.<br />
<br />
* The '''Workspace''' scope is located in <tt>workspace/.metadata/.plugins/org.eclipse.oomph.setup/workspace.setup</tt> 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.<br />
<br />
* The '''User''' scope is located in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup</tt> and contains tasks that are common to '''all''' installations and workspaces (unless they're restricted to particular installations or workspaces).<br />
<br />
<br />
The following additional scope types exist, so they can be referenced by the entry scopes:<br />
<br />
* The '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.setup Catalog Index]''' is the root scope and contains nested Product Catalogs and Project Catalogs.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.products.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/OomphInstaller.setup Product]''' contains nested Product Version scopes and possibly some tasks that are common to all nested scopes.<br />
<br />
* A '''Product Version''' contains no nested scopes but tasks that are specific to that product version.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.projects.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/Oomph.setup Project]''' contains nested Stream and/or (Sub-) Project scopes and typically some tasks that are common to all nested scopes.<br />
<br />
* A '''Stream''' contains no nested scopes but tasks that are specific to that stream.<br />
<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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 [[#Declaring_and_Using_Variables|Declaring and Using Variables]] below.<br />
<br />
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). <br />
<br />
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.<br />
<br />
=== Declaring and Using Variables ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:<br />
<br />
${''variable-name''}<br />
<br />
To prevent a variable reference from being expanded (e.g. you actually want to have the value '${var}' and not the value of "var"), you need to escape the variable syntax with an extra dollar character. So "$${var}" will result in "${var}".<br />
<br />
In addition to the variables that are declared by VariableTasks you can refer to all of the following:<br />
<br />
* Attribute values of setup tasks with a defined ID. The reference syntax is ${''taskID''.''attributeName''}.<br />
* [[#Predefined Variables|Predefined variables]] as determined by the setup engine from the user input to the installer (see below)<br />
* [[#Environment Variables|Environment variables]] as returned by <tt>System.getenv()</tt><br />
* System properties as returned by <tt>System.getProperties()</tt><br />
<br />
==== Predefined Variables ====<br />
<br />
The following variables are predefined by the setup engine:<br />
<br />
{| class="wikitable"<br />
| '''scope.installation.name''' || The value of the <em>name</em> attribute of the current installation scope. <br />
|-<br />
| '''scope.installation.label''' || The value of the <em>label</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.installation.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.workspace.name''' || The value of the <em>name</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.label''' || The value of the <em>label</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.description''' || The value of the <em>description</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.user.name''' || The value of the <em>name</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.label''' || The value of the <em>label</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.description''' || The value of the <em>description</em> attribute of the current user scope.<br />
|-<br />
| '''scope.product.catalog.name''' || The value of the <em>name</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.label''' || The value of the <em>label</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.description''' || The value of the <em>description</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.name''' || The value of the <em>name</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product scope and its parent scopes.<br />
|-<br />
| '''scope.product.label''' || The value of the <em>label</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.description''' || The value of the <em>description</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.version.name''' || The value of the <em>name</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product version scope and its parent scopes.<br />
|-<br />
| '''scope.product.version.label''' || The value of the <em>label</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.project.catalog.name''' || The value of the <em>name</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.label''' || The value of the <em>label</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.description''' || The value of the <em>description</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.name''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current project scope and its parent scopes.<br />
|-<br />
| '''scope.project.label''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.description''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.stream.name''' || The value of the <em>name</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current stream scope and its parent scopes.<br />
|-<br />
| '''scope.project.stream.label''' || The value of the <em>label</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.description''' || The value of the <em>description</em> attribute of the current stream scope.<br />
|}<br />
<br />
==== Variable Extensions ====<br />
<br />
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.:<br />
<br />
${installation.location/git/myproject} evaluates to C:\develop\installation1\git\myproject on Windows<br />
<br />
<br />
After the path extension part you can add filter calls with pipe symbols. Filter names are generally case-insensitive. Multiple filters can be chained. Example:<br />
<br />
${installation.location|uri}/git/myproject evaluates to file:/C:/develop/installation1/git/myproject<br />
<br />
<br />
==== Variable Filters ====<br />
<br />
The following filters are currently available:<br />
<br />
{| class="wikitable"<br />
| '''base64''' || Encodes the String value to its base64 representation.<br />
|-<br />
| '''basePath''' || Removes the last segment from a file system path.<br />
|-<br />
| '''camel''' || Converts a qualified name to camel case notation.<br />
|-<br />
| '''canonical''' || Canonicalizes a file system path.<br />
|-<br />
| '''cap''' || Capitalizes the first word of a String value.<br />
|-<br />
| '''capAll''' || Capitalizes all words of a String value.<br />
|-<br />
| '''file''' || Converts a file: URI to an OS-specific file system path.<br />
|-<br />
| '''fileExtension''' || Extracts the file extension from a URI or a file system path.<br />
|-<br />
| '''gitRepository''' || Extracts the name of the repository from a Git URI (excluding a possible .git suffix).<br />
|-<br />
| '''lastSegment''' || Extracts the last segment from a file system path.<br />
|-<br />
| '''length''' || Converts a String to a String that contains the alpha-numerical representation of the length of the original String.<br />
|-<br />
| '''lower''' || Converts all characters of a String value to lower-case.<br />
|-<br />
| '''not''' || The boolean logical negation, i.e., 'false' if the value is 'true', and 'true' if the value is 'false' (or anything else).<br />
|-<br />
| '''path''' || Converts all \ characters of a String value, typically a file system path, to /.<br />
|-<br />
| '''pathEncode''' || Converts a file system path to a String value that can be used as a file name.<br />
|-<br />
| '''patternQuote''' || Quotes regular-expression constructs in the String value such that the result can be used as a literal string in patterns.<br />
|-<br />
| '''preferenceNode''' || Escapes all forward slashes (/) of a String value, so that the result can be used as a value in preference nodes.<br />
|-<br />
| '''property''' || Escapes all double back slashes (\\) of a String value, so that the result can be used as a value in properties.<br />
|-<br />
| '''propertyValue''' || Interprets the String value as a preference property path and returns the value of that property.<br />
|-<br />
| '''qualifiedName''' || Converts a camel case String value name to a qualified name.<br />
|-<br />
| '''slashDecode''' || Decodes a slashEncoded String value.<br />
|-<br />
| '''slashEncode''' || Encodes all slashes and backslashes of a String value.<br />
|-<br />
| '''trim''' || Removes all whitespace from the beginning and the end of a String.<br />
|-<br />
| '''trimLeft''' || Removes all whitespace from the beginning of a String.<br />
|-<br />
| '''trimRight''' || Removes all whitespace from the end of a String.<br />
|-<br />
| '''trimTrailingSlashes''' || Removes all slashes and backslashes from the end of a String.<br />
|-<br />
| '''upper''' || Converts all characters of a String value to upper-case.<br />
|-<br />
| '''uri''' || Converts a file system path to a file: URI.<br />
|-<br />
| '''uriLastSegment''' || Extracts the last path segment from a hierarchical URI or the authority from an opaque URI.<br />
|-<br />
| '''urlDecode''' || Decodes a URL.<br />
|-<br />
| '''urlEncode''' || URL-encodes a String value.<br />
|-<br />
| '''username''' || Escapes all "at" symbols (@) of a String value, so that the result can be used in URI that contain a username.<br />
|}<br />
<br />
You can also define your own custom variable filters by contributing to the extension point <tt>org.eclipse.oomph.setup.core.stringFilters</tt>.<br />
<br />
==== Variables from Outer Scopes====<br />
<br />
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:<br />
<br />
* '''jre.location-1.4''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.5''' --> The folder containing a 1.5 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.6''' --> The folder containing a 1.6 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.7''' --> The folder containing a 1.7 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.8''' --> The folder containing a 1.8 compatible JDK/JRE for architecture ${os.arch}<br />
* '''git.user.id''' --> The Eclipse user ID for Git/Gerrit commits<br />
* '''git.author.name''' --> The Eclipse author name for Git/Gerrit commits<br />
* '''git.author.email''' --> The Eclipse author email for Git/Gerrit commits<br />
* '''bugzilla.id''' --> The Eclipse user ID for Bugzilla/Hudson<br />
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson<br />
<br />
<br />
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.<br />
<br />
==== Environment Variables ====<br />
<br />
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.<br />
<br />
=== Conditional Tasks ===<br />
<br />
All setup tasks support filters. Oomph reuses [https://wiki.eclipse.org/Equinox_P2_Resolution#Enablement_filter p2's implementation] of LDAP filters. I.e., it supports a string a representation of LDAP Search Filters, RFC 1960, UMich, 1996,<br />
http://www.ietf.org/rfc/rfc1960.txt<br />
<br />
The filter property of a setup task is an advanced property. To display this property, ensure that "Show Advanced Properties" is enabled in the Properties view tool bar. The properties of a filter expression can generally refer to any system property or any environment variable. For example, the following filter expression on a task will ensure that it is included only when performing a task on a Linux operating system.<br />
<br />
(osgi.os=linux)<br />
<br />
The latest version of Oomph allows filter properties to refer to the values of variables as defined in the setup itself. For example, this idiom can be used to express if-then-else.<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xmi:XMI xmi:version="2.0"<br />
xmlns:xmi="<nowiki>http://www.omg.org/XMI</nowiki>"<br />
xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"<br />
xmlns:setup="<nowiki>http://www.eclipse.org/oomph/setup/1.0</nowiki>"><br />
<setup:VariableTask<br />
type="BOOLEAN"<br />
name="example.filter"<br />
label="Example Filter"><br />
<description>An example of a variable used to conditionally filter tasks</description><br />
</setup:VariableTask><br />
<setup:CompoundTask<br />
filter="(example.filter=true)"<br />
name="Filter True"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.a"<br />
label="Property A"><br />
<description>The value use for system.property.a</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.a"<br />
value="=${example.variable.a}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is true</description><br />
</setup:CompoundTask><br />
<setup:CompoundTask<br />
filter="(example.filter=false)"<br />
name="Filter False"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.b"<br />
label="Property B"><br />
<description>The value used for system.property.b</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.b"<br />
value="=${example.variable.b}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is false.</description><br />
</setup:CompoundTask><br />
</xmi:XMI><br />
<br />
On the Variables page of the setup wizards, any variable that is used in property of a filter will be displayed in bold. It is significant to note that the value of a so-called filter variable can conditionally affect the presence of other variables. In this example, either variable <code>example.variable.a</code> or <code>example.variable.b</code> (but not both) will be present on the Variables page, depending on the value of the <code>example.filter</code> variable, which is displayed as a checkbox because it is of type <code>BOOLEAN</code>.<br />
<br />
Note that Oomph setup editors support textual copy and paste, so you can copy the above XML and paste it into your setup editor to try it out.<br />
<br />
== Macros and Macro Expansion Tasks ==<br />
<br />
As of Oomph 1.13, released with Eclipse 2019-06, there is support for Macros. A Macro is a Scope, i.e., is a container for setup tasks, and can specify 0 or more Parameters. Each Parameter specifies a name, a description, and optionally a default value. The parameter names can be used as variable references in the setup tasks contained by the Macro.<br />
<br />
=== Creating a Macro ===<br />
<br />
The simplest way to create a new Macro is from the context menu of the folder where you want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Macro Model in the wizard. You can then edit the new Macro with the Setup Editor. You can create Parameters, if desired, and of course you can create any other setup tasks.<br />
<br />
Here is an example of how one could use a Macro for creating a Git Clone task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Macro<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:git="http://www.eclipse.org/oomph/setup/git/1.0"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
xsi:schemaLocation="http://www.eclipse.org/oomph/setup/git/1.0 http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/models/Git.ecore"<br />
name="git.clone"<br />
label="Git Clone"><br />
<setupTask<br />
xsi:type="git:GitCloneTask"<br />
id="git.clone"<br />
remoteName="${remoteName}"<br />
remoteURI="${remoteURI}"<br />
pushURI="${pushURI}"<br />
checkoutBranch="${checkoutBranch}"><br />
<annotation<br />
source="http://www.eclipse.org/oomph/setup/FeatureSubstitution"><br />
<detail<br />
key="restrictToCheckoutBranch"><br />
<value>${restrictToCheckoutBranch}</value><br />
</detail><br />
<detail<br />
key="recursive"><br />
<value>${recursive}</value><br />
</detail><br />
</annotation><br />
<description>${description}</description><br />
</setupTask><br />
<description>The GitClone macro provides a template for creating a clone task</description><br />
<parameter<br />
name="description"><br />
<description>The description of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="pushURI"><br />
<description>The push URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="recursive"<br />
defaultValue="false"><br />
<description>Whether submodules should be recursively cloned</description><br />
</parameter><br />
<parameter<br />
name="remoteName"<br />
defaultValue="origin"><br />
<description>The name of the remote</description><br />
</parameter><br />
<parameter<br />
name="remoteURI"><br />
<description>The remote URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="restrictToCheckoutBranch"<br />
defaultValue="false"><br />
<description>Whether the clone should be restricted to clone only the checkout branch</description><br />
</parameter><br />
<parameter<br />
name="checkoutBranch"><br />
<description>The name of the branch that the Git clone task to checks out</description><br />
</parameter><br />
</setup:Macro><br />
<br />
Special support is provided for defining so called local Variables in a Macro. Any Variable with a name that starts with '*' will be handled in a special way during [[#Macro Expansion Processing|Macro Expansion]].<br />
<br />
=== Using a Macro with a Macro Expansion Task ===<br />
<br />
To use a Macro you must create a Macro Expansion task. The easiest way to do this is to drag the resource containing the Macro and then drop it into the Setup Editor where you want to use it. Similarly, if you want to use a Macro defined in the internet, you can use Load Resource... from the Setup Editor's context menu to load the Macro into the editor's resource set (or drag the link and drop it into the editor). Note that Macros available in the resource set are always shown in the Outline view. Once the Macro is available in the editor's resource set, or in the Outline, you can drag and drop the Macro anywhere that any other setup task can be created. This will create a Macro Expansion task that binds to the Macro.<br />
<br />
A Macro Expansion task must specify an ID, which of course must be unique within the containing resource. The ID is used during [[#Macro Expansion Processing|Macro Expansion Processing]]. Via drag and drop, an ID is automatically assigned, but you'll likely want to change it. A Macro Expansion task can supply Arguments to bind the values of the Parameters of the Macro. For every Parameter without a default value there must be a corresponding Argument to bind its value. The validator will complain when that's not the case, so be sure to enable Live Validation via the context menu. When creating a Macro Expansion task using drag and drop, the required Arguments are automatically created. Of course you'll want to change the generated values; you can delete any Arguments for which the Parameter specifies the default value that you wish to just use. You can change the Argument's value by double clicking the Argument to ensure that it's visible in the Properties view, and can then edit the Value property of the Argument there. The description of the corresponding Parameter is displayed in the Properties view after the Parameter's name. This is why it's important to include a description for each Parameter so that the author using the Macro knows how the Argument's value will be used by that Macro.<br />
<br />
The setup editor displays the Macro referenced by a Macro Expansion task as a child item, in light brown, in the tree view, so you can fully explore the Macro being used. In addition a Preview item is displayed, in light blue, to show how the Macro Expansion task will be expanded. And of course the Outline view allows you to preview all of the tasks that will be performed when you run the installer later.<br />
<br />
Here is an example of how the above Macro could be used by a Macro Expansion task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Project<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
name="sample.project"<br />
label="SampleProject"><br />
<setupTask<br />
xsi:type="setup:MacroTask"<br />
id="my"<br />
macro="GitCloneMacro.setup#/"><br />
<argument<br />
name="description"<br />
value="description_value"/><br />
<argument<br />
name="pushURI"<br />
value="pushURI_value"/><br />
<argument<br />
name="recursive"/><br />
<argument<br />
name="remoteName"/><br />
<argument<br />
name="remoteURI"<br />
value="remoteURI_value"/><br />
<argument<br />
name="restrictToCheckoutBranch"/><br />
<argument<br />
name="checkoutBranch"<br />
value="master"/><br />
</setupTask><br />
<stream name="stream"/><br />
<logicalProjectContainer<br />
xsi:type="setup:ProjectCatalog"<br />
href="index:/org.eclipse.setup#//@projectCatalogs[name='org.eclipse']"/><br />
<description>SampleProject provides cool stuff.</description><br />
</setup:Project><br />
<br />
Note that here we have several Arguments without a value. Those could be deleted or a value (presumably different from the default value of the Parameter) could be specified. Also note that a well-formed Argument can only bind to a Parameter of the containing Macro Expansion task's Macro, so the serialization is simplified to specify just the name of the bound Parameter in this case.<br />
<br />
=== Macro Expansion Processing ===<br />
<br />
A Macro Expansion task is expanded to a Compound Setup Task as illustrated by the Preview item. Each Argument is bound to its corresponding Parameter via a local variable of the form '*<macro-expansion-task-id>.<parameter-name>'. Every variable reference to the Parameter name is transformed to use this Variable's more-qualified name instead. Every setup task with an ID is transformed to specify instead a qualified ID of the form '<macro-expansion-task-id>.<original-id>' and every variable reference that's prefixed by '<original-id>.' will be transformed to use the more-qualified prefix instead. In addition, any Variable contained by the Macro with a name that start with '*' will also be changed to use the name '*<macro-extension-task-id>.<original-name>' and all references to '<original-name>' will be transformed to use that qualified name instead. This qualification process ensures that unique Variable names are provided by the Macro Expansion because in the end, there's no such thing as a local Variable.<br />
<br />
Of course Macros themselves can use Macro Expansion tasks, so the process of expansion is recursive. That being said, it's of course invalid for this to lead to a cycle. Cycles are detected by the validator and the expansion process prevents further expansion when a cycle is encountered.<br />
<br />
Note that from the context menu of a Macro Expansion task it's possible to invoke "Inline" to replace a Macro Expansion task with its fully expanded equivalent.<br />
<br />
== Automation and Specialization with Configurations ==<br />
<br />
As of Oomph 1.6, released with Neon.2, there is support for Configurations. A Configuration is not a Scope (is not a container for setup tasks) but rather a container for an Installation and a Workspace; each is optional, but a Configuration with neither is in effect useless. The Installation and Workspace of a Configuration are effectively used as a template to initialize the Installation and Workspace created by the Eclipse Installer, i.e., the setup resources that you can open with Navigate &rarr; Open Setup &rarr; Installation and Navigate &rarr; Open Setup &rarr; Workspace in your IDE. So you can specialize the installation with additional installation-specific tasks, e.g., a p2 task to install additional features, and you can specialize the workspace with workspace-specific tasks, e.g., a variable task to specify the value of a variable so you won't be prompted for that value. <br />
<br />
Configurations are not only useful for specifying installation-specific and workspace-specific tasks but also for automating the selection process in the setup wizards, including the installer. The Configuration's Installation can reference a specific Product Version and the Configuration's Workspace can optionally reference several specific Project Streams. Both the simple mode and the advanced mode of the installer support dragging and dropping a Configuration to the title area. You can drag to the title area either a file (i.e., a file from the file system or from an Eclipse IDE), a URL (i.e., a link from a browser), or a copy of a Configuration's XMI serialization. This will '''apply''' the Configuration to the wizard with the effect that the Installation's Product Version is selected in the wizard and the wizard advances to the next page. Similarly, the Workspace's Project Streams are selected in the wizard and the wizard advances to the next page. If you apply a Configuration with a Workspace to the simple mode of the installer, you will be prompted to switch to advanced mode because only the advanced mode supports Project selection. So in simple mode, applying a Configuration advances to the final page, and in advanced mode, applying a Configuration with an Installation and a Workspace advances to the Variables page.<br />
<br />
As an alternative to drag and drop support, rather than dragging a file, link, or XMI serialization, you can copy it to the clipboard and apply the clipboard contents to the wizard. In simple mode this is done via the Apply Configuration menu item. In advanced mode this is done via the Apply Configuration toolbar button on the Product or Project page; the menu item or toolbar item is visible only if the clipboard contains applicable content.<br />
<br />
The installer application supports command line arguments so you could also specify a Configuration's file path or URL link on the command line to apply it automatically.<br />
<br />
=== Creating a Configuration ===<br />
<br />
The simplest way to create a new Configuration is from the context menu of the folder where want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Configuration Model in the wizard. You can then edit the new Configuration with the Setup Editor. You can delete the Installation or Workspace if you don't need that aspect. You can use the Properties view to set the Installation's Product Version or the Workspace's Project Streams. And of course you can create any other setup tasks in either Scope.<br />
<br />
=== Configuration Handling ===<br />
<br />
The specific form of the serialized URLs that are used to reference a Product Version or a Project Stream are very important to correct behavior. Relative URLs in the serialization can only work relative to the location of the Configuration's resource, so will only work when you drag and drop a file or link because a dragging and dropping textual copy of the serialization provides no information about how to resolve relative references. This is not to say there is anything wrong with relative references, just be aware that they imply that the user must apply the overall file or link, not just the textual serialization. <br />
<br />
Another very useful aspect of Configurations is that the wizards handle of the references intelligently. I.e., if a Installation references a Product Version that's not in any Product Catalog in the Index, the Product will automatically be added to the user-extensible Product Catalog. If the Installation references a Product Version via its containing Product Catalog and that Product Catalog is not in the Index, and the redirectable Product Catalog is not already redirected, it will be redirected to the referenced Product Catalog and an appropriate Eclipse Ini redirection tasks will be synthesized so that the installation produced by the installer will be able to resolve the Product Version reference in its Installation via the correct containing Product Catalog. Analogous processing is done for the Project Stream references with the additional processing of Project's a logical Project container which determines which Project Catalog's extensible Project container is used. In other words, Configurations can also be used to automate the addition of Products and Projects to the user extensible catalogs.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Getting Early Feedback ===<br />
Why didn't the model editor tell me earlier that I've made a silly mistake?<br />
Please enable Live Validation in the editor menu to get early feedback.<br />
Also make use of the Outline view because it provides a preview of the tasks that will be executable and will diagnose problems such as undeclared variables, e.g., using <tt>${foo.bar}</tt> but not having a corresponding variable declaration for <tt>foo.bar</tt>.<br />
<br />
=== Testing a Setup in a Clean Environment ===<br />
<br />
Over time, many or most of your prompted variables will be saved in the user.setup.<br />
To test your setup in an environment that simulates what a brand new user will experience, you can launch the installer as follows:<br />
<br />
<eclipse-inst-executable> -vmargs -Duser.home=<absolute-user-home-folder> -Doomph.setup.user.home.redirect=true<br />
<br />
This also works for the self-extracting native Windows executable as well as for the eclipse-inst executable in extracted Eclipse Installer's folder. <br />
The value <tt><absolute-user-home-folder></tt> of the system property <tt>user.home</tt> should be an absolute path what will become the user home folder; it will be created if it doesn't exist.<br />
The value <tt>true</tt> of the system property <tt>oomph.setup.user.home.redirect</tt> will direct the installer to include the <tt>-Duser.home=<absolute-user-home-folder></tt> argument in the eclipse.ini of the created installation so that it too behaves as if that folder were its user home folder.<br />
<br />
In this fashion you can test in a clean environment and you can discard <tt><absolute-user-home-folder></tt> without impacting your real environment.<br />
<br />
=== Copying Tasks and Other Elements ===<br />
The Setup Editor supports the export and import of any model elements by using copy to or paste from the clipboard. The clipboard will/must contain a valid XML document. With this method, for example, you can easily copy task snippets from your model directly into a forum post when you ask for help (or into a Skype window when you chat with your collegues). Or you can easily paste such XML snippets from forum replies directly into your Setup Editor.<br />
<br />
You have access to many example setups from within your IDE! Use Navigate->Open Setup->Parent Models->Open Catalog Index to investigate everything within the index. The context menu provides a way to open elements in a text editor. This is particularly handy for finding out where a particular setup is hosted (hrefs are resolved in the Setup editor) - one use case is checking and repairing links to project setups added to your user projects.<br />
<br />
=== Hosting your own index / catalogs ===<br />
If you want to host your own product or project catalog, you must provide a URI mapping to the installer to locate the root setup file (the "index"). Open the eclipse.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, or use the wizard to create it. 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/. You can redirect to your own index with this redirection system property:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->http://<hostname>/<path>/</nowiki><br />
<br />
The source URI may be abbreviated to <nowiki>index:/</nowiki> and the target URI may also be a file URI, e.g. on a shared file server.<br />
<br />
In general it will be highly desirable to archive your setup, but documentation for that is TBD. The installer and other setup wizards support dragging and dropping an index or archived index onto the title area of the dialog. Documentation for that is also TBD.<br />
<br />
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=481580 Bug 481580] has introduced empty redirectable catalogs for products ('''redirectable.products.setup''') and projects ('''redirectable.projects.setup''') to the Oomph index. These allow providing your own catalogs without replacing the entire index or disabling the catalogs shipped with Oomph (by redirecting them). The following steps are necessary to make use of those setups.<br />
* Create your own project catalog setup file using the wizard. Project setups in the project catalog should typically be referenced using absolute URIs, otherwise redirection can become problematic. However, if the relative references are downward pointing to some uniquely named folder different from any of the file/folder names in the Eclipse.org index, i.e., no '''..''' traversal to the parent folder is involved and some folder name '''<my-projects-folder>''', then they will be resolved to absolute URIs of the form '''index:/<my-projects-folder>/<path>''' which can be handled as described below.<br />
* Add a redirection system property similar to that described above to the eclipse.ini file, e.g., '''-Doomph.redirection.myProjectCatalog=index:/redirectable.projects.setup->...'''.<br />
* If the projects in that catalog are referenced by relative downward references with a unique folder, also add a folder redirection system property, e.g.,'''-Doomph.redirection.myProjectCatalog=index:/<my-projects-folder>/->.../''', to redirect the locations of the referenced projects to the folder where they are physically hosted.<br />
* Your catalog setup file must contain an Eclipse Ini task creating the same redirection(s)! Otherwise your catalog (or the referenced projects) will not be visible in the Eclipse created by the installer and hence the projects selected from it cannot be provisioned.<br />
* The first time, you may have to enable your new catalog by selecting it in the folders icon of the drop-down in the upper right hand corner of the wizard's Projects page, otherwise it will be invisible.<br />
<br />
To debug the processing of -Doomph.redirection.* if needed, set a breakpoint in org.eclipse.oomph.setup.internal.core.util.SetupCoreUtil.configureResourceSet(ResourceSet) within if (((String)key).startsWith(SetupProperties.PROP_REDIRECTION_BASE)).<br />
<br />
=== Shipping your own index ===<br />
If you want to include your own product or project catalog, you may ship the root setup file (the "index") relative to the installer directory. Then you can redirect the index as explained in [[#Hosting your own index / catalogs| Hosting your own index / catalogs]]. For example, you can place all setup files in an eclipse-installer/setups/ folder and then redirect access to it with a relative target URI:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->setups/</nowiki><br />
<br />
Note that shipping the index rather than maintaining it in a central location (accessible to all parties interested) has the following disadvantage. As each user has her own copy of the index, updates in the setup files will not be distributed automatically.<br />
<br />
=== Accessing Setups that Require Authentication ===<br />
<br />
If basic authentication is used to access a setup, Oomph will generally prompt for the credentials and offer to store it in secure storage for future reuse, <br />
but only if the host responds with authorization request.<br />
Some hosts do not do so for security reasons, i.e., to hide the fact that anything exists at the specified URI.<br />
In that case you will need to specify the URI in such a way that directs Oomph to use basic authentication<br />
<br />
https://example.org/owner/repo/raw/master/path/Example.setup?oomph_basic_auth=true<br />
<br />
If form-based authentication is required, you will need to specify the URI to access the setup in such a way that it directs Oomph to the appropriate login/sign-in form <br />
in order to acquire the necessary cookies for an authenticated session.<br />
<br />
https://gitlab-example.com/project/raw/branch/repo-path/Example.setup?oomph_form=b%27users/sign_in%27#/<br />
https://github.com/ower/repo/raw/master/path/Example.setup?oomph_form=b'login'#/<br />
<br />
In this case too, Oomph will then prompt for the credentials and post them to the form.<br />
<br />
I show the %27 as an alternative to ' because if you provide the link to the setup via a web page, the process of copying the link might convert to that form, even if you've used ' rather than the equivalent %27 encoding of it.<br />
<br />
You can "debug" how this works using org.eclipse.oomph.setup.internal.core.util.ECFURIHandlerImpl.Main.main(String[]) in the org.eclipse.oomph.setup.core bundle. <br />
Currently around [https://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.setup.core/src/org/eclipse/oomph/setup/internal/core/util/ECFURIHandlerImpl.java#n2124 here].<br />
<br />
=== Generating PDE Target Definition files (*.target) and their use by Tycho ===<br />
<br />
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. <br />
<br />
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:<br />
<br />
<annotation<br />
source="http:/www.eclipse.org/oomph/targlets/TargetDefinitionGenerator"><br />
<detail<br />
key="location"><br />
<value>${git.clone.location}/targetdefinition/DesignStudio.target</value><br />
</detail><br />
<detail<br />
key="extraUnits"><br />
<value>org.eclipse.equinox.executable.feature.group</value><br />
</detail><br />
<detail<br />
key="includeAllPlatforms"><br />
<value>false</value><br />
</detail><br />
<detail<br />
key="includeSource"><br />
<value>true</value><br />
</detail><br />
<detail<br />
key="generateVersions"><br />
<value>true</value><br />
</detail><br />
</annotation><br />
<br />
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.<br />
<br />
''TODO Document what preferredRepositories, PomModulesUpdater & PomArtifactUpdater do...''<br />
<br />
=== Setting up WST Server Runtime and Instances in your Setup ===<br />
<br />
==== Server Runtime Preference ====<br />
<br />
1. Use an oomphed installation/workspace with preference recorder enabled.<br />
<br />
2. Open your project and user setup editors.<br />
<br />
3. Go to Preferences / Server / Runtime Environments and 'Add' it as usual.<br />
<br />
4. Drag the selected '/instance/org.eclipse.wst.server.core/runtimes' from user to project setup.<br />
<br />
Note: It's unclear if the above actually works. Please see thread https://www.eclipse.org/forums/index.php/t/1086488/ in forum for details.<br />
For some servers there are extension tasks to handle configuration, see below.<br />
<br />
==== Server Instance in Servers View ====<br />
Requires server runtime to be setup first.<br />
<br />
1. Open Servers View and create New server instance and deploy webapps as usual<br />
<br />
2. Optionally open server instance editor and adapt configuration as usual.<br />
<br />
3. Close Eclipse.<br />
<br />
4. Start it again.<br />
<br />
5. Open '.plugins/org.eclipse.wst.server.core/servers.xml' from your workspace/.metadata using a UTF capable editor<br />
<br />
6. Add Resource Creation Task to your setup:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
content="PUT_CONTENT_FROM_SERVERS_XML_INTO_HERE_USING_A_UTF_CAPABLE_EDITOR_AND_OOMPH_DIALOG"<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.wst.server.core/servers.xml"<br />
encoding="UTF-8"><br />
<description>tomcat server integration</description><br />
</setup:ResourceCreationTask><br />
<br />
7. Use the resource task content dialog to put the servers xml content into the task.<br />
<br />
8. Copy "Servers" project from this workspace into a suitable location of your branch checkout and add/commit/push.<br />
<br />
9. Setup project import task that can pick the Servers project up from that committed location.<br />
<br />
That's it. If you want to share it among fellows, be sure to agree on canonical paths for your server installations.<br />
<br />
==== Extension tasks for specific servers ====<br />
<br />
For some servers there are oomph extension tasks that can be used to handle the configuration:<br />
<br />
https://github.com/gratex/oomph-task-server - Tomcat, WebLogic, and WebSphere<br />
<br />
=== Suppress prompt for default workspace already upon very first start ===<br />
<br />
Adjust the SHOW_WORKSPACE_SELECTION_DIALOG property to false via configuration settings org.eclipse.ui.ide.prefs ...<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP MANUAL"<br />
content="MAX_RECENT_WORKSPACES=5&amp;#xD;&amp;#xA;RECENT_WORKSPACES=${workspace.location|property}&amp;#xD;&amp;#xA;RECENT_WORKSPACES_PROTOCOL=3&amp;#xD;&amp;#xA;SHOW_WORKSPACE_SELECTION_DIALOG=false&amp;#xD;&amp;#xA;eclipse.preferences.version=1"<br />
targetURL="configuration:/.settings/org.eclipse.ui.ide.prefs"<br />
encoding="UTF-8"/><br />
<br />
=== Open default perspective already upon very first start ===<br />
Examples below using Perspective ID for Java perspective.<br />
<br />
Tell Eclipse which perspective to open initially, by adding option to eclipse ini:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:EclipseIniTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP"<br />
option="-perspective"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
Setting a perspective to be default, by adding preference task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:PreferenceTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
key="/instance/org.eclipse.ui/defaultPerspectiveId"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
=== How to switch the current stream ===<br />
<br />
If you would like to switch the current stream/s, you can re-use Oomph's initial "Eclipse Importer" wizard, available as "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace.<br />
<br />
Note that it is currently not yet possible to remove the "current" project stream. As a workaround, use menu Navigate > Open Setup > Open Workspace (or if visible click the 'blue guy' icon in the Oomph toolbar) to Open Workspace workspace.setup, expand the first node, click on the Workspace entry, open Properties view, and change the last property named "Streams" and remove the current stream.<br />
<br />
Bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=476434 enhancement may make this easier in the future.<br />
<br />
<br />
=== How to install Eclipse plugins using the P2 Director and Repository Explorer ===<br />
<br />
Oomph can install Eclipse plugins which you require. This also works for normal Java Projects set up models, not just for Eclipse plug in OSGi development, and is handy to install commonly used 3rd-party Eclipse plugins which are not all available from eclipse.org p2 sites (think e.g. http://eclemma.org). Here's how:<br />
<br />
1. add a P2 Director child task to your *.setup, if it doesn't already have one<br />
<br />
2. add a Repository child in your P2 Director task<br />
<br />
3. in the Properties of the Repository set the URL to a valid p2 repo (e.g. http://update.eclemma.org)<br />
<br />
4. right-click that Repository and choose Explore, to open the Repository Explorer view<br />
<br />
5. in the Repository Explorer view change to [X] Compatible and (*) Minor at the lower-right hand corner<br />
<br />
6. drag & drop the version from the Repository Explorer view into the P2 Director task of your *.setup editor, to create a Requirement child<br />
<br />
Drag & Drop should normally work, but appears to be broken at least on Neon Milestone 6 on Linux; in that case:<br />
<br />
6. manually create a new child Requirement inside the P2 Director task<br />
<br />
7. in the Repository Explorer view use the brown (C) icon to switch to Expert Mode to see IDs instead of names<br />
<br />
8. find the ID of the feature IU, it's the one with a PDE feature + folder kind of icon, often ending in (feature.)feature.group<br />
<br />
9. in the Properties of the Requirement, type the Name to the ID found above (e.g. com.mountainminds.eclemma.feature.feature.group)<br />
<br />
10. in the Properties of the Requirement, Type should have automatically switched to Feature<br />
<br />
PS: If you are looking for the URL of p2 repos to pre-install some of the the M2E connectors, see https://git.eclipse.org/c/m2e/m2e-discovery-catalog.git/tree/org.eclipse.m2e.discovery.oss/connectors.xml<br />
<br />
<br />
<br />
=== How to create M2E lifecycle-mapping-metadata.xml to avoid littering your pom.xml with org.eclipse.m2e:lifecycle-mapping ===<br />
<br />
Read https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html & https://wiki.eclipse.org/M2E_compatible_maven_plugins and apply as follows:<br />
<br />
<setupTask<br />
xsi:type="setup:PreferenceTask"<br />
key="/instance/org.eclipse.m2e.core/eclipse.m2.WorkspacelifecycleMappingsLocation"<br />
value="${workspace.location}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"/><br />
<br />
<setupTask<br />
xsi:type="setup:ResourceCreationTask"<br />
content="..."<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"<br />
encoding="UTF-8"><br />
<description>Initialize M2E's Maven Lifecycle Mappings, see https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html &amp; https://wiki.eclipse.org/M2E_compatible_maven_plugins</description><br />
</setupTask><br />
<br />
For "content" just open the popup using the [...] icon in the Properties and copy/paste the content from menu Window > Preferences > Maven > Lifecycle Mappings: Open workspace lifecycle mappings metadata. (This is easier than editing the content=".." in source view, because it will correctly do the XML escaping for you.)<br />
<br />
Now whenever M2E whines about stuff like "Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-dependency-plugin:2.10:unpack (execution: unpack-license, phase: generate-resources)" etc. just use the Quick Fix in the Problems view and choose the option to use workspace preferences (instead of letting the quick fix modify your pom.xml to add org.eclipse.m2e:lifecycle-mapping <lifecycleMappingMetadata>).<br />
<br />
<br />
=== How to automatically pre-enable Gerrit ===<br />
<br />
If you would like to save your end-users from having to [[EGit/User_Guide#Enabling_Gerrit_for_a_repository|manually enabling Gerrit for a repository in EGit]], then you can use the follow magic variable which Oomph will recognize and act upon:<br />
<br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="YOURORG.gerrit.uri.pattern"<br />
value="(https|ssh)://([^@/]+@)?(git.YOURORG.org:29418/.*|git.YOURORG.org/gerrit/.*)"/><br />
<br />
=== How to find a P2 repository at Eclipse using the Repository Explorer ===<br />
<br />
Most projects don't document the locations of all their p2 update sites very well. This makes it hard to find the URL you need in order to install something or in order to specify a URL for your target platform definition. Oomph indexes all the p2 update sites available at download.eclipse.org to make this job easier. You can make use of this as follows:<br />
<br />
# In the Quick Access control, type "Repository Explorer" to show Oomph's Repository Explorer view.<br />
# In that view's toolbar, locate the tool item with the hover "Search Eclipse repositories by provided capabilities", i.e., the one that looks like a little search flashlight, and click it.<br />
# This brings up the "Eclipse Repository Search" dialog. The index is very large so it takes a while to load it. But it's cached locally and updated on the server once per day.<br />
# At the root of the displayed tree are p2's namespaces and under each of these are the capabilities in that namespace. They're organized hierarchically by their qualified name. It's all quite technical and the tree is very large. So while you can explore it, you'll most likely want to use the filter to find something quickly.<br />
# Type the fully qualified name of a Java package or installable unit you wish to locate into the filter. Note that tree items for which there exist a concrete version in some repository are decorated as such. Keep in mind that many projects don't version their Java packages, so it's often better to look at the org.eclipse.equinox.p2.iu category. Here's what it looks like searching for "org.eclipse.emf.ecore.xcore":<br>[[File:SearchEclipseRepositoryDialog.png]]<br><br />
# You can select a capability in the tree so that the lower panel displays all the versions of the capability that are available. Under each of those are nested the update sites that contain them. Composite update sites show their children hierarchically.<br />
# Of course you can double click a repository to further explore its contents in the Repository Explorer itself.<br />
<br />
<br />
=== How to extract the constituent parts that comprise the Windows self-extracting installer executable ===<br />
<br />
The Eclipse Installer distribution for the Windows platform is effectively a self-extracting executable. It is extracted at runtime by the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINExtractor.java Bin Extractor]. The pre-built version of this library, i.e., org.eclipse.oomph.extractor.lib-*.jar, is available in all Oomph-containing installations, i.e., in the installer itself and in applications installed by the installer. This library can also be used standalone to decompose the composed executable into its constituent parts. That can be accomplished if you run it with the correct magical program arguments as follows:<br />
<br />
java -classpath <path-to-extract-lib>\org.eclipse.oomph.extractor.lib-*.jar<br />
org.eclipse.oomph.extractor.lib.BINExtractor <br />
<path-to-executable-to-extract>\eclipse-inst-win64.exe <br />
<target-path>\product.zip <br />
-export <br />
<target-path>\marker.txt <br />
<target-path>\extractor.exe <br />
<target-path>\org.eclipse.oomph.extractor.lib.jar <br />
<target-path>\product-descriptor<br />
<br />
The Java VM arguments need only specify the extractor library along with the main class in that library. The first program argument is the location of the executable you wish to decompose, the 64 bit installer in this case. The remaining arguments are all best directed into a common folder, denoted as <target-path> in the example above. The second argument is the extracted location of the zip file of the product/distribution. The third argument is the -export flag. The fourth argument is the extracted location of the text file containing the marker text that is used to delimit the constituent parts of the composed executable. The fifth argument is the extracted location of the small native executable itself. The sixth argument is the extracted location of the extractor library, the same one being used to extract the parts. The seventh and final argument is the extracted location of the product descriptor. Such a [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINDescriptor.java descriptor] looks like this:<br />
<br />
1<br />
1<br />
7<br />
0<br />
64<br />
0<br />
eclipse-inst.exe<br />
eclipse-inst.ini<br />
Eclipse Installer<br />
http://wiki.eclipse.org/Eclipse_Installer<br />
http://download.eclipse.org/oomph/jre/128x128.png<br />
<br />
Of course you can edit these parts and then you can recompose the executable using the following cmd script executed within the common folder in which you have extracted the constituent parts:<br />
<br />
COPY /B extractor.exe + ^<br />
marker.txt + ^<br />
org.eclipse.oomph.extractor.lib.jar + ^<br />
marker.txt + ^<br />
product-descriptor + ^<br />
marker.txt + ^<br />
product.zip + ^<br />
marker.txt ^<br />
eclipse-inst-64.exe<br />
<br />
Our builds use the [https://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/releng/org.eclipse.oomph.releng/hudson/postprocess.sh postprocess.sh] to do this processing.<br />
One issues that's important in terms of signing, is that the extractor.exe that you've extracted above will already contain a signature and this might well cause signing of the composed executable fail. So our script actually uses the following to fetch the executable from Git:<br />
<br />
curl -O https://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/plugins/org.eclipse.oomph.extractor/extractor-64.exe<br />
<br />
Note that the file names match the extracted target file names. From this is should be clear that the native executable is just a composition of parts. This structure is used at runtime as follows. The extractor.exe runs natively, reading its own executable file, using the marker text to find the parts. It checks the descriptor to determine if an appropriate version of Java is already installed, i.e., one that will be able to launch the product; the native extractor consults the registry to find all installed JREs and JVMs. If an appropriate Java is not found, it opens a browser page prompting the user to install an appropriate Java version with the required bitness and at the minimum required version. If there is already an appropriate version of Java, it launches a Java process to execute the BinExtract's main method. That process in turn unzips the product zip to a temp folder and launches the Java process for that for the product/distribution.<br />
<br />
== Oomph Configuration Options ==<br />
<br />
=== Configuration Options for Installer .ini File ===<br />
<br />
{| class="wikitable"<br />
| '''-Doomph.redirection.setups''' || Redirects the location of setup files (index, catalog and products). The default URI is ''http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/'' and my be abbreviated with '''index:/'''. The syntax of the redirection is '''index:/->[redirection URI]'''. Examples: '''-Doomph.redirection.setups=index:/->http://<hostname>/<path>/''' (external server redirection) or '''-Doomph.redirection.setups=index:/->setups/''' (path relative to installer executable). See also [[#Hosting_your_own_index_.2F_catalogs|Hosting your own index & catalogs]]<br />
|-<br />
| '''-Doomph.setup.product.catalog.filter''' || Only displays product catalogs matching the given prefix. The default is ''org\\.eclipse\\.products''. Displays all catalogs if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.filter''' || Only displays products matching the given prefix. The default is ''(?\!org\\.eclipse\\.products\\.org\\.eclipse\\.platform\\.ide).*''. Displays all products if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.version.filter''' || Only displays product versions matching the given prefix. The default is ''.*\\.neon''. Displays all product versions if value is empty.<br />
|-<br />
| '''-Doomph.p2.pool''' || Set to ''@none'' to disable bundle pools. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=507594] for details.<br />
|}<br />
<br />
== Troubleshooting ==<br />
=== The preference task does not setup any preferences ===<br />
<br />
First of all. Please note that the preferences are not set up as part of the installation. They are setup when the installed eclipse is first started.<br />
<br />
To do this the installed product needs to have the following feature installed:<br />
''org.eclipse.oomph.setup.feature.group''<br />
<br />
The feature is already included in the root of the Eclipse.org Product Catalog. If you are not using it you can include the same task by yourself:<br />
<br />
<setup.p2:P2Task<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup.p2="http://www.eclipse.org/oomph/setup/p2/1.0"><br />
<requirement<br />
name="org.eclipse.oomph.setup.feature.group"/><br />
<repository<br />
url="${oomph.update.url}"/><br />
</setup.p2:P2Task></div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Oomph_Authoring&diff=441477Eclipse Oomph Authoring2020-11-12T13:58:23Z<p>Stepper.esc-net.de: /* Declaring and Using Variables */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
== Getting Started ==<br />
<br />
=== What is Oomph? ===<br />
<br />
Please read [[Eclipse Installer]].<br />
<br />
<br />
=== Installing Oomph ===<br />
<br />
# Download and install the Eclipse '''Installer''' as outlined in [[Eclipse Installer]].<br />
# Make sure that the Oomph setup '''SDK''' is installed in your IDE. Either:<br />
## That's already the case because your IDE is a Mars M5 or later Eclipse Package, or<br />
## Start the installer and install an IDE of your choice (select on the first installer page), or<br />
## Use p2 to install "Oomph Setup SDK" from [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest].<br />
<br />
== Creating a Setup Project Model ==<br />
<br />
=== Using the Setup Project Model Wizard ===<br />
<br />
# Create an empty project in your workspace or select a folder in an existing project. You'll create the new "Setup Project Model" in the selected folder.<br />
# Open the New... dialog and select the "Setup Project Model" wizard:<br>[[Image:new-wizard.png]]<br><br />
# Select one of the provided templates (e.g., Eclipse.org, Github.com, or Simple) and adjust the displayed values:<br>[[Image:new-wizard-2.png]]<br><br />
# Some values are automatically derived from your input to fields '''higher up'''.<br />
# Open the Preview>>> to understand the impact of changes to the current field.<br />
<br />
=== Using the Setup Editor ===<br />
<br />
# Open the resulting setup file with Oomph's Setup Editor:<br>[[Image:setup-edit.png]]<br><br />
# Configure the tasks in the Properties view. Note that there are "Expert" properties available.<br />
# Add setup tasks to your project and/or to your project streams and configure them, too.<br />
# The Outline view displays a ''preview'' of the executable model with resolved variables.<br />
<br />
=== Testing the Setup Model ===<br />
<br />
# To test/execute your new setup model:<br />
## Start the installer and, if necessary, switch to the Advanced Mode via the dialog menu.<br />
## Pick any product on page 1 and click the Next button to proceed to page 2.<br />
## Drag and drop your <tt>.setup</tt> file onto one of the top-level catalogs (<tt>Eclipse.org</tt> or <tt>Github.com</tt>) in the projects tree. Your project will appear as a subproject of the special <tt>&lt;User&gt;</tt> project.<br />
## Double-click your project to add it to the table at the 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.<br />
## Fill in the empty fields and press the Next button to proceed to the Confirmation page.<br />
## 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.<br><br />
# 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 [[#Using the Setup Editor|Using the Setup Editor]]. If the IDE comes up but the initial configuration fails continue with step 3.<br />
# In the new IDE (whether the initial configuration was successful or not) open your model file from the main menu, Navigate &rarr; Open Setup &rarr; [[Image:branch.png]]. Find the problems and fix them. Then start the setup process '''from within''' this IDE via the main menu, Help &rarr; [[Image:update.png]] Perform Setup Tasks&hellip;. 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.<br />
<br />
=== Contributing to a Project Catalog ===<br />
<br />
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 http://git.eclipse.org/c] and [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&bug_severity=enhancement&short_desc=Please%20include%20setup%20for%20project%20Xyz 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.<br />
<br />
The same can be done if your project is not an Eclipse project, but hosted on '''GitHub'''. Simply state this fact in the bug description and paste the "raw" content URL to the file instead.<br />
<br />
== Understanding the Setup Engine ==<br />
<br />
=== Understanding Setup Tasks and Scopes ===<br />
<br />
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:<br />
<br />
* The '''Installation''' scope is located in <tt>eclipse/configuration/org.eclipse.oomph.setup/installation.setup</tt> 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.<br />
<br />
* The '''Workspace''' scope is located in <tt>workspace/.metadata/.plugins/org.eclipse.oomph.setup/workspace.setup</tt> 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.<br />
<br />
* The '''User''' scope is located in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup</tt> and contains tasks that are common to '''all''' installations and workspaces (unless they're restricted to particular installations or workspaces).<br />
<br />
<br />
The following additional scope types exist, so they can be referenced by the entry scopes:<br />
<br />
* The '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.setup Catalog Index]''' is the root scope and contains nested Product Catalogs and Project Catalogs.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.products.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/OomphInstaller.setup Product]''' contains nested Product Version scopes and possibly some tasks that are common to all nested scopes.<br />
<br />
* A '''Product Version''' contains no nested scopes but tasks that are specific to that product version.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.projects.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/Oomph.setup Project]''' contains nested Stream and/or (Sub-) Project scopes and typically some tasks that are common to all nested scopes.<br />
<br />
* A '''Stream''' contains no nested scopes but tasks that are specific to that stream.<br />
<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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 [[#Declaring_and_Using_Variables|Declaring and Using Variables]] below.<br />
<br />
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). <br />
<br />
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.<br />
<br />
=== Declaring and Using Variables ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:<br />
<br />
${''variable-name''}<br />
<br />
To prevent a variable reference from being expanded (e.g. you actually want to have the value '${var}' and not the value of "var"), you need to escape the variable syntax with an extra dollar character. So "$${var}" will result in "${var}".<br />
<br />
In addition to the variables that are declared by VariableTasks you can refer to all of the following:<br />
<br />
* Attribute values of setup tasks with a defined ID. The reference syntax is ${''taskID''.''attributeName''}.<br />
* [[#Predefined Variables|Predefined variables]] as determined by the setup engine from the user input to the installer (see below)<br />
* [[#Environment Variables|Environment variables]] as returned by <tt>System.getenv()</tt><br />
* System properties as returned by <tt>System.getProperties()</tt><br />
<br />
==== Predefined Variables ====<br />
<br />
The following variables are predefined by the setup engine:<br />
<br />
{| class="wikitable"<br />
| '''scope.installation.name''' || The value of the <em>name</em> attribute of the current installation scope. <br />
|-<br />
| '''scope.installation.label''' || The value of the <em>label</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.installation.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.workspace.name''' || The value of the <em>name</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.label''' || The value of the <em>label</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.description''' || The value of the <em>description</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.user.name''' || The value of the <em>name</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.label''' || The value of the <em>label</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.description''' || The value of the <em>description</em> attribute of the current user scope.<br />
|-<br />
| '''scope.product.catalog.name''' || The value of the <em>name</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.label''' || The value of the <em>label</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.description''' || The value of the <em>description</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.name''' || The value of the <em>name</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product scope and its parent scopes.<br />
|-<br />
| '''scope.product.label''' || The value of the <em>label</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.description''' || The value of the <em>description</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.version.name''' || The value of the <em>name</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product version scope and its parent scopes.<br />
|-<br />
| '''scope.product.version.label''' || The value of the <em>label</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.project.catalog.name''' || The value of the <em>name</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.label''' || The value of the <em>label</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.description''' || The value of the <em>description</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.name''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current project scope and its parent scopes.<br />
|-<br />
| '''scope.project.label''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.description''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.stream.name''' || The value of the <em>name</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current stream scope and its parent scopes.<br />
|-<br />
| '''scope.project.stream.label''' || The value of the <em>label</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.description''' || The value of the <em>description</em> attribute of the current stream scope.<br />
|}<br />
<br />
==== Variable Extensions ====<br />
<br />
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.:<br />
<br />
${installation.location/git/myproject} evaluates to C:\develop\installation1\git\myproject on Windows<br />
<br />
<br />
After the path extension part you can add filter calls with pipe symbols. Filter names are generally case-insensitive. Multiple filters can be chained. Example:<br />
<br />
${installation.location|uri}/git/myproject evaluates to file:/C:/develop/installation1/git/myproject<br />
<br />
<br />
==== Variable Filters ====<br />
<br />
The following filters are currently available:<br />
<br />
{| class="wikitable"<br />
| '''base64''' || Encodes the String value to its base64 representation.<br />
|-<br />
| '''basePath''' || Removes the last segment from a file system path.<br />
|-<br />
| '''camel''' || Converts a qualified name to camel case notation.<br />
|-<br />
| '''canonical''' || Canonicalizes a file system path.<br />
|-<br />
| '''cap''' || Capitalizes the first word of a String value.<br />
|-<br />
| '''capAll''' || Capitalizes all words of a String value.<br />
|-<br />
| '''file''' || Converts a file: URI to an OS-specific file system path.<br />
|-<br />
| '''fileExtension''' || Extracts the file extension from a URI or a file system path.<br />
|-<br />
| '''gitRepository''' || Extracts the name of the repository from a Git URI (excluding a possible .git suffix).<br />
|-<br />
| '''lastSegment''' || Extracts the last segment from a file system path.<br />
|-<br />
| '''length''' || Converts a String to a String that contains the alpha-numerical representation of the length of the original String.<br />
|-<br />
| '''lower''' || Converts all characters of a String value to lower-case.<br />
|-<br />
| '''not''' || The boolean logical negation, i.e., 'false' if the value is 'true', and 'true' if the value is 'false' (or anything else).<br />
|-<br />
| '''path''' || Converts all \ characters of a String value, typically a file system path, to /.<br />
|-<br />
| '''pathEncode''' || Converts a file system path to a String value that can be used as a file name.<br />
|-<br />
| '''patternQuote''' || Quotes regular-expression constructs in the String value such that the result can be used as a literal string in patterns.<br />
|-<br />
| '''preferenceNode''' || Escapes all forward slashes (/) of a String value, so that the result can be used as a value in preference nodes.<br />
|-<br />
| '''property''' || Escapes all double back slashes (\\) of a String value, so that the result can be used as a value in properties.<br />
|-<br />
| '''propertyValue''' || Interprets the String value as a preference property path and returns the value of that property.<br />
|-<br />
| '''qualifiedName''' || Converts a camel case String value name to a qualified name.<br />
|-<br />
| '''slashDecode''' || Decodes a slashEncoded String value.<br />
|-<br />
| '''slashEncode''' || Encodes all slashes and backslashes of a String value.<br />
|-<br />
| '''trim''' || Removes all whitespace from the beginning and the end of a String.<br />
|-<br />
| '''trimLeft''' || Removes all whitespace from the beginning of a String.<br />
|-<br />
| '''trimRight''' || Removes all whitespace from the end of a String.<br />
|-<br />
| '''trimTrailingSlashes''' || Removes all slashes and backslashes from the end of a String.<br />
|-<br />
| '''upper''' || Converts all characters of a String value to upper-case.<br />
|-<br />
| '''uri''' || Converts a file system path to a file: URI.<br />
|-<br />
| '''uriLastSegment''' || Extracts the last path segment from a hierarchical URI or the authority from an opaque URI.<br />
|-<br />
| '''urlDecode''' || Decodes a URL.<br />
|-<br />
| '''urlEncode''' || URL-encodes a String value.<br />
|-<br />
| '''username''' || Escapes all "at" symbols (@) of a String value, so that the result can be used in URI that contain a username.<br />
|}<br />
<br />
You can also define your own custom variable filters by contributing to the extension point <tt>org.eclipse.oomph.setup.core.stringFilters</tt>.<br />
<br />
==== Variables from Outer Scopes====<br />
<br />
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:<br />
<br />
* '''jre.location-1.4''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.5''' --> The folder containing a 1.5 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.6''' --> The folder containing a 1.6 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.7''' --> The folder containing a 1.7 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.8''' --> The folder containing a 1.8 compatible JDK/JRE for architecture ${os.arch}<br />
* '''git.user.id''' --> The Eclipse user ID for Git/Gerrit commits<br />
* '''git.author.name''' --> The Eclipse author name for Git/Gerrit commits<br />
* '''git.author.email''' --> The Eclipse author email for Git/Gerrit commits<br />
* '''bugzilla.id''' --> The Eclipse user ID for Bugzilla/Hudson<br />
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson<br />
<br />
<br />
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.<br />
<br />
==== Environment Variables ====<br />
<br />
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.<br />
<br />
=== Conditional Tasks ===<br />
<br />
All setup tasks support filters. Oomph reuses [https://wiki.eclipse.org/Equinox_P2_Resolution#Enablement_filter p2's implementation] of LDAP filters. I.e., it supports a string a representation of LDAP Search Filters, RFC 1960, UMich, 1996,<br />
http://www.ietf.org/rfc/rfc1960.txt<br />
<br />
The filter property of a setup task is an advanced property. To display this property, ensure that the "Show Advanced Properties" is enabled in the Properties view tool bar. The properties of a filter expression can generally refer to any system property or any environment variable. For example, the following filter expression on a task will ensure that it is included only when performing a task on a Linux operating system.<br />
<br />
(osgi.os=linux)<br />
<br />
The latest version of Oomph allows filter properties to refer to the values of variables as defined in the setup itself. For example, this idiom can be used to express if-then-else.<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xmi:XMI xmi:version="2.0"<br />
xmlns:xmi="<nowiki>http://www.omg.org/XMI</nowiki>"<br />
xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"<br />
xmlns:setup="<nowiki>http://www.eclipse.org/oomph/setup/1.0</nowiki>"><br />
<setup:VariableTask<br />
type="BOOLEAN"<br />
name="example.filter"<br />
label="Example Filter"><br />
<description>An example of a variable used to conditionally filter tasks</description><br />
</setup:VariableTask><br />
<setup:CompoundTask<br />
filter="(example.filter=true)"<br />
name="Filter True"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.a"<br />
label="Property A"><br />
<description>The value use for system.property.a</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.a"<br />
value="=${example.variable.a}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is true</description><br />
</setup:CompoundTask><br />
<setup:CompoundTask<br />
filter="(example.filter=false)"<br />
name="Filter False"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.b"<br />
label="Property B"><br />
<description>The value used for system.property.b</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.b"<br />
value="=${example.variable.b}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is false.</description><br />
</setup:CompoundTask><br />
</xmi:XMI><br />
<br />
On the Variables page of the setup wizards, any variable that is used in property of a filter will be displayed in bold. It is significant to note that the value of a so-called filter variable can conditionally affect the presence of other variables. In this example, either variable <code>example.variable.a</code> or <code>example.variable.b</code> (but not both) will be present on the Variables page, depending on the value of the <code>example.filter</code> variable, which is displayed as a checkbox because it is of type <code>BOOLEAN</code>.<br />
<br />
Note that Oomph setup editors support textual copy and paste, so you can copy the above XML and paste it into your setup editor to try it out.<br />
<br />
== Macros and Macro Expansion Tasks ==<br />
<br />
As of Oomph 1.13, released with Eclipse 2019-06, there is support for Macros. A Macro is a Scope, i.e., is a container for setup tasks, and can specify 0 or more Parameters. Each Parameter specifies a name, a description, and optionally a default value. The parameter names can be used as variable references in the setup tasks contained by the Macro.<br />
<br />
=== Creating a Macro ===<br />
<br />
The simplest way to create a new Macro is from the context menu of the folder where you want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Macro Model in the wizard. You can then edit the new Macro with the Setup Editor. You can create Parameters, if desired, and of course you can create any other setup tasks.<br />
<br />
Here is an example of how one could use a Macro for creating a Git Clone task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Macro<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:git="http://www.eclipse.org/oomph/setup/git/1.0"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
xsi:schemaLocation="http://www.eclipse.org/oomph/setup/git/1.0 http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/models/Git.ecore"<br />
name="git.clone"<br />
label="Git Clone"><br />
<setupTask<br />
xsi:type="git:GitCloneTask"<br />
id="git.clone"<br />
remoteName="${remoteName}"<br />
remoteURI="${remoteURI}"<br />
pushURI="${pushURI}"<br />
checkoutBranch="${checkoutBranch}"><br />
<annotation<br />
source="http://www.eclipse.org/oomph/setup/FeatureSubstitution"><br />
<detail<br />
key="restrictToCheckoutBranch"><br />
<value>${restrictToCheckoutBranch}</value><br />
</detail><br />
<detail<br />
key="recursive"><br />
<value>${recursive}</value><br />
</detail><br />
</annotation><br />
<description>${description}</description><br />
</setupTask><br />
<description>The GitClone macro provides a template for creating a clone task</description><br />
<parameter<br />
name="description"><br />
<description>The description of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="pushURI"><br />
<description>The push URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="recursive"<br />
defaultValue="false"><br />
<description>Whether submodules should be recursively cloned</description><br />
</parameter><br />
<parameter<br />
name="remoteName"<br />
defaultValue="origin"><br />
<description>The name of the remote</description><br />
</parameter><br />
<parameter<br />
name="remoteURI"><br />
<description>The remote URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="restrictToCheckoutBranch"<br />
defaultValue="false"><br />
<description>Whether the clone should be restricted to clone only the checkout branch</description><br />
</parameter><br />
<parameter<br />
name="checkoutBranch"><br />
<description>The name of the branch that the Git clone task to checks out</description><br />
</parameter><br />
</setup:Macro><br />
<br />
Special support is provided for defining so called local Variables in a Macro. Any Variable with a name that starts with '*' will be handled in a special way during [[#Macro Expansion Processing|Macro Expansion]].<br />
<br />
=== Using a Macro with a Macro Expansion Task ===<br />
<br />
To use a Macro you must create a Macro Expansion task. The easiest way to do this is to drag the resource containing the Macro and then drop it into the Setup Editor where you want to use it. Similarly, if you want to use a Macro defined in the internet, you can use Load Resource... from the Setup Editor's context menu to load the Macro into the editor's resource set (or drag the link and drop it into the editor). Note that Macros available in the resource set are always shown in the Outline view. Once the Macro is available in the editor's resource set, or in the Outline, you can drag and drop the Macro anywhere that any other setup task can be created. This will create a Macro Expansion task that binds to the Macro.<br />
<br />
A Macro Expansion task must specify an ID, which of course must be unique within the containing resource. The ID is used during [[#Macro Expansion Processing|Macro Expansion Processing]]. Via drag and drop, an ID is automatically assigned, but you'll likely want to change it. A Macro Expansion task can supply Arguments to bind the values of the Parameters of the Macro. For every Parameter without a default value there must be a corresponding Argument to bind its value. The validator will complain when that's not the case, so be sure to enable Live Validation via the context menu. When creating a Macro Expansion task using drag and drop, the required Arguments are automatically created. Of course you'll want to change the generated values; you can delete any Arguments for which the Parameter specifies the default value that you wish to just use. You can change the Argument's value by double clicking the Argument to ensure that it's visible in the Properties view, and can then edit the Value property of the Argument there. The description of the corresponding Parameter is displayed in the Properties view after the Parameter's name. This is why it's important to include a description for each Parameter so that the author using the Macro knows how the Argument's value will be used by that Macro.<br />
<br />
The setup editor displays the Macro referenced by a Macro Expansion task as a child item, in light brown, in the tree view, so you can fully explore the Macro being used. In addition a Preview item is displayed, in light blue, to show how the Macro Expansion task will be expanded. And of course the Outline view allows you to preview all of the tasks that will be performed when you run the installer later.<br />
<br />
Here is an example of how the above Macro could be used by a Macro Expansion task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Project<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
name="sample.project"<br />
label="SampleProject"><br />
<setupTask<br />
xsi:type="setup:MacroTask"<br />
id="my"<br />
macro="GitCloneMacro.setup#/"><br />
<argument<br />
name="description"<br />
value="description_value"/><br />
<argument<br />
name="pushURI"<br />
value="pushURI_value"/><br />
<argument<br />
name="recursive"/><br />
<argument<br />
name="remoteName"/><br />
<argument<br />
name="remoteURI"<br />
value="remoteURI_value"/><br />
<argument<br />
name="restrictToCheckoutBranch"/><br />
<argument<br />
name="checkoutBranch"<br />
value="master"/><br />
</setupTask><br />
<stream name="stream"/><br />
<logicalProjectContainer<br />
xsi:type="setup:ProjectCatalog"<br />
href="index:/org.eclipse.setup#//@projectCatalogs[name='org.eclipse']"/><br />
<description>SampleProject provides cool stuff.</description><br />
</setup:Project><br />
<br />
Note that here we have several Arguments without a value. Those could be deleted or a value (presumably different from the default value of the Parameter) could be specified. Also note that a well-formed Argument can only bind to a Parameter of the containing Macro Expansion task's Macro, so the serialization is simplified to specify just the name of the bound Parameter in this case.<br />
<br />
=== Macro Expansion Processing ===<br />
<br />
A Macro Expansion task is expanded to a Compound Setup Task as illustrated by the Preview item. Each Argument is bound to its corresponding Parameter via a local variable of the form '*<macro-expansion-task-id>.<parameter-name>'. Every variable reference to the Parameter name is transformed to use this Variable's more-qualified name instead. Every setup task with an ID is transformed to specify instead a qualified ID of the form '<macro-expansion-task-id>.<original-id>' and every variable reference that's prefixed by '<original-id>.' will be transformed to use the more-qualified prefix instead. In addition, any Variable contained by the Macro with a name that start with '*' will also be changed to use the name '*<macro-extension-task-id>.<original-name>' and all references to '<original-name>' will be transformed to use that qualified name instead. This qualification process ensures that unique Variable names are provided by the Macro Expansion because in the end, there's no such thing as a local Variable.<br />
<br />
Of course Macros themselves can use Macro Expansion tasks, so the process of expansion is recursive. That being said, it's of course invalid for this to lead to a cycle. Cycles are detected by the validator and the expansion process prevents further expansion when a cycle is encountered.<br />
<br />
Note that from the context menu of a Macro Expansion task it's possible to invoke "Inline" to replace a Macro Expansion task with its fully expanded equivalent.<br />
<br />
== Automation and Specialization with Configurations ==<br />
<br />
As of Oomph 1.6, released with Neon.2, there is support for Configurations. A Configuration is not a Scope (is not a container for setup tasks) but rather a container for an Installation and a Workspace; each is optional, but a Configuration with neither is in effect useless. The Installation and Workspace of a Configuration are effectively used as a template to initialize the Installation and Workspace created by the Eclipse Installer, i.e., the setup resources that you can open with Navigate &rarr; Open Setup &rarr; Installation and Navigate &rarr; Open Setup &rarr; Workspace in your IDE. So you can specialize the installation with additional installation-specific tasks, e.g., a p2 task to install additional features, and you can specialize the workspace with workspace-specific tasks, e.g., a variable task to specify the value of a variable so you won't be prompted for that value. <br />
<br />
Configurations are not only useful for specifying installation-specific and workspace-specific tasks but also for automating the selection process in the setup wizards, including the installer. The Configuration's Installation can reference a specific Product Version and the Configuration's Workspace can optionally reference several specific Project Streams. Both the simple mode and the advanced mode of the installer support dragging and dropping a Configuration to the title area. You can drag to the title area either a file (i.e., a file from the file system or from an Eclipse IDE), a URL (i.e., a link from a browser), or a copy of a Configuration's XMI serialization. This will '''apply''' the Configuration to the wizard with the effect that the Installation's Product Version is selected in the wizard and the wizard advances to the next page. Similarly, the Workspace's Project Streams are selected in the wizard and the wizard advances to the next page. If you apply a Configuration with a Workspace to the simple mode of the installer, you will be prompted to switch to advanced mode because only the advanced mode supports Project selection. So in simple mode, applying a Configuration advances to the final page, and in advanced mode, applying a Configuration with an Installation and a Workspace advances to the Variables page.<br />
<br />
As an alternative to drag and drop support, rather than dragging a file, link, or XMI serialization, you can copy it to the clipboard and apply the clipboard contents to the wizard. In simple mode this is done via the Apply Configuration menu item. In advanced mode this is done via the Apply Configuration toolbar button on the Product or Project page; the menu item or toolbar item is visible only if the clipboard contains applicable content.<br />
<br />
The installer application supports command line arguments so you could also specify a Configuration's file path or URL link on the command line to apply it automatically.<br />
<br />
=== Creating a Configuration ===<br />
<br />
The simplest way to create a new Configuration is from the context menu of the folder where want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Configuration Model in the wizard. You can then edit the new Configuration with the Setup Editor. You can delete the Installation or Workspace if you don't need that aspect. You can use the Properties view to set the Installation's Product Version or the Workspace's Project Streams. And of course you can create any other setup tasks in either Scope.<br />
<br />
=== Configuration Handling ===<br />
<br />
The specific form of the serialized URLs that are used to reference a Product Version or a Project Stream are very important to correct behavior. Relative URLs in the serialization can only work relative to the location of the Configuration's resource, so will only work when you drag and drop a file or link because a dragging and dropping textual copy of the serialization provides no information about how to resolve relative references. This is not to say there is anything wrong with relative references, just be aware that they imply that the user must apply the overall file or link, not just the textual serialization. <br />
<br />
Another very useful aspect of Configurations is that the wizards handle of the references intelligently. I.e., if a Installation references a Product Version that's not in any Product Catalog in the Index, the Product will automatically be added to the user-extensible Product Catalog. If the Installation references a Product Version via its containing Product Catalog and that Product Catalog is not in the Index, and the redirectable Product Catalog is not already redirected, it will be redirected to the referenced Product Catalog and an appropriate Eclipse Ini redirection tasks will be synthesized so that the installation produced by the installer will be able to resolve the Product Version reference in its Installation via the correct containing Product Catalog. Analogous processing is done for the Project Stream references with the additional processing of Project's a logical Project container which determines which Project Catalog's extensible Project container is used. In other words, Configurations can also be used to automate the addition of Products and Projects to the user extensible catalogs.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Getting Early Feedback ===<br />
Why didn't the model editor tell me earlier that I've made a silly mistake?<br />
Please enable Live Validation in the editor menu to get early feedback.<br />
Also make use of the Outline view because it provides a preview of the tasks that will be executable and will diagnose problems such as undeclared variables, e.g., using <tt>${foo.bar}</tt> but not having a corresponding variable declaration for <tt>foo.bar</tt>.<br />
<br />
=== Testing a Setup in a Clean Environment ===<br />
<br />
Over time, many or most of your prompted variables will be saved in the user.setup.<br />
To test your setup in an environment that simulates what a brand new user will experience, you can launch the installer as follows:<br />
<br />
<eclipse-inst-executable> -vmargs -Duser.home=<absolute-user-home-folder> -Doomph.setup.user.home.redirect=true<br />
<br />
This also works for the self-extracting native Windows executable as well as for the eclipse-inst executable in extracted Eclipse Installer's folder. <br />
The value <tt><absolute-user-home-folder></tt> of the system property <tt>user.home</tt> should be an absolute path what will become the user home folder; it will be created if it doesn't exist.<br />
The value <tt>true</tt> of the system property <tt>oomph.setup.user.home.redirect</tt> will direct the installer to include the <tt>-Duser.home=<absolute-user-home-folder></tt> argument in the eclipse.ini of the created installation so that it too behaves as if that folder were its user home folder.<br />
<br />
In this fashion you can test in a clean environment and you can discard <tt><absolute-user-home-folder></tt> without impacting your real environment.<br />
<br />
=== Copying Tasks and Other Elements ===<br />
The Setup Editor supports the export and import of any model elements by using copy to or paste from the clipboard. The clipboard will/must contain a valid XML document. With this method, for example, you can easily copy task snippets from your model directly into a forum post when you ask for help (or into a Skype window when you chat with your collegues). Or you can easily paste such XML snippets from forum replies directly into your Setup Editor.<br />
<br />
You have access to many example setups from within your IDE! Use Navigate->Open Setup->Parent Models->Open Catalog Index to investigate everything within the index. The context menu provides a way to open elements in a text editor. This is particularly handy for finding out where a particular setup is hosted (hrefs are resolved in the Setup editor) - one use case is checking and repairing links to project setups added to your user projects.<br />
<br />
=== Hosting your own index / catalogs ===<br />
If you want to host your own product or project catalog, you must provide a URI mapping to the installer to locate the root setup file (the "index"). Open the eclipse.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, or use the wizard to create it. 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/. You can redirect to your own index with this redirection system property:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->http://<hostname>/<path>/</nowiki><br />
<br />
The source URI may be abbreviated to <nowiki>index:/</nowiki> and the target URI may also be a file URI, e.g. on a shared file server.<br />
<br />
In general it will be highly desirable to archive your setup, but documentation for that is TBD. The installer and other setup wizards support dragging and dropping an index or archived index onto the title area of the dialog. Documentation for that is also TBD.<br />
<br />
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=481580 Bug 481580] has introduced empty redirectable catalogs for products ('''redirectable.products.setup''') and projects ('''redirectable.projects.setup''') to the Oomph index. These allow providing your own catalogs without replacing the entire index or disabling the catalogs shipped with Oomph (by redirecting them). The following steps are necessary to make use of those setups.<br />
* Create your own project catalog setup file using the wizard. Project setups in the project catalog should typically be referenced using absolute URIs, otherwise redirection can become problematic. However, if the relative references are downward pointing to some uniquely named folder different from any of the file/folder names in the Eclipse.org index, i.e., no '''..''' traversal to the parent folder is involved and some folder name '''<my-projects-folder>''', then they will be resolved to absolute URIs of the form '''index:/<my-projects-folder>/<path>''' which can be handled as described below.<br />
* Add a redirection system property similar to that described above to the eclipse.ini file, e.g., '''-Doomph.redirection.myProjectCatalog=index:/redirectable.projects.setup->...'''.<br />
* If the projects in that catalog are referenced by relative downward references with a unique folder, also add a folder redirection system property, e.g.,'''-Doomph.redirection.myProjectCatalog=index:/<my-projects-folder>/->.../''', to redirect the locations of the referenced projects to the folder where they are physically hosted.<br />
* Your catalog setup file must contain an Eclipse Ini task creating the same redirection(s)! Otherwise your catalog (or the referenced projects) will not be visible in the Eclipse created by the installer and hence the projects selected from it cannot be provisioned.<br />
* The first time, you may have to enable your new catalog by selecting it in the folders icon of the drop-down in the upper right hand corner of the wizard's Projects page, otherwise it will be invisible.<br />
<br />
To debug the processing of -Doomph.redirection.* if needed, set a breakpoint in org.eclipse.oomph.setup.internal.core.util.SetupCoreUtil.configureResourceSet(ResourceSet) within if (((String)key).startsWith(SetupProperties.PROP_REDIRECTION_BASE)).<br />
<br />
=== Shipping your own index ===<br />
If you want to include your own product or project catalog, you may ship the root setup file (the "index") relative to the installer directory. Then you can redirect the index as explained in [[#Hosting your own index / catalogs| Hosting your own index / catalogs]]. For example, you can place all setup files in an eclipse-installer/setups/ folder and then redirect access to it with a relative target URI:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->setups/</nowiki><br />
<br />
Note that shipping the index rather than maintaining it in a central location (accessible to all parties interested) has the following disadvantage. As each user has her own copy of the index, updates in the setup files will not be distributed automatically.<br />
<br />
=== Accessing Setups that Require Authentication ===<br />
<br />
If basic authentication is used to access a setup, Oomph will generally prompt for the credentials and offer to store it in secure storage for future reuse, <br />
but only if the host responds with authorization request.<br />
Some hosts do not do so for security reasons, i.e., to hide the fact that anything exists at the specified URI.<br />
In that case you will need to specify the URI in such a way that directs Oomph to use basic authentication<br />
<br />
https://example.org/owner/repo/raw/master/path/Example.setup?oomph_basic_auth=true<br />
<br />
If form-based authentication is required, you will need to specify the URI to access the setup in such a way that it directs Oomph to the appropriate login/sign-in form <br />
in order to acquire the necessary cookies for an authenticated session.<br />
<br />
https://gitlab-example.com/project/raw/branch/repo-path/Example.setup?oomph_form=b%27users/sign_in%27#/<br />
https://github.com/ower/repo/raw/master/path/Example.setup?oomph_form=b'login'#/<br />
<br />
In this case too, Oomph will then prompt for the credentials and post them to the form.<br />
<br />
I show the %27 as an alternative to ' because if you provide the link to the setup via a web page, the process of copying the link might convert to that form, even if you've used ' rather than the equivalent %27 encoding of it.<br />
<br />
You can "debug" how this works using org.eclipse.oomph.setup.internal.core.util.ECFURIHandlerImpl.Main.main(String[]) in the org.eclipse.oomph.setup.core bundle. <br />
Currently around [https://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.setup.core/src/org/eclipse/oomph/setup/internal/core/util/ECFURIHandlerImpl.java#n2124 here].<br />
<br />
=== Generating PDE Target Definition files (*.target) and their use by Tycho ===<br />
<br />
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. <br />
<br />
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:<br />
<br />
<annotation<br />
source="http:/www.eclipse.org/oomph/targlets/TargetDefinitionGenerator"><br />
<detail<br />
key="location"><br />
<value>${git.clone.location}/targetdefinition/DesignStudio.target</value><br />
</detail><br />
<detail<br />
key="extraUnits"><br />
<value>org.eclipse.equinox.executable.feature.group</value><br />
</detail><br />
<detail<br />
key="includeAllPlatforms"><br />
<value>false</value><br />
</detail><br />
<detail<br />
key="includeSource"><br />
<value>true</value><br />
</detail><br />
<detail<br />
key="generateVersions"><br />
<value>true</value><br />
</detail><br />
</annotation><br />
<br />
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.<br />
<br />
''TODO Document what preferredRepositories, PomModulesUpdater & PomArtifactUpdater do...''<br />
<br />
=== Setting up WST Server Runtime and Instances in your Setup ===<br />
<br />
==== Server Runtime Preference ====<br />
<br />
1. Use an oomphed installation/workspace with preference recorder enabled.<br />
<br />
2. Open your project and user setup editors.<br />
<br />
3. Go to Preferences / Server / Runtime Environments and 'Add' it as usual.<br />
<br />
4. Drag the selected '/instance/org.eclipse.wst.server.core/runtimes' from user to project setup.<br />
<br />
Note: It's unclear if the above actually works. Please see thread https://www.eclipse.org/forums/index.php/t/1086488/ in forum for details.<br />
For some servers there are extension tasks to handle configuration, see below.<br />
<br />
==== Server Instance in Servers View ====<br />
Requires server runtime to be setup first.<br />
<br />
1. Open Servers View and create New server instance and deploy webapps as usual<br />
<br />
2. Optionally open server instance editor and adapt configuration as usual.<br />
<br />
3. Close Eclipse.<br />
<br />
4. Start it again.<br />
<br />
5. Open '.plugins/org.eclipse.wst.server.core/servers.xml' from your workspace/.metadata using a UTF capable editor<br />
<br />
6. Add Resource Creation Task to your setup:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
content="PUT_CONTENT_FROM_SERVERS_XML_INTO_HERE_USING_A_UTF_CAPABLE_EDITOR_AND_OOMPH_DIALOG"<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.wst.server.core/servers.xml"<br />
encoding="UTF-8"><br />
<description>tomcat server integration</description><br />
</setup:ResourceCreationTask><br />
<br />
7. Use the resource task content dialog to put the servers xml content into the task.<br />
<br />
8. Copy "Servers" project from this workspace into a suitable location of your branch checkout and add/commit/push.<br />
<br />
9. Setup project import task that can pick the Servers project up from that committed location.<br />
<br />
That's it. If you want to share it among fellows, be sure to agree on canonical paths for your server installations.<br />
<br />
==== Extension tasks for specific servers ====<br />
<br />
For some servers there are oomph extension tasks that can be used to handle the configuration:<br />
<br />
https://github.com/gratex/oomph-task-server - Tomcat, WebLogic, and WebSphere<br />
<br />
=== Suppress prompt for default workspace already upon very first start ===<br />
<br />
Adjust the SHOW_WORKSPACE_SELECTION_DIALOG property to false via configuration settings org.eclipse.ui.ide.prefs ...<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP MANUAL"<br />
content="MAX_RECENT_WORKSPACES=5&amp;#xD;&amp;#xA;RECENT_WORKSPACES=${workspace.location|property}&amp;#xD;&amp;#xA;RECENT_WORKSPACES_PROTOCOL=3&amp;#xD;&amp;#xA;SHOW_WORKSPACE_SELECTION_DIALOG=false&amp;#xD;&amp;#xA;eclipse.preferences.version=1"<br />
targetURL="configuration:/.settings/org.eclipse.ui.ide.prefs"<br />
encoding="UTF-8"/><br />
<br />
=== Open default perspective already upon very first start ===<br />
Examples below using Perspective ID for Java perspective.<br />
<br />
Tell Eclipse which perspective to open initially, by adding option to eclipse ini:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:EclipseIniTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP"<br />
option="-perspective"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
Setting a perspective to be default, by adding preference task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:PreferenceTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
key="/instance/org.eclipse.ui/defaultPerspectiveId"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
=== How to switch the current stream ===<br />
<br />
If you would like to switch the current stream/s, you can re-use Oomph's initial "Eclipse Importer" wizard, available as "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace.<br />
<br />
Note that it is currently not yet possible to remove the "current" project stream. As a workaround, use menu Navigate > Open Setup > Open Workspace (or if visible click the 'blue guy' icon in the Oomph toolbar) to Open Workspace workspace.setup, expand the first node, click on the Workspace entry, open Properties view, and change the last property named "Streams" and remove the current stream.<br />
<br />
Bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=476434 enhancement may make this easier in the future.<br />
<br />
<br />
=== How to install Eclipse plugins using the P2 Director and Repository Explorer ===<br />
<br />
Oomph can install Eclipse plugins which you require. This also works for normal Java Projects set up models, not just for Eclipse plug in OSGi development, and is handy to install commonly used 3rd-party Eclipse plugins which are not all available from eclipse.org p2 sites (think e.g. http://eclemma.org). Here's how:<br />
<br />
1. add a P2 Director child task to your *.setup, if it doesn't already have one<br />
<br />
2. add a Repository child in your P2 Director task<br />
<br />
3. in the Properties of the Repository set the URL to a valid p2 repo (e.g. http://update.eclemma.org)<br />
<br />
4. right-click that Repository and choose Explore, to open the Repository Explorer view<br />
<br />
5. in the Repository Explorer view change to [X] Compatible and (*) Minor at the lower-right hand corner<br />
<br />
6. drag & drop the version from the Repository Explorer view into the P2 Director task of your *.setup editor, to create a Requirement child<br />
<br />
Drag & Drop should normally work, but appears to be broken at least on Neon Milestone 6 on Linux; in that case:<br />
<br />
6. manually create a new child Requirement inside the P2 Director task<br />
<br />
7. in the Repository Explorer view use the brown (C) icon to switch to Expert Mode to see IDs instead of names<br />
<br />
8. find the ID of the feature IU, it's the one with a PDE feature + folder kind of icon, often ending in (feature.)feature.group<br />
<br />
9. in the Properties of the Requirement, type the Name to the ID found above (e.g. com.mountainminds.eclemma.feature.feature.group)<br />
<br />
10. in the Properties of the Requirement, Type should have automatically switched to Feature<br />
<br />
PS: If you are looking for the URL of p2 repos to pre-install some of the the M2E connectors, see https://git.eclipse.org/c/m2e/m2e-discovery-catalog.git/tree/org.eclipse.m2e.discovery.oss/connectors.xml<br />
<br />
<br />
<br />
=== How to create M2E lifecycle-mapping-metadata.xml to avoid littering your pom.xml with org.eclipse.m2e:lifecycle-mapping ===<br />
<br />
Read https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html & https://wiki.eclipse.org/M2E_compatible_maven_plugins and apply as follows:<br />
<br />
<setupTask<br />
xsi:type="setup:PreferenceTask"<br />
key="/instance/org.eclipse.m2e.core/eclipse.m2.WorkspacelifecycleMappingsLocation"<br />
value="${workspace.location}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"/><br />
<br />
<setupTask<br />
xsi:type="setup:ResourceCreationTask"<br />
content="..."<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"<br />
encoding="UTF-8"><br />
<description>Initialize M2E's Maven Lifecycle Mappings, see https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html &amp; https://wiki.eclipse.org/M2E_compatible_maven_plugins</description><br />
</setupTask><br />
<br />
For "content" just open the popup using the [...] icon in the Properties and copy/paste the content from menu Window > Preferences > Maven > Lifecycle Mappings: Open workspace lifecycle mappings metadata. (This is easier than editing the content=".." in source view, because it will correctly do the XML escaping for you.)<br />
<br />
Now whenever M2E whines about stuff like "Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-dependency-plugin:2.10:unpack (execution: unpack-license, phase: generate-resources)" etc. just use the Quick Fix in the Problems view and choose the option to use workspace preferences (instead of letting the quick fix modify your pom.xml to add org.eclipse.m2e:lifecycle-mapping <lifecycleMappingMetadata>).<br />
<br />
<br />
=== How to automatically pre-enable Gerrit ===<br />
<br />
If you would like to save your end-users from having to [[EGit/User_Guide#Enabling_Gerrit_for_a_repository|manually enabling Gerrit for a repository in EGit]], then you can use the follow magic variable which Oomph will recognize and act upon:<br />
<br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="YOURORG.gerrit.uri.pattern"<br />
value="(https|ssh)://([^@/]+@)?(git.YOURORG.org:29418/.*|git.YOURORG.org/gerrit/.*)"/><br />
<br />
=== How to find a P2 repository at Eclipse using the Repository Explorer ===<br />
<br />
Most projects don't document the locations of all their p2 update sites very well. This makes it hard to find the URL you need in order to install something or in order to specify a URL for your target platform definition. Oomph indexes all the p2 update sites available at download.eclipse.org to make this job easier. You can make use of this as follows:<br />
<br />
# In the Quick Access control, type "Repository Explorer" to show Oomph's Repository Explorer view.<br />
# In that view's toolbar, locate the tool item with the hover "Search Eclipse repositories by provided capabilities", i.e., the one that looks like a little search flashlight, and click it.<br />
# This brings up the "Eclipse Repository Search" dialog. The index is very large so it takes a while to load it. But it's cached locally and updated on the server once per day.<br />
# At the root of the displayed tree are p2's namespaces and under each of these are the capabilities in that namespace. They're organized hierarchically by their qualified name. It's all quite technical and the tree is very large. So while you can explore it, you'll most likely want to use the filter to find something quickly.<br />
# Type the fully qualified name of a Java package or installable unit you wish to locate into the filter. Note that tree items for which there exist a concrete version in some repository are decorated as such. Keep in mind that many projects don't version their Java packages, so it's often better to look at the org.eclipse.equinox.p2.iu category. Here's what it looks like searching for "org.eclipse.emf.ecore.xcore":<br>[[File:SearchEclipseRepositoryDialog.png]]<br><br />
# You can select a capability in the tree so that the lower panel displays all the versions of the capability that are available. Under each of those are nested the update sites that contain them. Composite update sites show their children hierarchically.<br />
# Of course you can double click a repository to further explore its contents in the Repository Explorer itself.<br />
<br />
<br />
=== How to extract the constituent parts that comprise the Windows self-extracting installer executable ===<br />
<br />
The Eclipse Installer distribution for the Windows platform is effectively a self-extracting executable. It is extracted at runtime by the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINExtractor.java Bin Extractor]. The pre-built version of this library, i.e., org.eclipse.oomph.extractor.lib-*.jar, is available in all Oomph-containing installations, i.e., in the installer itself and in applications installed by the installer. This library can also be used standalone to decompose the composed executable into its constituent parts. That can be accomplished if you run it with the correct magical program arguments as follows:<br />
<br />
java -classpath <path-to-extract-lib>\org.eclipse.oomph.extractor.lib-*.jar<br />
org.eclipse.oomph.extractor.lib.BINExtractor <br />
<path-to-executable-to-extract>\eclipse-inst-win64.exe <br />
<target-path>\product.zip <br />
-export <br />
<target-path>\marker.txt <br />
<target-path>\extractor.exe <br />
<target-path>\org.eclipse.oomph.extractor.lib.jar <br />
<target-path>\product-descriptor<br />
<br />
The Java VM arguments need only specify the extractor library along with the main class in that library. The first program argument is the location of the executable you wish to decompose, the 64 bit installer in this case. The remaining arguments are all best directed into a common folder, denoted as <target-path> in the example above. The second argument is the extracted location of the zip file of the product/distribution. The third argument is the -export flag. The fourth argument is the extracted location of the text file containing the marker text that is used to delimit the constituent parts of the composed executable. The fifth argument is the extracted location of the small native executable itself. The sixth argument is the extracted location of the extractor library, the same one being used to extract the parts. The seventh and final argument is the extracted location of the product descriptor. Such a [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINDescriptor.java descriptor] looks like this:<br />
<br />
1<br />
1<br />
7<br />
0<br />
64<br />
0<br />
eclipse-inst.exe<br />
eclipse-inst.ini<br />
Eclipse Installer<br />
http://wiki.eclipse.org/Eclipse_Installer<br />
http://download.eclipse.org/oomph/jre/128x128.png<br />
<br />
Of course you can edit these parts and then you can recompose the executable using the following cmd script executed within the common folder in which you have extracted the constituent parts:<br />
<br />
COPY /B extractor.exe + ^<br />
marker.txt + ^<br />
org.eclipse.oomph.extractor.lib.jar + ^<br />
marker.txt + ^<br />
product-descriptor + ^<br />
marker.txt + ^<br />
product.zip + ^<br />
marker.txt ^<br />
eclipse-inst-64.exe<br />
<br />
Our builds use the [https://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/releng/org.eclipse.oomph.releng/hudson/postprocess.sh postprocess.sh] to do this processing.<br />
One issues that's important in terms of signing, is that the extractor.exe that you've extracted above will already contain a signature and this might well cause signing of the composed executable fail. So our script actually uses the following to fetch the executable from Git:<br />
<br />
curl -O https://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/plugins/org.eclipse.oomph.extractor/extractor-64.exe<br />
<br />
Note that the file names match the extracted target file names. From this is should be clear that the native executable is just a composition of parts. This structure is used at runtime as follows. The extractor.exe runs natively, reading its own executable file, using the marker text to find the parts. It checks the descriptor to determine if an appropriate version of Java is already installed, i.e., one that will be able to launch the product; the native extractor consults the registry to find all installed JREs and JVMs. If an appropriate Java is not found, it opens a browser page prompting the user to install an appropriate Java version with the required bitness and at the minimum required version. If there is already an appropriate version of Java, it launches a Java process to execute the BinExtract's main method. That process in turn unzips the product zip to a temp folder and launches the Java process for that for the product/distribution.<br />
<br />
== Oomph Configuration Options ==<br />
<br />
=== Configuration Options for Installer .ini File ===<br />
<br />
{| class="wikitable"<br />
| '''-Doomph.redirection.setups''' || Redirects the location of setup files (index, catalog and products). The default URI is ''http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/'' and my be abbreviated with '''index:/'''. The syntax of the redirection is '''index:/->[redirection URI]'''. Examples: '''-Doomph.redirection.setups=index:/->http://<hostname>/<path>/''' (external server redirection) or '''-Doomph.redirection.setups=index:/->setups/''' (path relative to installer executable). See also [[#Hosting_your_own_index_.2F_catalogs|Hosting your own index & catalogs]]<br />
|-<br />
| '''-Doomph.setup.product.catalog.filter''' || Only displays product catalogs matching the given prefix. The default is ''org\\.eclipse\\.products''. Displays all catalogs if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.filter''' || Only displays products matching the given prefix. The default is ''(?\!org\\.eclipse\\.products\\.org\\.eclipse\\.platform\\.ide).*''. Displays all products if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.version.filter''' || Only displays product versions matching the given prefix. The default is ''.*\\.neon''. Displays all product versions if value is empty.<br />
|-<br />
| '''-Doomph.p2.pool''' || Set to ''@none'' to disable bundle pools. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=507594] for details.<br />
|}<br />
<br />
== Troubleshooting ==<br />
=== The preference task does not setup any preferences ===<br />
<br />
First of all. Please note that the preferences are not set up as part of the installation. They are setup when the installed eclipse is first started.<br />
<br />
To do this the installed product needs to have the following feature installed:<br />
''org.eclipse.oomph.setup.feature.group''<br />
<br />
The feature is already included in the root of the Eclipse.org Product Catalog. If you are not using it you can include the same task by yourself:<br />
<br />
<setup.p2:P2Task<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup.p2="http://www.eclipse.org/oomph/setup/p2/1.0"><br />
<requirement<br />
name="org.eclipse.oomph.setup.feature.group"/><br />
<repository<br />
url="${oomph.update.url}"/><br />
</setup.p2:P2Task></div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Oomph_Targlets&diff=438669Oomph Targlets2020-03-15T06:01:36Z<p>Stepper.esc-net.de: </p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
Oomph's Targlet technology extends [https://www.eclipse.org/pde/ PDE's] base functionality for specifying a target platform definition by providing a more expressive, flexible, scalable, and reliable mechanism.<br />
The Targlets framework is fully integrated with PDE; <br />
it uses PDE's target location extension point, providing a Targlet Container implementation to augment PDE's built-in target location implementations.<br />
<br />
As you'll see in the tutorial, here are some of the significant advantages of Oomph's Targlet Container versus PDE's Software Site container:<br />
<br />
* Dependencies are expressed as Requirements versus as Installable Units. <br />
** A Targlet's Requirement can specify a version range, optionality, greediness, cardinality, filters, and so on. Any p2 namespace, such as "java.package", can be specified, as well.<br />
** A PDE Software Site container's Installable Unit must specify either no version (omni-version) or an exact version.<br />
<br />
* Dependencies of local projects in the file system, e.g., in a local Git clone, can be taken into account during resolution using a Source Locator.<br />
** A Targlet Container resolves the requirements from the combination of all local projects and all available software sites.<br />
** It can use wildcards to specify all available Requirements of the Source Locator.<br />
** It imports projects into the workspace as a side-effect of resolution.<br />
<br />
* The resolution process supports roll-back on failure.<br />
** A resolution failure or network failure with Targlets will leave the old successful resolution in place.<br />
** A resolution failure with PDE's Software Site container will destroy your target platform, leaving all your workspace projects with errors until the problem is resolved, e.g., until your network or the hosting servers of the software sites are restored.<br />
<br />
* Resolved artifacts use a shared bundle pool, which is highly significant when you have multiple workspace.<br />
** Targlet Containers will download and store each artifact once in the file system, sharing them across workspaces (and even sharing the artifacts used by your installations).<br />
** PDE resolves artifacts separately into a workspace-specific bundle pool, resulting in many duplicates (and downloading artifacts already available in your installation).<br />
<br />
* Update sites can be grouped into named lists, so that a single target definition can be resolved against different sets of repositories by switching to different named Repository Lists. This is most useful in combination with a Targlet Task that can easily select the active Repository List.<br />
<br />
<br />
== Install Targlet Support ==<br />
<br />
Use ''Help &rarr; Install New Software...'' and enter one of the [[Oomph#Update_Sites|update sites]], e.g., [http://download.eclipse.org/oomph/updates/milestone http://download.eclipse.org/oomph/updates/milestone], into the "Work with:" combo.<br />
Enter "Oomph Targlets" in the filter, and select the Oomph Targlets feature.<br />
<br />
[[File:Oomph_Install_Targlets_Feature.png]]<br />
<br />
== Create an Empty Target Definition ==<br />
<br />
Use ''Window &rarr; Preferences... &rarr; Plug-in Development &rarr; Target Platform'' to "Add..." a new Target Platform.<br />
<br />
[[File:Oomph_PDE_Add_Target_Platform.png]]<br />
<br />
Choose "Nothing: Start with an empty target definition" and press "Next".<br />
<br />
[[File:Oomph_PDE_Create_Empty_Target_Definition.png]]<br />
<br />
Use the "Name:" text field to name it "Sample" and press "Add..." to add a target location.<br />
<br />
[[File:Oomph_PDE_Add_Target_Location.png]]<br />
<br />
== Add a Targlet Container ==<br />
<br />
In the "Add Content" dialog select "Targlet Container" and press "Next".<br />
<br />
[[Image:Oomph_Targlet_Add_Targlet_Container.png]]<br />
<br />
Use the "Targlet Container ID:" field to enter the name "Sample Targlet Container" and press "Finish".<br />
<br />
[[Image:Oomph_Targlet_Add_Targlet_Container_Specify_ID.png]]<br />
<br />
Select the new Targlet Container and press "Edit..." to edit it:<br />
<br />
[[Image:Oomph_Targlet_Edit_Targlet_Container.png]]<br />
<br />
This will save the target definition, dismiss the dialog, and open the Targlet Editor.<br />
<br />
== Edit Targlet Container with Targlet Editor ==<br />
<br />
The Targlet Editor works well in combination with the Properties view and Oomph's Repository Explorer.<br />
You can open the Properties view from the Targlet Editor's context menu or by double clicking any item in the editor.<br />
You can open the Repository Explorer by entering "Repository Explorer" in the "Quick Access" field to the left of the perspective toolbar in the upper right corner of the perspective.<br />
<br />
Double click the root item (only item, currently) in the Targlet Editor and use the context menu to invoke ''New Child &rarr; Targlet''.<br />
<br />
[[File:Oomph_Targlet_Editor_New_Child_Targlet.png]]<br />
<br />
The new Targlet must have a name.<br />
The editor decorates errors in the tree and in the Properties view.<br />
Use the Properties view to set the "Name" property to "Eclipse SDK".<br />
<br />
[[File:Oomph_Targlet_Editor_Set_Targlet_Name.png]]<br />
<br />
Use the context menu on the new Targlet named "Eclipse SDK" to invoke ''New Child &rarr; Repository List'' and then use the context menu again to invoke ''New Child &rarr; Repository''.<br />
A Repository must of course specify a URL for a p2 update site.<br />
Use the properties view to enter the URL "http://download.eclipse.org/eclipse/updates/I-builds".<br />
Open the Repository Explorer view and then drag the Repository item and drop it onto the Repository combo in the Repository Explorer.<br />
<br />
[[File:Oomph_Targlet_Editor_Drag_Repository_To_Repository_Explorer.png]]<br />
<br />
The Repository Explorer will load the p2 repository and display its contents, much like what you're familiar from using the ''Help &rarr; Install New Software...'' dialog.<br />
<br />
[[File:Oomph_Targlet_Editor_Use_Repository_Explorer.png]]<br />
<br />
For each item you select, you can see which Versions of that item are available in the p2 repository.<br />
You can alter how the Versions are displayed using the controls in the bottom right.<br />
Here "Compatible" is checked, and "Minor" is selected.<br />
You can drag any item, including the Version items, to the "Eclipse SDK" Targlet to create a Requirement.<br />
When dragging a Version item, the version range of the Requirement that's created in the Targlet will reflect the display settings you've chosen.<br />
Here is the result of dragging the "4.8.x" version item to the "Eclipse SDK" Target with the new Requirement selected to display its properties in the Properties view:<br />
<br />
[[File:Oomph_Targlet_Editor_New_Requirement_From_Repository_Explorer_Version_Item.png]]<br />
<br />
It is significant to note some of the differences between editing a Targlet Container with Oomph's Targlet Editor versus editing a *.target file PDE's Target editor.<br />
At this point, we have not downloaded any artifacts from the p2 repository, we've only explored the content metadata and we could author the complete definition based on just that information.<br />
Also, editing PDE's Software Site container is achieved by specifying so-called installable units, either with an exact version or with the so called omni-version,<br />
but Targlets use Requirements that can specify version ranges, and properties such as optional and greedy, exactly like what you're able to express in a plug-in' MANIFEST.MF.<br />
Requirements are a more expressive mechanism for expressing dependencies for the target platform.<br />
<br />
When you save the Targlet Editor's contents, the Targlet Container will resolve in the background.<br />
You can use ''Window &rarr; Preferences &rarr; Plug-in Development &rarr; Target Platform'' to make the "Sample" target platform the active target platform.<br />
<br />
== Using a Source Locator ==<br />
<br />
Suppose some of your project in the workspace still has dependencies that aren't satisfied.<br />
<br />
[[File:Oomph_Targlets_Unresolved_Dependency.png]]<br />
<br />
You can of course hunt for them in the Repository Explorer, assuming you know in which p2 repo to find them.<br />
If you don't know the p2 repository, but you expect it's in some repository hosted by Eclipse, you can use [[Eclipse_Oomph_Authoring#How_to_find_a_P2_repository_at_Eclipse_using_the_Repository_Explorer|Eclipse Repository Search]] to find the p2 repository.<br />
Once you know the repository, can you of course browse the contents and use drag and drop to create the necessary Requirements and to add the necessary Repository to a Repository List.<br />
<br />
But Oomph's Targlet framework supports another powerful mechanism, namely Source Locators.<br />
The basic concept is that the underlying p2 framework is able to publish p2 metadata from source projects.<br />
PDE's implementation reuses this to build a representation of the plug-ins and features in the workspace.<br />
Oomph's Targlet framework reuses the same technology to induce a logical p2 repository from projects in the file system.<br />
For example, you can use the Repository Explorer to browse all your workspace projects as a logical p2 repository.<br />
Select "platform:/resource/" in the Repository Explorer's URL combo and switch to Expert Mode using the view's toolbar button with that hover text:<br />
<br />
[[File:Oomph_Targlets_Use_Repository_Explorer_Workspace_Repository.png]]<br />
<br />
To exploit the use of a Source Locator feature, use the Targlet Editor to create another Targlet named "Workspace Dependencies",<br />
create a new Requirement in that new Targlet and use the Properties view to change the "Name" to "*";<br />
this is a so-called wildcard Requirement.<br />
Then create a Source Locator in that new Targlet and use the Properties view to set the "Root Folder" to "platform:/resource/";<br />
this too is effectively a wildcard that denotes the file system location of each project in the workspace.<br />
The result looks like this:<br />
<br />
[[File:Oomph_Targlet_Editor_With_Source_Locator.png]]<br />
<br />
Assuming you've made the "Sample" target definition the active definition from the previous steps in this tutorial,<br />
saving the Targlet Editor will resolve the target platform,<br />
taking into account the dependencies of all projects in your workspace.<br />
Because the Platform's I-builds include, the "org.junit" bundle,<br />
after the resolution, the workspace error is eliminated because the target platform will contain the required bundle.<br />
<br />
This is just a simple though useful example of using a Source Locator.<br />
It should be evident that authoring a target platform in this manner is significantly simpler because you need not replicate/repeat in the target platform definition, the dependencies already expressed in your projects.<br />
Another highly useful aspect not illustrated by this simple example is that you can use a Source Locator to point at a Git clone in your local file system.<br />
During resolution, not only will all the requirements of the projects in that Git clone be resolved,<br />
the projects themselves will be imported into the workspace!</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Oomph_Authoring&diff=438314Eclipse Oomph Authoring2020-02-19T08:53:05Z<p>Stepper.esc-net.de: /* Variable Filters */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
== Getting Started ==<br />
<br />
=== What is Oomph? ===<br />
<br />
Please read [[Eclipse Installer]].<br />
<br />
<br />
=== Installing Oomph ===<br />
<br />
# Download and install the Eclipse '''Installer''' as outlined in [[Eclipse Installer]].<br />
# Make sure that the Oomph setup '''SDK''' is installed in your IDE. Either:<br />
## That's already the case because your IDE is a Mars M5 or later Eclipse Package, or<br />
## Start the installer and install an IDE of your choice (select on the first installer page), or<br />
## Use p2 to install "Oomph Setup SDK" from [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest].<br />
<br />
== Creating a Setup Project Model ==<br />
<br />
=== Using the Setup Project Model Wizard ===<br />
<br />
# Create an empty project in your workspace or select a folder in an existing project. You'll create the new "Setup Project Model" in the selected folder.<br />
# Open the New... dialog and select the "Setup Project Model" wizard:<br>[[Image:new-wizard.png]]<br><br />
# Select one of the provided templates (e.g., Eclipse.org, Github.com, or Simple) and adjust the displayed values:<br>[[Image:new-wizard-2.png]]<br><br />
# Some values are automatically derived from your input to fields '''higher up'''.<br />
# Open the Preview>>> to understand the impact of changes to the current field.<br />
<br />
=== Using the Setup Editor ===<br />
<br />
# Open the resulting setup file with Oomph's Setup Editor:<br>[[Image:setup-edit.png]]<br><br />
# Configure the tasks in the Properties view. Note that there are "Expert" properties available.<br />
# Add setup tasks to your project and/or to your project streams and configure them, too.<br />
# The Outline view displays a ''preview'' of the executable model with resolved variables.<br />
<br />
=== Testing the Setup Model ===<br />
<br />
# To test/execute your new setup model:<br />
## Start the installer and, if necessary, switch to the Advanced Mode via the dialog menu.<br />
## Pick any product on page 1 and click the Next button to proceed to page 2.<br />
## Drag and drop your <tt>.setup</tt> file onto one of the top-level catalogs (<tt>Eclipse.org</tt> or <tt>Github.com</tt>) in the projects tree. Your project will appear as a subproject of the special <tt>&lt;User&gt;</tt> project.<br />
## Double-click your project to add it to the table at the 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.<br />
## Fill in the empty fields and press the Next button to proceed to the Confirmation page.<br />
## 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.<br><br />
# 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 [[#Using the Setup Editor|Using the Setup Editor]]. If the IDE comes up but the initial configuration fails continue with step 3.<br />
# In the new IDE (whether the initial configuration was successful or not) open your model file from the main menu, Navigate &rarr; Open Setup &rarr; [[Image:branch.png]]. Find the problems and fix them. Then start the setup process '''from within''' this IDE via the main menu, Help &rarr; [[Image:update.png]] Perform Setup Tasks&hellip;. 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.<br />
<br />
=== Contributing to a Project Catalog ===<br />
<br />
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 http://git.eclipse.org/c] and [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&bug_severity=enhancement&short_desc=Please%20include%20setup%20for%20project%20Xyz 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.<br />
<br />
The same can be done if your project is not an Eclipse project, but hosted on '''GitHub'''. Simply state this fact in the bug description and paste the "raw" content URL to the file instead.<br />
<br />
== Understanding the Setup Engine ==<br />
<br />
=== Understanding Setup Tasks and Scopes ===<br />
<br />
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:<br />
<br />
* The '''Installation''' scope is located in <tt>eclipse/configuration/org.eclipse.oomph.setup/installation.setup</tt> 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.<br />
<br />
* The '''Workspace''' scope is located in <tt>workspace/.metadata/.plugins/org.eclipse.oomph.setup/workspace.setup</tt> 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.<br />
<br />
* The '''User''' scope is located in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup</tt> and contains tasks that are common to '''all''' installations and workspaces (unless they're restricted to particular installations or workspaces).<br />
<br />
<br />
The following additional scope types exist, so they can be referenced by the entry scopes:<br />
<br />
* The '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.setup Catalog Index]''' is the root scope and contains nested Product Catalogs and Project Catalogs.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.products.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/OomphInstaller.setup Product]''' contains nested Product Version scopes and possibly some tasks that are common to all nested scopes.<br />
<br />
* A '''Product Version''' contains no nested scopes but tasks that are specific to that product version.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.projects.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/Oomph.setup Project]''' contains nested Stream and/or (Sub-) Project scopes and typically some tasks that are common to all nested scopes.<br />
<br />
* A '''Stream''' contains no nested scopes but tasks that are specific to that stream.<br />
<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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 [[#Declaring_and_Using_Variables|Declaring and Using Variables]] below.<br />
<br />
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). <br />
<br />
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.<br />
<br />
=== Declaring and Using Variables ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:<br />
<br />
${''variable-name''}<br />
<br />
To prevent a variable reference from being expanded (e.g. you actually want to have the value '${var}' and not the value of "var"), you need to escape the variable syntax with an extra double dollar character. So "$${var}" will result in "${var}".<br />
<br />
In addition to the variables that are declared by VariableTasks you can refer to all of the following:<br />
<br />
* Attribute values of setup tasks with a defined ID. The reference syntax is ${''taskID''.''attributeName''}.<br />
* System properties as returned by <tt>System.getProperties()</tt><br />
* [[#Environment Variables|Environment variables]] as returned by <tt>System.getenv()</tt><br />
* [[#Predefined Variables|Predefined variables]] as determined by the setup engine from the user input to the installer (see below)<br />
<br />
==== Predefined Variables ====<br />
<br />
The following variables are predefined by the setup engine:<br />
<br />
{| class="wikitable"<br />
| '''scope.installation.name''' || The value of the <em>name</em> attribute of the current installation scope. <br />
|-<br />
| '''scope.installation.label''' || The value of the <em>label</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.installation.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.workspace.name''' || The value of the <em>name</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.label''' || The value of the <em>label</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.description''' || The value of the <em>description</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.user.name''' || The value of the <em>name</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.label''' || The value of the <em>label</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.description''' || The value of the <em>description</em> attribute of the current user scope.<br />
|-<br />
| '''scope.product.catalog.name''' || The value of the <em>name</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.label''' || The value of the <em>label</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.description''' || The value of the <em>description</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.name''' || The value of the <em>name</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product scope and its parent scopes.<br />
|-<br />
| '''scope.product.label''' || The value of the <em>label</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.description''' || The value of the <em>description</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.version.name''' || The value of the <em>name</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product version scope and its parent scopes.<br />
|-<br />
| '''scope.product.version.label''' || The value of the <em>label</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.project.catalog.name''' || The value of the <em>name</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.label''' || The value of the <em>label</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.description''' || The value of the <em>description</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.name''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current project scope and its parent scopes.<br />
|-<br />
| '''scope.project.label''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.description''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.stream.name''' || The value of the <em>name</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current stream scope and its parent scopes.<br />
|-<br />
| '''scope.project.stream.label''' || The value of the <em>label</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.description''' || The value of the <em>description</em> attribute of the current stream scope.<br />
|}<br />
<br />
<br />
==== Variable Extensions ====<br />
<br />
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.:<br />
<br />
${installation.location/git/myproject} evaluates to C:\develop\installation1\git\myproject on Windows<br />
<br />
<br />
After the path extension part you can add filter calls with pipe symbols. Filter names are generally case-insensitive. Multiple filters can be chained. Example:<br />
<br />
${installation.location|uri}/git/myproject evaluates to file:/C:/develop/installation1/git/myproject<br />
<br />
<br />
==== Variable Filters ====<br />
<br />
The following filters are currently available:<br />
<br />
{| class="wikitable"<br />
| '''base64''' || Encodes the String value to its base64 representation.<br />
|-<br />
| '''basePath''' || Removes the last segment from a file system path.<br />
|-<br />
| '''camel''' || Converts a qualified name to camel case notation.<br />
|-<br />
| '''canonical''' || Canonicalizes a file system path.<br />
|-<br />
| '''cap''' || Capitalizes the first word of a String value.<br />
|-<br />
| '''capAll''' || Capitalizes all words of a String value.<br />
|-<br />
| '''file''' || Converts a file: URI to an OS-specific file system path.<br />
|-<br />
| '''fileExtension''' || Extracts the file extension from a URI or a file system path.<br />
|-<br />
| '''gitRepository''' || Extracts the name of the repository from a Git URI (excluding a possible .git suffix).<br />
|-<br />
| '''lastSegment''' || Extracts the last segment from a file system path.<br />
|-<br />
| '''length''' || Converts a String to a String that contains the alpha-numerical representation of the length of the original String.<br />
|-<br />
| '''lower''' || Converts all characters of a String value to lower-case.<br />
|-<br />
| '''not''' || The boolean logical negation, i.e., 'false' if the value is 'true', and 'true' if the value is 'false' (or anything else).<br />
|-<br />
| '''path''' || Extracts the path segments from a URI.<br />
|-<br />
| '''pathEncode''' || Converts a file system path to a String value that can be used as a file name.<br />
|-<br />
| '''patternQuote''' || Quotes regular-expression constructs in the String value such that the result can be used as a literal string in patterns.<br />
|-<br />
| '''preferenceNode''' || Escapes all forward slashes (/) of a String value, so that the result can be used as a value in preference nodes.<br />
|-<br />
| '''property''' || Escapes all double back slashes (\\) of a String value, so that the result can be used as a value in properties.<br />
|-<br />
| '''propertyValue''' || Interprets the String value as a preference property path and returns the value of that property.<br />
|-<br />
| '''qualifiedName''' || Converts a camel case String value name to a qualified name.<br />
|-<br />
| '''slashDecode''' || Decodes a slashEncoded String value.<br />
|-<br />
| '''slashEncode''' || Encodes all slashes and backslashes of a String value.<br />
|-<br />
| '''trim''' || Removes all whitespace from the beginning and the end of a String.<br />
|-<br />
| '''trimLeft''' || Removes all whitespace from the beginning of a String.<br />
|-<br />
| '''trimRight''' || Removes all whitespace from the end of a String.<br />
|-<br />
| '''trimTrailingSlashes''' || Removes all slashes and backslashes from the end of a String.<br />
|-<br />
| '''upper''' || Converts all characters of a String value to upper-case.<br />
|-<br />
| '''uri''' || Converts a file system path to a file: URI.<br />
|-<br />
| '''uriLastSegment''' || Extracts the last path segment from a hierarchical URI or the authority from an opaque URI.<br />
|-<br />
| '''urlDecode''' || Decodes a URL.<br />
|-<br />
| '''urlEncode''' || URL-encodes a String value.<br />
|-<br />
| '''username''' || Escapes all "at" symbols (@) of a String value, so that the result can be used in URI that contain a username.<br />
|}<br />
<br />
==== Variables from Outer Scopes====<br />
<br />
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:<br />
<br />
* '''jre.location-1.4''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.5''' --> The folder containing a 1.5 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.6''' --> The folder containing a 1.6 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.7''' --> The folder containing a 1.7 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.8''' --> The folder containing a 1.8 compatible JDK/JRE for architecture ${os.arch}<br />
* '''git.user.id''' --> The Eclipse user ID for Git/Gerrit commits<br />
* '''git.author.name''' --> The Eclipse author name for Git/Gerrit commits<br />
* '''git.author.email''' --> The Eclipse author email for Git/Gerrit commits<br />
* '''bugzilla.id''' --> The Eclipse user ID for Bugzilla/Hudson<br />
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson<br />
<br />
<br />
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.<br />
<br />
==== Environment Variables ====<br />
<br />
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.<br />
<br />
=== Conditional Tasks ===<br />
<br />
All setup tasks support filters. Oomph reuses [https://wiki.eclipse.org/Equinox_P2_Resolution#Enablement_filter p2's implementation] of LDAP filters. I.e., it supports a string a representation of LDAP Search Filters, RFC 1960, UMich, 1996,<br />
http://www.ietf.org/rfc/rfc1960.txt<br />
<br />
The filter property of a setup task is an advanced property. To display this property, ensure that the "Show Advanced Properties" is enabled in the Properties view tool bar. The properties of a filter expression can generally refer to any system property or any environment variable. For example, the following filter expression on a task will ensure that it is included only when performing a task on a Linux operating system.<br />
<br />
(osgi.os=linux)<br />
<br />
The latest version of Oomph allows filter properties to refer to the values of variables as defined in the setup itself. For example, this idiom can be used to express if-then-else.<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xmi:XMI xmi:version="2.0"<br />
xmlns:xmi="<nowiki>http://www.omg.org/XMI</nowiki>"<br />
xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"<br />
xmlns:setup="<nowiki>http://www.eclipse.org/oomph/setup/1.0</nowiki>"><br />
<setup:VariableTask<br />
type="BOOLEAN"<br />
name="example.filter"<br />
label="Example Filter"><br />
<description>An example of a variable used to conditionally filter tasks</description><br />
</setup:VariableTask><br />
<setup:CompoundTask<br />
filter="(example.filter=true)"<br />
name="Filter True"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.a"<br />
label="Property A"><br />
<description>The value use for system.property.a</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.a"<br />
value="=${example.variable.a}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is true</description><br />
</setup:CompoundTask><br />
<setup:CompoundTask<br />
filter="(example.filter=false)"<br />
name="Filter False"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.b"<br />
label="Property B"><br />
<description>The value used for system.property.b</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.b"<br />
value="=${example.variable.b}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is false.</description><br />
</setup:CompoundTask><br />
</xmi:XMI><br />
<br />
On the Variables page of the setup wizards, any variable that is used in property of a filter will be displayed in bold. It is significant to note that the value of a so-called filter variable can conditionally affect the presence of other variables. In this example, either variable <code>example.variable.a</code> or <code>example.variable.b</code> (but not both) will be present on the Variables page, depending on the value of the <code>example.filter</code> variable, which is displayed as a checkbox because it is of type <code>BOOLEAN</code>.<br />
<br />
Note that Oomph setup editors support textual copy and paste, so you can copy the above XML and paste it into your setup editor to try it out.<br />
<br />
== Macros and Macro Expansion Tasks ==<br />
<br />
As of Oomph 1.13, released with Eclipse 2019-06, there is support for Macros. A Macro is a Scope, i.e., is a container for setup tasks, and can specify 0 or more Parameters. Each Parameter specifies a name, a description, and optionally a default value. The parameter names can be used as variable references in the setup tasks contained by the Macro.<br />
<br />
=== Creating a Macro ===<br />
<br />
The simplest way to create a new Macro is from the context menu of the folder where you want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Macro Model in the wizard. You can then edit the new Macro with the Setup Editor. You can create Parameters, if desired, and of course you can create any other setup tasks.<br />
<br />
Here is an example of how one could use a Macro for creating a Git Clone task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Macro<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:git="http://www.eclipse.org/oomph/setup/git/1.0"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
xsi:schemaLocation="http://www.eclipse.org/oomph/setup/git/1.0 http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/models/Git.ecore"<br />
name="git.clone"<br />
label="Git Clone"><br />
<setupTask<br />
xsi:type="git:GitCloneTask"<br />
id="git.clone"<br />
remoteName="${remoteName}"<br />
remoteURI="${remoteURI}"<br />
pushURI="${pushURI}"<br />
checkoutBranch="${checkoutBranch}"><br />
<annotation<br />
source="http://www.eclipse.org/oomph/setup/FeatureSubstitution"><br />
<detail<br />
key="restrictToCheckoutBranch"><br />
<value>${restrictToCheckoutBranch}</value><br />
</detail><br />
<detail<br />
key="recursive"><br />
<value>${recursive}</value><br />
</detail><br />
</annotation><br />
<description>${description}</description><br />
</setupTask><br />
<description>The GitClone macro provides a template for creating a clone task</description><br />
<parameter<br />
name="description"><br />
<description>The description of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="pushURI"><br />
<description>The push URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="recursive"<br />
defaultValue="false"><br />
<description>Whether submodules should be recursively cloned</description><br />
</parameter><br />
<parameter<br />
name="remoteName"<br />
defaultValue="origin"><br />
<description>The name of the remote</description><br />
</parameter><br />
<parameter<br />
name="remoteURI"><br />
<description>The remote URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="restrictToCheckoutBranch"<br />
defaultValue="false"><br />
<description>Whether the clone should be restricted to clone only the checkout branch</description><br />
</parameter><br />
<parameter<br />
name="checkoutBranch"><br />
<description>The name of the branch that the Git clone task to checks out</description><br />
</parameter><br />
</setup:Macro><br />
<br />
Special support is provided for defining so called local Variables in a Macro. Any Variable with a name that starts with '*' will be handled in a special way during [[#Macro Expansion Processing|Macro Expansion]].<br />
<br />
=== Using a Macro with a Macro Expansion Task ===<br />
<br />
To use a Macro you must create a Macro Expansion task. The easiest way to do this is to drag the resource containing the Macro and then drop it into the Setup Editor where you want to use it. Similarly, if you want to use a Macro defined in the internet, you can use Load Resource... from the Setup Editor's context menu to load the Macro into the editor's resource set (or drag the link and drop it into the editor). Note that Macros available in the resource set are always shown in the Outline view. Once the Macro is available in the editor's resource set, or in the Outline, you can drag and drop the Macro anywhere that any other setup task can be created. This will create a Macro Expansion task that binds to the Macro.<br />
<br />
A Macro Expansion task must specify an ID, which of course must be unique within the containing resource. The ID is used during [[#Macro Expansion Processing|Macro Expansion Processing]]. Via drag and drop, an ID is automatically assigned, but you'll likely want to change it. A Macro Expansion task can supply Arguments to bind the values of the Parameters of the Macro. For every Parameter without a default value there must be a corresponding Argument to bind its value. The validator will complain when that's not the case, so be sure to enable Live Validation via the context menu. When creating a Macro Expansion task using drag and drop, the required Arguments are automatically created. Of course you'll want to change the generated values; you can delete any Arguments for which the Parameter specifies the default value that you wish to just use. You can change the Argument's value by double clicking the Argument to ensure that it's visible in the Properties view, and can then edit the Value property of the Argument there. The description of the corresponding Parameter is displayed in the Properties view after the Parameter's name. This is why it's important to include a description for each Parameter so that the author using the Macro knows how the Argument's value will be used by that Macro.<br />
<br />
The setup editor displays the Macro referenced by a Macro Expansion task as a child item, in light brown, in the tree view, so you can fully explore the Macro being used. In addition a Preview item is displayed, in light blue, to show how the Macro Expansion task will be expanded. And of course the Outline view allows you to preview all of the tasks that will be performed when you run the installer later.<br />
<br />
Here is an example of how the above Macro could be used by a Macro Expansion task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Project<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
name="sample.project"<br />
label="SampleProject"><br />
<setupTask<br />
xsi:type="setup:MacroTask"<br />
id="my"<br />
macro="GitCloneMacro.setup#/"><br />
<argument<br />
name="description"<br />
value="description_value"/><br />
<argument<br />
name="pushURI"<br />
value="pushURI_value"/><br />
<argument<br />
name="recursive"/><br />
<argument<br />
name="remoteName"/><br />
<argument<br />
name="remoteURI"<br />
value="remoteURI_value"/><br />
<argument<br />
name="restrictToCheckoutBranch"/><br />
<argument<br />
name="checkoutBranch"<br />
value="master"/><br />
</setupTask><br />
<stream name="stream"/><br />
<logicalProjectContainer<br />
xsi:type="setup:ProjectCatalog"<br />
href="index:/org.eclipse.setup#//@projectCatalogs[name='org.eclipse']"/><br />
<description>SampleProject provides cool stuff.</description><br />
</setup:Project><br />
<br />
Note that here we have several Arguments without a value. Those could be deleted or a value (presumably different from the default value of the Parameter) could be specified. Also note that a well-formed Argument can only bind to a Parameter of the containing Macro Expansion task's Macro, so the serialization is simplified to specify just the name of the bound Parameter in this case.<br />
<br />
=== Macro Expansion Processing ===<br />
<br />
A Macro Expansion task is expanded to a Compound Setup Task as illustrated by the Preview item. Each Argument is bound to its corresponding Parameter via a local variable of the form '*<macro-expansion-task-id>.<parameter-name>'. Every variable reference to the Parameter name is transformed to use this Variable's more-qualified name instead. Every setup task with an ID is transformed to specify instead a qualified ID of the form '<macro-expansion-task-id>.<original-id>' and every variable reference that's prefixed by '<original-id>.' will be transformed to use the more-qualified prefix instead. In addition, any Variable contained by the Macro with a name that start with '*' will also be changed to use the name '*<macro-extension-task-id>.<original-name>' and all references to '<original-name>' will be transformed to use that qualified name instead. This qualification process ensures that unique Variable names are provided by the Macro Expansion because in the end, there's no such thing as a local Variable.<br />
<br />
Of course Macros themselves can use Macro Expansion tasks, so the process of expansion is recursive. That being said, it's of course invalid for this to lead to a cycle. Cycles are detected by the validator and the expansion process prevents further expansion when a cycle is encountered.<br />
<br />
Note that from the context menu of a Macro Expansion task it's possible to invoke "Inline" to replace a Macro Expansion task with its fully expanded equivalent.<br />
<br />
== Automation and Specialization with Configurations ==<br />
<br />
As of Oomph 1.6, released with Neon.2, there is support for Configurations. A Configuration is not a Scope (is not a container for setup tasks) but rather a container for an Installation and a Workspace; each is optional, but a Configuration with neither is in effect useless. The Installation and Workspace of a Configuration are effectively used as a template to initialize the Installation and Workspace created by the Eclipse Installer, i.e., the setup resources that you can open with Navigate &rarr; Open Setup &rarr; Installation and Navigate &rarr; Open Setup &rarr; Workspace in your IDE. So you can specialize the installation with additional installation-specific tasks, e.g., a p2 task to install additional features, and you can specialize the workspace with workspace-specific tasks, e.g., a variable task to specify the value of a variable so you won't be prompted for that value. <br />
<br />
Configurations are not only useful for specifying installation-specific and workspace-specific tasks but also for automating the selection process in the setup wizards, including the installer. The Configuration's Installation can reference a specific Product Version and the Configuration's Workspace can optionally reference several specific Project Streams. Both the simple mode and the advanced mode of the installer support dragging and dropping a Configuration to the title area. You can drag to the title area either a file (i.e., a file from the file system or from an Eclipse IDE), a URL (i.e., a link from a browser), or a copy of a Configuration's XMI serialization. This will '''apply''' the Configuration to the wizard with the effect that the Installation's Product Version is selected in the wizard and the wizard advances to the next page. Similarly, the Workspace's Project Streams are selected in the wizard and the wizard advances to the next page. If you apply a Configuration with a Workspace to the simple mode of the installer, you will be prompted to switch to advanced mode because only the advanced mode supports Project selection. So in simple mode, applying a Configuration advances to the final page, and in advanced mode, applying a Configuration with an Installation and a Workspace advances to the Variables page.<br />
<br />
As an alternative to drag and drop support, rather than dragging a file, link, or XMI serialization, you can copy it to the clipboard and apply the clipboard contents to the wizard. In simple mode this is done via the Apply Configuration menu item. In advanced mode this is done via the Apply Configuration toolbar button on the Product or Project page; the menu item or toolbar item is visible only if the clipboard contains applicable content.<br />
<br />
The installer application supports command line arguments so you could also specify a Configuration's file path or URL link on the command line to apply it automatically.<br />
<br />
=== Creating a Configuration ===<br />
<br />
The simplest way to create a new Configuration is from the context menu of the folder where want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Configuration Model in the wizard. You can then edit the new Configuration with the Setup Editor. You can delete the Installation or Workspace if you don't need that aspect. You can use the Properties view to set the Installation's Product Version or the Workspace's Project Streams. And of course you can create any other setup tasks in either Scope.<br />
<br />
=== Configuration Handling ===<br />
<br />
The specific form of the serialized URLs that are used to reference a Product Version or a Project Stream are very important to correct behavior. Relative URLs in the serialization can only work relative to the location of the Configuration's resource, so will only work when you drag and drop a file or link because a dragging and dropping textual copy of the serialization provides no information about how to resolve relative references. This is not to say there is anything wrong with relative references, just be aware that they imply that the user must apply the overall file or link, not just the textual serialization. <br />
<br />
Another very useful aspect of Configurations is that the wizards handle of the references intelligently. I.e., if a Installation references a Product Version that's not in any Product Catalog in the Index, the Product will automatically be added to the user-extensible Product Catalog. If the Installation references a Product Version via its containing Product Catalog and that Product Catalog is not in the Index, and the redirectable Product Catalog is not already redirected, it will be redirected to the referenced Product Catalog and an appropriate Eclipse Ini redirection tasks will be synthesized so that the installation produced by the installer will be able to resolve the Product Version reference in its Installation via the correct containing Product Catalog. Analogous processing is done for the Project Stream references with the additional processing of Project's a logical Project container which determines which Project Catalog's extensible Project container is used. In other words, Configurations can also be used to automate the addition of Products and Projects to the user extensible catalogs.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Getting Early Feedback ===<br />
Why didn't the model editor tell me earlier that I've made a silly mistake?<br />
Please enable Live Validation in the editor menu to get early feedback.<br />
Also make use of the Outline view because it provides a preview of the tasks that will be executable and will diagnose problems such as undeclared variables, e.g., using <tt>${foo.bar}</tt> but not having a corresponding variable declaration for <tt>foo.bar</tt>.<br />
<br />
=== Testing a Setup in a Clean Environment ===<br />
<br />
Over time, many or most of your prompted variables will be saved in the user.setup.<br />
To test your setup in an environment that simulates what a brand new user will experience, you can launch the installer as follows:<br />
<br />
<eclipse-inst-executable> -vmargs -Duser.home=<absolute-user-home-folder> -Doomph.setup.user.home.redirect=true<br />
<br />
This also works for the self-extracting native Windows executable as well as for the eclipse-inst executable in extracted Eclipse Installer's folder. <br />
The value <tt><absolute-user-home-folder></tt> of the system property <tt>user.home</tt> should be an absolute path what will become the user home folder; it will be created if it doesn't exist.<br />
The value <tt>true</tt> of the system property <tt>oomph.setup.user.home.redirect</tt> will direct the installer to include the <tt>-Duser.home=<absolute-user-home-folder></tt> argument in the eclipse.ini of the created installation so that it too behaves as if that folder were its user home folder.<br />
<br />
In this fashion you can test in a clean environment and you can discard <tt><absolute-user-home-folder></tt> without impacting your real environment.<br />
<br />
=== Copying Tasks and Other Elements ===<br />
The Setup Editor supports the export and import of any model elements by using copy to or paste from the clipboard. The clipboard will/must contain a valid XML document. With this method, for example, you can easily copy task snippets from your model directly into a forum post when you ask for help (or into a Skype window when you chat with your collegues). Or you can easily paste such XML snippets from forum replies directly into your Setup Editor.<br />
<br />
You have access to many example setups from within your IDE! Use Navigate->Open Setup->Parent Models->Open Catalog Index to investigate everything within the index. The context menu provides a way to open elements in a text editor. This is particularly handy for finding out where a particular setup is hosted (hrefs are resolved in the Setup editor) - one use case is checking and repairing links to project setups added to your user projects.<br />
<br />
=== Hosting your own index / catalogs ===<br />
If you want to host your own product or project catalog, you must provide a URI mapping to the installer to locate the root setup file (the "index"). Open the eclipse.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, or use the wizard to create it. 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/. You can redirect to your own index with this redirection system property:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->http://<hostname>/<path>/</nowiki><br />
<br />
The source URI may be abbreviated to <nowiki>index:/</nowiki> and the target URI may also be a file URI, e.g. on a shared file server.<br />
<br />
In general it will be highly desirable to archive your setup, but documentation for that is TBD. The installer and other setup wizards support dragging and dropping an index or archived index onto the title area of the dialog. Documentation for that is also TBD.<br />
<br />
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=481580 Bug 481580] has introduced empty redirectable catalogs for products ('''redirectable.products.setup''') and projects ('''redirectable.projects.setup''') to the Oomph index. These allow providing your own catalogs without replacing the entire index or disabling the catalogs shipped with Oomph (by redirecting them). The following steps are necessary to make use of those setups.<br />
* Create your own project catalog setup file using the wizard. Project setups in the project catalog should typically be referenced using absolute URIs, otherwise redirection can become problematic. However, if the relative references are downward pointing to some uniquely named folder different from any of the file/folder names in the Eclipse.org index, i.e., no '''..''' traversal to the parent folder is involved and some folder name '''<my-projects-folder>''', then they will be resolved to absolute URIs of the form '''index:/<my-projects-folder>/<path>''' which can be handled as described below.<br />
* Add a redirection system property similar to that described above to the eclipse.ini file, e.g., '''-Doomph.redirection.myProjectCatalog=index:/redirectable.projects.setup->...'''.<br />
* If the projects in that catalog are referenced by relative downward references with a unique folder, also add a folder redirection system property, e.g.,'''-Doomph.redirection.myProjectCatalog=index:/<my-projects-folder>/->.../''', to redirect the locations of the referenced projects to the folder where they are physically hosted.<br />
* Your catalog setup file must contain an Eclipse Ini task creating the same redirection(s)! Otherwise your catalog (or the referenced projects) will not be visible in the Eclipse created by the installer and hence the projects selected from it cannot be provisioned.<br />
* The first time, you may have to enable your new catalog by selecting it in the folders icon of the drop-down in the upper right hand corner of the wizard's Projects page, otherwise it will be invisible.<br />
<br />
To debug the processing of -Doomph.redirection.* if needed, set a breakpoint in org.eclipse.oomph.setup.internal.core.util.SetupCoreUtil.configureResourceSet(ResourceSet) within if (((String)key).startsWith(SetupProperties.PROP_REDIRECTION_BASE)).<br />
<br />
=== Shipping your own index ===<br />
If you want to include your own product or project catalog, you may ship the root setup file (the "index") relative to the installer directory. Then you can redirect the index as explained in [[#Hosting your own index / catalogs| Hosting your own index / catalogs]]. For example, you can place all setup files in an eclipse-installer/setups/ folder and then redirect access to it with a relative target URI:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->setups/</nowiki><br />
<br />
Note that shipping the index rather than maintaining it in a central location (accessible to all parties interested) has the following disadvantage. As each user has her own copy of the index, updates in the setup files will not be distributed automatically.<br />
<br />
=== Accessing Setups that Require Authentication ===<br />
<br />
If basic authentication is used to access a setup, Oomph will generally prompt for the credentials and offer to store it in secure storage for future reuse, <br />
but only if the host responds with authorization request.<br />
Some hosts do not do so for security reasons, i.e., to hide the fact that anything exists at the specified URI.<br />
In that case you will need to specify the URI in such a way that directs Oomph to use basic authentication<br />
<br />
https://example.org/owner/repo/raw/master/path/Example.setup?oomph_basic_auth=true<br />
<br />
If form-based authentication is required, you will need to specify the URI to access the setup in such a way that it directs Oomph to the appropriate login/sign-in form <br />
in order to acquire the necessary cookies for an authenticated session.<br />
<br />
https://gitlab-example.com/project/raw/branch/repo-path/Example.setup?oomph_form=b%27users/sign_in%27#/<br />
https://github.com/ower/repo/raw/master/path/Example.setup?oomph_form=b'login'#/<br />
<br />
In this case too, Oomph will then prompt for the credentials and post them to the form.<br />
<br />
I show the %27 as an alternative to ' because if you provide the link to the setup via a web page, the process of copying the link might convert to that form, even if you've used ' rather than the equivalent %27 encoding of it.<br />
<br />
You can "debug" how this works using org.eclipse.oomph.setup.internal.core.util.ECFURIHandlerImpl.Main.main(String[]) in the org.eclipse.oomph.setup.core bundle. <br />
Currently around [https://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.setup.core/src/org/eclipse/oomph/setup/internal/core/util/ECFURIHandlerImpl.java#n2124 here].<br />
<br />
=== Generating PDE Target Definition files (*.target) and their use by Tycho ===<br />
<br />
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. <br />
<br />
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:<br />
<br />
<annotation<br />
source="http:/www.eclipse.org/oomph/targlets/TargetDefinitionGenerator"><br />
<detail<br />
key="location"><br />
<value>${git.clone.location}/targetdefinition/DesignStudio.target</value><br />
</detail><br />
<detail<br />
key="extraUnits"><br />
<value>org.eclipse.equinox.executable.feature.group</value><br />
</detail><br />
<detail<br />
key="includeAllPlatforms"><br />
<value>false</value><br />
</detail><br />
<detail<br />
key="includeSource"><br />
<value>true</value><br />
</detail><br />
<detail<br />
key="generateVersions"><br />
<value>true</value><br />
</detail><br />
</annotation><br />
<br />
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.<br />
<br />
''TODO Document what preferredRepositories, PomModulesUpdater & PomArtifactUpdater do...''<br />
<br />
=== Setting up WST Server Runtime and Instances in your Setup ===<br />
<br />
==== Server Runtime Preference ====<br />
<br />
1. Use an oomphed installation/workspace with preference recorder enabled.<br />
<br />
2. Open your project and user setup editors.<br />
<br />
3. Go to Preferences / Server / Runtime Environments and 'Add' it as usual.<br />
<br />
4. Drag the selected '/instance/org.eclipse.wst.server.core/runtimes' from user to project setup.<br />
<br />
Note: It's unclear if the above actually works. Please see thread https://www.eclipse.org/forums/index.php/t/1086488/ in forum for details.<br />
For some servers there are extension tasks to handle configuration, see below.<br />
<br />
==== Server Instance in Servers View ====<br />
Requires server runtime to be setup first.<br />
<br />
1. Open Servers View and create New server instance and deploy webapps as usual<br />
<br />
2. Optionally open server instance editor and adapt configuration as usual.<br />
<br />
3. Close Eclipse.<br />
<br />
4. Start it again.<br />
<br />
5. Open '.plugins/org.eclipse.wst.server.core/servers.xml' from your workspace/.metadata using a UTF capable editor<br />
<br />
6. Add Resource Creation Task to your setup:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
content="PUT_CONTENT_FROM_SERVERS_XML_INTO_HERE_USING_A_UTF_CAPABLE_EDITOR_AND_OOMPH_DIALOG"<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.wst.server.core/servers.xml"<br />
encoding="UTF-8"><br />
<description>tomcat server integration</description><br />
</setup:ResourceCreationTask><br />
<br />
7. Use the resource task content dialog to put the servers xml content into the task.<br />
<br />
8. Copy "Servers" project from this workspace into a suitable location of your branch checkout and add/commit/push.<br />
<br />
9. Setup project import task that can pick the Servers project up from that committed location.<br />
<br />
That's it. If you want to share it among fellows, be sure to agree on canonical paths for your server installations.<br />
<br />
==== Extension tasks for specific servers ====<br />
<br />
For some servers there are oomph extension tasks that can be used to handle the configuration:<br />
<br />
https://github.com/gratex/oomph-task-server - Tomcat, WebLogic, and WebSphere<br />
<br />
=== Suppress prompt for default workspace already upon very first start ===<br />
<br />
Adjust the SHOW_WORKSPACE_SELECTION_DIALOG property to false via configuration settings org.eclipse.ui.ide.prefs ...<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP MANUAL"<br />
content="MAX_RECENT_WORKSPACES=5&amp;#xD;&amp;#xA;RECENT_WORKSPACES=${workspace.location|property}&amp;#xD;&amp;#xA;RECENT_WORKSPACES_PROTOCOL=3&amp;#xD;&amp;#xA;SHOW_WORKSPACE_SELECTION_DIALOG=false&amp;#xD;&amp;#xA;eclipse.preferences.version=1"<br />
targetURL="configuration:/.settings/org.eclipse.ui.ide.prefs"<br />
encoding="UTF-8"/><br />
<br />
=== Open default perspective already upon very first start ===<br />
Examples below using Perspective ID for Java perspective.<br />
<br />
Tell Eclipse which perspective to open initially, by adding option to eclipse ini:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:EclipseIniTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP"<br />
option="-perspective"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
Setting a perspective to be default, by adding preference task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:PreferenceTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
key="/instance/org.eclipse.ui/defaultPerspectiveId"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
=== How to switch the current stream ===<br />
<br />
If you would like to switch the current stream/s, you can re-use Oomph's initial "Eclipse Importer" wizard, available as "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace.<br />
<br />
Note that it is currently not yet possible to remove the "current" project stream. As a workaround, use menu Navigate > Open Setup > Open Workspace (or if visible click the 'blue guy' icon in the Oomph toolbar) to Open Workspace workspace.setup, expand the first node, click on the Workspace entry, open Properties view, and change the last property named "Streams" and remove the current stream.<br />
<br />
Bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=476434 enhancement may make this easier in the future.<br />
<br />
<br />
=== How to install Eclipse plugins using the P2 Director and Repository Explorer ===<br />
<br />
Oomph can install Eclipse plugins which you require. This also works for normal Java Projects set up models, not just for Eclipse plug in OSGi development, and is handy to install commonly used 3rd-party Eclipse plugins which are not all available from eclipse.org p2 sites (think e.g. http://eclemma.org). Here's how:<br />
<br />
1. add a P2 Director child task to your *.setup, if it doesn't already have one<br />
<br />
2. add a Repository child in your P2 Director task<br />
<br />
3. in the Properties of the Repository set the URL to a valid p2 repo (e.g. http://update.eclemma.org)<br />
<br />
4. right-click that Repository and choose Explore, to open the Repository Explorer view<br />
<br />
5. in the Repository Explorer view change to [X] Compatible and (*) Minor at the lower-right hand corner<br />
<br />
6. drag & drop the version from the Repository Explorer view into the P2 Director task of your *.setup editor, to create a Requirement child<br />
<br />
Drag & Drop should normally work, but appears to be broken at least on Neon Milestone 6 on Linux; in that case:<br />
<br />
6. manually create a new child Requirement inside the P2 Director task<br />
<br />
7. in the Repository Explorer view use the brown (C) icon to switch to Expert Mode to see IDs instead of names<br />
<br />
8. find the ID of the feature IU, it's the one with a PDE feature + folder kind of icon, often ending in (feature.)feature.group<br />
<br />
9. in the Properties of the Requirement, type the Name to the ID found above (e.g. com.mountainminds.eclemma.feature.feature.group)<br />
<br />
10. in the Properties of the Requirement, Type should have automatically switched to Feature<br />
<br />
PS: If you are looking for the URL of p2 repos to pre-install some of the the M2E connectors, see https://git.eclipse.org/c/m2e/m2e-discovery-catalog.git/tree/org.eclipse.m2e.discovery.oss/connectors.xml<br />
<br />
<br />
<br />
=== How to create M2E lifecycle-mapping-metadata.xml to avoid littering your pom.xml with org.eclipse.m2e:lifecycle-mapping ===<br />
<br />
Read https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html & https://wiki.eclipse.org/M2E_compatible_maven_plugins and apply as follows:<br />
<br />
<setupTask<br />
xsi:type="setup:PreferenceTask"<br />
key="/instance/org.eclipse.m2e.core/eclipse.m2.WorkspacelifecycleMappingsLocation"<br />
value="${workspace.location}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"/><br />
<br />
<setupTask<br />
xsi:type="setup:ResourceCreationTask"<br />
content="..."<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"<br />
encoding="UTF-8"><br />
<description>Initialize M2E's Maven Lifecycle Mappings, see https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html &amp; https://wiki.eclipse.org/M2E_compatible_maven_plugins</description><br />
</setupTask><br />
<br />
For "content" just open the popup using the [...] icon in the Properties and copy/paste the content from menu Window > Preferences > Maven > Lifecycle Mappings: Open workspace lifecycle mappings metadata. (This is easier than editing the content=".." in source view, because it will correctly do the XML escaping for you.)<br />
<br />
Now whenever M2E whines about stuff like "Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-dependency-plugin:2.10:unpack (execution: unpack-license, phase: generate-resources)" etc. just use the Quick Fix in the Problems view and choose the option to use workspace preferences (instead of letting the quick fix modify your pom.xml to add org.eclipse.m2e:lifecycle-mapping <lifecycleMappingMetadata>).<br />
<br />
<br />
=== How to automatically pre-enable Gerrit ===<br />
<br />
If you would like to save your end-users from having to [[EGit/User_Guide#Enabling_Gerrit_for_a_repository|manually enabling Gerrit for a repository in EGit]], then you can use the follow magic variable which Oomph will recognize and act upon:<br />
<br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="YOURORG.gerrit.uri.pattern"<br />
value="(https|ssh)://([^@/]+@)?(git.YOURORG.org:29418/.*|git.YOURORG.org/gerrit/.*)"/><br />
<br />
=== How to find a P2 repository at Eclipse using the Repository Explorer ===<br />
<br />
Most projects don't document the locations of all their p2 update sites very well. This makes it hard to find the URL you need in order to install something or in order to specify a URL for your target platform definition. Oomph indexes all the p2 update sites available at download.eclipse.org to make this job easier. You can make use of this as follows:<br />
<br />
# In the Quick Access control, type "Repository Explorer" to show Oomph's Repository Explorer view.<br />
# In that view's toolbar, locate the tool item with the hover "Search Eclipse repositories by provided capabilities", i.e., the one that looks like a little search flashlight, and click it.<br />
# This brings up the "Eclipse Repository Search" dialog. The index is very large so it takes a while to load it. But it's cached locally and updated on the server once per day.<br />
# At the root of the displayed tree are p2's namespaces and under each of these are the capabilities in that namespace. They're organized hierarchically by their qualified name. It's all quite technical and the tree is very large. So while you can explore it, you'll most likely want to use the filter to find something quickly.<br />
# Type the fully qualified name of a Java package or installable unit you wish to locate into the filter. Note that tree items for which there exist a concrete version in some repository are decorated as such. Keep in mind that many projects don't version their Java packages, so it's often better to look at the org.eclipse.equinox.p2.iu category. Here's what it looks like searching for "org.eclipse.emf.ecore.xcore":<br>[[File:SearchEclipseRepositoryDialog.png]]<br><br />
# You can select a capability in the tree so that the lower panel displays all the versions of the capability that are available. Under each of those are nested the update sites that contain them. Composite update sites show their children hierarchically.<br />
# Of course you can double click a repository to further explore its contents in the Repository Explorer itself.<br />
<br />
<br />
=== How to extract the constituent parts that comprise the Windows self-extracting installer executable ===<br />
<br />
The Eclipse Installer distribution for the Windows platform is effectively a self-extracting executable. It is extracted at runtime by the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINExtractor.java Bin Extractor]. The pre-built version of this library, i.e., org.eclipse.oomph.extractor.lib-*.jar, is available in all Oomph-containing installations, i.e., in the installer itself and in applications installed by the installer. This library can also be used standalone to decompose the composed executable into its constituent parts. That can be accomplished if you run it with the correct magical program arguments as follows:<br />
<br />
java -classpath <path-to-extract-lib>\org.eclipse.oomph.extractor.lib-*.jar<br />
org.eclipse.oomph.extractor.lib.BINExtractor <br />
<path-to-executable-to-extract>\eclipse-inst-win64.exe <br />
<target-path>\product.zip <br />
-export <br />
<target-path>\marker.txt <br />
<target-path>\extractor.exe <br />
<target-path>\org.eclipse.oomph.extractor.lib.jar <br />
<target-path>\product-descriptor<br />
<br />
The Java VM arguments need only specify the extractor library along with the main class in that library. The first program argument is the location of the executable you wish to decompose, the 64 bit installer in this case. The remaining arguments are all best directed into a common folder, denoted as <target-path> in the example above. The second argument is the extracted location of the zip file of the product/distribution. The third argument is the -export flag. The fourth argument is the extracted location of the text file containing the marker text that is used to delimit the constituent parts of the composed executable. The fifth argument is the extracted location of the small native executable itself. The sixth argument is the extracted location of the extractor library, the same one being used to extract the parts. The seventh and final argument is the extracted location of the product descriptor. Such a [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINDescriptor.java descriptor] looks like this:<br />
<br />
1<br />
1<br />
7<br />
0<br />
64<br />
0<br />
eclipse-inst.exe<br />
eclipse-inst.ini<br />
Eclipse Installer<br />
http://wiki.eclipse.org/Eclipse_Installer<br />
http://download.eclipse.org/oomph/jre/128x128.png<br />
<br />
Of course you can edit these parts and then you can recompose the executable using the following cmd script executed within the common folder in which you have extracted the constituent parts:<br />
<br />
COPY /B extractor.exe + ^<br />
marker.txt + ^<br />
org.eclipse.oomph.extractor.lib.jar + ^<br />
marker.txt + ^<br />
product-descriptor + ^<br />
marker.txt + ^<br />
product.zip + ^<br />
marker.txt ^<br />
eclipse-inst-64.exe<br />
<br />
Our builds use the [https://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/releng/org.eclipse.oomph.releng/hudson/postprocess.sh postprocess.sh] to do this processing.<br />
One issues that's important in terms of signing, is that the extractor.exe that you've extracted above will already contain a signature and this might well cause signing of the composed executable fail. So our script actually uses the following to fetch the executable from Git:<br />
<br />
curl -O https://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/plugins/org.eclipse.oomph.extractor/extractor-64.exe<br />
<br />
Note that the file names match the extracted target file names. From this is should be clear that the native executable is just a composition of parts. This structure is used at runtime as follows. The extractor.exe runs natively, reading its own executable file, using the marker text to find the parts. It checks the descriptor to determine if an appropriate version of Java is already installed, i.e., one that will be able to launch the product; the native extractor consults the registry to find all installed JREs and JVMs. If an appropriate Java is not found, it opens a browser page prompting the user to install an appropriate Java version with the required bitness and at the minimum required version. If there is already an appropriate version of Java, it launches a Java process to execute the BinExtract's main method. That process in turn unzips the product zip to a temp folder and launches the Java process for that for the product/distribution.<br />
<br />
== Oomph Configuration Options ==<br />
<br />
=== Configuration Options for Installer .ini File ===<br />
<br />
{| class="wikitable"<br />
| '''-Doomph.redirection.setups''' || Redirects the location of setup files (index, catalog and products). The default URI is ''http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/'' and my be abbreviated with '''index:/'''. The syntax of the redirection is '''index:/->[redirection URI]'''. Examples: '''-Doomph.redirection.setups=index:/->http://<hostname>/<path>/''' (external server redirection) or '''-Doomph.redirection.setups=index:/->setups/''' (path relative to installer executable). See also [[#Hosting_your_own_index_.2F_catalogs|Hosting your own index & catalogs]]<br />
|-<br />
| '''-Doomph.setup.product.catalog.filter''' || Only displays product catalogs matching the given prefix. The default is ''org\\.eclipse\\.products''. Displays all catalogs if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.filter''' || Only displays products matching the given prefix. The default is ''(?\!org\\.eclipse\\.products\\.org\\.eclipse\\.platform\\.ide).*''. Displays all products if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.version.filter''' || Only displays product versions matching the given prefix. The default is ''.*\\.neon''. Displays all product versions if value is empty.<br />
|-<br />
| '''-Doomph.p2.pool''' || Set to ''@none'' to disable bundle pools. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=507594] for details.<br />
|}<br />
<br />
== Troubleshooting ==<br />
=== The preference task does not setup any preferences ===<br />
<br />
First of all. Please note that the preferences are not set up as part of the installation. They are setup when the installed eclipse is first started.<br />
<br />
To do this the installed product needs to have the following feature installed:<br />
''org.eclipse.oomph.setup.feature.group''<br />
<br />
The feature is already included in the root of the Eclipse.org Product Catalog. If you are not using it you can include the same task by yourself:<br />
<br />
<setup.p2:P2Task<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup.p2="http://www.eclipse.org/oomph/setup/p2/1.0"><br />
<requirement<br />
name="org.eclipse.oomph.setup.feature.group"/><br />
<repository<br />
url="${oomph.update.url}"/><br />
</setup.p2:P2Task></div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Oomph&diff=433354Oomph2019-07-12T15:26:29Z<p>Stepper.esc-net.de: /* Frequently Asked Questions */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">Powered by Oomph</span><br />
<br />
The [http://www.eclipse.org/oomph Oomph Project] is dedicated to providing extensions to the Eclipse Platform that improve the user experience.<br />
<br />
One of Oomph's show case technologies is the [[Eclipse_Installer|Eclipse Installer]].<br />
The installer exploits Oomph's flexible and powerful [[Eclipse_Oomph_Authoring#Understanding the Setup Engine|setup engine]] to automate the installation of applications as well as the provisioning of workspaces.<br />
For an overview of this technology in action on a very large useful example, have a look a the instructions for [[Eclipse_Platform_SDK_Provisioning|Provisioning the Platform SDK]] which creates a dedicated installation for working the source code of all projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]].<br />
<br />
Note that the latest version of the installer supports [[Eclipse_Installer_Marketplace#Apply_a_Marketplace_Listing|installing Marketplace listings]].<br />
<br />
== Eclipse Installer ==<br />
<br />
The [[Eclipse_Installer|Eclipse Installer]] can be used to create specialized installations and to provision customized workspaces.<br />
<br />
[[Image:OomphSimpleInstaller2.png]]<br />
<br />
== Features ==<br />
<br />
The following technologies are supported by Oomph:<br />
<br />
* [[Oomph_Targlets|Targlets]] provide a more expressive, flexible, scalable, and reliable infrastructure for defining a target platform.<br />
* [[Dynamic_Working_Sets|Dynamic Working Sets]] provide the ability to create project working sets based on flexible predicates (rules) for specifying which projects should be in each particular working set.<br />
<br />
== Update Sites ==<br />
<br />
We offer three types of drops: release, milestone, and nightly. They can be found in these composite repos:<br />
<br />
* [http://download.eclipse.org/oomph/updates/release http://download.eclipse.org/oomph/updates/release]<br />
* [http://download.eclipse.org/oomph/updates/milestone http://download.eclipse.org/oomph/updates/milestone]<br />
* [http://download.eclipse.org/oomph/updates/nightly http://download.eclipse.org/oomph/updates/nightly]<br />
<br />
<br />
The following is an uber composite of the three above composites:<br />
<br />
* [http://download.eclipse.org/oomph/updates http://download.eclipse.org/oomph/updates]<br />
<br />
<br />
For each of the four composite repos we offer a smaller variant that contains only the latest drop:<br />
<br />
* [http://download.eclipse.org/oomph/updates/release/latest http://download.eclipse.org/oomph/updates/release/latest] (contains only the latest release build)<br />
* [http://download.eclipse.org/oomph/updates/milestone/latest http://download.eclipse.org/oomph/updates/milestone/latest] (contains only the latest milestone build)<br />
* [http://download.eclipse.org/oomph/updates/nightly/latest http://download.eclipse.org/oomph/updates/nightly/latest] (contains only the latest nightly build)<br />
* [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest] (contains only the latest build)<br />
<br />
<br />
The single drops are individually available under '''http://download.eclipse.org/oomph/drops''' as follows:<br />
<br />
[[Image:OomphDrops.png]]<br />
<br />
Note that at most five nightly drops are kept and that milestone drops are only kept until shortly after the next release.<br />
<br />
<br />
== Authoring Setup Models ==<br />
<br />
Please read [[Eclipse Oomph Authoring|Oomph Authoring Guide]].<br />
<br />
<br />
== Frequently Asked Questions ==<br />
<br />
Please read the [[Eclipse Oomph FAQ|FAQ]], learn from the [[Eclipse Oomph Authoring#Tips and Tricks|authoring tips and tricks]], or revisit our [http://download.eclipse.org/oomph/help help center].<br />
<br />
== Getting in Touch ==<br />
<br />
First browse the [[Eclipse Oomph FAQ|FAQ]] to see if your question has already been answered.<br />
<br />
<br />
As a '''user''' you should post your questions and comments to the public forum:<br />
* Web: [http://www.eclipse.org/forums/eclipse.oomph http://www.eclipse.org/forums/eclipse.oomph]<br />
* Newsgroup: [news://news.eclipse.org:119/eclipse.oomph news://news.eclipse.org:119/eclipse.oomph]<br />
<br />
<br />
You can also monitor the '''developer''' mailing list or discuss development topics:<br />
* Archive: [https://dev.eclipse.org/mhonarc/lists/oomph-dev https://dev.eclipse.org/mhonarc/lists/oomph-dev]<br />
* Mail: [mailto:oomph-dev@eclipse.org mailto:oomph-dev@eclipse.org]<br />
* Newsgroup: [news://news.gmane.org:119/gmane.comp.ide.eclipse.oomph.devel news://news.gmane.org:119/gmane.comp.ide.eclipse.oomph.devel]<br />
<br />
<br />
If you encounter '''trouble''' or miss a '''feature''' please:<br />
* Search for [https://bugs.eclipse.org/bugs/buglist.cgi?classification=Tools&list_id=8268012&product=Oomph&query_format=advanced existing bugzillas] to avoid duplication.<br />
* You can [https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email watch] the <code>oomph-inbox@eclipse.org</code> user to be notified about new bugzillas.<br />
* If nothing else helps kindly submit a new [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0 bug report] or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0&bug_severity=enhancement feature request].<br />
<br />
<br />
== Contributing to Oomph ==<br />
<br />
Please read the [[Oomph Contribution Guide|Oomph Contributor Guide]].<br />
<br />
<br />
== Tutorials ==<br />
<br />
* [[Eclipse_Platform_SDK_Provisioning|Provisioning the Platform SDK]]<br />
* [http://eclipsesource.com/blogs/tutorials/oomph-basic-tutorial/ Oomph Basic Tutorial] by Jonas Helming (December 2016)<br />
* [http://www.lorenzobettini.it/2015/10/oomph-setup-for-xtext-projects Oomph setup for Xtext projects] by Lorenzo Bettini (October 10th, 2015)<br />
* [https://www.youtube.com/watch?v=GRKhxroJsS8 The Eclipse Installer] by Martin Ambrus, a short presentation video of the Oomph-powered Eclipse Installer (August 2015)<br />
* [http://thecodingflow.com/?p=50 Create your own product] by Florian Thienel (July 5th, 2015)<br />
* [http://thegordian.blogspot.de/2015/06/oomph-workshop-eclipse-way-you-want-it.html Oomph Workshop: Eclipse the Way You Want It] by Eike Stepper (June 21st, 2015)<br />
* [http://www.lorenzobettini.it/2015/05/using-the-new-eclipse-installer Using the New Eclipse Installer] by Lorenzo Bettini (May 11th, 2015)<br />
* [http://github.com/joergreichert/oomph-catalogue Walk-Through with Many Examples] by Jörg Reichert (March 22nd, 2015)<br />
* [http://community.bonitasoft.com/blog/how-configure-mylyn-task-queries-atlassian-jira-connector-oomph-installer How to configure Mylyn Task Queries for an Atlassian JIRA Connector with Oomph Installer] by Aurelien Pupier (September, 2014)<br />
* [http://blogs.itemis.de/leipzig/archives/936 Quicker Start Guide for Oomph] by Philipp Hauer and Alexander Nittka (June 30th, 2014)<br />
* [http://www.winklerweb.net/index.php/blog/12-eclipse/20-creating-custom-installations-with-oomph Creating Custom Installations with Oomph] by Stefan Winkler (April 1st, 2014)<br />
<br />
<br />
== Articles ==<br />
<br />
* [http://eclipsesource.com/blogs/2015/06/24/top-10-eclipse-mars-features Top 10 Eclipse Mars Features] by Ian Bull (June 24th, 2015)<br />
* [http://blog2.vorburger.ch/2015/06/using-oomphs-bleeding-edge-nightly.html Using Oomph's bleeding edge nightly builds] by Michael Vorburger (June 2015)<br />
* [http://gradot.wordpress.com/2015/06/01/eclipse-installer-avec-oomph Eclipse Installer avec Oomph] by Pierre Gradot (June 1st, 2015)<br />
* [http://www.infoq.com/news/2015/03/eclipse-oomph Install Eclipse Projects with a lot more Oomph] by Alex Blewitt (March 21st, 2015)<br />
* [http://www.eclipse.org/community/eclipse_newsletter/2014/november/article2.php Oomph: A Matter of Preference] by Ed Merks (November 2014)<br />
* [http://www.eclipse.org/community/eclipse_newsletter/2014/may/article3.php Eclipse has Oomph] by Eike Stepper (May 2014)<br />
* [http://jaxenter.com/installer-tool-oomph-proposed-as-eclipse-project-107676.html Installer Tool Oomph Proposed as Eclipse Project] by Lucy Carey (March 31st, 2014)<br />
* [http://ed-merks.blogspot.fr/2014/02/shoes-for-shoemaker.html Shoes for the Shoemaker] by Ed Merks (February 14th, 2014)<br />
* [http://jaxenter.de/eclipse-oomph-bringt-schwung-ins-projekt-12977 Eclipse Oomph bringt Schwung ins Projekt] by Eike Stepper (June 26th, 2014)<br />
<br />
<br />
== Videos ==<br />
<br />
* [https://www.youtube.com/watch?v=TU1zjytlwFE OpenDaylight Mini Summit recording of an Oopmh related presentation (June 2016)] Slides from this session are also available [http://www.slideshare.net/mikervorburger/opendaylight-developers-experience-15-eclipse-setup-hot-reload-future-plans on slideshare (faster)] and [https://docs.google.com/presentation/d/14yLzog3OhIlVsk7Clr0Tff1YayRcFnQCUZqxHMWxiNI/ on GDocs in better quality]<br />
* [https://www.youtube.com/watch?v=BLW8aOh6WeQ OpenDaylight.org has Oomph, Eclipse.org Installer for automated workspace provisioning (April 2016)]<br />
* [http://www.youtube.com/watch?v=GRKhxroJsS8 The Eclipse Installer] a short presentation video of the Oomph-powered Eclipse Installer (August 2015)<br />
* [http://www.youtube.com/watch?v=a3h76AQQKN0 Oomph: Eclipse the Way You Want It] a speaker pitch video for the EclipseCon France (June 2015)<br />
* [http://www.infoq.com/interviews/eike-stepper-eclipse-oomph-project Interview with Eike Stepper on the Eclipse Oomph project] by Alex Blewitt (May 27th, 2015)<br />
* [http://www.infoq.com/presentations/oomph Oomph: Eclipse the Way You Want It] session recording and slides from the EclipseCon North America (May 21st, 2015)<br />
* [http://www.youtube.com/watch?v=M6ZnL2mO88Q Papyrus Oomph Model Refinements] by Christian Damus (July 8th, 2014)<br />
* [http://www.youtube.com/watch?v=hgKjzr2pXzI Provisioning a Papyrus Development IDE with Oomph] by Christian Damus (July 6th, 2014)<br />
* [http://www.youtube.com/watch?v=_QlSosecEUo&list=UUej18QqbZDxuYxyERPgs2Fw Oomph: Automatically Provision a Project-specific IDE] a video recording of the talk at the EclipseCon France (June 2014)</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Installer_Marketplace&diff=433284Eclipse Installer Marketplace2019-07-03T04:54:51Z<p>Stepper.esc-net.de: </p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to use the [[Eclipse_Installer|Eclipse Installer]] to install [https://marketplace.eclipse.org/ Marketplace] listings.<br />
<br />
If you encounter problems or have suggestions for improvements, please use [https://bugs.eclipse.org/bugs/show_bug.cgi?id=548868 Bug 548868] for that purpose.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the Eclipse Installer on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated; support for Marketplace is new to Oomph version 1.14. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update:<br />
<br />
[[File:Oomph_Installer_Simple_Update.png]]<br />
<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
[[File:Oomph_Installer_Advanced_Update.png]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures in the following section.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Apply a Marketplace Listing ==<br />
<br />
Open the [https://marketplace.eclipse.org/ Marketplace] web page and use it to locate the listing you wish to install, e.g., [https://marketplace.eclipse.org/content/darkest-dark-theme-devstyle Darkest Dark Theme with DevStyle].<br />
Each listing has an Install icon that you can drag from the browser and drop onto the title area of the installer.<br />
<br />
[[File:Oomph_Installer_MarketplaceListing_Example.png]]<br />
<br />
You can even drag and drop the URL of the listing itself, so, as an example, <br />
you can drag and drop [https://marketplace.eclipse.org/content/darkest-dark-theme-devstyle this link].<br />
<br />
As an alternative to drag-and-drop, you can copy the link, and apply it to the installer. <br />
In simple mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid Marketplace listing:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_MarketplaceListing.png|800px]]<br />
<br />
Note that the menu has a convenient link for opening the Marketplace in your favorite browser.<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid Marketplace listing:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
After dropping the link or applying the link, the Marketplace Install dialog will appear.<br />
<br />
== Configure a Marketplace Listing ==<br />
<br />
Initially the OK button will be disabled while the p2 repository loads.<br />
At this point, only the installable units IDs are available and displayed.<br />
<br />
[[File:Oomph_Installer_MarketplaceListing_Dialog_Loading.png]]<br />
<br />
When the repository is loaded, the detailed information becomes available and the OK button will be enabled.<br />
<br />
[[File:Oomph_Installer_MarketplaceListing_Dialog_Loaded.png]]<br />
<br />
You can hover over each feature to see its description.<br />
Note that the features in bold are so-called required features so you cannot deselect them.<br />
<br />
You can of course add multiple listings to the installer before proceeding with the installation of your selected product.<br />
The Marketplace is full of goodies!<br />
<br />
== Automation the Installation Process ==<br />
<br />
A wiki describing how the entire installation processed can be automated will be available soon.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Oomph_Authoring&diff=432503Eclipse Oomph Authoring2019-05-26T08:05:57Z<p>Stepper.esc-net.de: /* Using a Macro with a Macro Expansion Task */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
== Getting Started ==<br />
<br />
=== What is Oomph? ===<br />
<br />
Please read [[Eclipse Installer]].<br />
<br />
<br />
=== Installing Oomph ===<br />
<br />
# Download and install the Eclipse '''Installer''' as outlined in [[Eclipse Installer]].<br />
# Make sure that the Oomph setup '''SDK''' is installed in your IDE. Either:<br />
## That's already the case because your IDE is a Mars M5 or later Eclipse Package, or<br />
## Start the installer and install an IDE of your choice (select on the first installer page), or<br />
## Use p2 to install "Oomph Setup SDK" from [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest].<br />
<br />
== Creating a Setup Project Model ==<br />
<br />
=== Using the Setup Project Model Wizard ===<br />
<br />
# Create an empty project in your workspace or select a folder in an existing project. You'll create the new "Setup Project Model" in the selected folder.<br />
# Open the New... dialog and select the "Setup Project Model" wizard:<br>[[Image:new-wizard.png]]<br><br />
# Select one of the provided templates (e.g., Eclipse.org, Github.com, or Simple) and adjust the displayed values:<br>[[Image:new-wizard-2.png]]<br><br />
# Some values are automatically derived from your input to fields '''higher up'''.<br />
# Open the Preview>>> to understand the impact of changes to the current field.<br />
<br />
=== Using the Setup Editor ===<br />
<br />
# Open the resulting setup file with Oomph's Setup Editor:<br>[[Image:setup-edit.png]]<br><br />
# Configure the tasks in the Properties view. Note that there are "Expert" properties available.<br />
# Add setup tasks to your project and/or to your project streams and configure them, too.<br />
# The Outline view displays a ''preview'' of the executable model with resolved variables.<br />
<br />
=== Testing the Setup Model ===<br />
<br />
# To test/execute your new setup model:<br />
## Start the installer and, if necessary, switch to the Advanced Mode via the dialog menu.<br />
## Pick any product on page 1 and click the Next button to proceed to page 2.<br />
## Drag and drop your <tt>.setup</tt> file onto one of the top-level catalogs (<tt>Eclipse.org</tt> or <tt>Github.com</tt>) in the projects tree. Your project will appear as a subproject of the special <tt>&lt;User&gt;</tt> project.<br />
## Double-click your project to add it to the table at the 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.<br />
## Fill in the empty fields and press the Next button to proceed to the Confirmation page.<br />
## 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.<br><br />
# 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 [[#Using the Setup Editor|Using the Setup Editor]]. If the IDE comes up but the initial configuration fails continue with step 3.<br />
# In the new IDE (whether the initial configuration was successful or not) open your model file from the main menu, Navigate &rarr; Open Setup &rarr; [[Image:branch.png]]. Find the problems and fix them. Then start the setup process '''from within''' this IDE via the main menu, Help &rarr; [[Image:update.png]] Perform Setup Tasks&hellip;. 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.<br />
<br />
=== Contributing to a Project Catalog ===<br />
<br />
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 http://git.eclipse.org/c] and [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&bug_severity=enhancement&short_desc=Please%20include%20setup%20for%20project%20Xyz 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.<br />
<br />
The same can be done if your project is not an Eclipse project, but hosted on '''GitHub'''. Simply state this fact in the bug description and paste the "raw" content URL to the file instead.<br />
<br />
== Understanding the Setup Engine ==<br />
<br />
=== Understanding Setup Tasks and Scopes ===<br />
<br />
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:<br />
<br />
* The '''Installation''' scope is located in <tt>eclipse/configuration/org.eclipse.oomph.setup/installation.setup</tt> 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.<br />
<br />
* The '''Workspace''' scope is located in <tt>workspace/.metadata/.plugins/org.eclipse.oomph.setup/workspace.setup</tt> 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.<br />
<br />
* The '''User''' scope is located in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup</tt> and contains tasks that are common to '''all''' installations and workspaces (unless they're restricted to particular installations or workspaces).<br />
<br />
<br />
The following additional scope types exist, so they can be referenced by the entry scopes:<br />
<br />
* The '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.setup Catalog Index]''' is the root scope and contains nested Product Catalogs and Project Catalogs.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.products.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/OomphInstaller.setup Product]''' contains nested Product Version scopes and possibly some tasks that are common to all nested scopes.<br />
<br />
* A '''Product Version''' contains no nested scopes but tasks that are specific to that product version.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.projects.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/Oomph.setup Project]''' contains nested Stream and/or (Sub-) Project scopes and typically some tasks that are common to all nested scopes.<br />
<br />
* A '''Stream''' contains no nested scopes but tasks that are specific to that stream.<br />
<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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 [[#Declaring_and_Using_Variables|Declaring and Using Variables]] below.<br />
<br />
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). <br />
<br />
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.<br />
<br />
=== Declaring and Using Variables ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:<br />
<br />
${''variable-name''}<br />
<br />
To prevent a variable reference from being expanded (e.g. you actually want to have the value '${var}' and not the value of "var"), you need to escape the variable syntax with an extra double dollar character. So "$${var}" will result in "${var}".<br />
<br />
In addition to the variables that are declared by VariableTasks you can refer to all of the following:<br />
<br />
* Attribute values of setup tasks with a defined ID. The reference syntax is ${''taskID''.''attributeName''}.<br />
* System properties as returned by <tt>System.getProperties()</tt><br />
* [[#Environment Variables|Environment variables]] as returned by <tt>System.getenv()</tt><br />
* [[#Predefined Variables|Predefined variables]] as determined by the setup engine from the user input to the installer (see below)<br />
<br />
==== Predefined Variables ====<br />
<br />
The following variables are predefined by the setup engine:<br />
<br />
{| class="wikitable"<br />
| '''scope.installation.name''' || The value of the <em>name</em> attribute of the current installation scope. <br />
|-<br />
| '''scope.installation.label''' || The value of the <em>label</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.installation.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.workspace.name''' || The value of the <em>name</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.label''' || The value of the <em>label</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.description''' || The value of the <em>description</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.user.name''' || The value of the <em>name</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.label''' || The value of the <em>label</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.description''' || The value of the <em>description</em> attribute of the current user scope.<br />
|-<br />
| '''scope.product.catalog.name''' || The value of the <em>name</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.label''' || The value of the <em>label</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.description''' || The value of the <em>description</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.name''' || The value of the <em>name</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product scope and its parent scopes.<br />
|-<br />
| '''scope.product.label''' || The value of the <em>label</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.description''' || The value of the <em>description</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.version.name''' || The value of the <em>name</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product version scope and its parent scopes.<br />
|-<br />
| '''scope.product.version.label''' || The value of the <em>label</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.project.catalog.name''' || The value of the <em>name</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.label''' || The value of the <em>label</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.description''' || The value of the <em>description</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.name''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current project scope and its parent scopes.<br />
|-<br />
| '''scope.project.label''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.description''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.stream.name''' || The value of the <em>name</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current stream scope and its parent scopes.<br />
|-<br />
| '''scope.project.stream.label''' || The value of the <em>label</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.description''' || The value of the <em>description</em> attribute of the current stream scope.<br />
|}<br />
<br />
<br />
==== Variable Extensions ====<br />
<br />
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.:<br />
<br />
${installation.location/git/myproject} evaluates to C:\develop\installation1\git\myproject on Windows<br />
<br />
<br />
After the path extension part you can add filter calls with pipe symbols. Filter names are generally case-insensitive. Multiple filters can be chained. Example:<br />
<br />
${installation.location|uri}/git/myproject evaluates to file:/C:/develop/installation1/git/myproject<br />
<br />
<br />
==== Variable Filters ====<br />
<br />
The following filters are currently available:<br />
<br />
{| class="wikitable"<br />
| '''base64''' || <br />
|-<br />
| '''basePath''' || Removes the last segment from a file system path.<br />
|-<br />
| '''camel''' || Converts a qualified name to camel case notation.<br />
|-<br />
| '''canonical''' || Canonicalizes a file system path.<br />
|-<br />
| '''cap''' || Capitalizes the first word of a String value.<br />
|-<br />
| '''capAll''' || Capitalizes all words of a String value.<br />
|-<br />
| '''file''' || Converts a file: URI to an OS-specific file system path.<br />
|-<br />
| '''fileExtension''' || Extracts the file extension from a URI or a file system path.<br />
|-<br />
| '''gitRepository''' || Extracts the name of the repository from a Git URI (excluding a possible .git suffix).<br />
|-<br />
| '''lastSegment''' || Extracts the last segment from a file system path.<br />
|-<br />
| '''length''' || Converts a String to a String that contains the alpha-numerical representation of the length of the original String.<br />
|-<br />
| '''lower''' || Converts all characters of a String value to lower-case.<br />
|-<br />
| '''path''' || Extracts the path segments from a URI.<br />
|-<br />
| '''pathEncode''' || Converts a file system path to a String value that can be used as a file name.<br />
|-<br />
| '''preferenceNode''' || Escapes all forward slashes (/) of a String value, so that the result can be used as a value in preference nodes.<br />
|-<br />
| '''property''' || Escapes all double back slashes (\\) of a String value, so that the result can be used as a value in properties.<br />
|-<br />
| '''propertyValue''' || Interprets the String value as a preference property path and returns the value of that property.<br />
|-<br />
| '''qualifiedName''' || Converts a camel case String value name to a qualified name.<br />
|-<br />
| '''slashDecode''' || Decodes a slashEncoded String value.<br />
|-<br />
| '''slashEncode''' || Encodes all slashes and backslashes of a String value.<br />
|-<br />
| '''trim''' || Removes all whitespace from the beginning and the end of a String.<br />
|-<br />
| '''trimLeft''' || Removes all whitespace from the beginning of a String.<br />
|-<br />
| '''trimRight''' || Removes all whitespace from the end of a String.<br />
|-<br />
| '''trimTrailingSlashes''' || Removes all slashes and backslashes from the end of a String.<br />
|-<br />
| '''upper''' || Converts all characters of a String value to upper-case.<br />
|-<br />
| '''uri''' || Converts a file system path to a file: URI.<br />
|-<br />
| '''uriLastSegment''' || Extracts the last path segment from a hierarchical URI or the authority from an opaque URI.<br />
|-<br />
| '''urlDecode''' || Decodes a URL.<br />
|-<br />
| '''urlEncode''' || URL-encodes a String value.<br />
|-<br />
| '''username''' || Escapes all "at" symbols (@) of a String value, so that the result can be used in URI that contain a username.<br />
|}<br />
<br />
==== Variables from Outer Scopes====<br />
<br />
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:<br />
<br />
* '''jre.location-1.4''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.5''' --> The folder containing a 1.5 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.6''' --> The folder containing a 1.6 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.7''' --> The folder containing a 1.7 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.8''' --> The folder containing a 1.8 compatible JDK/JRE for architecture ${os.arch}<br />
* '''git.user.id''' --> The Eclipse user ID for Git/Gerrit commits<br />
* '''git.author.name''' --> The Eclipse author name for Git/Gerrit commits<br />
* '''git.author.email''' --> The Eclipse author email for Git/Gerrit commits<br />
* '''bugzilla.id''' --> The Eclipse user ID for Bugzilla/Hudson<br />
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson<br />
<br />
<br />
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.<br />
<br />
==== Environment Variables ====<br />
<br />
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.<br />
<br />
=== Conditional Tasks ===<br />
<br />
All setup tasks support filters. Oomph reuses [https://wiki.eclipse.org/Equinox_P2_Resolution#Enablement_filter p2's implementation] of LDAP filters. I.e., it supports a string a representation of LDAP Search Filters, RFC 1960, UMich, 1996,<br />
http://www.ietf.org/rfc/rfc1960.txt<br />
<br />
The filter property of a setup task is an advanced property. To display this property, ensure that the "Show Advanced Properties" is enabled in the Properties view tool bar. The properties of a filter expression can generally refer to any system property or any environment variable. For example, the following filter expression on a task will ensure that it is included only when performing a task on a Linux operating system.<br />
<br />
(osgi.os=linux)<br />
<br />
The latest version of Oomph allows filter properties to refer to the values of variables as defined in the setup itself. For example, this idiom can be used to express if-then-else.<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xmi:XMI xmi:version="2.0"<br />
xmlns:xmi="<nowiki>http://www.omg.org/XMI</nowiki>"<br />
xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"<br />
xmlns:setup="<nowiki>http://www.eclipse.org/oomph/setup/1.0</nowiki>"><br />
<setup:VariableTask<br />
type="BOOLEAN"<br />
name="example.filter"<br />
label="Example Filter"><br />
<description>An example of a variable used to conditionally filter tasks</description><br />
</setup:VariableTask><br />
<setup:CompoundTask<br />
filter="(example.filter=true)"<br />
name="Filter True"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.a"<br />
label="Property A"><br />
<description>The value use for system.property.a</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.a"<br />
value="=${example.variable.a}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is true</description><br />
</setup:CompoundTask><br />
<setup:CompoundTask<br />
filter="(example.filter=false)"<br />
name="Filter False"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.b"<br />
label="Property B"><br />
<description>The value used for system.property.b</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.b"<br />
value="=${example.variable.b}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is false.</description><br />
</setup:CompoundTask><br />
</xmi:XMI><br />
<br />
On the Variables page of the setup wizards, any variable that is used in property of a filter will be displayed in bold. It is significant to note that the value of a so-called filter variable can conditionally affect the presence of other variables. In this example, either variable <code>example.variable.a</code> or <code>example.variable.b</code> (but not both) will be present on the Variables page, depending on the value of the <code>example.filter</code> variable, which is displayed as a checkbox because it is of type <code>BOOLEAN</code>.<br />
<br />
Note that Oomph setup editors support textual copy and paste, so you can copy the above XML and paste it into your setup editor to try it out.<br />
<br />
== Macros and Macro Expansion Tasks ==<br />
<br />
As of Oomph 1.13, released with Eclipse 2019-06, there is support for Macros. A Macro is a Scope, i.e., is a container for setup tasks, and can specify 0 or more Parameters. Each Parameter specifies a name, a description, and optionally a default value. The parameter names can be used as variable references in the setup tasks contained by the Macro.<br />
<br />
=== Creating a Macro ===<br />
<br />
The simplest way to create a new Macro is from the context menu of the folder where you want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Macro Model in the wizard. You can then edit the new Macro with the Setup Editor. You can create Parameters, if desired, and of course you can create any other setup tasks.<br />
<br />
Here is an example of how one could use a Macro for creating a Git Clone task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Macro<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:git="http://www.eclipse.org/oomph/setup/git/1.0"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
xsi:schemaLocation="http://www.eclipse.org/oomph/setup/git/1.0 http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/models/Git.ecore"<br />
name="git.clone"<br />
label="Git Clone"><br />
<setupTask<br />
xsi:type="git:GitCloneTask"<br />
id="git.clone"<br />
remoteName="${remoteName}"<br />
remoteURI="${remoteURI}"<br />
pushURI="${pushURI}"<br />
checkoutBranch="${checkoutBranch}"><br />
<annotation<br />
source="http://www.eclipse.org/oomph/setup/FeatureSubstitution"><br />
<detail<br />
key="restrictToCheckoutBranch"><br />
<value>${restrictToCheckoutBranch}</value><br />
</detail><br />
<detail<br />
key="recursive"><br />
<value>${recursive}</value><br />
</detail><br />
</annotation><br />
<description>${description}</description><br />
</setupTask><br />
<description>The GitClone macro provides a template for creating a clone task</description><br />
<parameter<br />
name="description"><br />
<description>The description of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="pushURI"><br />
<description>The push URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="recursive"<br />
defaultValue="false"><br />
<description>Whether submodules should be recursively cloned</description><br />
</parameter><br />
<parameter<br />
name="remoteName"<br />
defaultValue="origin"><br />
<description>The name of the remote</description><br />
</parameter><br />
<parameter<br />
name="remoteURI"><br />
<description>The remote URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="restrictToCheckoutBranch"<br />
defaultValue="false"><br />
<description>Whether the clone should be restricted to clone only the checkout branch</description><br />
</parameter><br />
<parameter<br />
name="checkoutBranch"><br />
<description>The name of the branch that the Git clone task to checks out</description><br />
</parameter><br />
</setup:Macro><br />
<br />
Special support is provided for defining so called local Variables in a Macro. Any Variable with a name that starts with '*' will be handled in a special way during [[#Macro Expansion Processing|Macro Expansion]].<br />
<br />
=== Using a Macro with a Macro Expansion Task ===<br />
<br />
To use a Macro you must create a Macro Expansion task. The easiest way to do this is to drag the resource containing the Macro and then drop it into the Setup Editor where you want to use it. Similarly, if you want to use a Macro defined in the internet, you can use Load Resource... from the Setup Editor's context menu to load the Macro into the editor's resource set (or drag the link and drop it into the editor). Note that Macros available in the resource set are always shown in the Outline view. Once the Macro is available in the editor's resource set, or in the Outline, you can drag and drop the Macro anywhere that any other setup task can be created. This will create a Macro Expansion task that binds to the Macro.<br />
<br />
A Macro Expansion task must specify an ID, which of course must be unique within the containing resource. The ID is used during [[#Macro Expansion Processing|Macro Expansion Processing]]. Via drag and drop, an ID is automatically assigned, but you'll likely want to change it. A Macro Expansion task can supply Arguments to bind the values of the Parameters of the Macro. For every Parameter without a default value there must be a corresponding Argument to bind its value. The validator will complain when that's not the case, so be sure to enable Live Validation via the context menu. When creating a Macro Expansion task using drag and drop, the required Arguments are automatically created. Of course you'll want to change the generated values; you can delete any Arguments for which the Parameter specifies the default value that you wish to just use. You can change the Argument's value by double clicking the Argument to ensure that it's visible in the Properties view, and can then edit the Value property of the Argument there. The description of the corresponding Parameter is displayed in the Properties view after the Parameter's name. This is why it's important to include a description for each Parameter so that the author using the Macro knows how the Argument's value will be used by that Macro.<br />
<br />
The setup editor displays the Macro referenced by a Macro Expansion task as a child item, in light brown, in the tree view, so you can fully explore the Macro being used. In addition a Preview item is displayed, in light blue, to show how the Macro Expansion task will be expanded. And of course the Outline view allows you to preview all of the tasks that will be performed when you run the installer later.<br />
<br />
Here is an example of how the above Macro could be used by a Macro Expansion task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Project<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
name="sample.project"<br />
label="SampleProject"><br />
<setupTask<br />
xsi:type="setup:MacroTask"<br />
id="my"<br />
macro="GitCloneMacro.setup#/"><br />
<argument<br />
name="description"<br />
value="description_value"/><br />
<argument<br />
name="pushURI"<br />
value="pushURI_value"/><br />
<argument<br />
name="recursive"/><br />
<argument<br />
name="remoteName"/><br />
<argument<br />
name="remoteURI"<br />
value="remoteURI_value"/><br />
<argument<br />
name="restrictToCheckoutBranch"/><br />
<argument<br />
name="checkoutBranch"<br />
value="master"/><br />
</setupTask><br />
<stream name="stream"/><br />
<logicalProjectContainer<br />
xsi:type="setup:ProjectCatalog"<br />
href="index:/org.eclipse.setup#//@projectCatalogs[name='org.eclipse']"/><br />
<description>SampleProject provides cool stuff.</description><br />
</setup:Project><br />
<br />
Note that here we have several Arguments without a value. Those could be deleted or a value (presumably different from the default value of the Parameter) could be specified. Also note that a well-formed Argument can only bind to a Parameter of the containing Macro Expansion task's Macro, so the serialization is simplified to specify just the name of the bound Parameter in this case.<br />
<br />
=== Macro Expansion Processing ===<br />
<br />
A Macro Expansion task is expanded to a Compound Setup Task as illustrated by the Preview item. Each Argument is bound to its corresponding Parameter via a local variable of the form '*<macro-expansion-task-id>.<parameter-name>'. Every variable reference to the Parameter name is transformed to use this Variable's more-qualified name instead. Every setup task with an ID is transformed to specify instead a qualified ID of the form '<macro-expansion-task-id>.<original-id>' and every variable reference that's prefixed by '<original-id>.' will be transformed to use the more-qualified prefix instead. In addition, any Variable contained by the Macro with a name that start with '*' will also be changed to use the name '*<macro-extension-task-id>.<original-name>' and all references to '<original-name>' will be transformed to use that qualified name instead. This qualification process ensures that unique Variable names are provided by the Macro Expansion because in the end, there's no such thing as a local Variable.<br />
<br />
Of course Macros themselves can use Macro Expansion tasks, so the process of expansion is recursive. That being said, it's of course invalid for this to lead to a cycle. Cycles are detected by the validator and the expansion process prevents further expansion when a cycle is encountered.<br />
<br />
Note that from the context menu of a Macro Expansion task it's possible to invoke "Inline" to replace a Macro Expansion task with its fully expanded equivalent.<br />
<br />
== Automation and Specialization with Configurations ==<br />
<br />
As of Oomph 1.6, released with Neon.2, there is support for Configurations. A Configuration is not a Scope (is not a container for setup tasks) but rather a container for an Installation and a Workspace; each is optional, but a Configuration with neither is in effect useless. The Installation and Workspace of a Configuration are effectively used as a template to initialize the Installation and Workspace created by the Eclipse Installer, i.e., the setup resources that you can open with Navigate &rarr; Open Setup &rarr; Installation and Navigate &rarr; Open Setup &rarr; Workspace in your IDE. So you can specialize the installation with additional installation-specific tasks, e.g., a p2 task to install additional features, and you can specialize the workspace with workspace-specific tasks, e.g., a variable task to specify the value of a variable so you won't be prompted for that value. <br />
<br />
Configurations are not only useful for specifying installation-specific and workspace-specific tasks but also for automating the selection process in the setup wizards, including the installer. The Configuration's Installation can reference a specific Product Version and the Configuration's Workspace can optionally reference several specific Project Streams. Both the simple mode and the advanced mode of the installer support dragging and dropping a Configuration to the title area. You can drag to the title area either a file (i.e., a file from the file system or from an Eclipse IDE), a URL (i.e., a link from a browser), or a copy of a Configuration's XMI serialization. This will '''apply''' the Configuration to the wizard with the effect that the Installation's Product Version is selected in the wizard and the wizard advances to the next page. Similarly, the Workspace's Project Streams are selected in the wizard and the wizard advances to the next page. If you apply a Configuration with a Workspace to the simple mode of the installer, you will be prompted to switch to advanced mode because only the advanced mode supports Project selection. So in simple mode, applying a Configuration advances to the final page, and in advanced mode, applying a Configuration with an Installation and a Workspace advances to the Variables page.<br />
<br />
As an alternative to drag and drop support, rather than dragging a file, link, or XMI serialization, you can copy it to the clipboard and apply the clipboard contents to the wizard. In simple mode this is done via the Apply Configuration menu item. In advanced mode this is done via the Apply Configuration toolbar button on the Product or Project page; the menu item or toolbar item is visible only if the clipboard contains applicable content.<br />
<br />
The installer application supports command line arguments so you could also specify a Configuration's file path or URL link on the command line to apply it automatically.<br />
<br />
=== Creating a Configuration ===<br />
<br />
The simplest way to create a new Configuration is from the context menu of the folder where want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Configuration Model in the wizard. You can then edit the new Configuration with the Setup Editor. You can delete the Installation or Workspace if you don't need that aspect. You can use the Properties view to set the Installation's Product Version or the Workspace's Project Streams. And of course you can create any other setup tasks in either Scope.<br />
<br />
=== Configuration Handling ===<br />
<br />
The specific form of the serialized URLs that are used to reference a Product Version or a Project Stream are very important to correct behavior. Relative URLs in the serialization can only work relative to the location of the Configuration's resource, so will only work when you drag and drop a file or link because a dragging and dropping textual copy of the serialization provides no information about how to resolve relative references. This is not to say there is anything wrong with relative references, just be aware that they imply that the user must apply the overall file or link, not just the textual serialization. <br />
<br />
Another very useful aspect of Configurations is that the wizards handle of the references intelligently. I.e., if a Installation references a Product Version that's not in any Product Catalog in the Index, the Product will automatically be added to the user-extensible Product Catalog. If the Installation references a Product Version via its containing Product Catalog and that Product Catalog is not in the Index, and the redirectable Product Catalog is not already redirected, it will be redirected to the referenced Product Catalog and an appropriate Eclipse Ini redirection tasks will be synthesized so that the installation produced by the installer will be able to resolve the Product Version reference in its Installation via the correct containing Product Catalog. Analogous processing is done for the Project Stream references with the additional processing of Project's a logical Project container which determines which Project Catalog's extensible Project container is used. In other words, Configurations can also be used to automate the addition of Products and Projects to the user extensible catalogs.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Getting Early Feedback ===<br />
Why didn't the model editor tell me earlier that I've made a silly mistake?<br />
Please enable Live Validation in the editor menu to get early feedback.<br />
<br />
=== Copying Tasks and Other Elements ===<br />
The Setup Editor supports the export and import of any model elements by using copy to or paste from the clipboard. The clipboard will/must contain a valid XML document. With this method, for example, you can easily copy task snippets from your model directly into a forum post when you ask for help (or into a Skype window when you chat with your collegues). Or you can easily paste such XML snippets from forum replies directly into your Setup Editor.<br />
<br />
You have access to many example setups from within your IDE! Use Navigate->Open Setup->Parent Models->Open Catalog Index to investigate everything within the index. The context menu provides a way to open elements in a text editor. This is particularly handy for finding out where a particular setup is hosted (hrefs are resolved in the Setup editor) - one use case is checking and repairing links to project setups added to your user projects.<br />
<br />
=== Hosting your own index / catalogs ===<br />
If you want to host your own product or project catalog, you must provide a URI mapping to the installer to locate the root setup file (the "index"). Open the eclipse.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, or use the wizard to create it. 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/. You can redirect to your own index with this redirection system property:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->http://<hostname>/<path>/</nowiki><br />
<br />
The source URI may be abbreviated to <nowiki>index:/</nowiki> and the target URI may also be a file URI, e.g. on a shared file server.<br />
<br />
In general it will be highly desirable to archive your setup, but documentation for that is TBD. The installer and other setup wizards support dragging and dropping an index or archived index onto the title area of the dialog. Documentation for that is also TBD.<br />
<br />
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=481580 Bug 481580] has introduced empty redirectable catalogs for products ('''redirectable.products.setup''') and projects ('''redirectable.projects.setup''') to the Oomph index. These allow providing your own catalogs without replacing the entire index or disabling the catalogs shipped with Oomph (by redirecting them). The following steps are necessary to make use of those setups.<br />
* Create your own project catalog setup file using the wizard. Project setups in the project catalog should typically be referenced using absolute URIs, otherwise redirection can become problematic. However, if the relative references are downward pointing to some uniquely named folder different from any of the file/folder names in the Eclipse.org index, i.e., no '''..''' traversal to the parent folder is involved and some folder name '''<my-projects-folder>''', then they will be resolved to absolute URIs of the form '''index:/<my-projects-folder>/<path>''' which can be handled as described below.<br />
* Add a redirection system property similar to that described above to the eclipse.ini file, e.g., '''-Doomph.redirection.myProjectCatalog=index:/redirectable.projects.setup->...'''.<br />
* If the projects in that catalog are referenced by relative downward references with a unique folder, also add a folder redirection system property, e.g.,'''-Doomph.redirection.myProjectCatalog=index:/<my-projects-folder>/->.../''', to redirect the locations of the referenced projects to the folder where they are physically hosted.<br />
* Your catalog setup file must contain an Eclipse Ini task creating the same redirection(s)! Otherwise your catalog (or the referenced projects) will not be visible in the Eclipse created by the installer and hence the projects selected from it cannot be provisioned.<br />
* The first time, you may have to enable your new catalog by selecting it in the folders icon of the drop-down in the upper right hand corner of the wizard's Projects page, otherwise it will be invisible.<br />
<br />
To debug the processing of -Doomph.redirection.* if needed, set a breakpoint in org.eclipse.oomph.setup.internal.core.util.SetupCoreUtil.configureResourceSet(ResourceSet) within if (((String)key).startsWith(SetupProperties.PROP_REDIRECTION_BASE)).<br />
<br />
=== Shipping your own index ===<br />
If you want to include your own product or project catalog, you may ship the root setup file (the "index") relative to the installer directory. Then you can redirect the index as explained in [[#Hosting your own index / catalogs| Hosting your own index / catalogs]]. For example, you can place all setup files in an eclipse-installer/setups/ folder and then redirect access to it with a relative target URI:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->setups/</nowiki><br />
<br />
Note that shipping the index rather than maintaining it in a central location (accessible to all parties interested) has the following disadvantage. As each user has her own copy of the index, updates in the setup files will not be distributed automatically.<br />
<br />
=== Generating PDE Target Definition files (*.target) and their use by Tycho ===<br />
<br />
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. <br />
<br />
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:<br />
<br />
<annotation<br />
source="http:/www.eclipse.org/oomph/targlets/TargetDefinitionGenerator"><br />
<detail<br />
key="location"><br />
<value>${git.clone.location}/targetdefinition/DesignStudio.target</value><br />
</detail><br />
<detail<br />
key="extraUnits"><br />
<value>org.eclipse.equinox.executable.feature.group</value><br />
</detail><br />
<detail<br />
key="includeAllPlatforms"><br />
<value>false</value><br />
</detail><br />
<detail<br />
key="includeSource"><br />
<value>true</value><br />
</detail><br />
<detail<br />
key="generateVersions"><br />
<value>true</value><br />
</detail><br />
</annotation><br />
<br />
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.<br />
<br />
''TODO Document what preferredRepositories, PomModulesUpdater & PomArtifactUpdater do...''<br />
<br />
=== Setting up WST Server Runtime and Instances in your Setup ===<br />
<br />
==== Server Runtime Preference ====<br />
<br />
1. Use an oomphed installation/workspace with preference recorder enabled.<br />
<br />
2. Open your project and user setup editors.<br />
<br />
3. Go to Preferences / Server / Runtime Environments and 'Add' it as usual.<br />
<br />
4. Drag the selected '/instance/org.eclipse.wst.server.core/runtimes' from user to project setup.<br />
<br />
Note: It's unclear if the above actually works. Please see thread https://www.eclipse.org/forums/index.php/t/1086488/ in forum for details.<br />
For some servers there are extension tasks to handle configuration, see below.<br />
<br />
==== Server Instance in Servers View ====<br />
Requires server runtime to be setup first.<br />
<br />
1. Open Servers View and create New server instance and deploy webapps as usual<br />
<br />
2. Optionally open server instance editor and adapt configuration as usual.<br />
<br />
3. Close Eclipse.<br />
<br />
4. Start it again.<br />
<br />
5. Open '.plugins/org.eclipse.wst.server.core/servers.xml' from your workspace/.metadata using a UTF capable editor<br />
<br />
6. Add Resource Creation Task to your setup:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
content="PUT_CONTENT_FROM_SERVERS_XML_INTO_HERE_USING_A_UTF_CAPABLE_EDITOR_AND_OOMPH_DIALOG"<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.wst.server.core/servers.xml"<br />
encoding="UTF-8"><br />
<description>tomcat server integration</description><br />
</setup:ResourceCreationTask><br />
<br />
7. Use the resource task content dialog to put the servers xml content into the task.<br />
<br />
8. Copy "Servers" project from this workspace into a suitable location of your branch checkout and add/commit/push.<br />
<br />
9. Setup project import task that can pick the Servers project up from that committed location.<br />
<br />
That's it. If you want to share it among fellows, be sure to agree on canonical paths for your server installations.<br />
<br />
==== Extension tasks for specific servers ====<br />
<br />
For some servers there are oomph extension tasks that can be used to handle the configuration:<br />
<br />
https://github.com/gratex/oomph-task-server - Tomcat, WebLogic, and WebSphere<br />
<br />
=== Suppress prompt for default workspace already upon very first start ===<br />
<br />
Adjust the SHOW_WORKSPACE_SELECTION_DIALOG property to false via configuration settings org.eclipse.ui.ide.prefs ...<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP MANUAL"<br />
content="MAX_RECENT_WORKSPACES=5&amp;#xD;&amp;#xA;RECENT_WORKSPACES=${workspace.location|property}&amp;#xD;&amp;#xA;RECENT_WORKSPACES_PROTOCOL=3&amp;#xD;&amp;#xA;SHOW_WORKSPACE_SELECTION_DIALOG=false&amp;#xD;&amp;#xA;eclipse.preferences.version=1"<br />
targetURL="configuration:/.settings/org.eclipse.ui.ide.prefs"<br />
encoding="UTF-8"/><br />
<br />
=== Open default perspective already upon very first start ===<br />
Examples below using Perspective ID for Java perspective.<br />
<br />
Tell Eclipse which perspective to open initially, by adding option to eclipse ini:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:EclipseIniTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP"<br />
option="-perspective"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
Setting a perspective to be default, by adding preference task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:PreferenceTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
key="/instance/org.eclipse.ui/defaultPerspectiveId"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
=== How to switch the current stream ===<br />
<br />
If you would like to switch the current stream/s, you can re-use Oomph's initial "Eclipse Importer" wizard, available as "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace.<br />
<br />
Note that it is currently not yet possible to remove the "current" project stream. As a workaround, use menu Navigate > Open Setup > Open Workspace (or if visible click the 'blue guy' icon in the Oomph toolbar) to Open Workspace workspace.setup, expand the first node, click on the Workspace entry, open Properties view, and change the last property named "Streams" and remove the current stream.<br />
<br />
Bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=476434 enhancement may make this easier in the future.<br />
<br />
<br />
=== How to install Eclipse plugins using the P2 Director and Repository Explorer ===<br />
<br />
Oomph can install Eclipse plugins which you require. This also works for normal Java Projects set up models, not just for Eclipse plug in OSGi development, and is handy to install commonly used 3rd-party Eclipse plugins which are not all available from eclipse.org p2 sites (think e.g. http://eclemma.org). Here's how:<br />
<br />
1. add a P2 Director child task to your *.setup, if it doesn't already have one<br />
<br />
2. add a Repository child in your P2 Director task<br />
<br />
3. in the Properties of the Repository set the URL to a valid p2 repo (e.g. http://update.eclemma.org)<br />
<br />
4. right-click that Repository and choose Explore, to open the Repository Explorer view<br />
<br />
5. in the Repository Explorer view change to [X] Compatible and (*) Minor at the lower-right hand corner<br />
<br />
6. drag & drop the version from the Repository Explorer view into the P2 Director task of your *.setup editor, to create a Requirement child<br />
<br />
Drag & Drop should normally work, but appears to be broken at least on Neon Milestone 6 on Linux; in that case:<br />
<br />
6. manually create a new child Requirement inside the P2 Director task<br />
<br />
7. in the Repository Explorer view use the brown (C) icon to switch to Expert Mode to see IDs instead of names<br />
<br />
8. find the ID of the feature IU, it's the one with a PDE feature + folder kind of icon, often ending in (feature.)feature.group<br />
<br />
9. in the Properties of the Requirement, type the Name to the ID found above (e.g. com.mountainminds.eclemma.feature.feature.group)<br />
<br />
10. in the Properties of the Requirement, Type should have automatically switched to Feature<br />
<br />
PS: If you are looking for the URL of p2 repos to pre-install some of the the M2E connectors, see https://git.eclipse.org/c/m2e/m2e-discovery-catalog.git/tree/org.eclipse.m2e.discovery.oss/connectors.xml<br />
<br />
<br />
<br />
=== How to create M2E lifecycle-mapping-metadata.xml to avoid littering your pom.xml with org.eclipse.m2e:lifecycle-mapping ===<br />
<br />
Read https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html & https://wiki.eclipse.org/M2E_compatible_maven_plugins and apply as follows:<br />
<br />
<setupTask<br />
xsi:type="setup:PreferenceTask"<br />
key="/instance/org.eclipse.m2e.core/eclipse.m2.WorkspacelifecycleMappingsLocation"<br />
value="${workspace.location}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"/><br />
<br />
<setupTask<br />
xsi:type="setup:ResourceCreationTask"<br />
content="..."<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"<br />
encoding="UTF-8"><br />
<description>Initialize M2E's Maven Lifecycle Mappings, see https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html &amp; https://wiki.eclipse.org/M2E_compatible_maven_plugins</description><br />
</setupTask><br />
<br />
For "content" just open the popup using the [...] icon in the Properties and copy/paste the content from menu Window > Preferences > Maven > Lifecycle Mappings: Open workspace lifecycle mappings metadata. (This is easier than editing the content=".." in source view, because it will correctly do the XML escaping for you.)<br />
<br />
Now whenever M2E whines about stuff like "Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-dependency-plugin:2.10:unpack (execution: unpack-license, phase: generate-resources)" etc. just use the Quick Fix in the Problems view and choose the option to use workspace preferences (instead of letting the quick fix modify your pom.xml to add org.eclipse.m2e:lifecycle-mapping <lifecycleMappingMetadata>).<br />
<br />
<br />
=== How to automatically pre-enable Gerrit ===<br />
<br />
If you would like to save your end-users from having to [[EGit/User_Guide#Enabling_Gerrit_for_a_repository|manually enabling Gerrit for a repository in EGit]], then you can use the follow magic variable which Oomph will recognize and act upon:<br />
<br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="YOURORG.gerrit.uri.pattern"<br />
value="(https|ssh)://([^@/]+@)?(git.YOURORG.org:29418/.*|git.YOURORG.org/gerrit/.*)"/><br />
<br />
=== How to find a P2 repository at Eclipse using the Repository Explorer ===<br />
<br />
Most projects don't document the locations of all their p2 update sites very well. This makes it hard to find the URL you need in order to install something or in order to specify a URL for your target platform definition. Oomph indexes all the p2 update sites available at download.eclipse.org to make this job easier. You can make use of this as follows:<br />
<br />
# In the Quick Access control, type "Repository Explorer" to show Oomph's Repository Explorer view.<br />
# In that view's toolbar, locate the tool item with the hover "Search Eclipse repositories by provided capabilities", i.e., the one that looks like a little search flashlight, and click it.<br />
# This brings up the "Eclipse Repository Search" dialog. The index is very large so it takes a while to load it. But it's cached locally and updated on the server once per day.<br />
# At the root of the displayed tree are p2's namespaces and under each of these are the capabilities in that namespace. They're organized hierarchically by their qualified name. It's all quite technical and the tree is very large. So while you can explore it, you'll most likely want to use the filter to find something quickly.<br />
# Type the fully qualified name of a Java package or installable unit you wish to locate into the filter. Note that tree items for which there exist a concrete version in some repository are decorated as such. Keep in mind that many projects don't version their Java packages, so it's often better to look at the org.eclipse.equinox.p2.iu category. Here's what it looks like searching for "org.eclipse.emf.ecore.xcore":<br>[[File:SearchEclipseRepositoryDialog.png]]<br><br />
# You can select a capability in the tree so that the lower panel displays all the versions of the capability that are available. Under each of those are nested the update sites that contain them. Composite update sites show their children hierarchically.<br />
# Of course you can double click a repository to further explore its contents in the Repository Explorer itself.<br />
<br />
<br />
=== How to extract the constituent parts that comprise the Windows self-extracting installer executable ===<br />
<br />
The Eclipse Installer distribution for the Windows platform is effectively a self-extracting executable. It is extracted at runtime by the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINExtractor.java Bin Extractor]. The pre-built version of this library, i.e., org.eclipse.oomph.extractor.lib-*.jar, is available in all Oomph-containing installations, i.e., in the installer itself and in applications installed by the installer. This library can also be used standalone to decompose the composed executable into its constituent parts. That can be accomplished if you run it with the correct magical program arguments as follows:<br />
<br />
java -classpath <path-to-extract-lib>\org.eclipse.oomph.extractor.lib-*.jar<br />
org.eclipse.oomph.extractor.lib.BINExtractor <br />
<path-to-executable-to-extract>\eclipse-inst-win64.exe <br />
<target-path>\product.zip <br />
-export <br />
<target-path>\marker.txt <br />
<target-path>\extractor.exe <br />
<target-path>\org.eclipse.oomph.extractor.lib.jar <br />
<target-path>\product-descriptor<br />
<br />
The Java VM arguments need only specify the extractor library along with the main class in that library. The first program argument is the location of the executable you wish to decompose, the 64 bit installer in this case. The remaining arguments are all best directed into a common folder, denoted as <target-path> in the example above. The second argument is the extracted location of the zip file of the product/distribution. The third argument is the -export flag. The fourth argument is the extracted location of the text file containing the marker text that is used to delimit the constituent parts of the composed executable. The fifth argument is the extracted location of the small native executable itself. The sixth argument is the extracted location of the extractor library, the same one being used to extract the parts. The seventh and final argument is the extracted location of the product descriptor. Such a [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINDescriptor.java descriptor] looks like this:<br />
<br />
1<br />
1<br />
7<br />
0<br />
64<br />
0<br />
eclipse-inst.exe<br />
eclipse-inst.ini<br />
Eclipse Installer<br />
http://wiki.eclipse.org/Eclipse_Installer<br />
http://download.eclipse.org/oomph/jre/128x128.png<br />
<br />
Of course you can edit these parts and then you can recompose the executable using the following bash script executed within the common folder in which you have extracted the constituent parts:<br />
<br />
COPY /B extractor.exe + ^<br />
marker.txt + ^<br />
org.eclipse.oomph.extractor.lib.jar + ^<br />
marker.txt + ^<br />
product-descriptor + ^<br />
marker.txt + ^<br />
product.zip + ^<br />
marker.txt ^<br />
eclipse-inst-64.exe<br />
<br />
Note that the file names match the extracted target file names. From this is should be clear that the native executable is just a composition of parts. This structure is used at runtime as follows. The extractor.exe runs natively, reading its own executable file, using the marker text to find the parts. It checks the descriptor to determine if an appropriate version of Java is already installed, i.e., one that will be able to launch the product; the native extractor consults the registry to find all installed JREs and JVMs. If an appropriate Java is not found, it opens a browser page prompting the user to install an appropriate Java version with the required bitness and at the minimum required version. If there is already an appropriate version of Java, it launches a Java process to execute the BinExtract's main method. That process in turn unzips the product zip to a temp folder and launches the Java process for that for the product/distribution.<br />
<br />
== Oomph Configuration Options ==<br />
<br />
=== Configuration Options for Installer .ini File ===<br />
<br />
{| class="wikitable"<br />
| '''-Doomph.redirection.setups''' || Redirects the location of setup files (index, catalog and products). The default URI is ''http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/'' and my be abbreviated with '''index:/'''. The syntax of the redirection is '''index:/->[redirection URI]'''. Examples: '''-Doomph.redirection.setups=index:/->http://<hostname>/<path>/''' (external server redirection) or '''-Doomph.redirection.setups=index:/->setups/''' (path relative to installer executable). See also [[#Hosting_your_own_index_.2F_catalogs|Hosting your own index & catalogs]]<br />
|-<br />
| '''-Doomph.setup.product.catalog.filter''' || Only displays product catalogs matching the given prefix. The default is ''org\\.eclipse\\.products''. Displays all catalogs if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.filter''' || Only displays products matching the given prefix. The default is ''(?\!org\\.eclipse\\.products\\.org\\.eclipse\\.platform\\.ide).*''. Displays all products if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.version.filter''' || Only displays product versions matching the given prefix. The default is ''.*\\.neon''. Displays all product versions if value is empty.<br />
|-<br />
| '''-Doomph.p2.pool''' || Set to ''@none'' to disable bundle pools. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=507594] for details.<br />
|}<br />
<br />
== Troubleshooting ==<br />
=== The preference task does not setup any preferences ===<br />
<br />
First of all. Please note that the preferences are not set up as part of the installation. They are setup when the installed eclipse is first started.<br />
<br />
To do this the installed product needs to have the following feature installed:<br />
''org.eclipse.oomph.setup.feature.group''<br />
<br />
The feature is already included in the root of the Eclipse.org Product Catalog. If you are not using it you can include the same task by yourself:<br />
<br />
<setup.p2:P2Task<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup.p2="http://www.eclipse.org/oomph/setup/p2/1.0"><br />
<requirement<br />
name="org.eclipse.oomph.setup.feature.group"/><br />
<repository<br />
url="${oomph.update.url}"/><br />
</setup.p2:P2Task></div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Oomph_Authoring&diff=432500Eclipse Oomph Authoring2019-05-26T05:10:23Z<p>Stepper.esc-net.de: /* Macro Expansion Processing */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
== Getting Started ==<br />
<br />
=== What is Oomph? ===<br />
<br />
Please read [[Eclipse Installer]].<br />
<br />
<br />
=== Installing Oomph ===<br />
<br />
# Download and install the Eclipse '''Installer''' as outlined in [[Eclipse Installer]].<br />
# Make sure that the Oomph setup '''SDK''' is installed in your IDE. Either:<br />
## That's already the case because your IDE is a Mars M5 or later Eclipse Package, or<br />
## Start the installer and install an IDE of your choice (select on the first installer page), or<br />
## Use p2 to install "Oomph Setup SDK" from [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest].<br />
<br />
== Creating a Setup Project Model ==<br />
<br />
=== Using the Setup Project Model Wizard ===<br />
<br />
# Create an empty project in your workspace or select a folder in an existing project. You'll create the new "Setup Project Model" in the selected folder.<br />
# Open the New... dialog and select the "Setup Project Model" wizard:<br>[[Image:new-wizard.png]]<br><br />
# Select one of the provided templates (e.g., Eclipse.org, Github.com, or Simple) and adjust the displayed values:<br>[[Image:new-wizard-2.png]]<br><br />
# Some values are automatically derived from your input to fields '''higher up'''.<br />
# Open the Preview>>> to understand the impact of changes to the current field.<br />
<br />
=== Using the Setup Editor ===<br />
<br />
# Open the resulting setup file with Oomph's Setup Editor:<br>[[Image:setup-edit.png]]<br><br />
# Configure the tasks in the Properties view. Note that there are "Expert" properties available.<br />
# Add setup tasks to your project and/or to your project streams and configure them, too.<br />
# The Outline view displays a ''preview'' of the executable model with resolved variables.<br />
<br />
=== Testing the Setup Model ===<br />
<br />
# To test/execute your new setup model:<br />
## Start the installer and, if necessary, switch to the Advanced Mode via the dialog menu.<br />
## Pick any product on page 1 and click the Next button to proceed to page 2.<br />
## Drag and drop your <tt>.setup</tt> file onto one of the top-level catalogs (<tt>Eclipse.org</tt> or <tt>Github.com</tt>) in the projects tree. Your project will appear as a subproject of the special <tt>&lt;User&gt;</tt> project.<br />
## Double-click your project to add it to the table at the 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.<br />
## Fill in the empty fields and press the Next button to proceed to the Confirmation page.<br />
## 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.<br><br />
# 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 [[#Using the Setup Editor|Using the Setup Editor]]. If the IDE comes up but the initial configuration fails continue with step 3.<br />
# In the new IDE (whether the initial configuration was successful or not) open your model file from the main menu, Navigate &rarr; Open Setup &rarr; [[Image:branch.png]]. Find the problems and fix them. Then start the setup process '''from within''' this IDE via the main menu, Help &rarr; [[Image:update.png]] Perform Setup Tasks&hellip;. 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.<br />
<br />
=== Contributing to a Project Catalog ===<br />
<br />
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 http://git.eclipse.org/c] and [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&bug_severity=enhancement&short_desc=Please%20include%20setup%20for%20project%20Xyz 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.<br />
<br />
The same can be done if your project is not an Eclipse project, but hosted on '''GitHub'''. Simply state this fact in the bug description and paste the "raw" content URL to the file instead.<br />
<br />
== Understanding the Setup Engine ==<br />
<br />
=== Understanding Setup Tasks and Scopes ===<br />
<br />
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:<br />
<br />
* The '''Installation''' scope is located in <tt>eclipse/configuration/org.eclipse.oomph.setup/installation.setup</tt> 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.<br />
<br />
* The '''Workspace''' scope is located in <tt>workspace/.metadata/.plugins/org.eclipse.oomph.setup/workspace.setup</tt> 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.<br />
<br />
* The '''User''' scope is located in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup</tt> and contains tasks that are common to '''all''' installations and workspaces (unless they're restricted to particular installations or workspaces).<br />
<br />
<br />
The following additional scope types exist, so they can be referenced by the entry scopes:<br />
<br />
* The '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.setup Catalog Index]''' is the root scope and contains nested Product Catalogs and Project Catalogs.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.products.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/OomphInstaller.setup Product]''' contains nested Product Version scopes and possibly some tasks that are common to all nested scopes.<br />
<br />
* A '''Product Version''' contains no nested scopes but tasks that are specific to that product version.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.projects.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/Oomph.setup Project]''' contains nested Stream and/or (Sub-) Project scopes and typically some tasks that are common to all nested scopes.<br />
<br />
* A '''Stream''' contains no nested scopes but tasks that are specific to that stream.<br />
<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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 [[#Declaring_and_Using_Variables|Declaring and Using Variables]] below.<br />
<br />
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). <br />
<br />
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.<br />
<br />
=== Declaring and Using Variables ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:<br />
<br />
${''variable-name''}<br />
<br />
To prevent a variable reference from being expanded (e.g. you actually want to have the value '${var}' and not the value of "var"), you need to escape the variable syntax with an extra double dollar character. So "$${var}" will result in "${var}".<br />
<br />
In addition to the variables that are declared by VariableTasks you can refer to all of the following:<br />
<br />
* Attribute values of setup tasks with a defined ID. The reference syntax is ${''taskID''.''attributeName''}.<br />
* System properties as returned by <tt>System.getProperties()</tt><br />
* [[#Environment Variables|Environment variables]] as returned by <tt>System.getenv()</tt><br />
* [[#Predefined Variables|Predefined variables]] as determined by the setup engine from the user input to the installer (see below)<br />
<br />
==== Predefined Variables ====<br />
<br />
The following variables are predefined by the setup engine:<br />
<br />
{| class="wikitable"<br />
| '''scope.installation.name''' || The value of the <em>name</em> attribute of the current installation scope. <br />
|-<br />
| '''scope.installation.label''' || The value of the <em>label</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.installation.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.workspace.name''' || The value of the <em>name</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.label''' || The value of the <em>label</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.description''' || The value of the <em>description</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.user.name''' || The value of the <em>name</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.label''' || The value of the <em>label</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.description''' || The value of the <em>description</em> attribute of the current user scope.<br />
|-<br />
| '''scope.product.catalog.name''' || The value of the <em>name</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.label''' || The value of the <em>label</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.description''' || The value of the <em>description</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.name''' || The value of the <em>name</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product scope and its parent scopes.<br />
|-<br />
| '''scope.product.label''' || The value of the <em>label</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.description''' || The value of the <em>description</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.version.name''' || The value of the <em>name</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product version scope and its parent scopes.<br />
|-<br />
| '''scope.product.version.label''' || The value of the <em>label</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.project.catalog.name''' || The value of the <em>name</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.label''' || The value of the <em>label</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.description''' || The value of the <em>description</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.name''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current project scope and its parent scopes.<br />
|-<br />
| '''scope.project.label''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.description''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.stream.name''' || The value of the <em>name</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current stream scope and its parent scopes.<br />
|-<br />
| '''scope.project.stream.label''' || The value of the <em>label</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.description''' || The value of the <em>description</em> attribute of the current stream scope.<br />
|}<br />
<br />
<br />
==== Variable Extensions ====<br />
<br />
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.:<br />
<br />
${installation.location/git/myproject} evaluates to C:\develop\installation1\git\myproject on Windows<br />
<br />
<br />
After the path extension part you can add filter calls with pipe symbols. Filter names are generally case-insensitive. Multiple filters can be chained. Example:<br />
<br />
${installation.location|uri}/git/myproject evaluates to file:/C:/develop/installation1/git/myproject<br />
<br />
<br />
==== Variable Filters ====<br />
<br />
The following filters are currently available:<br />
<br />
{| class="wikitable"<br />
| '''base64''' || <br />
|-<br />
| '''basePath''' || Removes the last segment from a file system path.<br />
|-<br />
| '''camel''' || Converts a qualified name to camel case notation.<br />
|-<br />
| '''canonical''' || Canonicalizes a file system path.<br />
|-<br />
| '''cap''' || Capitalizes the first word of a String value.<br />
|-<br />
| '''capAll''' || Capitalizes all words of a String value.<br />
|-<br />
| '''file''' || Converts a file: URI to an OS-specific file system path.<br />
|-<br />
| '''fileExtension''' || Extracts the file extension from a URI or a file system path.<br />
|-<br />
| '''gitRepository''' || Extracts the name of the repository from a Git URI (excluding a possible .git suffix).<br />
|-<br />
| '''lastSegment''' || Extracts the last segment from a file system path.<br />
|-<br />
| '''length''' || Converts a String to a String that contains the alpha-numerical representation of the length of the original String.<br />
|-<br />
| '''lower''' || Converts all characters of a String value to lower-case.<br />
|-<br />
| '''path''' || Extracts the path segments from a URI.<br />
|-<br />
| '''pathEncode''' || Converts a file system path to a String value that can be used as a file name.<br />
|-<br />
| '''preferenceNode''' || Escapes all forward slashes (/) of a String value, so that the result can be used as a value in preference nodes.<br />
|-<br />
| '''property''' || Escapes all double back slashes (\\) of a String value, so that the result can be used as a value in properties.<br />
|-<br />
| '''propertyValue''' || Interprets the String value as a preference property path and returns the value of that property.<br />
|-<br />
| '''qualifiedName''' || Converts a camel case String value name to a qualified name.<br />
|-<br />
| '''slashDecode''' || Decodes a slashEncoded String value.<br />
|-<br />
| '''slashEncode''' || Encodes all slashes and backslashes of a String value.<br />
|-<br />
| '''trim''' || Removes all whitespace from the beginning and the end of a String.<br />
|-<br />
| '''trimLeft''' || Removes all whitespace from the beginning of a String.<br />
|-<br />
| '''trimRight''' || Removes all whitespace from the end of a String.<br />
|-<br />
| '''trimTrailingSlashes''' || Removes all slashes and backslashes from the end of a String.<br />
|-<br />
| '''upper''' || Converts all characters of a String value to upper-case.<br />
|-<br />
| '''uri''' || Converts a file system path to a file: URI.<br />
|-<br />
| '''uriLastSegment''' || Extracts the last path segment from a hierarchical URI or the authority from an opaque URI.<br />
|-<br />
| '''urlDecode''' || Decodes a URL.<br />
|-<br />
| '''urlEncode''' || URL-encodes a String value.<br />
|-<br />
| '''username''' || Escapes all "at" symbols (@) of a String value, so that the result can be used in URI that contain a username.<br />
|}<br />
<br />
==== Variables from Outer Scopes====<br />
<br />
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:<br />
<br />
* '''jre.location-1.4''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.5''' --> The folder containing a 1.5 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.6''' --> The folder containing a 1.6 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.7''' --> The folder containing a 1.7 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.8''' --> The folder containing a 1.8 compatible JDK/JRE for architecture ${os.arch}<br />
* '''git.user.id''' --> The Eclipse user ID for Git/Gerrit commits<br />
* '''git.author.name''' --> The Eclipse author name for Git/Gerrit commits<br />
* '''git.author.email''' --> The Eclipse author email for Git/Gerrit commits<br />
* '''bugzilla.id''' --> The Eclipse user ID for Bugzilla/Hudson<br />
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson<br />
<br />
<br />
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.<br />
<br />
==== Environment Variables ====<br />
<br />
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.<br />
<br />
=== Conditional Tasks ===<br />
<br />
All setup tasks support filters. Oomph reuses [https://wiki.eclipse.org/Equinox_P2_Resolution#Enablement_filter p2's implementation] of LDAP filters. I.e., it supports a string a representation of LDAP Search Filters, RFC 1960, UMich, 1996,<br />
http://www.ietf.org/rfc/rfc1960.txt<br />
<br />
The filter property of a setup task is an advanced property. To display this property, ensure that the "Show Advanced Properties" is enabled in the Properties view tool bar. The properties of a filter expression can generally refer to any system property or any environment variable. For example, the following filter expression on a task will ensure that it is included only when performing a task on a Linux operating system.<br />
<br />
(osgi.os=linux)<br />
<br />
The latest version of Oomph allows filter properties to refer to the values of variables as defined in the setup itself. For example, this idiom can be used to express if-then-else.<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xmi:XMI xmi:version="2.0"<br />
xmlns:xmi="<nowiki>http://www.omg.org/XMI</nowiki>"<br />
xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"<br />
xmlns:setup="<nowiki>http://www.eclipse.org/oomph/setup/1.0</nowiki>"><br />
<setup:VariableTask<br />
type="BOOLEAN"<br />
name="example.filter"<br />
label="Example Filter"><br />
<description>An example of a variable used to conditionally filter tasks</description><br />
</setup:VariableTask><br />
<setup:CompoundTask<br />
filter="(example.filter=true)"<br />
name="Filter True"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.a"<br />
label="Property A"><br />
<description>The value use for system.property.a</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.a"<br />
value="=${example.variable.a}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is true</description><br />
</setup:CompoundTask><br />
<setup:CompoundTask<br />
filter="(example.filter=false)"<br />
name="Filter False"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.b"<br />
label="Property B"><br />
<description>The value used for system.property.b</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.b"<br />
value="=${example.variable.b}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is false.</description><br />
</setup:CompoundTask><br />
</xmi:XMI><br />
<br />
On the Variables page of the setup wizards, any variable that is used in property of a filter will be displayed in bold. It is significant to note that the value of a so-called filter variable can conditionally affect the presence of other variables. In this example, either variable <code>example.variable.a</code> or <code>example.variable.b</code> (but not both) will be present on the Variables page, depending on the value of the <code>example.filter</code> variable, which is displayed as a checkbox because it is of type <code>BOOLEAN</code>.<br />
<br />
Note that Oomph setup editors support textual copy and paste, so you can copy the above XML and paste it into your setup editor to try it out.<br />
<br />
== Macros and Macro Expansion Tasks ==<br />
<br />
As of Oomph 1.13, released with Eclipse 2019-06, there is support for Macros. A Macro is a Scope, i.e., is a container for setup tasks, and can specify 0 or more Parameters. Each Parameter specifies a name, a description, and optionally a default value. The parameter names can be used as variable references in the setup tasks contained by the Macro.<br />
<br />
=== Creating a Macro ===<br />
<br />
The simplest way to create a new Macro is from the context menu of the folder where you want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Macro Model in the wizard. You can then edit the new Macro with the Setup Editor. You can create Parameters, if desired, and of course you can create any other setup tasks.<br />
<br />
Here is an example of how one could use a Macro for creating a Git Clone task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Macro<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:git="http://www.eclipse.org/oomph/setup/git/1.0"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
xsi:schemaLocation="http://www.eclipse.org/oomph/setup/git/1.0 http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/models/Git.ecore"<br />
name="git.clone"<br />
label="Git Clone"><br />
<setupTask<br />
xsi:type="git:GitCloneTask"<br />
id="git.clone"<br />
remoteName="${remoteName}"<br />
remoteURI="${remoteURI}"<br />
pushURI="${pushURI}"<br />
checkoutBranch="${checkoutBranch}"><br />
<annotation<br />
source="http://www.eclipse.org/oomph/setup/FeatureSubstitution"><br />
<detail<br />
key="restrictToCheckoutBranch"><br />
<value>${restrictToCheckoutBranch}</value><br />
</detail><br />
<detail<br />
key="recursive"><br />
<value>${recursive}</value><br />
</detail><br />
</annotation><br />
<description>${description}</description><br />
</setupTask><br />
<description>The GitClone macro provides a template for creating a clone task</description><br />
<parameter<br />
name="description"><br />
<description>The description of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="pushURI"><br />
<description>The push URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="recursive"<br />
defaultValue="false"><br />
<description>Whether submodules should be recursively cloned</description><br />
</parameter><br />
<parameter<br />
name="remoteName"<br />
defaultValue="origin"><br />
<description>The name of the remote</description><br />
</parameter><br />
<parameter<br />
name="remoteURI"><br />
<description>The remote URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="restrictToCheckoutBranch"<br />
defaultValue="false"><br />
<description>Whether the clone should be restricted to clone only the checkout branch</description><br />
</parameter><br />
<parameter<br />
name="checkoutBranch"><br />
<description>The name of the branch that the Git clone task to checks out</description><br />
</parameter><br />
</setup:Macro><br />
<br />
Special support is provided for defining so called local Variables in a Macro. Any Variable with a name that starts with '*' will be handled in a special way during [[#Macro Expansion Processing|Macro Expansion]].<br />
<br />
=== Using a Macro with a Macro Expansion Task ===<br />
<br />
To use a Macro you must create a Macro Expansion task. The easiest way to do this is to drag the resource containing the Macro and then drop it into the Setup Editor where you want to use it. Similarly, if you want to use a Macro defined in the internet, you can use Load Resource... from the Setup Editor's context menu to load the Macro into the editor's resource set (or drag the link and drop it into the editor). Note that Macros available in the resource set are always shown in the Outline view. Once the Macro is available in the editor's resource set, or in the Outline, you can drag and drop the Macro anywhere that any other setup task can be created. This will create a Macro Expansion task that binds to the Macro.<br />
<br />
A Macro Expansion task must specify an ID, which of course must be unique within the containing resource. The ID is used during [[#Macro Expansion Processing|Macro Expansion Processing]]. Via drag and drop, an ID is automatically assigned, but you'll likely want to change it. A Macro Expansion task can supply Arguments to bind the values of the Parameters of the Macro. For every Parameter without a default value there must be a corresponding Argument to bind its value. The validator will complain when that's not the case, so be sure to enable Live Validation via the context menu. When creating a Macro Expansion task using drag and drop, the required Arguments are automatically created. Of course you'll want to change the generated values; you can delete any Arguments for which the Parameter specifies the default value that you wish to just use. You can change the Argument's value by double clicking the Argument to ensure that it's visible in the Properties view, and can then edit the Value property of the Argument there. The description of the corresponding Parameter is displayed in the Properties view after the Parameter's name. This is why it's important to include a description for each Parameter so that the author using the Macro knows how the Argument's value will be used by that Macro.<br />
<br />
The setup editor displays the Macro referenced by a Macro Expansion task as a child item, in light brown, in the tree view, so you can fully explore the Macro being used. In addition a Preview item is displayed, in light blue, to show how the Macro Expansion task will be expanded. And of course the Outline view allows you to preview all of the tasks that will be performed when you run the installer later.<br />
<br />
Here is an example of how the above Macro could be used by a Macro Expansion task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Project<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
name="sample.project"<br />
label="SampleProject"><br />
<setupTask<br />
xsi:type="setup:MacroTask"<br />
id="my"><br />
<macro href="GitCloneMacro.setup#/"/><br />
<argument<br />
value="description_value"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='description']"/><br />
</argument><br />
<argument<br />
value="pushURI_value"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='pushURI']"/><br />
</argument><br />
<argument><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='recursive']"/><br />
</argument><br />
<argument><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='remoteName']"/><br />
</argument><br />
<argument<br />
value="remoteURI_value"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='remoteURI']"/><br />
</argument><br />
<argument><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='restrictToCheckoutBranch']"/><br />
</argument><br />
<argument<br />
value="master"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='checkoutBranch']"/><br />
</argument><br />
</setupTask><br />
<logicalProjectContainer<br />
xsi:type="setup:ProjectCatalog"<br />
href="index:/org.eclipse.setup#//@projectCatalogs[name='org.eclipse']"/><br />
<description>SampleProject provides cool stuff.</description><br />
</setup:Project><br />
<br />
Note that here we have several Arguments without a value. Those could be deleted or a value (presumably different from the default value of the Parameter) could be specified.<br />
<br />
=== Macro Expansion Processing ===<br />
<br />
A Macro Expansion task is expanded to a Compound Setup Task as illustrated by the Preview item. Each Argument is bound to its corresponding Parameter via a local variable of the form '*<macro-expansion-task-id>.<parameter-name>'. Every variable reference to the Parameter name is transformed to use this Variable's more-qualified name instead. Every setup task with an ID is transformed to specify instead a qualified ID of the form '<macro-expansion-task-id>.<original-id>' and every variable reference that's prefixed by '<original-id>.' will be transformed to use the more-qualified prefix instead. In addition, any Variable contained by the Macro with a name that start with '*' will also be changed to use the name '*<macro-extension-task-id>.<original-name>' and all references to '<original-name>' will be transformed to use that qualified name instead. This qualification process ensures that unique Variable names are provided by the Macro Expansion because in the end, there's no such thing as a local Variable.<br />
<br />
Of course Macros themselves can use Macro Expansion tasks, so the process of expansion is recursive. That being said, it's of course invalid for this to lead to a cycle. Cycles are detected by the validator and the expansion process prevents further expansion when a cycle is encountered.<br />
<br />
Note that from the context menu of a Macro Expansion task it's possible to invoke "Inline" to replace a Macro Expansion task with its fully expanded equivalent.<br />
<br />
== Automation and Specialization with Configurations ==<br />
<br />
As of Oomph 1.6, released with Neon.2, there is support for Configurations. A Configuration is not a Scope (is not a container for setup tasks) but rather a container for an Installation and a Workspace; each is optional, but a Configuration with neither is in effect useless. The Installation and Workspace of a Configuration are effectively used as a template to initialize the Installation and Workspace created by the Eclipse Installer, i.e., the setup resources that you can open with Navigate &rarr; Open Setup &rarr; Installation and Navigate &rarr; Open Setup &rarr; Workspace in your IDE. So you can specialize the installation with additional installation-specific tasks, e.g., a p2 task to install additional features, and you can specialize the workspace with workspace-specific tasks, e.g., a variable task to specify the value of a variable so you won't be prompted for that value. <br />
<br />
Configurations are not only useful for specifying installation-specific and workspace-specific tasks but also for automating the selection process in the setup wizards, including the installer. The Configuration's Installation can reference a specific Product Version and the Configuration's Workspace can optionally reference several specific Project Streams. Both the simple mode and the advanced mode of the installer support dragging and dropping a Configuration to the title area. You can drag to the title area either a file (i.e., a file from the file system or from an Eclipse IDE), a URL (i.e., a link from a browser), or a copy of a Configuration's XMI serialization. This will '''apply''' the Configuration to the wizard with the effect that the Installation's Product Version is selected in the wizard and the wizard advances to the next page. Similarly, the Workspace's Project Streams are selected in the wizard and the wizard advances to the next page. If you apply a Configuration with a Workspace to the simple mode of the installer, you will be prompted to switch to advanced mode because only the advanced mode supports Project selection. So in simple mode, applying a Configuration advances to the final page, and in advanced mode, applying a Configuration with an Installation and a Workspace advances to the Variables page.<br />
<br />
As an alternative to drag and drop support, rather than dragging a file, link, or XMI serialization, you can copy it to the clipboard and apply the clipboard contents to the wizard. In simple mode this is done via the Apply Configuration menu item. In advanced mode this is done via the Apply Configuration toolbar button on the Product or Project page; the menu item or toolbar item is visible only if the clipboard contains applicable content.<br />
<br />
The installer application supports command line arguments so you could also specify a Configuration's file path or URL link on the command line to apply it automatically.<br />
<br />
=== Creating a Configuration ===<br />
<br />
The simplest way to create a new Configuration is from the context menu of the folder where want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Configuration Model in the wizard. You can then edit the new Configuration with the Setup Editor. You can delete the Installation or Workspace if you don't need that aspect. You can use the Properties view to set the Installation's Product Version or the Workspace's Project Streams. And of course you can create any other setup tasks in either Scope.<br />
<br />
=== Configuration Handling ===<br />
<br />
The specific form of the serialized URLs that are used to reference a Product Version or a Project Stream are very important to correct behavior. Relative URLs in the serialization can only work relative to the location of the Configuration's resource, so will only work when you drag and drop a file or link because a dragging and dropping textual copy of the serialization provides no information about how to resolve relative references. This is not to say there is anything wrong with relative references, just be aware that they imply that the user must apply the overall file or link, not just the textual serialization. <br />
<br />
Another very useful aspect of Configurations is that the wizards handle of the references intelligently. I.e., if a Installation references a Product Version that's not in any Product Catalog in the Index, the Product will automatically be added to the user-extensible Product Catalog. If the Installation references a Product Version via its containing Product Catalog and that Product Catalog is not in the Index, and the redirectable Product Catalog is not already redirected, it will be redirected to the referenced Product Catalog and an appropriate Eclipse Ini redirection tasks will be synthesized so that the installation produced by the installer will be able to resolve the Product Version reference in its Installation via the correct containing Product Catalog. Analogous processing is done for the Project Stream references with the additional processing of Project's a logical Project container which determines which Project Catalog's extensible Project container is used. In other words, Configurations can also be used to automate the addition of Products and Projects to the user extensible catalogs.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Getting Early Feedback ===<br />
Why didn't the model editor tell me earlier that I've made a silly mistake?<br />
Please enable Live Validation in the editor menu to get early feedback.<br />
<br />
=== Copying Tasks and Other Elements ===<br />
The Setup Editor supports the export and import of any model elements by using copy to or paste from the clipboard. The clipboard will/must contain a valid XML document. With this method, for example, you can easily copy task snippets from your model directly into a forum post when you ask for help (or into a Skype window when you chat with your collegues). Or you can easily paste such XML snippets from forum replies directly into your Setup Editor.<br />
<br />
You have access to many example setups from within your IDE! Use Navigate->Open Setup->Parent Models->Open Catalog Index to investigate everything within the index. The context menu provides a way to open elements in a text editor. This is particularly handy for finding out where a particular setup is hosted (hrefs are resolved in the Setup editor) - one use case is checking and repairing links to project setups added to your user projects.<br />
<br />
=== Hosting your own index / catalogs ===<br />
If you want to host your own product or project catalog, you must provide a URI mapping to the installer to locate the root setup file (the "index"). Open the eclipse.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, or use the wizard to create it. 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/. You can redirect to your own index with this redirection system property:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->http://<hostname>/<path>/</nowiki><br />
<br />
The source URI may be abbreviated to <nowiki>index:/</nowiki> and the target URI may also be a file URI, e.g. on a shared file server.<br />
<br />
In general it will be highly desirable to archive your setup, but documentation for that is TBD. The installer and other setup wizards support dragging and dropping an index or archived index onto the title area of the dialog. Documentation for that is also TBD.<br />
<br />
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=481580 Bug 481580] has introduced empty redirectable catalogs for products ('''redirectable.products.setup''') and projects ('''redirectable.projects.setup''') to the Oomph index. These allow providing your own catalogs without replacing the entire index or disabling the catalogs shipped with Oomph (by redirecting them). The following steps are necessary to make use of those setups.<br />
* Create your own project catalog setup file using the wizard. Project setups in the project catalog should typically be referenced using absolute URIs, otherwise redirection can become problematic. However, if the relative references are downward pointing to some uniquely named folder different from any of the file/folder names in the Eclipse.org index, i.e., no '''..''' traversal to the parent folder is involved and some folder name '''<my-projects-folder>''', then they will be resolved to absolute URIs of the form '''index:/<my-projects-folder>/<path>''' which can be handled as described below.<br />
* Add a redirection system property similar to that described above to the eclipse.ini file, e.g., '''-Doomph.redirection.myProjectCatalog=index:/redirectable.projects.setup->...'''.<br />
* If the projects in that catalog are referenced by relative downward references with a unique folder, also add a folder redirection system property, e.g.,'''-Doomph.redirection.myProjectCatalog=index:/<my-projects-folder>/->.../''', to redirect the locations of the referenced projects to the folder where they are physically hosted.<br />
* Your catalog setup file must contain an Eclipse Ini task creating the same redirection(s)! Otherwise your catalog (or the referenced projects) will not be visible in the Eclipse created by the installer and hence the projects selected from it cannot be provisioned.<br />
* The first time, you may have to enable your new catalog by selecting it in the folders icon of the drop-down in the upper right hand corner of the wizard's Projects page, otherwise it will be invisible.<br />
<br />
To debug the processing of -Doomph.redirection.* if needed, set a breakpoint in org.eclipse.oomph.setup.internal.core.util.SetupCoreUtil.configureResourceSet(ResourceSet) within if (((String)key).startsWith(SetupProperties.PROP_REDIRECTION_BASE)).<br />
<br />
=== Shipping your own index ===<br />
If you want to include your own product or project catalog, you may ship the root setup file (the "index") relative to the installer directory. Then you can redirect the index as explained in [[#Hosting your own index / catalogs| Hosting your own index / catalogs]]. For example, you can place all setup files in an eclipse-installer/setups/ folder and then redirect access to it with a relative target URI:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->setups/</nowiki><br />
<br />
Note that shipping the index rather than maintaining it in a central location (accessible to all parties interested) has the following disadvantage. As each user has her own copy of the index, updates in the setup files will not be distributed automatically.<br />
<br />
=== Generating PDE Target Definition files (*.target) and their use by Tycho ===<br />
<br />
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. <br />
<br />
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:<br />
<br />
<annotation<br />
source="http:/www.eclipse.org/oomph/targlets/TargetDefinitionGenerator"><br />
<detail<br />
key="location"><br />
<value>${git.clone.location}/targetdefinition/DesignStudio.target</value><br />
</detail><br />
<detail<br />
key="extraUnits"><br />
<value>org.eclipse.equinox.executable.feature.group</value><br />
</detail><br />
<detail<br />
key="includeAllPlatforms"><br />
<value>false</value><br />
</detail><br />
<detail<br />
key="includeSource"><br />
<value>true</value><br />
</detail><br />
<detail<br />
key="generateVersions"><br />
<value>true</value><br />
</detail><br />
</annotation><br />
<br />
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.<br />
<br />
''TODO Document what preferredRepositories, PomModulesUpdater & PomArtifactUpdater do...''<br />
<br />
=== Setting up WST Server Runtime and Instances in your Setup ===<br />
<br />
==== Server Runtime Preference ====<br />
<br />
1. Use an oomphed installation/workspace with preference recorder enabled.<br />
<br />
2. Open your project and user setup editors.<br />
<br />
3. Go to Preferences / Server / Runtime Environments and 'Add' it as usual.<br />
<br />
4. Drag the selected '/instance/org.eclipse.wst.server.core/runtimes' from user to project setup.<br />
<br />
Note: It's unclear if the above actually works. Please see thread https://www.eclipse.org/forums/index.php/t/1086488/ in forum for details.<br />
For some servers there are extension tasks to handle configuration, see below.<br />
<br />
==== Server Instance in Servers View ====<br />
Requires server runtime to be setup first.<br />
<br />
1. Open Servers View and create New server instance and deploy webapps as usual<br />
<br />
2. Optionally open server instance editor and adapt configuration as usual.<br />
<br />
3. Close Eclipse.<br />
<br />
4. Start it again.<br />
<br />
5. Open '.plugins/org.eclipse.wst.server.core/servers.xml' from your workspace/.metadata using a UTF capable editor<br />
<br />
6. Add Resource Creation Task to your setup:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
content="PUT_CONTENT_FROM_SERVERS_XML_INTO_HERE_USING_A_UTF_CAPABLE_EDITOR_AND_OOMPH_DIALOG"<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.wst.server.core/servers.xml"<br />
encoding="UTF-8"><br />
<description>tomcat server integration</description><br />
</setup:ResourceCreationTask><br />
<br />
7. Use the resource task content dialog to put the servers xml content into the task.<br />
<br />
8. Copy "Servers" project from this workspace into a suitable location of your branch checkout and add/commit/push.<br />
<br />
9. Setup project import task that can pick the Servers project up from that committed location.<br />
<br />
That's it. If you want to share it among fellows, be sure to agree on canonical paths for your server installations.<br />
<br />
==== Extension tasks for specific servers ====<br />
<br />
For some servers there are oomph extension tasks that can be used to handle the configuration:<br />
<br />
https://github.com/gratex/oomph-task-server - Tomcat, WebLogic, and WebSphere<br />
<br />
=== Suppress prompt for default workspace already upon very first start ===<br />
<br />
Adjust the SHOW_WORKSPACE_SELECTION_DIALOG property to false via configuration settings org.eclipse.ui.ide.prefs ...<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP MANUAL"<br />
content="MAX_RECENT_WORKSPACES=5&amp;#xD;&amp;#xA;RECENT_WORKSPACES=${workspace.location|property}&amp;#xD;&amp;#xA;RECENT_WORKSPACES_PROTOCOL=3&amp;#xD;&amp;#xA;SHOW_WORKSPACE_SELECTION_DIALOG=false&amp;#xD;&amp;#xA;eclipse.preferences.version=1"<br />
targetURL="configuration:/.settings/org.eclipse.ui.ide.prefs"<br />
encoding="UTF-8"/><br />
<br />
=== Open default perspective already upon very first start ===<br />
Examples below using Perspective ID for Java perspective.<br />
<br />
Tell Eclipse which perspective to open initially, by adding option to eclipse ini:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:EclipseIniTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP"<br />
option="-perspective"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
Setting a perspective to be default, by adding preference task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:PreferenceTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
key="/instance/org.eclipse.ui/defaultPerspectiveId"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
=== How to switch the current stream ===<br />
<br />
If you would like to switch the current stream/s, you can re-use Oomph's initial "Eclipse Importer" wizard, available as "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace.<br />
<br />
Note that it is currently not yet possible to remove the "current" project stream. As a workaround, use menu Navigate > Open Setup > Open Workspace (or if visible click the 'blue guy' icon in the Oomph toolbar) to Open Workspace workspace.setup, expand the first node, click on the Workspace entry, open Properties view, and change the last property named "Streams" and remove the current stream.<br />
<br />
Bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=476434 enhancement may make this easier in the future.<br />
<br />
<br />
=== How to install Eclipse plugins using the P2 Director and Repository Explorer ===<br />
<br />
Oomph can install Eclipse plugins which you require. This also works for normal Java Projects set up models, not just for Eclipse plug in OSGi development, and is handy to install commonly used 3rd-party Eclipse plugins which are not all available from eclipse.org p2 sites (think e.g. http://eclemma.org). Here's how:<br />
<br />
1. add a P2 Director child task to your *.setup, if it doesn't already have one<br />
<br />
2. add a Repository child in your P2 Director task<br />
<br />
3. in the Properties of the Repository set the URL to a valid p2 repo (e.g. http://update.eclemma.org)<br />
<br />
4. right-click that Repository and choose Explore, to open the Repository Explorer view<br />
<br />
5. in the Repository Explorer view change to [X] Compatible and (*) Minor at the lower-right hand corner<br />
<br />
6. drag & drop the version from the Repository Explorer view into the P2 Director task of your *.setup editor, to create a Requirement child<br />
<br />
Drag & Drop should normally work, but appears to be broken at least on Neon Milestone 6 on Linux; in that case:<br />
<br />
6. manually create a new child Requirement inside the P2 Director task<br />
<br />
7. in the Repository Explorer view use the brown (C) icon to switch to Expert Mode to see IDs instead of names<br />
<br />
8. find the ID of the feature IU, it's the one with a PDE feature + folder kind of icon, often ending in (feature.)feature.group<br />
<br />
9. in the Properties of the Requirement, type the Name to the ID found above (e.g. com.mountainminds.eclemma.feature.feature.group)<br />
<br />
10. in the Properties of the Requirement, Type should have automatically switched to Feature<br />
<br />
PS: If you are looking for the URL of p2 repos to pre-install some of the the M2E connectors, see https://git.eclipse.org/c/m2e/m2e-discovery-catalog.git/tree/org.eclipse.m2e.discovery.oss/connectors.xml<br />
<br />
<br />
<br />
=== How to create M2E lifecycle-mapping-metadata.xml to avoid littering your pom.xml with org.eclipse.m2e:lifecycle-mapping ===<br />
<br />
Read https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html & https://wiki.eclipse.org/M2E_compatible_maven_plugins and apply as follows:<br />
<br />
<setupTask<br />
xsi:type="setup:PreferenceTask"<br />
key="/instance/org.eclipse.m2e.core/eclipse.m2.WorkspacelifecycleMappingsLocation"<br />
value="${workspace.location}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"/><br />
<br />
<setupTask<br />
xsi:type="setup:ResourceCreationTask"<br />
content="..."<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"<br />
encoding="UTF-8"><br />
<description>Initialize M2E's Maven Lifecycle Mappings, see https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html &amp; https://wiki.eclipse.org/M2E_compatible_maven_plugins</description><br />
</setupTask><br />
<br />
For "content" just open the popup using the [...] icon in the Properties and copy/paste the content from menu Window > Preferences > Maven > Lifecycle Mappings: Open workspace lifecycle mappings metadata. (This is easier than editing the content=".." in source view, because it will correctly do the XML escaping for you.)<br />
<br />
Now whenever M2E whines about stuff like "Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-dependency-plugin:2.10:unpack (execution: unpack-license, phase: generate-resources)" etc. just use the Quick Fix in the Problems view and choose the option to use workspace preferences (instead of letting the quick fix modify your pom.xml to add org.eclipse.m2e:lifecycle-mapping <lifecycleMappingMetadata>).<br />
<br />
<br />
=== How to automatically pre-enable Gerrit ===<br />
<br />
If you would like to save your end-users from having to [[EGit/User_Guide#Enabling_Gerrit_for_a_repository|manually enabling Gerrit for a repository in EGit]], then you can use the follow magic variable which Oomph will recognize and act upon:<br />
<br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="YOURORG.gerrit.uri.pattern"<br />
value="(https|ssh)://([^@/]+@)?(git.YOURORG.org:29418/.*|git.YOURORG.org/gerrit/.*)"/><br />
<br />
=== How to find a P2 repository at Eclipse using the Repository Explorer ===<br />
<br />
Most projects don't document the locations of all their p2 update sites very well. This makes it hard to find the URL you need in order to install something or in order to specify a URL for your target platform definition. Oomph indexes all the p2 update sites available at download.eclipse.org to make this job easier. You can make use of this as follows:<br />
<br />
# In the Quick Access control, type "Repository Explorer" to show Oomph's Repository Explorer view.<br />
# In that view's toolbar, locate the tool item with the hover "Search Eclipse repositories by provided capabilities", i.e., the one that looks like a little search flashlight, and click it.<br />
# This brings up the "Eclipse Repository Search" dialog. The index is very large so it takes a while to load it. But it's cached locally and updated on the server once per day.<br />
# At the root of the displayed tree are p2's namespaces and under each of these are the capabilities in that namespace. They're organized hierarchically by their qualified name. It's all quite technical and the tree is very large. So while you can explore it, you'll most likely want to use the filter to find something quickly.<br />
# Type the fully qualified name of a Java package or installable unit you wish to locate into the filter. Note that tree items for which there exist a concrete version in some repository are decorated as such. Keep in mind that many projects don't version their Java packages, so it's often better to look at the org.eclipse.equinox.p2.iu category. Here's what it looks like searching for "org.eclipse.emf.ecore.xcore":<br>[[File:SearchEclipseRepositoryDialog.png]]<br><br />
# You can select a capability in the tree so that the lower panel displays all the versions of the capability that are available. Under each of those are nested the update sites that contain them. Composite update sites show their children hierarchically.<br />
# Of course you can double click a repository to further explore its contents in the Repository Explorer itself.<br />
<br />
<br />
=== How to extract the constituent parts that comprise the Windows self-extracting installer executable ===<br />
<br />
The Eclipse Installer distribution for the Windows platform is effectively a self-extracting executable. It is extracted at runtime by the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINExtractor.java Bin Extractor]. The pre-built version of this library, i.e., org.eclipse.oomph.extractor.lib-*.jar, is available in all Oomph-containing installations, i.e., in the installer itself and in applications installed by the installer. This library can also be used standalone to decompose the composed executable into its constituent parts. That can be accomplished if you run it with the correct magical program arguments as follows:<br />
<br />
java -classpath <path-to-extract-lib>\org.eclipse.oomph.extractor.lib-*.jar<br />
org.eclipse.oomph.extractor.lib.BINExtractor <br />
<path-to-executable-to-extract>\eclipse-inst-win64.exe <br />
<target-path>\product.zip <br />
-export <br />
<target-path>\marker.txt <br />
<target-path>\extractor.exe <br />
<target-path>\org.eclipse.oomph.extractor.lib.jar <br />
<target-path>\product-descriptor<br />
<br />
The Java VM arguments need only specify the extractor library along with the main class in that library. The first program argument is the location of the executable you wish to decompose, the 64 bit installer in this case. The remaining arguments are all best directed into a common folder, denoted as <target-path> in the example above. The second argument is the extracted location of the zip file of the product/distribution. The third argument is the -export flag. The fourth argument is the extracted location of the text file containing the marker text that is used to delimit the constituent parts of the composed executable. The fifth argument is the extracted location of the small native executable itself. The sixth argument is the extracted location of the extractor library, the same one being used to extract the parts. The seventh and final argument is the extracted location of the product descriptor. Such a [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINDescriptor.java descriptor] looks like this:<br />
<br />
1<br />
1<br />
7<br />
0<br />
64<br />
0<br />
eclipse-inst.exe<br />
eclipse-inst.ini<br />
Eclipse Installer<br />
http://wiki.eclipse.org/Eclipse_Installer<br />
http://download.eclipse.org/oomph/jre/128x128.png<br />
<br />
Of course you can edit these parts and then you can recompose the executable using the following bash script executed within the common folder in which you have extracted the constituent parts:<br />
<br />
COPY /B extractor.exe + ^<br />
marker.txt + ^<br />
org.eclipse.oomph.extractor.lib.jar + ^<br />
marker.txt + ^<br />
product-descriptor + ^<br />
marker.txt + ^<br />
product.zip + ^<br />
marker.txt ^<br />
eclipse-inst-64.exe<br />
<br />
Note that the file names match the extracted target file names. From this is should be clear that the native executable is just a composition of parts. This structure is used at runtime as follows. The extractor.exe runs natively, reading its own executable file, using the marker text to find the parts. It checks the descriptor to determine if an appropriate version of Java is already installed, i.e., one that will be able to launch the product; the native extractor consults the registry to find all installed JREs and JVMs. If an appropriate Java is not found, it opens a browser page prompting the user to install an appropriate Java version with the required bitness and at the minimum required version. If there is already an appropriate version of Java, it launches a Java process to execute the BinExtract's main method. That process in turn unzips the product zip to a temp folder and launches the Java process for that for the product/distribution.<br />
<br />
== Oomph Configuration Options ==<br />
<br />
=== Configuration Options for Installer .ini File ===<br />
<br />
{| class="wikitable"<br />
| '''-Doomph.redirection.setups''' || Redirects the location of setup files (index, catalog and products). The default URI is ''http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/'' and my be abbreviated with '''index:/'''. The syntax of the redirection is '''index:/->[redirection URI]'''. Examples: '''-Doomph.redirection.setups=index:/->http://<hostname>/<path>/''' (external server redirection) or '''-Doomph.redirection.setups=index:/->setups/''' (path relative to installer executable). See also [[#Hosting_your_own_index_.2F_catalogs|Hosting your own index & catalogs]]<br />
|-<br />
| '''-Doomph.setup.product.catalog.filter''' || Only displays product catalogs matching the given prefix. The default is ''org\\.eclipse\\.products''. Displays all catalogs if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.filter''' || Only displays products matching the given prefix. The default is ''(?\!org\\.eclipse\\.products\\.org\\.eclipse\\.platform\\.ide).*''. Displays all products if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.version.filter''' || Only displays product versions matching the given prefix. The default is ''.*\\.neon''. Displays all product versions if value is empty.<br />
|-<br />
| '''-Doomph.p2.pool''' || Set to ''@none'' to disable bundle pools. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=507594] for details.<br />
|}<br />
<br />
== Troubleshooting ==<br />
=== The preference task does not setup any preferences ===<br />
<br />
First of all. Please note that the preferences are not set up as part of the installation. They are setup when the installed eclipse is first started.<br />
<br />
To do this the installed product needs to have the following feature installed:<br />
''org.eclipse.oomph.setup.feature.group''<br />
<br />
The feature is already included in the root of the Eclipse.org Product Catalog. If you are not using it you can include the same task by yourself:<br />
<br />
<setup.p2:P2Task<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup.p2="http://www.eclipse.org/oomph/setup/p2/1.0"><br />
<requirement<br />
name="org.eclipse.oomph.setup.feature.group"/><br />
<repository<br />
url="${oomph.update.url}"/><br />
</setup.p2:P2Task></div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Oomph_Authoring&diff=432499Eclipse Oomph Authoring2019-05-26T05:05:22Z<p>Stepper.esc-net.de: /* Using a Macro with a Macro Expansion Task */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
== Getting Started ==<br />
<br />
=== What is Oomph? ===<br />
<br />
Please read [[Eclipse Installer]].<br />
<br />
<br />
=== Installing Oomph ===<br />
<br />
# Download and install the Eclipse '''Installer''' as outlined in [[Eclipse Installer]].<br />
# Make sure that the Oomph setup '''SDK''' is installed in your IDE. Either:<br />
## That's already the case because your IDE is a Mars M5 or later Eclipse Package, or<br />
## Start the installer and install an IDE of your choice (select on the first installer page), or<br />
## Use p2 to install "Oomph Setup SDK" from [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest].<br />
<br />
== Creating a Setup Project Model ==<br />
<br />
=== Using the Setup Project Model Wizard ===<br />
<br />
# Create an empty project in your workspace or select a folder in an existing project. You'll create the new "Setup Project Model" in the selected folder.<br />
# Open the New... dialog and select the "Setup Project Model" wizard:<br>[[Image:new-wizard.png]]<br><br />
# Select one of the provided templates (e.g., Eclipse.org, Github.com, or Simple) and adjust the displayed values:<br>[[Image:new-wizard-2.png]]<br><br />
# Some values are automatically derived from your input to fields '''higher up'''.<br />
# Open the Preview>>> to understand the impact of changes to the current field.<br />
<br />
=== Using the Setup Editor ===<br />
<br />
# Open the resulting setup file with Oomph's Setup Editor:<br>[[Image:setup-edit.png]]<br><br />
# Configure the tasks in the Properties view. Note that there are "Expert" properties available.<br />
# Add setup tasks to your project and/or to your project streams and configure them, too.<br />
# The Outline view displays a ''preview'' of the executable model with resolved variables.<br />
<br />
=== Testing the Setup Model ===<br />
<br />
# To test/execute your new setup model:<br />
## Start the installer and, if necessary, switch to the Advanced Mode via the dialog menu.<br />
## Pick any product on page 1 and click the Next button to proceed to page 2.<br />
## Drag and drop your <tt>.setup</tt> file onto one of the top-level catalogs (<tt>Eclipse.org</tt> or <tt>Github.com</tt>) in the projects tree. Your project will appear as a subproject of the special <tt>&lt;User&gt;</tt> project.<br />
## Double-click your project to add it to the table at the 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.<br />
## Fill in the empty fields and press the Next button to proceed to the Confirmation page.<br />
## 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.<br><br />
# 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 [[#Using the Setup Editor|Using the Setup Editor]]. If the IDE comes up but the initial configuration fails continue with step 3.<br />
# In the new IDE (whether the initial configuration was successful or not) open your model file from the main menu, Navigate &rarr; Open Setup &rarr; [[Image:branch.png]]. Find the problems and fix them. Then start the setup process '''from within''' this IDE via the main menu, Help &rarr; [[Image:update.png]] Perform Setup Tasks&hellip;. 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.<br />
<br />
=== Contributing to a Project Catalog ===<br />
<br />
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 http://git.eclipse.org/c] and [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&bug_severity=enhancement&short_desc=Please%20include%20setup%20for%20project%20Xyz 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.<br />
<br />
The same can be done if your project is not an Eclipse project, but hosted on '''GitHub'''. Simply state this fact in the bug description and paste the "raw" content URL to the file instead.<br />
<br />
== Understanding the Setup Engine ==<br />
<br />
=== Understanding Setup Tasks and Scopes ===<br />
<br />
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:<br />
<br />
* The '''Installation''' scope is located in <tt>eclipse/configuration/org.eclipse.oomph.setup/installation.setup</tt> 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.<br />
<br />
* The '''Workspace''' scope is located in <tt>workspace/.metadata/.plugins/org.eclipse.oomph.setup/workspace.setup</tt> 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.<br />
<br />
* The '''User''' scope is located in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup</tt> and contains tasks that are common to '''all''' installations and workspaces (unless they're restricted to particular installations or workspaces).<br />
<br />
<br />
The following additional scope types exist, so they can be referenced by the entry scopes:<br />
<br />
* The '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.setup Catalog Index]''' is the root scope and contains nested Product Catalogs and Project Catalogs.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.products.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/OomphInstaller.setup Product]''' contains nested Product Version scopes and possibly some tasks that are common to all nested scopes.<br />
<br />
* A '''Product Version''' contains no nested scopes but tasks that are specific to that product version.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.projects.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/Oomph.setup Project]''' contains nested Stream and/or (Sub-) Project scopes and typically some tasks that are common to all nested scopes.<br />
<br />
* A '''Stream''' contains no nested scopes but tasks that are specific to that stream.<br />
<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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 [[#Declaring_and_Using_Variables|Declaring and Using Variables]] below.<br />
<br />
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). <br />
<br />
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.<br />
<br />
=== Declaring and Using Variables ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:<br />
<br />
${''variable-name''}<br />
<br />
To prevent a variable reference from being expanded (e.g. you actually want to have the value '${var}' and not the value of "var"), you need to escape the variable syntax with an extra double dollar character. So "$${var}" will result in "${var}".<br />
<br />
In addition to the variables that are declared by VariableTasks you can refer to all of the following:<br />
<br />
* Attribute values of setup tasks with a defined ID. The reference syntax is ${''taskID''.''attributeName''}.<br />
* System properties as returned by <tt>System.getProperties()</tt><br />
* [[#Environment Variables|Environment variables]] as returned by <tt>System.getenv()</tt><br />
* [[#Predefined Variables|Predefined variables]] as determined by the setup engine from the user input to the installer (see below)<br />
<br />
==== Predefined Variables ====<br />
<br />
The following variables are predefined by the setup engine:<br />
<br />
{| class="wikitable"<br />
| '''scope.installation.name''' || The value of the <em>name</em> attribute of the current installation scope. <br />
|-<br />
| '''scope.installation.label''' || The value of the <em>label</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.installation.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.workspace.name''' || The value of the <em>name</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.label''' || The value of the <em>label</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.description''' || The value of the <em>description</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.user.name''' || The value of the <em>name</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.label''' || The value of the <em>label</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.description''' || The value of the <em>description</em> attribute of the current user scope.<br />
|-<br />
| '''scope.product.catalog.name''' || The value of the <em>name</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.label''' || The value of the <em>label</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.description''' || The value of the <em>description</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.name''' || The value of the <em>name</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product scope and its parent scopes.<br />
|-<br />
| '''scope.product.label''' || The value of the <em>label</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.description''' || The value of the <em>description</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.version.name''' || The value of the <em>name</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product version scope and its parent scopes.<br />
|-<br />
| '''scope.product.version.label''' || The value of the <em>label</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.project.catalog.name''' || The value of the <em>name</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.label''' || The value of the <em>label</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.description''' || The value of the <em>description</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.name''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current project scope and its parent scopes.<br />
|-<br />
| '''scope.project.label''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.description''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.stream.name''' || The value of the <em>name</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current stream scope and its parent scopes.<br />
|-<br />
| '''scope.project.stream.label''' || The value of the <em>label</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.description''' || The value of the <em>description</em> attribute of the current stream scope.<br />
|}<br />
<br />
<br />
==== Variable Extensions ====<br />
<br />
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.:<br />
<br />
${installation.location/git/myproject} evaluates to C:\develop\installation1\git\myproject on Windows<br />
<br />
<br />
After the path extension part you can add filter calls with pipe symbols. Filter names are generally case-insensitive. Multiple filters can be chained. Example:<br />
<br />
${installation.location|uri}/git/myproject evaluates to file:/C:/develop/installation1/git/myproject<br />
<br />
<br />
==== Variable Filters ====<br />
<br />
The following filters are currently available:<br />
<br />
{| class="wikitable"<br />
| '''base64''' || <br />
|-<br />
| '''basePath''' || Removes the last segment from a file system path.<br />
|-<br />
| '''camel''' || Converts a qualified name to camel case notation.<br />
|-<br />
| '''canonical''' || Canonicalizes a file system path.<br />
|-<br />
| '''cap''' || Capitalizes the first word of a String value.<br />
|-<br />
| '''capAll''' || Capitalizes all words of a String value.<br />
|-<br />
| '''file''' || Converts a file: URI to an OS-specific file system path.<br />
|-<br />
| '''fileExtension''' || Extracts the file extension from a URI or a file system path.<br />
|-<br />
| '''gitRepository''' || Extracts the name of the repository from a Git URI (excluding a possible .git suffix).<br />
|-<br />
| '''lastSegment''' || Extracts the last segment from a file system path.<br />
|-<br />
| '''length''' || Converts a String to a String that contains the alpha-numerical representation of the length of the original String.<br />
|-<br />
| '''lower''' || Converts all characters of a String value to lower-case.<br />
|-<br />
| '''path''' || Extracts the path segments from a URI.<br />
|-<br />
| '''pathEncode''' || Converts a file system path to a String value that can be used as a file name.<br />
|-<br />
| '''preferenceNode''' || Escapes all forward slashes (/) of a String value, so that the result can be used as a value in preference nodes.<br />
|-<br />
| '''property''' || Escapes all double back slashes (\\) of a String value, so that the result can be used as a value in properties.<br />
|-<br />
| '''propertyValue''' || Interprets the String value as a preference property path and returns the value of that property.<br />
|-<br />
| '''qualifiedName''' || Converts a camel case String value name to a qualified name.<br />
|-<br />
| '''slashDecode''' || Decodes a slashEncoded String value.<br />
|-<br />
| '''slashEncode''' || Encodes all slashes and backslashes of a String value.<br />
|-<br />
| '''trim''' || Removes all whitespace from the beginning and the end of a String.<br />
|-<br />
| '''trimLeft''' || Removes all whitespace from the beginning of a String.<br />
|-<br />
| '''trimRight''' || Removes all whitespace from the end of a String.<br />
|-<br />
| '''trimTrailingSlashes''' || Removes all slashes and backslashes from the end of a String.<br />
|-<br />
| '''upper''' || Converts all characters of a String value to upper-case.<br />
|-<br />
| '''uri''' || Converts a file system path to a file: URI.<br />
|-<br />
| '''uriLastSegment''' || Extracts the last path segment from a hierarchical URI or the authority from an opaque URI.<br />
|-<br />
| '''urlDecode''' || Decodes a URL.<br />
|-<br />
| '''urlEncode''' || URL-encodes a String value.<br />
|-<br />
| '''username''' || Escapes all "at" symbols (@) of a String value, so that the result can be used in URI that contain a username.<br />
|}<br />
<br />
==== Variables from Outer Scopes====<br />
<br />
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:<br />
<br />
* '''jre.location-1.4''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.5''' --> The folder containing a 1.5 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.6''' --> The folder containing a 1.6 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.7''' --> The folder containing a 1.7 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.8''' --> The folder containing a 1.8 compatible JDK/JRE for architecture ${os.arch}<br />
* '''git.user.id''' --> The Eclipse user ID for Git/Gerrit commits<br />
* '''git.author.name''' --> The Eclipse author name for Git/Gerrit commits<br />
* '''git.author.email''' --> The Eclipse author email for Git/Gerrit commits<br />
* '''bugzilla.id''' --> The Eclipse user ID for Bugzilla/Hudson<br />
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson<br />
<br />
<br />
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.<br />
<br />
==== Environment Variables ====<br />
<br />
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.<br />
<br />
=== Conditional Tasks ===<br />
<br />
All setup tasks support filters. Oomph reuses [https://wiki.eclipse.org/Equinox_P2_Resolution#Enablement_filter p2's implementation] of LDAP filters. I.e., it supports a string a representation of LDAP Search Filters, RFC 1960, UMich, 1996,<br />
http://www.ietf.org/rfc/rfc1960.txt<br />
<br />
The filter property of a setup task is an advanced property. To display this property, ensure that the "Show Advanced Properties" is enabled in the Properties view tool bar. The properties of a filter expression can generally refer to any system property or any environment variable. For example, the following filter expression on a task will ensure that it is included only when performing a task on a Linux operating system.<br />
<br />
(osgi.os=linux)<br />
<br />
The latest version of Oomph allows filter properties to refer to the values of variables as defined in the setup itself. For example, this idiom can be used to express if-then-else.<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xmi:XMI xmi:version="2.0"<br />
xmlns:xmi="<nowiki>http://www.omg.org/XMI</nowiki>"<br />
xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"<br />
xmlns:setup="<nowiki>http://www.eclipse.org/oomph/setup/1.0</nowiki>"><br />
<setup:VariableTask<br />
type="BOOLEAN"<br />
name="example.filter"<br />
label="Example Filter"><br />
<description>An example of a variable used to conditionally filter tasks</description><br />
</setup:VariableTask><br />
<setup:CompoundTask<br />
filter="(example.filter=true)"<br />
name="Filter True"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.a"<br />
label="Property A"><br />
<description>The value use for system.property.a</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.a"<br />
value="=${example.variable.a}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is true</description><br />
</setup:CompoundTask><br />
<setup:CompoundTask<br />
filter="(example.filter=false)"<br />
name="Filter False"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.b"<br />
label="Property B"><br />
<description>The value used for system.property.b</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.b"<br />
value="=${example.variable.b}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is false.</description><br />
</setup:CompoundTask><br />
</xmi:XMI><br />
<br />
On the Variables page of the setup wizards, any variable that is used in property of a filter will be displayed in bold. It is significant to note that the value of a so-called filter variable can conditionally affect the presence of other variables. In this example, either variable <code>example.variable.a</code> or <code>example.variable.b</code> (but not both) will be present on the Variables page, depending on the value of the <code>example.filter</code> variable, which is displayed as a checkbox because it is of type <code>BOOLEAN</code>.<br />
<br />
Note that Oomph setup editors support textual copy and paste, so you can copy the above XML and paste it into your setup editor to try it out.<br />
<br />
== Macros and Macro Expansion Tasks ==<br />
<br />
As of Oomph 1.13, released with Eclipse 2019-06, there is support for Macros. A Macro is a Scope, i.e., is a container for setup tasks, and can specify 0 or more Parameters. Each Parameter specifies a name, a description, and optionally a default value. The parameter names can be used as variable references in the setup tasks contained by the Macro.<br />
<br />
=== Creating a Macro ===<br />
<br />
The simplest way to create a new Macro is from the context menu of the folder where you want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Macro Model in the wizard. You can then edit the new Macro with the Setup Editor. You can create Parameters, if desired, and of course you can create any other setup tasks.<br />
<br />
Here is an example of how one could use a Macro for creating a Git Clone task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Macro<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:git="http://www.eclipse.org/oomph/setup/git/1.0"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
xsi:schemaLocation="http://www.eclipse.org/oomph/setup/git/1.0 http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/models/Git.ecore"<br />
name="git.clone"<br />
label="Git Clone"><br />
<setupTask<br />
xsi:type="git:GitCloneTask"<br />
id="git.clone"<br />
remoteName="${remoteName}"<br />
remoteURI="${remoteURI}"<br />
pushURI="${pushURI}"<br />
checkoutBranch="${checkoutBranch}"><br />
<annotation<br />
source="http://www.eclipse.org/oomph/setup/FeatureSubstitution"><br />
<detail<br />
key="restrictToCheckoutBranch"><br />
<value>${restrictToCheckoutBranch}</value><br />
</detail><br />
<detail<br />
key="recursive"><br />
<value>${recursive}</value><br />
</detail><br />
</annotation><br />
<description>${description}</description><br />
</setupTask><br />
<description>The GitClone macro provides a template for creating a clone task</description><br />
<parameter<br />
name="description"><br />
<description>The description of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="pushURI"><br />
<description>The push URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="recursive"<br />
defaultValue="false"><br />
<description>Whether submodules should be recursively cloned</description><br />
</parameter><br />
<parameter<br />
name="remoteName"<br />
defaultValue="origin"><br />
<description>The name of the remote</description><br />
</parameter><br />
<parameter<br />
name="remoteURI"><br />
<description>The remote URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="restrictToCheckoutBranch"<br />
defaultValue="false"><br />
<description>Whether the clone should be restricted to clone only the checkout branch</description><br />
</parameter><br />
<parameter<br />
name="checkoutBranch"><br />
<description>The name of the branch that the Git clone task to checks out</description><br />
</parameter><br />
</setup:Macro><br />
<br />
Special support is provided for defining so called local Variables in a Macro. Any Variable with a name that starts with '*' will be handled in a special way during [[#Macro Expansion Processing|Macro Expansion]].<br />
<br />
=== Using a Macro with a Macro Expansion Task ===<br />
<br />
To use a Macro you must create a Macro Expansion task. The easiest way to do this is to drag the resource containing the Macro and then drop it into the Setup Editor where you want to use it. Similarly, if you want to use a Macro defined in the internet, you can use Load Resource... from the Setup Editor's context menu to load the Macro into the editor's resource set (or drag the link and drop it into the editor). Note that Macros available in the resource set are always shown in the Outline view. Once the Macro is available in the editor's resource set, or in the Outline, you can drag and drop the Macro anywhere that any other setup task can be created. This will create a Macro Expansion task that binds to the Macro.<br />
<br />
A Macro Expansion task must specify an ID, which of course must be unique within the containing resource. The ID is used during [[#Macro Expansion Processing|Macro Expansion Processing]]. Via drag and drop, an ID is automatically assigned, but you'll likely want to change it. A Macro Expansion task can supply Arguments to bind the values of the Parameters of the Macro. For every Parameter without a default value there must be a corresponding Argument to bind its value. The validator will complain when that's not the case, so be sure to enable Live Validation via the context menu. When creating a Macro Expansion task using drag and drop, the required Arguments are automatically created. Of course you'll want to change the generated values; you can delete any Arguments for which the Parameter specifies the default value that you wish to just use. You can change the Argument's value by double clicking the Argument to ensure that it's visible in the Properties view, and can then edit the Value property of the Argument there. The description of the corresponding Parameter is displayed in the Properties view after the Parameter's name. This is why it's important to include a description for each Parameter so that the author using the Macro knows how the Argument's value will be used by that Macro.<br />
<br />
The setup editor displays the Macro referenced by a Macro Expansion task as a child item, in light brown, in the tree view, so you can fully explore the Macro being used. In addition a Preview item is displayed, in light blue, to show how the Macro Expansion task will be expanded. And of course the Outline view allows you to preview all of the tasks that will be performed when you run the installer later.<br />
<br />
Here is an example of how the above Macro could be used by a Macro Expansion task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Project<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
name="sample.project"<br />
label="SampleProject"><br />
<setupTask<br />
xsi:type="setup:MacroTask"<br />
id="my"><br />
<macro href="GitCloneMacro.setup#/"/><br />
<argument<br />
value="description_value"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='description']"/><br />
</argument><br />
<argument<br />
value="pushURI_value"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='pushURI']"/><br />
</argument><br />
<argument><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='recursive']"/><br />
</argument><br />
<argument><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='remoteName']"/><br />
</argument><br />
<argument<br />
value="remoteURI_value"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='remoteURI']"/><br />
</argument><br />
<argument><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='restrictToCheckoutBranch']"/><br />
</argument><br />
<argument<br />
value="master"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='checkoutBranch']"/><br />
</argument><br />
</setupTask><br />
<logicalProjectContainer<br />
xsi:type="setup:ProjectCatalog"<br />
href="index:/org.eclipse.setup#//@projectCatalogs[name='org.eclipse']"/><br />
<description>SampleProject provides cool stuff.</description><br />
</setup:Project><br />
<br />
Note that here we have several Arguments without a value. Those could be deleted or a value (presumably different from the default value of the Parameter) could be specified.<br />
<br />
=== Macro Expansion Processing ===<br />
<br />
A Macro Expansion task is expanded to a Compound Setup Task as illustrated by the Preview item. Each Argument is bound to its corresponding Parameter via a local variable of the form '*<macro-extension-task-id>.<parameter-name>'. Every variable reference to the Parameter name is transformed to use this Variable's more-qualified name instead. Every setup task with an ID is transformed to specify instead a qualified ID of the form '<macro-expansion-task-id>.<original-id>' and every variable reference that's prefixed by '<original-id>.' will be transformed to use the more-qualified prefix instead. In addition, any Variable contained by the Macro with a name that start with '*' will also be changed to use the name '*<macro-extension-task-id>.<original-name>' and all references to '<original-name>' will be transformed to use that qualified name instead. This qualification process ensures that unique Variable names are provided by the Macro Expansion because in the end, there's no such thing as a local Variable.<br />
<br />
Of course Macro's themselves can use Macro Expansion tasks, so the process of expansion is recursive. That being said, it's of course invalid for this to lead to a cycle. Cycles are detected by the validator and the expansion process prevents further expansion when a cycle is encountered.<br />
<br />
Note that from the context menu of a Macro Expansion task it's possible to invoke "Inline" to replace a Macro Expand task with its fully expanded equivalent.<br />
<br />
== Automation and Specialization with Configurations ==<br />
<br />
As of Oomph 1.6, released with Neon.2, there is support for Configurations. A Configuration is not a Scope (is not a container for setup tasks) but rather a container for an Installation and a Workspace; each is optional, but a Configuration with neither is in effect useless. The Installation and Workspace of a Configuration are effectively used as a template to initialize the Installation and Workspace created by the Eclipse Installer, i.e., the setup resources that you can open with Navigate &rarr; Open Setup &rarr; Installation and Navigate &rarr; Open Setup &rarr; Workspace in your IDE. So you can specialize the installation with additional installation-specific tasks, e.g., a p2 task to install additional features, and you can specialize the workspace with workspace-specific tasks, e.g., a variable task to specify the value of a variable so you won't be prompted for that value. <br />
<br />
Configurations are not only useful for specifying installation-specific and workspace-specific tasks but also for automating the selection process in the setup wizards, including the installer. The Configuration's Installation can reference a specific Product Version and the Configuration's Workspace can optionally reference several specific Project Streams. Both the simple mode and the advanced mode of the installer support dragging and dropping a Configuration to the title area. You can drag to the title area either a file (i.e., a file from the file system or from an Eclipse IDE), a URL (i.e., a link from a browser), or a copy of a Configuration's XMI serialization. This will '''apply''' the Configuration to the wizard with the effect that the Installation's Product Version is selected in the wizard and the wizard advances to the next page. Similarly, the Workspace's Project Streams are selected in the wizard and the wizard advances to the next page. If you apply a Configuration with a Workspace to the simple mode of the installer, you will be prompted to switch to advanced mode because only the advanced mode supports Project selection. So in simple mode, applying a Configuration advances to the final page, and in advanced mode, applying a Configuration with an Installation and a Workspace advances to the Variables page.<br />
<br />
As an alternative to drag and drop support, rather than dragging a file, link, or XMI serialization, you can copy it to the clipboard and apply the clipboard contents to the wizard. In simple mode this is done via the Apply Configuration menu item. In advanced mode this is done via the Apply Configuration toolbar button on the Product or Project page; the menu item or toolbar item is visible only if the clipboard contains applicable content.<br />
<br />
The installer application supports command line arguments so you could also specify a Configuration's file path or URL link on the command line to apply it automatically.<br />
<br />
=== Creating a Configuration ===<br />
<br />
The simplest way to create a new Configuration is from the context menu of the folder where want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Configuration Model in the wizard. You can then edit the new Configuration with the Setup Editor. You can delete the Installation or Workspace if you don't need that aspect. You can use the Properties view to set the Installation's Product Version or the Workspace's Project Streams. And of course you can create any other setup tasks in either Scope.<br />
<br />
=== Configuration Handling ===<br />
<br />
The specific form of the serialized URLs that are used to reference a Product Version or a Project Stream are very important to correct behavior. Relative URLs in the serialization can only work relative to the location of the Configuration's resource, so will only work when you drag and drop a file or link because a dragging and dropping textual copy of the serialization provides no information about how to resolve relative references. This is not to say there is anything wrong with relative references, just be aware that they imply that the user must apply the overall file or link, not just the textual serialization. <br />
<br />
Another very useful aspect of Configurations is that the wizards handle of the references intelligently. I.e., if a Installation references a Product Version that's not in any Product Catalog in the Index, the Product will automatically be added to the user-extensible Product Catalog. If the Installation references a Product Version via its containing Product Catalog and that Product Catalog is not in the Index, and the redirectable Product Catalog is not already redirected, it will be redirected to the referenced Product Catalog and an appropriate Eclipse Ini redirection tasks will be synthesized so that the installation produced by the installer will be able to resolve the Product Version reference in its Installation via the correct containing Product Catalog. Analogous processing is done for the Project Stream references with the additional processing of Project's a logical Project container which determines which Project Catalog's extensible Project container is used. In other words, Configurations can also be used to automate the addition of Products and Projects to the user extensible catalogs.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Getting Early Feedback ===<br />
Why didn't the model editor tell me earlier that I've made a silly mistake?<br />
Please enable Live Validation in the editor menu to get early feedback.<br />
<br />
=== Copying Tasks and Other Elements ===<br />
The Setup Editor supports the export and import of any model elements by using copy to or paste from the clipboard. The clipboard will/must contain a valid XML document. With this method, for example, you can easily copy task snippets from your model directly into a forum post when you ask for help (or into a Skype window when you chat with your collegues). Or you can easily paste such XML snippets from forum replies directly into your Setup Editor.<br />
<br />
You have access to many example setups from within your IDE! Use Navigate->Open Setup->Parent Models->Open Catalog Index to investigate everything within the index. The context menu provides a way to open elements in a text editor. This is particularly handy for finding out where a particular setup is hosted (hrefs are resolved in the Setup editor) - one use case is checking and repairing links to project setups added to your user projects.<br />
<br />
=== Hosting your own index / catalogs ===<br />
If you want to host your own product or project catalog, you must provide a URI mapping to the installer to locate the root setup file (the "index"). Open the eclipse.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, or use the wizard to create it. 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/. You can redirect to your own index with this redirection system property:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->http://<hostname>/<path>/</nowiki><br />
<br />
The source URI may be abbreviated to <nowiki>index:/</nowiki> and the target URI may also be a file URI, e.g. on a shared file server.<br />
<br />
In general it will be highly desirable to archive your setup, but documentation for that is TBD. The installer and other setup wizards support dragging and dropping an index or archived index onto the title area of the dialog. Documentation for that is also TBD.<br />
<br />
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=481580 Bug 481580] has introduced empty redirectable catalogs for products ('''redirectable.products.setup''') and projects ('''redirectable.projects.setup''') to the Oomph index. These allow providing your own catalogs without replacing the entire index or disabling the catalogs shipped with Oomph (by redirecting them). The following steps are necessary to make use of those setups.<br />
* Create your own project catalog setup file using the wizard. Project setups in the project catalog should typically be referenced using absolute URIs, otherwise redirection can become problematic. However, if the relative references are downward pointing to some uniquely named folder different from any of the file/folder names in the Eclipse.org index, i.e., no '''..''' traversal to the parent folder is involved and some folder name '''<my-projects-folder>''', then they will be resolved to absolute URIs of the form '''index:/<my-projects-folder>/<path>''' which can be handled as described below.<br />
* Add a redirection system property similar to that described above to the eclipse.ini file, e.g., '''-Doomph.redirection.myProjectCatalog=index:/redirectable.projects.setup->...'''.<br />
* If the projects in that catalog are referenced by relative downward references with a unique folder, also add a folder redirection system property, e.g.,'''-Doomph.redirection.myProjectCatalog=index:/<my-projects-folder>/->.../''', to redirect the locations of the referenced projects to the folder where they are physically hosted.<br />
* Your catalog setup file must contain an Eclipse Ini task creating the same redirection(s)! Otherwise your catalog (or the referenced projects) will not be visible in the Eclipse created by the installer and hence the projects selected from it cannot be provisioned.<br />
* The first time, you may have to enable your new catalog by selecting it in the folders icon of the drop-down in the upper right hand corner of the wizard's Projects page, otherwise it will be invisible.<br />
<br />
To debug the processing of -Doomph.redirection.* if needed, set a breakpoint in org.eclipse.oomph.setup.internal.core.util.SetupCoreUtil.configureResourceSet(ResourceSet) within if (((String)key).startsWith(SetupProperties.PROP_REDIRECTION_BASE)).<br />
<br />
=== Shipping your own index ===<br />
If you want to include your own product or project catalog, you may ship the root setup file (the "index") relative to the installer directory. Then you can redirect the index as explained in [[#Hosting your own index / catalogs| Hosting your own index / catalogs]]. For example, you can place all setup files in an eclipse-installer/setups/ folder and then redirect access to it with a relative target URI:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->setups/</nowiki><br />
<br />
Note that shipping the index rather than maintaining it in a central location (accessible to all parties interested) has the following disadvantage. As each user has her own copy of the index, updates in the setup files will not be distributed automatically.<br />
<br />
=== Generating PDE Target Definition files (*.target) and their use by Tycho ===<br />
<br />
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. <br />
<br />
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:<br />
<br />
<annotation<br />
source="http:/www.eclipse.org/oomph/targlets/TargetDefinitionGenerator"><br />
<detail<br />
key="location"><br />
<value>${git.clone.location}/targetdefinition/DesignStudio.target</value><br />
</detail><br />
<detail<br />
key="extraUnits"><br />
<value>org.eclipse.equinox.executable.feature.group</value><br />
</detail><br />
<detail<br />
key="includeAllPlatforms"><br />
<value>false</value><br />
</detail><br />
<detail<br />
key="includeSource"><br />
<value>true</value><br />
</detail><br />
<detail<br />
key="generateVersions"><br />
<value>true</value><br />
</detail><br />
</annotation><br />
<br />
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.<br />
<br />
''TODO Document what preferredRepositories, PomModulesUpdater & PomArtifactUpdater do...''<br />
<br />
=== Setting up WST Server Runtime and Instances in your Setup ===<br />
<br />
==== Server Runtime Preference ====<br />
<br />
1. Use an oomphed installation/workspace with preference recorder enabled.<br />
<br />
2. Open your project and user setup editors.<br />
<br />
3. Go to Preferences / Server / Runtime Environments and 'Add' it as usual.<br />
<br />
4. Drag the selected '/instance/org.eclipse.wst.server.core/runtimes' from user to project setup.<br />
<br />
Note: It's unclear if the above actually works. Please see thread https://www.eclipse.org/forums/index.php/t/1086488/ in forum for details.<br />
For some servers there are extension tasks to handle configuration, see below.<br />
<br />
==== Server Instance in Servers View ====<br />
Requires server runtime to be setup first.<br />
<br />
1. Open Servers View and create New server instance and deploy webapps as usual<br />
<br />
2. Optionally open server instance editor and adapt configuration as usual.<br />
<br />
3. Close Eclipse.<br />
<br />
4. Start it again.<br />
<br />
5. Open '.plugins/org.eclipse.wst.server.core/servers.xml' from your workspace/.metadata using a UTF capable editor<br />
<br />
6. Add Resource Creation Task to your setup:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
content="PUT_CONTENT_FROM_SERVERS_XML_INTO_HERE_USING_A_UTF_CAPABLE_EDITOR_AND_OOMPH_DIALOG"<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.wst.server.core/servers.xml"<br />
encoding="UTF-8"><br />
<description>tomcat server integration</description><br />
</setup:ResourceCreationTask><br />
<br />
7. Use the resource task content dialog to put the servers xml content into the task.<br />
<br />
8. Copy "Servers" project from this workspace into a suitable location of your branch checkout and add/commit/push.<br />
<br />
9. Setup project import task that can pick the Servers project up from that committed location.<br />
<br />
That's it. If you want to share it among fellows, be sure to agree on canonical paths for your server installations.<br />
<br />
==== Extension tasks for specific servers ====<br />
<br />
For some servers there are oomph extension tasks that can be used to handle the configuration:<br />
<br />
https://github.com/gratex/oomph-task-server - Tomcat, WebLogic, and WebSphere<br />
<br />
=== Suppress prompt for default workspace already upon very first start ===<br />
<br />
Adjust the SHOW_WORKSPACE_SELECTION_DIALOG property to false via configuration settings org.eclipse.ui.ide.prefs ...<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP MANUAL"<br />
content="MAX_RECENT_WORKSPACES=5&amp;#xD;&amp;#xA;RECENT_WORKSPACES=${workspace.location|property}&amp;#xD;&amp;#xA;RECENT_WORKSPACES_PROTOCOL=3&amp;#xD;&amp;#xA;SHOW_WORKSPACE_SELECTION_DIALOG=false&amp;#xD;&amp;#xA;eclipse.preferences.version=1"<br />
targetURL="configuration:/.settings/org.eclipse.ui.ide.prefs"<br />
encoding="UTF-8"/><br />
<br />
=== Open default perspective already upon very first start ===<br />
Examples below using Perspective ID for Java perspective.<br />
<br />
Tell Eclipse which perspective to open initially, by adding option to eclipse ini:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:EclipseIniTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP"<br />
option="-perspective"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
Setting a perspective to be default, by adding preference task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:PreferenceTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
key="/instance/org.eclipse.ui/defaultPerspectiveId"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
=== How to switch the current stream ===<br />
<br />
If you would like to switch the current stream/s, you can re-use Oomph's initial "Eclipse Importer" wizard, available as "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace.<br />
<br />
Note that it is currently not yet possible to remove the "current" project stream. As a workaround, use menu Navigate > Open Setup > Open Workspace (or if visible click the 'blue guy' icon in the Oomph toolbar) to Open Workspace workspace.setup, expand the first node, click on the Workspace entry, open Properties view, and change the last property named "Streams" and remove the current stream.<br />
<br />
Bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=476434 enhancement may make this easier in the future.<br />
<br />
<br />
=== How to install Eclipse plugins using the P2 Director and Repository Explorer ===<br />
<br />
Oomph can install Eclipse plugins which you require. This also works for normal Java Projects set up models, not just for Eclipse plug in OSGi development, and is handy to install commonly used 3rd-party Eclipse plugins which are not all available from eclipse.org p2 sites (think e.g. http://eclemma.org). Here's how:<br />
<br />
1. add a P2 Director child task to your *.setup, if it doesn't already have one<br />
<br />
2. add a Repository child in your P2 Director task<br />
<br />
3. in the Properties of the Repository set the URL to a valid p2 repo (e.g. http://update.eclemma.org)<br />
<br />
4. right-click that Repository and choose Explore, to open the Repository Explorer view<br />
<br />
5. in the Repository Explorer view change to [X] Compatible and (*) Minor at the lower-right hand corner<br />
<br />
6. drag & drop the version from the Repository Explorer view into the P2 Director task of your *.setup editor, to create a Requirement child<br />
<br />
Drag & Drop should normally work, but appears to be broken at least on Neon Milestone 6 on Linux; in that case:<br />
<br />
6. manually create a new child Requirement inside the P2 Director task<br />
<br />
7. in the Repository Explorer view use the brown (C) icon to switch to Expert Mode to see IDs instead of names<br />
<br />
8. find the ID of the feature IU, it's the one with a PDE feature + folder kind of icon, often ending in (feature.)feature.group<br />
<br />
9. in the Properties of the Requirement, type the Name to the ID found above (e.g. com.mountainminds.eclemma.feature.feature.group)<br />
<br />
10. in the Properties of the Requirement, Type should have automatically switched to Feature<br />
<br />
PS: If you are looking for the URL of p2 repos to pre-install some of the the M2E connectors, see https://git.eclipse.org/c/m2e/m2e-discovery-catalog.git/tree/org.eclipse.m2e.discovery.oss/connectors.xml<br />
<br />
<br />
<br />
=== How to create M2E lifecycle-mapping-metadata.xml to avoid littering your pom.xml with org.eclipse.m2e:lifecycle-mapping ===<br />
<br />
Read https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html & https://wiki.eclipse.org/M2E_compatible_maven_plugins and apply as follows:<br />
<br />
<setupTask<br />
xsi:type="setup:PreferenceTask"<br />
key="/instance/org.eclipse.m2e.core/eclipse.m2.WorkspacelifecycleMappingsLocation"<br />
value="${workspace.location}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"/><br />
<br />
<setupTask<br />
xsi:type="setup:ResourceCreationTask"<br />
content="..."<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"<br />
encoding="UTF-8"><br />
<description>Initialize M2E's Maven Lifecycle Mappings, see https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html &amp; https://wiki.eclipse.org/M2E_compatible_maven_plugins</description><br />
</setupTask><br />
<br />
For "content" just open the popup using the [...] icon in the Properties and copy/paste the content from menu Window > Preferences > Maven > Lifecycle Mappings: Open workspace lifecycle mappings metadata. (This is easier than editing the content=".." in source view, because it will correctly do the XML escaping for you.)<br />
<br />
Now whenever M2E whines about stuff like "Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-dependency-plugin:2.10:unpack (execution: unpack-license, phase: generate-resources)" etc. just use the Quick Fix in the Problems view and choose the option to use workspace preferences (instead of letting the quick fix modify your pom.xml to add org.eclipse.m2e:lifecycle-mapping <lifecycleMappingMetadata>).<br />
<br />
<br />
=== How to automatically pre-enable Gerrit ===<br />
<br />
If you would like to save your end-users from having to [[EGit/User_Guide#Enabling_Gerrit_for_a_repository|manually enabling Gerrit for a repository in EGit]], then you can use the follow magic variable which Oomph will recognize and act upon:<br />
<br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="YOURORG.gerrit.uri.pattern"<br />
value="(https|ssh)://([^@/]+@)?(git.YOURORG.org:29418/.*|git.YOURORG.org/gerrit/.*)"/><br />
<br />
=== How to find a P2 repository at Eclipse using the Repository Explorer ===<br />
<br />
Most projects don't document the locations of all their p2 update sites very well. This makes it hard to find the URL you need in order to install something or in order to specify a URL for your target platform definition. Oomph indexes all the p2 update sites available at download.eclipse.org to make this job easier. You can make use of this as follows:<br />
<br />
# In the Quick Access control, type "Repository Explorer" to show Oomph's Repository Explorer view.<br />
# In that view's toolbar, locate the tool item with the hover "Search Eclipse repositories by provided capabilities", i.e., the one that looks like a little search flashlight, and click it.<br />
# This brings up the "Eclipse Repository Search" dialog. The index is very large so it takes a while to load it. But it's cached locally and updated on the server once per day.<br />
# At the root of the displayed tree are p2's namespaces and under each of these are the capabilities in that namespace. They're organized hierarchically by their qualified name. It's all quite technical and the tree is very large. So while you can explore it, you'll most likely want to use the filter to find something quickly.<br />
# Type the fully qualified name of a Java package or installable unit you wish to locate into the filter. Note that tree items for which there exist a concrete version in some repository are decorated as such. Keep in mind that many projects don't version their Java packages, so it's often better to look at the org.eclipse.equinox.p2.iu category. Here's what it looks like searching for "org.eclipse.emf.ecore.xcore":<br>[[File:SearchEclipseRepositoryDialog.png]]<br><br />
# You can select a capability in the tree so that the lower panel displays all the versions of the capability that are available. Under each of those are nested the update sites that contain them. Composite update sites show their children hierarchically.<br />
# Of course you can double click a repository to further explore its contents in the Repository Explorer itself.<br />
<br />
<br />
=== How to extract the constituent parts that comprise the Windows self-extracting installer executable ===<br />
<br />
The Eclipse Installer distribution for the Windows platform is effectively a self-extracting executable. It is extracted at runtime by the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINExtractor.java Bin Extractor]. The pre-built version of this library, i.e., org.eclipse.oomph.extractor.lib-*.jar, is available in all Oomph-containing installations, i.e., in the installer itself and in applications installed by the installer. This library can also be used standalone to decompose the composed executable into its constituent parts. That can be accomplished if you run it with the correct magical program arguments as follows:<br />
<br />
java -classpath <path-to-extract-lib>\org.eclipse.oomph.extractor.lib-*.jar<br />
org.eclipse.oomph.extractor.lib.BINExtractor <br />
<path-to-executable-to-extract>\eclipse-inst-win64.exe <br />
<target-path>\product.zip <br />
-export <br />
<target-path>\marker.txt <br />
<target-path>\extractor.exe <br />
<target-path>\org.eclipse.oomph.extractor.lib.jar <br />
<target-path>\product-descriptor<br />
<br />
The Java VM arguments need only specify the extractor library along with the main class in that library. The first program argument is the location of the executable you wish to decompose, the 64 bit installer in this case. The remaining arguments are all best directed into a common folder, denoted as <target-path> in the example above. The second argument is the extracted location of the zip file of the product/distribution. The third argument is the -export flag. The fourth argument is the extracted location of the text file containing the marker text that is used to delimit the constituent parts of the composed executable. The fifth argument is the extracted location of the small native executable itself. The sixth argument is the extracted location of the extractor library, the same one being used to extract the parts. The seventh and final argument is the extracted location of the product descriptor. Such a [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINDescriptor.java descriptor] looks like this:<br />
<br />
1<br />
1<br />
7<br />
0<br />
64<br />
0<br />
eclipse-inst.exe<br />
eclipse-inst.ini<br />
Eclipse Installer<br />
http://wiki.eclipse.org/Eclipse_Installer<br />
http://download.eclipse.org/oomph/jre/128x128.png<br />
<br />
Of course you can edit these parts and then you can recompose the executable using the following bash script executed within the common folder in which you have extracted the constituent parts:<br />
<br />
COPY /B extractor.exe + ^<br />
marker.txt + ^<br />
org.eclipse.oomph.extractor.lib.jar + ^<br />
marker.txt + ^<br />
product-descriptor + ^<br />
marker.txt + ^<br />
product.zip + ^<br />
marker.txt ^<br />
eclipse-inst-64.exe<br />
<br />
Note that the file names match the extracted target file names. From this is should be clear that the native executable is just a composition of parts. This structure is used at runtime as follows. The extractor.exe runs natively, reading its own executable file, using the marker text to find the parts. It checks the descriptor to determine if an appropriate version of Java is already installed, i.e., one that will be able to launch the product; the native extractor consults the registry to find all installed JREs and JVMs. If an appropriate Java is not found, it opens a browser page prompting the user to install an appropriate Java version with the required bitness and at the minimum required version. If there is already an appropriate version of Java, it launches a Java process to execute the BinExtract's main method. That process in turn unzips the product zip to a temp folder and launches the Java process for that for the product/distribution.<br />
<br />
== Oomph Configuration Options ==<br />
<br />
=== Configuration Options for Installer .ini File ===<br />
<br />
{| class="wikitable"<br />
| '''-Doomph.redirection.setups''' || Redirects the location of setup files (index, catalog and products). The default URI is ''http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/'' and my be abbreviated with '''index:/'''. The syntax of the redirection is '''index:/->[redirection URI]'''. Examples: '''-Doomph.redirection.setups=index:/->http://<hostname>/<path>/''' (external server redirection) or '''-Doomph.redirection.setups=index:/->setups/''' (path relative to installer executable). See also [[#Hosting_your_own_index_.2F_catalogs|Hosting your own index & catalogs]]<br />
|-<br />
| '''-Doomph.setup.product.catalog.filter''' || Only displays product catalogs matching the given prefix. The default is ''org\\.eclipse\\.products''. Displays all catalogs if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.filter''' || Only displays products matching the given prefix. The default is ''(?\!org\\.eclipse\\.products\\.org\\.eclipse\\.platform\\.ide).*''. Displays all products if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.version.filter''' || Only displays product versions matching the given prefix. The default is ''.*\\.neon''. Displays all product versions if value is empty.<br />
|-<br />
| '''-Doomph.p2.pool''' || Set to ''@none'' to disable bundle pools. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=507594] for details.<br />
|}<br />
<br />
== Troubleshooting ==<br />
=== The preference task does not setup any preferences ===<br />
<br />
First of all. Please note that the preferences are not set up as part of the installation. They are setup when the installed eclipse is first started.<br />
<br />
To do this the installed product needs to have the following feature installed:<br />
''org.eclipse.oomph.setup.feature.group''<br />
<br />
The feature is already included in the root of the Eclipse.org Product Catalog. If you are not using it you can include the same task by yourself:<br />
<br />
<setup.p2:P2Task<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup.p2="http://www.eclipse.org/oomph/setup/p2/1.0"><br />
<requirement<br />
name="org.eclipse.oomph.setup.feature.group"/><br />
<repository<br />
url="${oomph.update.url}"/><br />
</setup.p2:P2Task></div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Oomph_Authoring&diff=432498Eclipse Oomph Authoring2019-05-26T04:58:49Z<p>Stepper.esc-net.de: /* Creating a Macro */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
== Getting Started ==<br />
<br />
=== What is Oomph? ===<br />
<br />
Please read [[Eclipse Installer]].<br />
<br />
<br />
=== Installing Oomph ===<br />
<br />
# Download and install the Eclipse '''Installer''' as outlined in [[Eclipse Installer]].<br />
# Make sure that the Oomph setup '''SDK''' is installed in your IDE. Either:<br />
## That's already the case because your IDE is a Mars M5 or later Eclipse Package, or<br />
## Start the installer and install an IDE of your choice (select on the first installer page), or<br />
## Use p2 to install "Oomph Setup SDK" from [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest].<br />
<br />
== Creating a Setup Project Model ==<br />
<br />
=== Using the Setup Project Model Wizard ===<br />
<br />
# Create an empty project in your workspace or select a folder in an existing project. You'll create the new "Setup Project Model" in the selected folder.<br />
# Open the New... dialog and select the "Setup Project Model" wizard:<br>[[Image:new-wizard.png]]<br><br />
# Select one of the provided templates (e.g., Eclipse.org, Github.com, or Simple) and adjust the displayed values:<br>[[Image:new-wizard-2.png]]<br><br />
# Some values are automatically derived from your input to fields '''higher up'''.<br />
# Open the Preview>>> to understand the impact of changes to the current field.<br />
<br />
=== Using the Setup Editor ===<br />
<br />
# Open the resulting setup file with Oomph's Setup Editor:<br>[[Image:setup-edit.png]]<br><br />
# Configure the tasks in the Properties view. Note that there are "Expert" properties available.<br />
# Add setup tasks to your project and/or to your project streams and configure them, too.<br />
# The Outline view displays a ''preview'' of the executable model with resolved variables.<br />
<br />
=== Testing the Setup Model ===<br />
<br />
# To test/execute your new setup model:<br />
## Start the installer and, if necessary, switch to the Advanced Mode via the dialog menu.<br />
## Pick any product on page 1 and click the Next button to proceed to page 2.<br />
## Drag and drop your <tt>.setup</tt> file onto one of the top-level catalogs (<tt>Eclipse.org</tt> or <tt>Github.com</tt>) in the projects tree. Your project will appear as a subproject of the special <tt>&lt;User&gt;</tt> project.<br />
## Double-click your project to add it to the table at the 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.<br />
## Fill in the empty fields and press the Next button to proceed to the Confirmation page.<br />
## 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.<br><br />
# 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 [[#Using the Setup Editor|Using the Setup Editor]]. If the IDE comes up but the initial configuration fails continue with step 3.<br />
# In the new IDE (whether the initial configuration was successful or not) open your model file from the main menu, Navigate &rarr; Open Setup &rarr; [[Image:branch.png]]. Find the problems and fix them. Then start the setup process '''from within''' this IDE via the main menu, Help &rarr; [[Image:update.png]] Perform Setup Tasks&hellip;. 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.<br />
<br />
=== Contributing to a Project Catalog ===<br />
<br />
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 http://git.eclipse.org/c] and [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&bug_severity=enhancement&short_desc=Please%20include%20setup%20for%20project%20Xyz 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.<br />
<br />
The same can be done if your project is not an Eclipse project, but hosted on '''GitHub'''. Simply state this fact in the bug description and paste the "raw" content URL to the file instead.<br />
<br />
== Understanding the Setup Engine ==<br />
<br />
=== Understanding Setup Tasks and Scopes ===<br />
<br />
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:<br />
<br />
* The '''Installation''' scope is located in <tt>eclipse/configuration/org.eclipse.oomph.setup/installation.setup</tt> 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.<br />
<br />
* The '''Workspace''' scope is located in <tt>workspace/.metadata/.plugins/org.eclipse.oomph.setup/workspace.setup</tt> 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.<br />
<br />
* The '''User''' scope is located in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup</tt> and contains tasks that are common to '''all''' installations and workspaces (unless they're restricted to particular installations or workspaces).<br />
<br />
<br />
The following additional scope types exist, so they can be referenced by the entry scopes:<br />
<br />
* The '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.setup Catalog Index]''' is the root scope and contains nested Product Catalogs and Project Catalogs.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.products.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/OomphInstaller.setup Product]''' contains nested Product Version scopes and possibly some tasks that are common to all nested scopes.<br />
<br />
* A '''Product Version''' contains no nested scopes but tasks that are specific to that product version.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.projects.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/Oomph.setup Project]''' contains nested Stream and/or (Sub-) Project scopes and typically some tasks that are common to all nested scopes.<br />
<br />
* A '''Stream''' contains no nested scopes but tasks that are specific to that stream.<br />
<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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 [[#Declaring_and_Using_Variables|Declaring and Using Variables]] below.<br />
<br />
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). <br />
<br />
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.<br />
<br />
=== Declaring and Using Variables ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:<br />
<br />
${''variable-name''}<br />
<br />
To prevent a variable reference from being expanded (e.g. you actually want to have the value '${var}' and not the value of "var"), you need to escape the variable syntax with an extra double dollar character. So "$${var}" will result in "${var}".<br />
<br />
In addition to the variables that are declared by VariableTasks you can refer to all of the following:<br />
<br />
* Attribute values of setup tasks with a defined ID. The reference syntax is ${''taskID''.''attributeName''}.<br />
* System properties as returned by <tt>System.getProperties()</tt><br />
* [[#Environment Variables|Environment variables]] as returned by <tt>System.getenv()</tt><br />
* [[#Predefined Variables|Predefined variables]] as determined by the setup engine from the user input to the installer (see below)<br />
<br />
==== Predefined Variables ====<br />
<br />
The following variables are predefined by the setup engine:<br />
<br />
{| class="wikitable"<br />
| '''scope.installation.name''' || The value of the <em>name</em> attribute of the current installation scope. <br />
|-<br />
| '''scope.installation.label''' || The value of the <em>label</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.installation.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.workspace.name''' || The value of the <em>name</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.label''' || The value of the <em>label</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.description''' || The value of the <em>description</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.user.name''' || The value of the <em>name</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.label''' || The value of the <em>label</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.description''' || The value of the <em>description</em> attribute of the current user scope.<br />
|-<br />
| '''scope.product.catalog.name''' || The value of the <em>name</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.label''' || The value of the <em>label</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.description''' || The value of the <em>description</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.name''' || The value of the <em>name</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product scope and its parent scopes.<br />
|-<br />
| '''scope.product.label''' || The value of the <em>label</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.description''' || The value of the <em>description</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.version.name''' || The value of the <em>name</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product version scope and its parent scopes.<br />
|-<br />
| '''scope.product.version.label''' || The value of the <em>label</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.project.catalog.name''' || The value of the <em>name</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.label''' || The value of the <em>label</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.description''' || The value of the <em>description</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.name''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current project scope and its parent scopes.<br />
|-<br />
| '''scope.project.label''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.description''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.stream.name''' || The value of the <em>name</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current stream scope and its parent scopes.<br />
|-<br />
| '''scope.project.stream.label''' || The value of the <em>label</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.description''' || The value of the <em>description</em> attribute of the current stream scope.<br />
|}<br />
<br />
<br />
==== Variable Extensions ====<br />
<br />
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.:<br />
<br />
${installation.location/git/myproject} evaluates to C:\develop\installation1\git\myproject on Windows<br />
<br />
<br />
After the path extension part you can add filter calls with pipe symbols. Filter names are generally case-insensitive. Multiple filters can be chained. Example:<br />
<br />
${installation.location|uri}/git/myproject evaluates to file:/C:/develop/installation1/git/myproject<br />
<br />
<br />
==== Variable Filters ====<br />
<br />
The following filters are currently available:<br />
<br />
{| class="wikitable"<br />
| '''base64''' || <br />
|-<br />
| '''basePath''' || Removes the last segment from a file system path.<br />
|-<br />
| '''camel''' || Converts a qualified name to camel case notation.<br />
|-<br />
| '''canonical''' || Canonicalizes a file system path.<br />
|-<br />
| '''cap''' || Capitalizes the first word of a String value.<br />
|-<br />
| '''capAll''' || Capitalizes all words of a String value.<br />
|-<br />
| '''file''' || Converts a file: URI to an OS-specific file system path.<br />
|-<br />
| '''fileExtension''' || Extracts the file extension from a URI or a file system path.<br />
|-<br />
| '''gitRepository''' || Extracts the name of the repository from a Git URI (excluding a possible .git suffix).<br />
|-<br />
| '''lastSegment''' || Extracts the last segment from a file system path.<br />
|-<br />
| '''length''' || Converts a String to a String that contains the alpha-numerical representation of the length of the original String.<br />
|-<br />
| '''lower''' || Converts all characters of a String value to lower-case.<br />
|-<br />
| '''path''' || Extracts the path segments from a URI.<br />
|-<br />
| '''pathEncode''' || Converts a file system path to a String value that can be used as a file name.<br />
|-<br />
| '''preferenceNode''' || Escapes all forward slashes (/) of a String value, so that the result can be used as a value in preference nodes.<br />
|-<br />
| '''property''' || Escapes all double back slashes (\\) of a String value, so that the result can be used as a value in properties.<br />
|-<br />
| '''propertyValue''' || Interprets the String value as a preference property path and returns the value of that property.<br />
|-<br />
| '''qualifiedName''' || Converts a camel case String value name to a qualified name.<br />
|-<br />
| '''slashDecode''' || Decodes a slashEncoded String value.<br />
|-<br />
| '''slashEncode''' || Encodes all slashes and backslashes of a String value.<br />
|-<br />
| '''trim''' || Removes all whitespace from the beginning and the end of a String.<br />
|-<br />
| '''trimLeft''' || Removes all whitespace from the beginning of a String.<br />
|-<br />
| '''trimRight''' || Removes all whitespace from the end of a String.<br />
|-<br />
| '''trimTrailingSlashes''' || Removes all slashes and backslashes from the end of a String.<br />
|-<br />
| '''upper''' || Converts all characters of a String value to upper-case.<br />
|-<br />
| '''uri''' || Converts a file system path to a file: URI.<br />
|-<br />
| '''uriLastSegment''' || Extracts the last path segment from a hierarchical URI or the authority from an opaque URI.<br />
|-<br />
| '''urlDecode''' || Decodes a URL.<br />
|-<br />
| '''urlEncode''' || URL-encodes a String value.<br />
|-<br />
| '''username''' || Escapes all "at" symbols (@) of a String value, so that the result can be used in URI that contain a username.<br />
|}<br />
<br />
==== Variables from Outer Scopes====<br />
<br />
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:<br />
<br />
* '''jre.location-1.4''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.5''' --> The folder containing a 1.5 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.6''' --> The folder containing a 1.6 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.7''' --> The folder containing a 1.7 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.8''' --> The folder containing a 1.8 compatible JDK/JRE for architecture ${os.arch}<br />
* '''git.user.id''' --> The Eclipse user ID for Git/Gerrit commits<br />
* '''git.author.name''' --> The Eclipse author name for Git/Gerrit commits<br />
* '''git.author.email''' --> The Eclipse author email for Git/Gerrit commits<br />
* '''bugzilla.id''' --> The Eclipse user ID for Bugzilla/Hudson<br />
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson<br />
<br />
<br />
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.<br />
<br />
==== Environment Variables ====<br />
<br />
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.<br />
<br />
=== Conditional Tasks ===<br />
<br />
All setup tasks support filters. Oomph reuses [https://wiki.eclipse.org/Equinox_P2_Resolution#Enablement_filter p2's implementation] of LDAP filters. I.e., it supports a string a representation of LDAP Search Filters, RFC 1960, UMich, 1996,<br />
http://www.ietf.org/rfc/rfc1960.txt<br />
<br />
The filter property of a setup task is an advanced property. To display this property, ensure that the "Show Advanced Properties" is enabled in the Properties view tool bar. The properties of a filter expression can generally refer to any system property or any environment variable. For example, the following filter expression on a task will ensure that it is included only when performing a task on a Linux operating system.<br />
<br />
(osgi.os=linux)<br />
<br />
The latest version of Oomph allows filter properties to refer to the values of variables as defined in the setup itself. For example, this idiom can be used to express if-then-else.<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xmi:XMI xmi:version="2.0"<br />
xmlns:xmi="<nowiki>http://www.omg.org/XMI</nowiki>"<br />
xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"<br />
xmlns:setup="<nowiki>http://www.eclipse.org/oomph/setup/1.0</nowiki>"><br />
<setup:VariableTask<br />
type="BOOLEAN"<br />
name="example.filter"<br />
label="Example Filter"><br />
<description>An example of a variable used to conditionally filter tasks</description><br />
</setup:VariableTask><br />
<setup:CompoundTask<br />
filter="(example.filter=true)"<br />
name="Filter True"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.a"<br />
label="Property A"><br />
<description>The value use for system.property.a</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.a"<br />
value="=${example.variable.a}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is true</description><br />
</setup:CompoundTask><br />
<setup:CompoundTask<br />
filter="(example.filter=false)"<br />
name="Filter False"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.b"<br />
label="Property B"><br />
<description>The value used for system.property.b</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.b"<br />
value="=${example.variable.b}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is false.</description><br />
</setup:CompoundTask><br />
</xmi:XMI><br />
<br />
On the Variables page of the setup wizards, any variable that is used in property of a filter will be displayed in bold. It is significant to note that the value of a so-called filter variable can conditionally affect the presence of other variables. In this example, either variable <code>example.variable.a</code> or <code>example.variable.b</code> (but not both) will be present on the Variables page, depending on the value of the <code>example.filter</code> variable, which is displayed as a checkbox because it is of type <code>BOOLEAN</code>.<br />
<br />
Note that Oomph setup editors support textual copy and paste, so you can copy the above XML and paste it into your setup editor to try it out.<br />
<br />
== Macros and Macro Expansion Tasks ==<br />
<br />
As of Oomph 1.13, released with Eclipse 2019-06, there is support for Macros. A Macro is a Scope, i.e., is a container for setup tasks, and can specify 0 or more Parameters. Each Parameter specifies a name, a description, and optionally a default value. The parameter names can be used as variable references in the setup tasks contained by the Macro.<br />
<br />
=== Creating a Macro ===<br />
<br />
The simplest way to create a new Macro is from the context menu of the folder where you want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Macro Model in the wizard. You can then edit the new Macro with the Setup Editor. You can create Parameters, if desired, and of course you can create any other setup tasks.<br />
<br />
Here is an example of how one could use a Macro for creating a Git Clone task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Macro<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:git="http://www.eclipse.org/oomph/setup/git/1.0"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
xsi:schemaLocation="http://www.eclipse.org/oomph/setup/git/1.0 http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/models/Git.ecore"<br />
name="git.clone"<br />
label="Git Clone"><br />
<setupTask<br />
xsi:type="git:GitCloneTask"<br />
id="git.clone"<br />
remoteName="${remoteName}"<br />
remoteURI="${remoteURI}"<br />
pushURI="${pushURI}"<br />
checkoutBranch="${checkoutBranch}"><br />
<annotation<br />
source="http://www.eclipse.org/oomph/setup/FeatureSubstitution"><br />
<detail<br />
key="restrictToCheckoutBranch"><br />
<value>${restrictToCheckoutBranch}</value><br />
</detail><br />
<detail<br />
key="recursive"><br />
<value>${recursive}</value><br />
</detail><br />
</annotation><br />
<description>${description}</description><br />
</setupTask><br />
<description>The GitClone macro provides a template for creating a clone task</description><br />
<parameter<br />
name="description"><br />
<description>The description of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="pushURI"><br />
<description>The push URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="recursive"<br />
defaultValue="false"><br />
<description>Whether submodules should be recursively cloned</description><br />
</parameter><br />
<parameter<br />
name="remoteName"<br />
defaultValue="origin"><br />
<description>The name of the remote</description><br />
</parameter><br />
<parameter<br />
name="remoteURI"><br />
<description>The remote URI of the Git clone task</description><br />
</parameter><br />
<parameter<br />
name="restrictToCheckoutBranch"<br />
defaultValue="false"><br />
<description>Whether the clone should be restricted to clone only the checkout branch</description><br />
</parameter><br />
<parameter<br />
name="checkoutBranch"><br />
<description>The name of the branch that the Git clone task to checks out</description><br />
</parameter><br />
</setup:Macro><br />
<br />
Special support is provided for defining so called local Variables in a Macro. Any Variable with a name that starts with '*' will be handled in a special way during [[#Macro Expansion Processing|Macro Expansion]].<br />
<br />
=== Using a Macro with a Macro Expansion Task ===<br />
<br />
To use a Macro you must create a Macro Expansion task. The easiest way to do this is to drag the resource containing the Macro and then drop it into the Setup Editor where you want to use it. Similarly, if you want to use a Macro defined in the internet, you can use Load Resource... from the Setup Editor's context menu to load the Macro into the editor's resource set (or drag the link and drop it into the editor). Note that Macros available in the resource set are always shown in the Outline view. Once the Macro is available in the editors resource set, or in the Outline, you can drag and drop the Macro anywhere that any other setup task can be created. This will create a Macro Expansion task that binds to the Macro.<br />
<br />
A Macro Expansion task must specify an ID, which of course must be unique within the containing resource. Via drag and drop, an ID is automatically assigned, but you'll likely want to change it. A Macro Expansion task can supply Arguments to bind the values of the Parameters of the Macro. For every Parameter without a default value there must be a corresponding Argument to bind its value. The validator will complain when that's not the case, so be sure to enable Live Validation via the context menu. When creating a Macro Expansion task using drag and drop, the required Arguments are automatically created. Of course you'll want to change the generated values; you can delete any Arguments for which the Parameter specifies the default value that you wish to just use. You can change the Argument's value by double clicking the Argument to ensure that it's visible in the Properties view, and can then edit the Value property of the Argument there. The description of the corresponding Parameter is displayed in the Properties view after the Parameter's name. This is why it's important to include a description for each Parameter so that the author using the Macro knows how the Argument's value will be used by that Macro.<br />
<br />
The setup editor displays the Macro referenced by a Macro Expansion task as a child item, in light brown, in the tree view, so you can fully explorer the Macro being used. In addition a Preview item is displayed, in light blue, to show how the Macro Expansion task will be expanded. And of course the Outline view allows you to preview of all the tasks that will be performed when you run the installer later.<br />
<br />
Here is an example of how the above Macro could be used by a Macro Expansion task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:Project<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
name="sample.project"<br />
label="SampleProject"><br />
<setupTask<br />
xsi:type="setup:MacroTask"<br />
id="my"><br />
<macro href="GitCloneMacro.setup#/"/><br />
<argument<br />
value="description_value"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='description']"/><br />
</argument><br />
<argument<br />
value="pushURI_value"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='pushURI']"/><br />
</argument><br />
<argument><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='recursive']"/><br />
</argument><br />
<argument><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='remoteName']"/><br />
</argument><br />
<argument<br />
value="remoteURI_value"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='remoteURI']"/><br />
</argument><br />
<argument><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='restrictToCheckoutBranch']"/><br />
</argument><br />
<argument<br />
value="master"><br />
<parameter<br />
href="GitCloneMacro.setup#//@parameters[name='checkoutBranch']"/><br />
</argument><br />
</setupTask><br />
<logicalProjectContainer<br />
xsi:type="setup:ProjectCatalog"<br />
href="index:/org.eclipse.setup#//@projectCatalogs[name='org.eclipse']"/><br />
<description>SampleProject provides cool stuff.</description><br />
</setup:Project><br />
<br />
Note that here we have several Arguments without a value. Those could be deleted or a value (presumably different from the default value of the Parameter) could be specified.<br />
<br />
=== Macro Expansion Processing ===<br />
<br />
A Macro Expansion task is expanded to a Compound Setup Task as illustrated by the Preview item. Each Argument is bound to its corresponding Parameter via a local variable of the form '*<macro-extension-task-id>.<parameter-name>'. Every variable reference to the Parameter name is transformed to use this Variable's more-qualified name instead. Every setup task with an ID is transformed to specify instead a qualified ID of the form '<macro-expansion-task-id>.<original-id>' and every variable reference that's prefixed by '<original-id>.' will be transformed to use the more-qualified prefix instead. In addition, any Variable contained by the Macro with a name that start with '*' will also be changed to use the name '*<macro-extension-task-id>.<original-name>' and all references to '<original-name>' will be transformed to use that qualified name instead. This qualification process ensures that unique Variable names are provided by the Macro Expansion because in the end, there's no such thing as a local Variable.<br />
<br />
Of course Macro's themselves can use Macro Expansion tasks, so the process of expansion is recursive. That being said, it's of course invalid for this to lead to a cycle. Cycles are detected by the validator and the expansion process prevents further expansion when a cycle is encountered.<br />
<br />
Note that from the context menu of a Macro Expansion task it's possible to invoke "Inline" to replace a Macro Expand task with its fully expanded equivalent.<br />
<br />
== Automation and Specialization with Configurations ==<br />
<br />
As of Oomph 1.6, released with Neon.2, there is support for Configurations. A Configuration is not a Scope (is not a container for setup tasks) but rather a container for an Installation and a Workspace; each is optional, but a Configuration with neither is in effect useless. The Installation and Workspace of a Configuration are effectively used as a template to initialize the Installation and Workspace created by the Eclipse Installer, i.e., the setup resources that you can open with Navigate &rarr; Open Setup &rarr; Installation and Navigate &rarr; Open Setup &rarr; Workspace in your IDE. So you can specialize the installation with additional installation-specific tasks, e.g., a p2 task to install additional features, and you can specialize the workspace with workspace-specific tasks, e.g., a variable task to specify the value of a variable so you won't be prompted for that value. <br />
<br />
Configurations are not only useful for specifying installation-specific and workspace-specific tasks but also for automating the selection process in the setup wizards, including the installer. The Configuration's Installation can reference a specific Product Version and the Configuration's Workspace can optionally reference several specific Project Streams. Both the simple mode and the advanced mode of the installer support dragging and dropping a Configuration to the title area. You can drag to the title area either a file (i.e., a file from the file system or from an Eclipse IDE), a URL (i.e., a link from a browser), or a copy of a Configuration's XMI serialization. This will '''apply''' the Configuration to the wizard with the effect that the Installation's Product Version is selected in the wizard and the wizard advances to the next page. Similarly, the Workspace's Project Streams are selected in the wizard and the wizard advances to the next page. If you apply a Configuration with a Workspace to the simple mode of the installer, you will be prompted to switch to advanced mode because only the advanced mode supports Project selection. So in simple mode, applying a Configuration advances to the final page, and in advanced mode, applying a Configuration with an Installation and a Workspace advances to the Variables page.<br />
<br />
As an alternative to drag and drop support, rather than dragging a file, link, or XMI serialization, you can copy it to the clipboard and apply the clipboard contents to the wizard. In simple mode this is done via the Apply Configuration menu item. In advanced mode this is done via the Apply Configuration toolbar button on the Product or Project page; the menu item or toolbar item is visible only if the clipboard contains applicable content.<br />
<br />
The installer application supports command line arguments so you could also specify a Configuration's file path or URL link on the command line to apply it automatically.<br />
<br />
=== Creating a Configuration ===<br />
<br />
The simplest way to create a new Configuration is from the context menu of the folder where want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Configuration Model in the wizard. You can then edit the new Configuration with the Setup Editor. You can delete the Installation or Workspace if you don't need that aspect. You can use the Properties view to set the Installation's Product Version or the Workspace's Project Streams. And of course you can create any other setup tasks in either Scope.<br />
<br />
=== Configuration Handling ===<br />
<br />
The specific form of the serialized URLs that are used to reference a Product Version or a Project Stream are very important to correct behavior. Relative URLs in the serialization can only work relative to the location of the Configuration's resource, so will only work when you drag and drop a file or link because a dragging and dropping textual copy of the serialization provides no information about how to resolve relative references. This is not to say there is anything wrong with relative references, just be aware that they imply that the user must apply the overall file or link, not just the textual serialization. <br />
<br />
Another very useful aspect of Configurations is that the wizards handle of the references intelligently. I.e., if a Installation references a Product Version that's not in any Product Catalog in the Index, the Product will automatically be added to the user-extensible Product Catalog. If the Installation references a Product Version via its containing Product Catalog and that Product Catalog is not in the Index, and the redirectable Product Catalog is not already redirected, it will be redirected to the referenced Product Catalog and an appropriate Eclipse Ini redirection tasks will be synthesized so that the installation produced by the installer will be able to resolve the Product Version reference in its Installation via the correct containing Product Catalog. Analogous processing is done for the Project Stream references with the additional processing of Project's a logical Project container which determines which Project Catalog's extensible Project container is used. In other words, Configurations can also be used to automate the addition of Products and Projects to the user extensible catalogs.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Getting Early Feedback ===<br />
Why didn't the model editor tell me earlier that I've made a silly mistake?<br />
Please enable Live Validation in the editor menu to get early feedback.<br />
<br />
=== Copying Tasks and Other Elements ===<br />
The Setup Editor supports the export and import of any model elements by using copy to or paste from the clipboard. The clipboard will/must contain a valid XML document. With this method, for example, you can easily copy task snippets from your model directly into a forum post when you ask for help (or into a Skype window when you chat with your collegues). Or you can easily paste such XML snippets from forum replies directly into your Setup Editor.<br />
<br />
You have access to many example setups from within your IDE! Use Navigate->Open Setup->Parent Models->Open Catalog Index to investigate everything within the index. The context menu provides a way to open elements in a text editor. This is particularly handy for finding out where a particular setup is hosted (hrefs are resolved in the Setup editor) - one use case is checking and repairing links to project setups added to your user projects.<br />
<br />
=== Hosting your own index / catalogs ===<br />
If you want to host your own product or project catalog, you must provide a URI mapping to the installer to locate the root setup file (the "index"). Open the eclipse.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, or use the wizard to create it. 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/. You can redirect to your own index with this redirection system property:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->http://<hostname>/<path>/</nowiki><br />
<br />
The source URI may be abbreviated to <nowiki>index:/</nowiki> and the target URI may also be a file URI, e.g. on a shared file server.<br />
<br />
In general it will be highly desirable to archive your setup, but documentation for that is TBD. The installer and other setup wizards support dragging and dropping an index or archived index onto the title area of the dialog. Documentation for that is also TBD.<br />
<br />
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=481580 Bug 481580] has introduced empty redirectable catalogs for products ('''redirectable.products.setup''') and projects ('''redirectable.projects.setup''') to the Oomph index. These allow providing your own catalogs without replacing the entire index or disabling the catalogs shipped with Oomph (by redirecting them). The following steps are necessary to make use of those setups.<br />
* Create your own project catalog setup file using the wizard. Project setups in the project catalog should typically be referenced using absolute URIs, otherwise redirection can become problematic. However, if the relative references are downward pointing to some uniquely named folder different from any of the file/folder names in the Eclipse.org index, i.e., no '''..''' traversal to the parent folder is involved and some folder name '''<my-projects-folder>''', then they will be resolved to absolute URIs of the form '''index:/<my-projects-folder>/<path>''' which can be handled as described below.<br />
* Add a redirection system property similar to that described above to the eclipse.ini file, e.g., '''-Doomph.redirection.myProjectCatalog=index:/redirectable.projects.setup->...'''.<br />
* If the projects in that catalog are referenced by relative downward references with a unique folder, also add a folder redirection system property, e.g.,'''-Doomph.redirection.myProjectCatalog=index:/<my-projects-folder>/->.../''', to redirect the locations of the referenced projects to the folder where they are physically hosted.<br />
* Your catalog setup file must contain an Eclipse Ini task creating the same redirection(s)! Otherwise your catalog (or the referenced projects) will not be visible in the Eclipse created by the installer and hence the projects selected from it cannot be provisioned.<br />
* The first time, you may have to enable your new catalog by selecting it in the folders icon of the drop-down in the upper right hand corner of the wizard's Projects page, otherwise it will be invisible.<br />
<br />
To debug the processing of -Doomph.redirection.* if needed, set a breakpoint in org.eclipse.oomph.setup.internal.core.util.SetupCoreUtil.configureResourceSet(ResourceSet) within if (((String)key).startsWith(SetupProperties.PROP_REDIRECTION_BASE)).<br />
<br />
=== Shipping your own index ===<br />
If you want to include your own product or project catalog, you may ship the root setup file (the "index") relative to the installer directory. Then you can redirect the index as explained in [[#Hosting your own index / catalogs| Hosting your own index / catalogs]]. For example, you can place all setup files in an eclipse-installer/setups/ folder and then redirect access to it with a relative target URI:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->setups/</nowiki><br />
<br />
Note that shipping the index rather than maintaining it in a central location (accessible to all parties interested) has the following disadvantage. As each user has her own copy of the index, updates in the setup files will not be distributed automatically.<br />
<br />
=== Generating PDE Target Definition files (*.target) and their use by Tycho ===<br />
<br />
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. <br />
<br />
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:<br />
<br />
<annotation<br />
source="http:/www.eclipse.org/oomph/targlets/TargetDefinitionGenerator"><br />
<detail<br />
key="location"><br />
<value>${git.clone.location}/targetdefinition/DesignStudio.target</value><br />
</detail><br />
<detail<br />
key="extraUnits"><br />
<value>org.eclipse.equinox.executable.feature.group</value><br />
</detail><br />
<detail<br />
key="includeAllPlatforms"><br />
<value>false</value><br />
</detail><br />
<detail<br />
key="includeSource"><br />
<value>true</value><br />
</detail><br />
<detail<br />
key="generateVersions"><br />
<value>true</value><br />
</detail><br />
</annotation><br />
<br />
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.<br />
<br />
''TODO Document what preferredRepositories, PomModulesUpdater & PomArtifactUpdater do...''<br />
<br />
=== Setting up WST Server Runtime and Instances in your Setup ===<br />
<br />
==== Server Runtime Preference ====<br />
<br />
1. Use an oomphed installation/workspace with preference recorder enabled.<br />
<br />
2. Open your project and user setup editors.<br />
<br />
3. Go to Preferences / Server / Runtime Environments and 'Add' it as usual.<br />
<br />
4. Drag the selected '/instance/org.eclipse.wst.server.core/runtimes' from user to project setup.<br />
<br />
Note: It's unclear if the above actually works. Please see thread https://www.eclipse.org/forums/index.php/t/1086488/ in forum for details.<br />
For some servers there are extension tasks to handle configuration, see below.<br />
<br />
==== Server Instance in Servers View ====<br />
Requires server runtime to be setup first.<br />
<br />
1. Open Servers View and create New server instance and deploy webapps as usual<br />
<br />
2. Optionally open server instance editor and adapt configuration as usual.<br />
<br />
3. Close Eclipse.<br />
<br />
4. Start it again.<br />
<br />
5. Open '.plugins/org.eclipse.wst.server.core/servers.xml' from your workspace/.metadata using a UTF capable editor<br />
<br />
6. Add Resource Creation Task to your setup:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
content="PUT_CONTENT_FROM_SERVERS_XML_INTO_HERE_USING_A_UTF_CAPABLE_EDITOR_AND_OOMPH_DIALOG"<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.wst.server.core/servers.xml"<br />
encoding="UTF-8"><br />
<description>tomcat server integration</description><br />
</setup:ResourceCreationTask><br />
<br />
7. Use the resource task content dialog to put the servers xml content into the task.<br />
<br />
8. Copy "Servers" project from this workspace into a suitable location of your branch checkout and add/commit/push.<br />
<br />
9. Setup project import task that can pick the Servers project up from that committed location.<br />
<br />
That's it. If you want to share it among fellows, be sure to agree on canonical paths for your server installations.<br />
<br />
==== Extension tasks for specific servers ====<br />
<br />
For some servers there are oomph extension tasks that can be used to handle the configuration:<br />
<br />
https://github.com/gratex/oomph-task-server - Tomcat, WebLogic, and WebSphere<br />
<br />
=== Suppress prompt for default workspace already upon very first start ===<br />
<br />
Adjust the SHOW_WORKSPACE_SELECTION_DIALOG property to false via configuration settings org.eclipse.ui.ide.prefs ...<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP MANUAL"<br />
content="MAX_RECENT_WORKSPACES=5&amp;#xD;&amp;#xA;RECENT_WORKSPACES=${workspace.location|property}&amp;#xD;&amp;#xA;RECENT_WORKSPACES_PROTOCOL=3&amp;#xD;&amp;#xA;SHOW_WORKSPACE_SELECTION_DIALOG=false&amp;#xD;&amp;#xA;eclipse.preferences.version=1"<br />
targetURL="configuration:/.settings/org.eclipse.ui.ide.prefs"<br />
encoding="UTF-8"/><br />
<br />
=== Open default perspective already upon very first start ===<br />
Examples below using Perspective ID for Java perspective.<br />
<br />
Tell Eclipse which perspective to open initially, by adding option to eclipse ini:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:EclipseIniTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP"<br />
option="-perspective"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
Setting a perspective to be default, by adding preference task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:PreferenceTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
key="/instance/org.eclipse.ui/defaultPerspectiveId"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
=== How to switch the current stream ===<br />
<br />
If you would like to switch the current stream/s, you can re-use Oomph's initial "Eclipse Importer" wizard, available as "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace.<br />
<br />
Note that it is currently not yet possible to remove the "current" project stream. As a workaround, use menu Navigate > Open Setup > Open Workspace (or if visible click the 'blue guy' icon in the Oomph toolbar) to Open Workspace workspace.setup, expand the first node, click on the Workspace entry, open Properties view, and change the last property named "Streams" and remove the current stream.<br />
<br />
Bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=476434 enhancement may make this easier in the future.<br />
<br />
<br />
=== How to install Eclipse plugins using the P2 Director and Repository Explorer ===<br />
<br />
Oomph can install Eclipse plugins which you require. This also works for normal Java Projects set up models, not just for Eclipse plug in OSGi development, and is handy to install commonly used 3rd-party Eclipse plugins which are not all available from eclipse.org p2 sites (think e.g. http://eclemma.org). Here's how:<br />
<br />
1. add a P2 Director child task to your *.setup, if it doesn't already have one<br />
<br />
2. add a Repository child in your P2 Director task<br />
<br />
3. in the Properties of the Repository set the URL to a valid p2 repo (e.g. http://update.eclemma.org)<br />
<br />
4. right-click that Repository and choose Explore, to open the Repository Explorer view<br />
<br />
5. in the Repository Explorer view change to [X] Compatible and (*) Minor at the lower-right hand corner<br />
<br />
6. drag & drop the version from the Repository Explorer view into the P2 Director task of your *.setup editor, to create a Requirement child<br />
<br />
Drag & Drop should normally work, but appears to be broken at least on Neon Milestone 6 on Linux; in that case:<br />
<br />
6. manually create a new child Requirement inside the P2 Director task<br />
<br />
7. in the Repository Explorer view use the brown (C) icon to switch to Expert Mode to see IDs instead of names<br />
<br />
8. find the ID of the feature IU, it's the one with a PDE feature + folder kind of icon, often ending in (feature.)feature.group<br />
<br />
9. in the Properties of the Requirement, type the Name to the ID found above (e.g. com.mountainminds.eclemma.feature.feature.group)<br />
<br />
10. in the Properties of the Requirement, Type should have automatically switched to Feature<br />
<br />
PS: If you are looking for the URL of p2 repos to pre-install some of the the M2E connectors, see https://git.eclipse.org/c/m2e/m2e-discovery-catalog.git/tree/org.eclipse.m2e.discovery.oss/connectors.xml<br />
<br />
<br />
<br />
=== How to create M2E lifecycle-mapping-metadata.xml to avoid littering your pom.xml with org.eclipse.m2e:lifecycle-mapping ===<br />
<br />
Read https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html & https://wiki.eclipse.org/M2E_compatible_maven_plugins and apply as follows:<br />
<br />
<setupTask<br />
xsi:type="setup:PreferenceTask"<br />
key="/instance/org.eclipse.m2e.core/eclipse.m2.WorkspacelifecycleMappingsLocation"<br />
value="${workspace.location}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"/><br />
<br />
<setupTask<br />
xsi:type="setup:ResourceCreationTask"<br />
content="..."<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"<br />
encoding="UTF-8"><br />
<description>Initialize M2E's Maven Lifecycle Mappings, see https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html &amp; https://wiki.eclipse.org/M2E_compatible_maven_plugins</description><br />
</setupTask><br />
<br />
For "content" just open the popup using the [...] icon in the Properties and copy/paste the content from menu Window > Preferences > Maven > Lifecycle Mappings: Open workspace lifecycle mappings metadata. (This is easier than editing the content=".." in source view, because it will correctly do the XML escaping for you.)<br />
<br />
Now whenever M2E whines about stuff like "Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-dependency-plugin:2.10:unpack (execution: unpack-license, phase: generate-resources)" etc. just use the Quick Fix in the Problems view and choose the option to use workspace preferences (instead of letting the quick fix modify your pom.xml to add org.eclipse.m2e:lifecycle-mapping <lifecycleMappingMetadata>).<br />
<br />
<br />
=== How to automatically pre-enable Gerrit ===<br />
<br />
If you would like to save your end-users from having to [[EGit/User_Guide#Enabling_Gerrit_for_a_repository|manually enabling Gerrit for a repository in EGit]], then you can use the follow magic variable which Oomph will recognize and act upon:<br />
<br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="YOURORG.gerrit.uri.pattern"<br />
value="(https|ssh)://([^@/]+@)?(git.YOURORG.org:29418/.*|git.YOURORG.org/gerrit/.*)"/><br />
<br />
=== How to find a P2 repository at Eclipse using the Repository Explorer ===<br />
<br />
Most projects don't document the locations of all their p2 update sites very well. This makes it hard to find the URL you need in order to install something or in order to specify a URL for your target platform definition. Oomph indexes all the p2 update sites available at download.eclipse.org to make this job easier. You can make use of this as follows:<br />
<br />
# In the Quick Access control, type "Repository Explorer" to show Oomph's Repository Explorer view.<br />
# In that view's toolbar, locate the tool item with the hover "Search Eclipse repositories by provided capabilities", i.e., the one that looks like a little search flashlight, and click it.<br />
# This brings up the "Eclipse Repository Search" dialog. The index is very large so it takes a while to load it. But it's cached locally and updated on the server once per day.<br />
# At the root of the displayed tree are p2's namespaces and under each of these are the capabilities in that namespace. They're organized hierarchically by their qualified name. It's all quite technical and the tree is very large. So while you can explore it, you'll most likely want to use the filter to find something quickly.<br />
# Type the fully qualified name of a Java package or installable unit you wish to locate into the filter. Note that tree items for which there exist a concrete version in some repository are decorated as such. Keep in mind that many projects don't version their Java packages, so it's often better to look at the org.eclipse.equinox.p2.iu category. Here's what it looks like searching for "org.eclipse.emf.ecore.xcore":<br>[[File:SearchEclipseRepositoryDialog.png]]<br><br />
# You can select a capability in the tree so that the lower panel displays all the versions of the capability that are available. Under each of those are nested the update sites that contain them. Composite update sites show their children hierarchically.<br />
# Of course you can double click a repository to further explore its contents in the Repository Explorer itself.<br />
<br />
<br />
=== How to extract the constituent parts that comprise the Windows self-extracting installer executable ===<br />
<br />
The Eclipse Installer distribution for the Windows platform is effectively a self-extracting executable. It is extracted at runtime by the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINExtractor.java Bin Extractor]. The pre-built version of this library, i.e., org.eclipse.oomph.extractor.lib-*.jar, is available in all Oomph-containing installations, i.e., in the installer itself and in applications installed by the installer. This library can also be used standalone to decompose the composed executable into its constituent parts. That can be accomplished if you run it with the correct magical program arguments as follows:<br />
<br />
java -classpath <path-to-extract-lib>\org.eclipse.oomph.extractor.lib-*.jar<br />
org.eclipse.oomph.extractor.lib.BINExtractor <br />
<path-to-executable-to-extract>\eclipse-inst-win64.exe <br />
<target-path>\product.zip <br />
-export <br />
<target-path>\marker.txt <br />
<target-path>\extractor.exe <br />
<target-path>\org.eclipse.oomph.extractor.lib.jar <br />
<target-path>\product-descriptor<br />
<br />
The Java VM arguments need only specify the extractor library along with the main class in that library. The first program argument is the location of the executable you wish to decompose, the 64 bit installer in this case. The remaining arguments are all best directed into a common folder, denoted as <target-path> in the example above. The second argument is the extracted location of the zip file of the product/distribution. The third argument is the -export flag. The fourth argument is the extracted location of the text file containing the marker text that is used to delimit the constituent parts of the composed executable. The fifth argument is the extracted location of the small native executable itself. The sixth argument is the extracted location of the extractor library, the same one being used to extract the parts. The seventh and final argument is the extracted location of the product descriptor. Such a [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINDescriptor.java descriptor] looks like this:<br />
<br />
1<br />
1<br />
7<br />
0<br />
64<br />
0<br />
eclipse-inst.exe<br />
eclipse-inst.ini<br />
Eclipse Installer<br />
http://wiki.eclipse.org/Eclipse_Installer<br />
http://download.eclipse.org/oomph/jre/128x128.png<br />
<br />
Of course you can edit these parts and then you can recompose the executable using the following bash script executed within the common folder in which you have extracted the constituent parts:<br />
<br />
COPY /B extractor.exe + ^<br />
marker.txt + ^<br />
org.eclipse.oomph.extractor.lib.jar + ^<br />
marker.txt + ^<br />
product-descriptor + ^<br />
marker.txt + ^<br />
product.zip + ^<br />
marker.txt ^<br />
eclipse-inst-64.exe<br />
<br />
Note that the file names match the extracted target file names. From this is should be clear that the native executable is just a composition of parts. This structure is used at runtime as follows. The extractor.exe runs natively, reading its own executable file, using the marker text to find the parts. It checks the descriptor to determine if an appropriate version of Java is already installed, i.e., one that will be able to launch the product; the native extractor consults the registry to find all installed JREs and JVMs. If an appropriate Java is not found, it opens a browser page prompting the user to install an appropriate Java version with the required bitness and at the minimum required version. If there is already an appropriate version of Java, it launches a Java process to execute the BinExtract's main method. That process in turn unzips the product zip to a temp folder and launches the Java process for that for the product/distribution.<br />
<br />
== Oomph Configuration Options ==<br />
<br />
=== Configuration Options for Installer .ini File ===<br />
<br />
{| class="wikitable"<br />
| '''-Doomph.redirection.setups''' || Redirects the location of setup files (index, catalog and products). The default URI is ''http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/'' and my be abbreviated with '''index:/'''. The syntax of the redirection is '''index:/->[redirection URI]'''. Examples: '''-Doomph.redirection.setups=index:/->http://<hostname>/<path>/''' (external server redirection) or '''-Doomph.redirection.setups=index:/->setups/''' (path relative to installer executable). See also [[#Hosting_your_own_index_.2F_catalogs|Hosting your own index & catalogs]]<br />
|-<br />
| '''-Doomph.setup.product.catalog.filter''' || Only displays product catalogs matching the given prefix. The default is ''org\\.eclipse\\.products''. Displays all catalogs if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.filter''' || Only displays products matching the given prefix. The default is ''(?\!org\\.eclipse\\.products\\.org\\.eclipse\\.platform\\.ide).*''. Displays all products if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.version.filter''' || Only displays product versions matching the given prefix. The default is ''.*\\.neon''. Displays all product versions if value is empty.<br />
|-<br />
| '''-Doomph.p2.pool''' || Set to ''@none'' to disable bundle pools. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=507594] for details.<br />
|}<br />
<br />
== Troubleshooting ==<br />
=== The preference task does not setup any preferences ===<br />
<br />
First of all. Please note that the preferences are not set up as part of the installation. They are setup when the installed eclipse is first started.<br />
<br />
To do this the installed product needs to have the following feature installed:<br />
''org.eclipse.oomph.setup.feature.group''<br />
<br />
The feature is already included in the root of the Eclipse.org Product Catalog. If you are not using it you can include the same task by yourself:<br />
<br />
<setup.p2:P2Task<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup.p2="http://www.eclipse.org/oomph/setup/p2/1.0"><br />
<requirement<br />
name="org.eclipse.oomph.setup.feature.group"/><br />
<repository<br />
url="${oomph.update.url}"/><br />
</setup.p2:P2Task></div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Oomph_Targlets&diff=424980Oomph Targlets2018-04-30T09:08:38Z<p>Stepper.esc-net.de: /* Edit Targlet Container with Targlet Editor */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
Oomph's Targlet technology extends [https://www.eclipse.org/pde/ PDE's] base functionality for specifying a target platform definition by providing a more expressive, flexible, scalable, and reliable mechanism.<br />
The Targlets framework is fully integrated with PDE; <br />
it uses PDE's target location extension point, providing a Targlet Container implementation to augment PDE's built-in target location implementations.<br />
<br />
As you'll see in the tutorial, here are some of the significant advantages of Oomph's Targlet Container versus PDE's Software Site container:<br />
* Dependencies are expressed as Requirements versus as Installable Units. <br />
** A Targlet's Requirement can specify a version range, optionality, greediness, cardinality, filters, and so on. Any p2 namespace, such as "java.package", can be specified, as well.<br />
** A PDE Software Site container's Installable Unit must specify either no version (omni-version) or an exact version.<br />
* Dependencies of local projects in the file system, e.g., in a local Git clone, can be taken into account during resolution using a Source Locator.<br />
** A Targlet Container resolves the requirements from the combination of all local projects and all available software sites.<br />
** It can use wildcards to specify all available Requirements of the Source Locator.<br />
** It imports projects into the workspace as a side-effect of resolution.<br />
* The resolution process supports roll-back on failure.<br />
** A resolution failure or network failure with Targlets will leave the old successful resolution in place.<br />
** A resolution failure with PDE's Software Site container will destroy your target platform, leaving all your workspace projects with errors until the problem is resolved, e.g., until your network or the hosting servers of the software sites are restored.<br />
* Resolved artifacts use a shared bundle pool, which is highly significant when you have multiple workspace.<br />
** Targlet Containers will download and store each artifact once in the file system, sharing them across workspaces (and even sharing the artifacts used by your installations).<br />
** PDE resolves artifacts separately into a each workspace-specific bundle pool, resulting in many duplicates (and downloading artifacts already available in your installation).<br />
* Update sites can be grouped into named lists, so that a single target definition can be resolved against different sets of repositories by switching to different named Repository Lists. This is most useful in combination with a Targlet Task that can easily select the active Repository List.<br />
<br />
== Install Targlet Support ==<br />
<br />
Use ''Help &rarr; Install New Software...'' and enter one of the [[Oomph#Update_Sites|update sites]], e.g., [http://download.eclipse.org/oomph/updates/milestone http://download.eclipse.org/oomph/updates/milestone], into the "Work with:" combo.<br />
Enter "Oomph Targlets" in the filter, and select the Oomph Targlets feature.<br />
<br />
[[File:Oomph_Install_Targlets_Feature.png]]<br />
<br />
== Create an Empty Target Definition ==<br />
<br />
Use ''Window &rarr; Preferences... &rarr; Plug-in Development &rarr; Target Platform'' to "Add..." a new Target Platform.<br />
<br />
[[File:Oomph_PDE_Add_Target_Platform.png]]<br />
<br />
Choose "Nothing: Start with an empty target definition" and press "Next".<br />
<br />
[[File:Oomph_PDE_Create_Empty_Target_Definition.png]]<br />
<br />
Use the "Name:" text field to name it "Sample" and press "Add..." to add a target location.<br />
<br />
[[File:Oomph_PDE_Add_Target_Location.png]]<br />
<br />
== Add a Targlet Container ==<br />
<br />
In the "Add Content" dialog select "Targlet Container" and press "Next".<br />
<br />
[[Image:Oomph_Targlet_Add_Targlet_Container.png]]<br />
<br />
Use the "Targlet Container ID:" field to enter the name "Sample Targlet Container" and press "Finish".<br />
<br />
[[Image:Oomph_Targlet_Add_Targlet_Container_Specify_ID.png]]<br />
<br />
Select the new Targlet Container and press "Edit..." to edit it:<br />
<br />
[[Image:Oomph_Targlet_Edit_Targlet_Container.png]]<br />
<br />
This will save the target definition, dismiss the dialog, and open the Targlet Editor.<br />
<br />
== Edit Targlet Container with Targlet Editor ==<br />
<br />
The Targlet Editor works well in combination with the Properties view and Oomph's Repository Explorer.<br />
You can open the Properties view from the Targlet Editor's context menu or by double clicking any item in the editor.<br />
You can open the Repository Explorer by entering "Repository Explorer" in the "Quick Access" field to the left of the perspective toolbar in the upper right corner of the perspective.<br />
<br />
Double click the root item (only item, currently) in the Targlet Editor and use the context menu to invoke ''New Child &rarr; Targlet''.<br />
<br />
[[File:Oomph_Targlet_Editor_New_Child_Targlet.png]]<br />
<br />
The new Targlet must have a name.<br />
The editor decorates errors in the tree and in the Properties view.<br />
Use the Properties view to set the "Name" property to "Eclipse SDK".<br />
<br />
[[File:Oomph_Targlet_Editor_Set_Targlet_Name.png]]<br />
<br />
Use the context menu on the new Targlet named "Eclipse SDK" to invoke ''New Child &rarr; Repository List'' and then use the context menu again to invoke ''New Child &rarr; Repository''.<br />
A Repository must of course specify a URL for a p2 update site.<br />
Use the properties view to enter the URL "http://download.eclipse.org/eclipse/updates/I-builds".<br />
Open the Repository Explorer view and then drag the Repository item and drop it onto the Repository combo in the Repository Explorer.<br />
<br />
[[File:Oomph_Targlet_Editor_Drag_Repository_To_Repository_Explorer.png]]<br />
<br />
The Repository Explorer will load the p2 repository and display its contents, much like what you're familiar from using the ''Help &rarr; Install New Software...'' dialog.<br />
<br />
[[File:Oomph_Targlet_Editor_Use_Repository_Explorer.png]]<br />
<br />
For each item you select, you can see which Versions of that item are available in the p2 repository.<br />
You can alter how the Versions are displayed using the controls in the bottom right.<br />
Here "Compatible" is checked, and "Minor" is selected.<br />
You can drag any item, including the Version items, to the "Eclipse SDK" Targlet to create a Requirement.<br />
When dragging a Version item, the version range of the Requirement that's created in the Targlet will reflect the display settings you've chosen.<br />
Here is the result of dragging the "4.8.x" version item to the "Eclipse SDK" Target with the new Requirement selected to display its properties in the Properties view:<br />
<br />
[[File:Oomph_Targlet_Editor_New_Requirement_From_Repository_Explorer_Version_Item.png]]<br />
<br />
It is significant to note some of the differences between editing a Targlet Container with Oomph's Targlet Editor versus editing a *.target file PDE's Target editor.<br />
At this point, we have not downloaded any artifacts from the p2 repository, we've only explored the content metadata and we could author the complete definition based on just that information.<br />
Also, editing PDE's Software Site container is achieved by specifying so-called installable units, either with an exact version or with the so called omni-version,<br />
but Targlets use Requirements that can specify version ranges, and properties such as optional and greedy, exactly like what you're able to express in a plug-in' MANIFEST.MF.<br />
Requirements are a more expressive mechanism for expressing dependencies for the target platform.<br />
<br />
When you save the Targlet Editor's contents, the Targlet Container will resolve in the background.<br />
You can use ''Window &rarr; Preferences &rarr; Plug-in Development &rarr; Target Platform'' to make the "Sample" target platform the active target platform.<br />
<br />
== Using a Source Locator ==<br />
<br />
Suppose some of your project in the workspace still has dependencies that aren't satisfied.<br />
<br />
[[File:Oomph_Targlets_Unresolved_Dependency.png]]<br />
<br />
You can of course hunt for them in the Repository Explorer, assuming you know in which p2 repo to find them.<br />
If you don't know the p2 repository, but you expect it's in some repository hosted by Eclipse, you can use [[Eclipse_Oomph_Authoring#How_to_find_a_P2_repository_at_Eclipse_using_the_Repository_Explorer|Eclipse Repository Search]] to find the p2 repository.<br />
Once you know the repository, can you of course browse the contents and use drag and drop to create the necessary Requirements and to add the necessary Repository to a Repository List.<br />
<br />
But Oomph's Targlet framework supports another powerful mechanism, namely Source Locators.<br />
The basic concept is that the underlying p2 framework is able to publish p2 metadata from source projects.<br />
PDE's implementation reuses this to build a representation of the plug-ins and features in the workspace.<br />
Oomph's Targlet framework reuses the same technology to induce a logical p2 repository from projects in the file system.<br />
For example, you can use the Repository Explorer to browse all your workspace projects as a logical p2 repository.<br />
Select "platform:/resource/" in the Repository Explorer's URL combo and switch to Expert Mode using the view's toolbar button with that hover text:<br />
<br />
[[File:Oomph_Targlets_Use_Repository_Explorer_Workspace_Repository.png]]<br />
<br />
To exploit the use of a Source Locator feature, use the Targlet Editor to create another Targlet named "Workspace Dependencies",<br />
create a new Requirement in that new Targlet and use the Properties view to change the "Name" to "*";<br />
this is a so-called wildcard Requirement.<br />
Then create a Source Locator in that new Targlet and use the Properties view to set the "Root Folder" to "platform:/resource/";<br />
this too is effectively a wildcard that denotes the file system location of each project in the workspace.<br />
The result looks like this:<br />
<br />
[[File:Oomph_Targlet_Editor_With_Source_Locator.png]]<br />
<br />
Assuming you've made the "Sample" target definition the active definition from the previous steps in this tutorial,<br />
saving the Targlet Editor will resolve the target platform,<br />
taking into account the dependencies of all projects in your workspace.<br />
Because the Platform's I-builds include, the "org.junit" bundle,<br />
after the resolution, the workspace error is eliminated because the target platform will contain the required bundle.<br />
<br />
This is just a simple though useful example of using a Source Locator.<br />
It should be evident that authoring a target platform in this manner is significantly simpler because you need not replicate/repeat in the target platform definition, the dependencies already expressed in your projects.<br />
Another highly useful aspect not illustrated by this simple example is that you can use a Source Locator to point at a Git clone in your local file system.<br />
During resolution, not only will all the requirements of the projects in that Git clone be resolved,<br />
the projects themselves will be imported into the workspace!</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Oomph_Targlets&diff=424977Oomph Targlets2018-04-30T08:43:20Z<p>Stepper.esc-net.de: </p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
Oomph's Targlet technology extends [https://www.eclipse.org/pde/ PDE's] base functionality for specifying a target platform definition by providing a more expressive, flexible, scalable, and reliable mechanism.<br />
The Targlets framework is fully integrated with PDE; <br />
it uses PDE's target location extension point, providing a Targlet Container implementation to augment PDE's built-in target location implementations.<br />
<br />
As you'll see in the tutorial, here are some of the significant advantages of Oomph's Targlet Container versus PDE's Software Site container:<br />
* Dependencies are expressed as Requirements versus as Installable Units. <br />
** A Targlet's Requirement can specify a version range, optionality, greediness, cardinality, filters, and so on. Any p2 namespace, such as "java.package", can be specified, as well.<br />
** A PDE Software Site container's Installable Unit must specify either no version (omni-version) or an exact version.<br />
* Dependencies of local projects in the file system, e.g., in a local Git clone, can be taken into account during resolution using a Source Locator.<br />
** A Targlet Container resolves the requirements from the combination of all local projects and all available software sites.<br />
** It can use wildcards to specify all available Requirements of the Source Locator.<br />
** It imports projects into the workspace as a side-effect of resolution.<br />
* The resolution process supports roll-back on failure.<br />
** A resolution failure or network failure with Targlets will leave the old successful resolution in place.<br />
** A resolution failure with PDE's Software Site container will destroy your target platform, leaving all your workspace projects with errors until the problem is resolved, e.g., until your network or the hosting servers of the software sites are restored.<br />
* Resolved artifacts use a shared bundle pool, which is highly significant when you have multiple workspace.<br />
** Targlet Containers will download and store each artifact once in the file system, sharing them across workspaces (and even sharing the artifacts used by your installations).<br />
** PDE resolves artifacts separately into a each workspace-specific bundle pool, resulting in many duplicates (and downloading artifacts already available in your installation).<br />
* Update sites can be grouped into named lists, so that a single target definition can be resolved against different sets of repositories by switching to different named Repository Lists. This is most useful in combination with a Targlet Task that can easily select the active Repository List.<br />
<br />
== Install Targlet Support ==<br />
<br />
Use ''Help &rarr; Install New Software...'' and enter one of the [[Oomph#Update_Sites|update sites]], e.g., [http://download.eclipse.org/oomph/updates/milestone http://download.eclipse.org/oomph/updates/milestone], into the "Work with:" combo.<br />
Enter "Oomph Targlets" in the filter, and select the Oomph Targlets feature.<br />
<br />
[[File:Oomph_Install_Targlets_Feature.png]]<br />
<br />
== Create an Empty Target Definition ==<br />
<br />
Use ''Window &rarr; Preferences... &rarr; Plug-in Development &rarr; Target Platform'' to "Add..." a new Target Platform.<br />
<br />
[[File:Oomph_PDE_Add_Target_Platform.png]]<br />
<br />
Choose "Nothing: Start with an empty target definition" and press "Next".<br />
<br />
[[File:Oomph_PDE_Create_Empty_Target_Definition.png]]<br />
<br />
Use the "Name:" text field to name it "Sample" and press "Add..." to add a target location.<br />
<br />
[[File:Oomph_PDE_Add_Target_Location.png]]<br />
<br />
== Add a Targlet Container ==<br />
<br />
In the "Add Content" dialog select "Targlet Container" and press "Next".<br />
<br />
[[Image:Oomph_Targlet_Add_Targlet_Container.png]]<br />
<br />
Use the "Targlet Container ID:" field to enter the name "Sample Targlet Container" and press "Finish".<br />
<br />
[[Image:Oomph_Targlet_Add_Targlet_Container_Specify_ID.png]]<br />
<br />
Select the new Targlet Container and press "Edit..." to edit it:<br />
<br />
[[Image:Oomph_Targlet_Edit_Targlet_Container.png]]<br />
<br />
This will save the target definition, dismiss the dialog, and open the Targlet Editor.<br />
<br />
== Edit Targlet Container with Targlet Editor ==<br />
<br />
The Targlet Editor works well in combination with the Properties view and Oomph's Repository Explorer.<br />
You can open the Properties view from the Targlet Editor's context menu or by double clicking any item in the editor.<br />
You can open the Repository Explorer by entering "Repository Explorer" in the "Quick Access" field to the left of the perspective toolbar in the upper right corner of the perspective.<br />
<br />
Double click the root item (only item, currently) in the Targlet Editor and use the context menu to invoke ''New Child &rarr; Targlet''.<br />
<br />
[[File:Oomph_Targlet_Editor_New_Child_Targlet.png]]<br />
<br />
The new Targlet must have a name.<br />
The editor decorates errors in the tree and in the Properties view.<br />
Use the Properties view to set the "Name" property to "Eclipse SDK".<br />
<br />
[[File:Oomph_Targlet_Editor_Set_Targlet_Name.png]]<br />
<br />
Use the context menu on the new Targlet named "Eclipse SDK" to invoke ''New Child &rarr; Repository List'' and then use the context menu again to invoke ''New Child &rarr; Repository''.<br />
A Repository must of course specify a URL for a p2 update site.<br />
Use the properties view to enter the URL "http://download.eclipse.org/eclipse/updates/I-builds".<br />
Open the Repository Explorer view and then drag the Repository item and drop it onto the Repository combo in the Repository Explorer.<br />
<br />
[[File:Oomph_Targlet_Editor_Drag_Repository_To_Repository_Explorer.png]]<br />
<br />
The Repository Explorer will load the p2 repository and display its contents, much like what you're familiar from using the ''Help &rarr; Install New Software...'' dialog.<br />
<br />
[[File:Oomph_Targlet_Editor_Use_Repository_Explorer.png]]<br />
<br />
For each item you select, you can see which Versions of that item are available in the p2 repository.<br />
You can alter how the Versions are displayed using the controls in the bottom right.<br />
Here "Compatible" is checked, and "Minor" is selected.<br />
You can drag any item, including the Version items, to the "Eclipse SDK" Targlet to create a Requirement.<br />
When dragging a Version item, the version range of the Requirement that's created in the Targlet will reflect the display settings you've chosen.<br />
Here is the result of dragging the "4.8.x" version item to the "Eclipse SDK" Target with the new Requirement selected to display its properties in the Properties view:<br />
<br />
[[File:Oomph_Targlet_Editor_New_Requirement_From_Repository_Explorer_Version_Item.png]]<br />
<br />
It is significant to note some the difference between editing a Targlet Container with Oomph's Targlet Editor versus editing a *.target file PDE's Target editor.<br />
At this point, we have not downloaded any artifacts from the p2 repository, we've only explored the content metadata and we could author the complete definition based on just that information.<br />
Also, editing PDE's Software Site container is achieved by specifying so-call installable units, either with an exact version or with the so called omni-version,<br />
but Targlets use Requirements that can specify version ranges, and properties such as optional and greedy, exactly like what you're able to express in a plug-in' MANIFEST.MF.<br />
Requirements are a more expressive mechanism for expressing dependencies for the target platform.<br />
<br />
When you save the Targlet Editor's contents, the Targlet Container will resolve in the background.<br />
You can use ''Window &rarr; Preferences &rarr; Plug-in Development &rarr; Target Platform'' to make the "Sample" target platform the active target platform.<br />
<br />
== Using a Source Locator ==<br />
<br />
Suppose some of your project in the workspace still has dependencies that aren't satisfied.<br />
<br />
[[File:Oomph_Targlets_Unresolved_Dependency.png]]<br />
<br />
You can of course hunt for them in the Repository Explorer, assuming you know in which p2 repo to find them.<br />
If you don't know the p2 repository, but you expect it's in some repository hosted by Eclipse, you can use [[Eclipse_Oomph_Authoring#How_to_find_a_P2_repository_at_Eclipse_using_the_Repository_Explorer|Eclipse Repository Search]] to find the p2 repository.<br />
Once you know the repository, can you of course browse the contents and use drag and drop to create the necessary Requirements and to add the necessary Repository to a Repository List.<br />
<br />
But Oomph's Targlet framework supports another powerful mechanism, namely Source Locators.<br />
The basic concept is that the underlying p2 framework is able to publish p2 metadata from source projects.<br />
PDE's implementation reuses this to build a representation of the plug-ins and features in the workspace.<br />
Oomph's Targlet framework reuses the same technology to induce a logical p2 repository from projects in the file system.<br />
For example, you can use the Repository Explorer to browse all your workspace projects as a logical p2 repository.<br />
Select "platform:/resource/" in the Repository Explorer's URL combo and switch to Expert Mode using the view's toolbar button with that hover text:<br />
<br />
[[File:Oomph_Targlets_Use_Repository_Explorer_Workspace_Repository.png]]<br />
<br />
To exploit the use of a Source Locator feature, use the Targlet Editor to create another Targlet named "Workspace Dependencies",<br />
create a new Requirement in that new Targlet and use the Properties view to change the "Name" to "*";<br />
this is a so-called wildcard Requirement.<br />
Then create a Source Locator in that new Targlet and use the Properties view to set the "Root Folder" to "platform:/resource/";<br />
this too is effectively a wildcard that denotes the file system location of each project in the workspace.<br />
The result looks like this:<br />
<br />
[[File:Oomph_Targlet_Editor_With_Source_Locator.png]]<br />
<br />
Assuming you've made the "Sample" target definition the active definition from the previous steps in this tutorial,<br />
saving the Targlet Editor will resolve the target platform,<br />
taking into account the dependencies of all projects in your workspace.<br />
Because the Platform's I-builds include, the "org.junit" bundle,<br />
after the resolution, the workspace error is eliminated because the target platform will contain the required bundle.<br />
<br />
This is just a simple though useful example of using a Source Locator.<br />
It should be evident that authoring a target platform in this manner is significantly simpler because you need not replicate/repeat in the target platform definition, the dependencies already expressed in your projects.<br />
Another highly useful aspect not illustrated by this simple example is that you can use a Source Locator to point at a Git clone in your local file system.<br />
During resolution, not only will all the requirements of the projects in that Git clone be resolved,<br />
the projects themselves will be imported into the workspace!</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Installer&diff=424921Eclipse Installer2018-04-27T10:04:31Z<p>Stepper.esc-net.de: </p>
<hr />
<div>[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
The Eclipse Installer automates the installation and update of Eclipse development environments:<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-win64.exe Windows 64 Bit] (self-extracting exe)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-win32.exe Windows 32 Bit] (self-extracting exe)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-mac64.tar.gz Mac OS 64 Bit] (tar.gz)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-linux64.tar.gz Linux 64 Bit] (tar.gz)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-linux32.tar.gz Linux 32 Bit] (tar.gz)<br />
<br />
<br />
To download the latest nightly build of the installer, pick one of <br />
[http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-win64.exe Windows 64 Bit], <br />
[http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-win32.exe Windows 32 Bit], <br />
[http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-mac64.tar.gz Mac OS 64 Bit], <br />
[http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-linux64.tar.gz Linux 64 Bit], <br />
or [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-linux32.tar.gz Linux 32 Bit].<br />
<br />
You can also install the Oomph runtime into an existing IDE from the latest [http://download.eclipse.org/oomph/updates/latest update site] or [http://www.eclipse.org/downloads/download.php?file=/oomph/updates/latest/org.eclipse.oomph.site.zip site archive]. See [[#Update Sites|update sites]] for more...<br />
<br />
Our [http://download.eclipse.org/oomph/help help center] is still work in progress but you may already find answers to your questions there.<br />
<br />
The installer is provided by the [http://www.eclipse.org/oomph Oomph] project.<br />
<br />
<br />
[[Image:OomphSimpleInstaller2.png]]<br />
<br />
See the [[Eclipse_Oomph_Authoring|Authoring Guide]] for details about how to customize the installer to create installations and provision workspaces for your specialized needs.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424863Eclipse Platform SDK Provisioning2018-04-26T16:20:51Z<p>Stepper.esc-net.de: /* Update the Installation and Workspace */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update:<br />
<br />
[[File:Oomph_Installer_Simple_Update.png]]<br />
<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
[[File:Oomph_Installer_Advanced_Update.png]]<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the Variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the Product page and the Projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the Confirmation page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested element to review its properties. <br />
The most important task is the so-called P2 Director task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the Progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the P2 Director task's repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review these licenses again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically be launched upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Eclipse Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.<br />
<br />
== Update the Installation and Workspace ==<br />
<br />
Suppose you've performed these steps a few weeks ago and would like to update the installation and workspace to the latest and greatest state.<br />
Of course you can easily select all Git repositories in the Git Repositories view and do a Pull.<br />
But you can also easily update the installation and the workspace using the tool bar contributions provided by Oomph.<br />
The Perform Setup Tasks tool bar menu button is useful for this purpose:<br />
<br />
[[File:Oomph_Perform_Setup_Tasks_Menu_Button.png]]<br />
<br />
It launches the Eclipse Updater.<br />
<br />
[[File:Oomph_Eclipse_Updater.png|800px]]<br />
<br />
The P2 Director task will update the installation with the latest Eclipse Platform integration build.<br />
The Modular Target task will update the target platform with the latest dependencies;<br />
it will even import new projects if there are any.<br />
The API baseline changes rarely, i.e., only between releases, so you won't need to perform the tasks for updating the API baseline nearly as frequently.<br />
Note that you can selectively enable tasks.<br />
In the above I have only enabled the first and the last task.<br />
It's very convenient to enable a single task with a double-click; all other tasks will be unchecked and only the selected task will be checked.<br />
Hitting Finish will perform the enabled tasks.<br />
By default the dialog will minimize to the status bar, where it will be visible as an animated icon.<br />
It's a non-modal dialog, so you can make it visible by clicking the status icon.<br />
The status icon will eventually disappear if the tasks perform successfully; if not, you'll need to open the dialog to see what's going on.<br />
For example, when the installation is updated, you'll need to restart the IDE, which you can do by pressing the Finish button of the wizard.<br />
<br />
You may also wish to view the setup definitions provided for the various projects.<br />
The Open setup menu button is useful for this purpose:<br />
<br />
[[File:Oomph_Open_Setup_Menu_Button.png]]<br />
<br />
Please refer to the [[Eclipse_Oomph_Authoring#Understanding_the_Setup_Engine|authoring guide]] if you're interested in the details.<br />
Many of the project setups are located within the Git clones themselves, so you can contribute changes to them, and can test the impact in the running installation;<br />
the long term goal is for each project to maintain its own project setup, but we're not quite there.<br />
In any case, you might get some good ideas for how best to author an Oomph setup for your own projects!</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424843Eclipse Platform SDK Provisioning2018-04-25T14:28:42Z<p>Stepper.esc-net.de: /* Monitor the Progress */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the Variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the Product page and the Projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the Confirmation page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested element to review its properties. <br />
The most important task is the so-called P2 Director task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the Progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the P2 Director task's repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review these licenses again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically be launched upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424842Eclipse Platform SDK Provisioning2018-04-25T14:28:17Z<p>Stepper.esc-net.de: /* Confirm the Tasks */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the Variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the Product page and the Projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the Confirmation page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested element to review its properties. <br />
The most important task is the so-called P2 Director task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the Progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the p2 task' repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review these licenses again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically be launched upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424841Eclipse Platform SDK Provisioning2018-04-25T14:23:08Z<p>Stepper.esc-net.de: /* Review the Variables */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the Variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the Product page and the Projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the Confirmation page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested element to review its properties. <br />
The most important task is the so-called p2 task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the Progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the p2 task' repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review these licenses again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically be launched upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424840Eclipse Platform SDK Provisioning2018-04-25T14:22:41Z<p>Stepper.esc-net.de: /* Review the Variables */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the Variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the product page and the projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the Confirmation page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested element to review its properties. <br />
The most important task is the so-called p2 task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the Progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the p2 task' repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review these licenses again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically be launched upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424839Eclipse Platform SDK Provisioning2018-04-25T14:17:49Z<p>Stepper.esc-net.de: /* Monitor the Progress */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the product page and the projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the Confirmation page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested element to review its properties. <br />
The most important task is the so-called p2 task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the Progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the p2 task' repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review these licenses again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically be launched upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424838Eclipse Platform SDK Provisioning2018-04-25T14:16:35Z<p>Stepper.esc-net.de: /* Monitor the Progress */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the product page and the projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the Confirmation page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested element to review its properties. <br />
The most important task is the so-called p2 task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the Progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the p2 task' repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review these licenses again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically launches upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424837Eclipse Platform SDK Provisioning2018-04-25T14:15:43Z<p>Stepper.esc-net.de: /* Monitor the Progress */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the product page and the projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the Confirmation page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested element to review its properties. <br />
The most important task is the so-called p2 task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the Progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the p2 task' repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review this license again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically launches upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424836Eclipse Platform SDK Provisioning2018-04-25T14:14:21Z<p>Stepper.esc-net.de: /* Confirm the Tasks */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the product page and the projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the Confirmation page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested element to review its properties. <br />
The most important task is the so-called p2 task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the p2 task' repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review this license again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically launches upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424835Eclipse Platform SDK Provisioning2018-04-25T14:13:26Z<p>Stepper.esc-net.de: /* Confirm the Tasks */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the product page and the projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the Confirmation page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested elements to review its properties. <br />
The most important task is the so-called p2 task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the p2 task' repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review this license again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically launches upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424834Eclipse Platform SDK Provisioning2018-04-25T14:13:09Z<p>Stepper.esc-net.de: /* Confirm the Tasks */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the product page and the projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the confirmation page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested elements to review its properties. <br />
The most important task is the so-called p2 task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the p2 task' repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review this license again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically launches upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424833Eclipse Platform SDK Provisioning2018-04-25T14:06:48Z<p>Stepper.esc-net.de: /* Apply the Platform SDK Configuration */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pool section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the product page and the projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the configuration page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested elements to review its properties. <br />
The most important task is the so-called p2 task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the p2 task' repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review this license again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically launches upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Platform_SDK_Provisioning&diff=424832Eclipse Platform SDK Provisioning2018-04-25T13:58:52Z<p>Stepper.esc-net.de: /* Launch the Eclipse Installer */</p>
<hr />
<div>[[File:Oomph_Project_Logo.png]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span><br />
<br />
This page provides step-by-step instructions for how to provision a dedicated development environment for the complete set of projects that comprise the [[Eclipse_Project|Eclipse Platform's SDK]], i.e., the projects used to build the [http://download.eclipse.org/eclipse/downloads/ downloads] of the Eclipse Platform Project.<br />
The provisioning process is entirely automated, except for course from user input to choose configurable options, e.g., where in the file system to place the installation, but even for these, defaults are provided.<br />
<br />
== Launch the Eclipse Installer ==<br />
<br />
If you don't already have the [[Eclipse_Installer|Eclipse Installer]] on your system, [[Eclipse_Installer|download]] the installer that is appropriate for your operating system's architecture. <br />
For Windows, the installer is distributed as an executable. It will start without a JRE or JDK installed, but if you don't have at Java 8 installed, it will guide you to install that. <br />
For Mac and Linux, you must unpack the installer before you can run the application. <br />
In all cases, you must install a JRE or JDK (currently at least Java 8) before you can successfully use the installer, <br />
and of course the installation you will create needs it too. <br />
Please look at [[Eclipse/Installation#Install_a_JVM|these instructions]] if you need further details. <br />
And note that on Mac you must install a JDK, not merely a JRE.<br />
<br />
Now launch the installer application.<br />
Unless you just downloaded a new installer, the one you have probably needs to be updated. <br />
In simple mode, you'll see a "!" indicator on the menu button in the upper right corner; the menu will have an update item to start an update.<br />
In advanced mode, the right-most toolbar button at the bottom can be pressed to start an update.<br />
<br />
== Apply the Platform SDK Configuration ==<br />
<br />
We will use a so-called Oomph [[Eclipse_Oomph_Authoring#Automation_and_Specialization_with_Configurations|configuration]] to automate the selection of the product and projects to provision. <br />
Drag and drop the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link on the title area of the installer. <br />
If the installer is in simple mode, it will ask to Switch to Advanced Mode; confirm that prompt. <br />
When the configuration is successfully applied, the installer will be in advanced mode and will automatically turn to the Variables page. <br />
As an alternative to drag-and-drop, you can copy the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/interim/PlatformSDKConfiguration.setup Platform SDK Configuration] link, <br />
and apply it to the installer. <br />
In advanced mode, this is done via the menu action; this action will appear in the menu only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Simple_Apply_Configuration.png|800px]]<br />
<br />
In simple mode, this is done via the left-most button in the toolbar; this button will appear in the toolbar only if the clipboard contains a valid configuration:<br />
<br />
[[File:Oomph_Installer_Advanced_Apply_Configuration.png|800px]]<br />
<br />
Note that the installer will by default use a shared bundle pool for creating installations. <br />
This defaults to the .p2 folder in the home folder.<br />
If the file system for the home folder is relatively small, you can change the default location using the Bundle Pools menu option in simple mode, <br />
or the right-most toolbar button in the Bundle Pools section in advanced mode, as seen in each of the corresponding screen captures above.<br />
<br />
Note also that you can choose which Java VM is used by the installation you are about to create.<br />
The installer will generally detected the JREs and JDKs installed on your system, choosing an appropriate default, and remembering it for the next time you use the installer.<br />
But failing that, the installer will stay on the product page and you must use the tool button to locate a Java VM that is suitable for the installation being created.<br />
<br />
== Review the Variables ==<br />
<br />
After applying the configuration, you'll be on the variable page of the install wizard's advanced mode:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Variables.png|800px]]<br />
<br />
Of course you can use the Back button to review the selections that were made on the previous two pages, i.e., on the product page and the projects page.<br />
If this is the first time you've used the installer, there will be large number of variables, but all have suitable defaults.<br />
Of particular note, you may wish to change the "Root install folder" to a different location, it defaults to your home folder, keeping in mind that this location will use a significant amount of disk space.<br />
The three so-called location rule variables, for this tutorial's example scenario, will create <br />
the installation in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\eclipse</tt> (<tt>Eclipse.app</tt> on Mac), <br />
the workspace in <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\ws</tt>, <br />
and all the Git clones under <tt>D:\sandbox\USER-HOME-CLEAN\platform-sdk\git</tt>.<br />
<br />
The long list of variables is mostly the result of the different choices available for the URI used to clone each Git repository.<br />
Currently there are six choices, but that may soon be reduced to three if the Eclipse Foundation eliminates the non-Gerrit servers.<br />
All the clone URIs for the Platform SDK Configuration's repositories default to anonymous, read-only Gerrit access.<br />
If you are a committer, or a contributor with a [[Gerrit]] account, you will want to change each of these URIs to a form that allows read-write access.<br />
If you do not have a Gerrit account, you should [[Gerrit#User_Account|get one]] immediately!<br />
When you select the SSH (read-write, Gerrit) choice,<br />
a new variable prompt, Eclipse Git/Gerrit user ID, will appear at the very bottom.<br />
Here you should enter your Eclipse account ID, e.g., for me, emerks.<br />
Note that if you find it very painful to change each of the many URIs in the dialog,<br />
you'll only ever have to do this once,<br />
because the installer will remember this choice and will no longer display the variable, unless you check Show all variables, in which case you can change the choice you made previously.<br />
<br />
Press the Next button.<br />
<br />
== Confirm the Tasks ==<br />
<br />
After pressing the Next button, you'll be on the configuration page:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Confirmation.png|800px]]<br />
<br />
Here you can see all the setup tasks that must be performed before the installation can be launched.<br />
You can select each task to review its nested element structure and its properties; you can also select a nested elements to review its properties. <br />
The most important task is the so-called p2 task, it specifies the requirements of what needs to be installed and the update sites from which to install them.<br />
Note in particular that the Platform SDK Configuration will install using the Eclipse Platform Project's most recent Integration build.<br />
<br />
Press the Finish button and accept the license that is likely associated with the features you are about to install.<br />
<br />
== Monitor the Progress ==<br />
<br />
After pressing the Finish button, you'll be on the progress page where you can review the progress of the tasks being performed.<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Progress.png|800px]]<br />
<br />
After the p2 task' repositories are loaded, when it's time to download the artifacts to install, you'll likely be prompted to accept all the specific licenses.<br />
Note that this confirmation dialog has a "Remember accepted licenses" check box,<br />
be sure to click it so that you'll never be asked to review this license again.<br />
<br />
If this is the first time you've created an installation using the installer you may wish to go for a quick coffee break while the artifacts download.<br />
Be sure the Launch automatically check box is checked so that the installation will automatically launches upon completion (in case your coffee break turned out to be longer than expected).<br />
Unfortunately the platform's integration build is not mirrored, and there are frequent new builds, so this process can take a while.<br />
Also the download.eclipse.org server sometimes gets overloaded, so if there is a timeout failure, you can press the Back button, followed by the Finish button,<br />
to resume downloading.<br />
<br />
== Provision the Workspace ==<br />
<br />
When you get back from your coffee break, the installation will have launched and the setup engine will be working hard to provision its workspace.<br />
Note that there will be an animated button at the bottom of the window, near the right-hand side.<br />
You can press that control to bring up the Updater dialog, so you can review the progress of provisioning the workspace:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Progress.png|800px]]<br />
<br />
There's nothing else you need to do.<br />
Cloning all these repositories will definitely take some time, some are very large, and the update sites might be slow, so you can go on your lunch break now because this could take 90 minutes.<br />
<br />
== Review the Result ==<br />
<br />
The end result is a workspace like this:<br />
<br />
[[File:Oomph_Installer_Advanced_Platform_SDK_Workspace_Result.png|800px]]<br />
<br />
All the projects are organized into sensible working sets. <br />
All the Git clones are Gerrit enabled for easy contribution.<br />
And the setup even created a feature-based "Runtime Workspace" launcher and added it to the favorites list, so it's already in the menu.<br />
Now you can make changes to any project to fix bugs or to add new features and you can launch a runtime instance to test any of your changes.<br />
<br />
Note that PDE's target platform for this workspace also contains binary equivalents of all projects in the workspace,<br />
so you can close any combination of projects to improve build time without causing compile errors.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Oomph_Authoring&diff=424413Eclipse Oomph Authoring2018-04-10T07:19:24Z<p>Stepper.esc-net.de: /* Variable Filters */</p>
<hr />
<div>== Getting Started ==<br />
<br />
=== What is Oomph? ===<br />
<br />
Please read [[Eclipse Installer]].<br />
<br />
<br />
=== Installing Oomph ===<br />
<br />
# Download and install the Eclipse '''Installer''' as outlined in [[Eclipse Installer]].<br />
# Make sure that the Oomph setup '''SDK''' is installed in your IDE. Either:<br />
## That's already the case because your IDE is a Mars M5 or later Eclipse Package, or<br />
## Start the installer and install an IDE of your choice (select on the first installer page), or<br />
## Use p2 to install "Oomph Setup SDK" from [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest].<br />
<br />
== Creating a Setup Project Model ==<br />
<br />
=== Using the Setup Project Model Wizard ===<br />
<br />
# Create an empty project in your workspace or select a folder in an existing project. You'll create the new "Setup Project Model" in the selected folder.<br />
# Open the New... dialog and select the "Setup Project Model" wizard:<br>[[Image:new-wizard.png]]<br><br />
# Select one of the provided templates (e.g., Eclipse.org, Github.com, or Simple) and adjust the displayed values:<br>[[Image:new-wizard-2.png]]<br><br />
# Some values are automatically derived from your input to fields '''higher up'''.<br />
# Open the Preview>>> to understand the impact of changes to the current field.<br />
<br />
=== Using the Setup Editor ===<br />
<br />
# Open the resulting setup file with Oomph's Setup Editor:<br>[[Image:setup-edit.png]]<br><br />
# Configure the tasks in the Properties view. Note that there are "Expert" properties available.<br />
# Add setup tasks to your project and/or to your project streams and configure them, too.<br />
# The Outline view displays a ''preview'' of the executable model with resolved variables.<br />
<br />
=== Testing the Setup Model ===<br />
<br />
# To test/execute your new setup model:<br />
## Start the installer and, if necessary, switch to the Advanced Mode via the dialog menu.<br />
## Pick any product on page 1 and click the Next button to proceed to page 2.<br />
## Drag and drop your <tt>.setup</tt> file onto one of the top-level catalogs (<tt>Eclipse.org</tt> or <tt>Github.com</tt>) in the projects tree. Your project will appear as a subproject of the special <tt>&lt;User&gt;</tt> project.<br />
## Double-click your project to add it to the table at the 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.<br />
## Fill in the empty fields and press the Next button to proceed to the Confirmation page.<br />
## 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.<br><br />
# 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 [[#Using the Setup Editor|Using the Setup Editor]]. If the IDE comes up but the initial configuration fails continue with step 3.<br />
# In the new IDE (whether the initial configuration was successful or not) open your model file from the main menu, Navigate &rarr; Open Setup &rarr; [[Image:branch.png]]. Find the problems and fix them. Then start the setup process '''from within''' this IDE via the main menu, Help &rarr; [[Image:update.png]] Perform Setup Tasks&hellip;. 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.<br />
<br />
=== Contributing to a Project Catalog ===<br />
<br />
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 http://git.eclipse.org/c] and [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&bug_severity=enhancement&short_desc=Please%20include%20setup%20for%20project%20Xyz 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.<br />
<br />
The same can be done if your project is not an Eclipse project, but hosted on '''GitHub'''. Simply state this fact in the bug description and paste the "raw" content URL to the file instead.<br />
<br />
== Understanding the Setup Engine ==<br />
<br />
=== Understanding Setup Tasks and Scopes ===<br />
<br />
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:<br />
<br />
* The '''Installation''' scope is located in <tt>eclipse/configuration/org.eclipse.oomph.setup/installation.setup</tt> 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.<br />
<br />
* The '''Workspace''' scope is located in <tt>workspace/.metadata/.plugins/org.eclipse.oomph.setup/workspace.setup</tt> 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.<br />
<br />
* The '''User''' scope is located in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup</tt> and contains tasks that are common to '''all''' installations and workspaces (unless they're restricted to particular installations or workspaces).<br />
<br />
<br />
The following additional scope types exist, so they can be referenced by the entry scopes:<br />
<br />
* The '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.setup Catalog Index]''' is the root scope and contains nested Product Catalogs and Project Catalogs.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.products.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/OomphInstaller.setup Product]''' contains nested Product Version scopes and possibly some tasks that are common to all nested scopes.<br />
<br />
* A '''Product Version''' contains no nested scopes but tasks that are specific to that product version.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.projects.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/Oomph.setup Project]''' contains nested Stream and/or (Sub-) Project scopes and typically some tasks that are common to all nested scopes.<br />
<br />
* A '''Stream''' contains no nested scopes but tasks that are specific to that stream.<br />
<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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 [[#Declaring_and_Using_Variables|Declaring and Using Variables]] below.<br />
<br />
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). <br />
<br />
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.<br />
<br />
=== Declaring and Using Variables ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:<br />
<br />
${''variable-name''}<br />
<br />
To prevent a variable reference from being expanded (e.g. you actually want to have the value '${var}' and not the value of "var"), you need to escape the variable syntax with an extra double dollar character. So "$${var}" will result in "${var}".<br />
<br />
In addition to the variables that are declared by VariableTasks you can refer to all of the following:<br />
<br />
* Attribute values of setup tasks with a defined ID. The reference syntax is ${''taskID''.''attributeName''}.<br />
* System properties as returned by <tt>System.getProperties()</tt><br />
* [[#Environment Variables|Environment variables]] as returned by <tt>System.getenv()</tt><br />
* [[#Predefined Variables|Predefined variables]] as determined by the setup engine from the user input to the installer (see below)<br />
<br />
==== Predefined Variables ====<br />
<br />
The following variables are predefined by the setup engine:<br />
<br />
{| class="wikitable"<br />
| '''scope.installation.name''' || The value of the <em>name</em> attribute of the current installation scope. <br />
|-<br />
| '''scope.installation.label''' || The value of the <em>label</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.installation.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.workspace.name''' || The value of the <em>name</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.label''' || The value of the <em>label</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.description''' || The value of the <em>description</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.user.name''' || The value of the <em>name</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.label''' || The value of the <em>label</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.description''' || The value of the <em>description</em> attribute of the current user scope.<br />
|-<br />
| '''scope.product.catalog.name''' || The value of the <em>name</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.label''' || The value of the <em>label</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.description''' || The value of the <em>description</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.name''' || The value of the <em>name</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product scope and its parent scopes.<br />
|-<br />
| '''scope.product.label''' || The value of the <em>label</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.description''' || The value of the <em>description</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.version.name''' || The value of the <em>name</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product version scope and its parent scopes.<br />
|-<br />
| '''scope.product.version.label''' || The value of the <em>label</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.project.catalog.name''' || The value of the <em>name</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.label''' || The value of the <em>label</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.description''' || The value of the <em>description</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.name''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current project scope and its parent scopes.<br />
|-<br />
| '''scope.project.label''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.description''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.stream.name''' || The value of the <em>name</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current stream scope and its parent scopes.<br />
|-<br />
| '''scope.project.stream.label''' || The value of the <em>label</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.description''' || The value of the <em>description</em> attribute of the current stream scope.<br />
|}<br />
<br />
<br />
==== Variable Extensions ====<br />
<br />
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.:<br />
<br />
${installation.location/git/myproject} evaluates to C:\develop\installation1\git\myproject on Windows<br />
<br />
<br />
After the path extension part you can add filter calls with pipe symbols. Filter names are generally case-insensitive. Multiple filters can be chained. Example:<br />
<br />
${installation.location|uri}/git/myproject evaluates to file:/C:/develop/installation1/git/myproject<br />
<br />
<br />
==== Variable Filters ====<br />
<br />
The following filters are currently available:<br />
<br />
{| class="wikitable"<br />
| '''base64''' || <br />
|-<br />
| '''basePath''' || Removes the last segment from a file system path.<br />
|-<br />
| '''camel''' || Converts a qualified name to camel case notation.<br />
|-<br />
| '''canonical''' || Canonicalizes a file system path.<br />
|-<br />
| '''cap''' || Capitalizes the first word of a String value.<br />
|-<br />
| '''capAll''' || Capitalizes all words of a String value.<br />
|-<br />
| '''file''' || Converts a file: URI to an OS-specific file system path.<br />
|-<br />
| '''fileExtension''' || Extracts the file extension from a URI or a file system path.<br />
|-<br />
| '''gitRepository''' || Extracts the name of the repository from a Git URI (excluding a possible .git suffix).<br />
|-<br />
| '''lastSegment''' || Extracts the last segment from a file system path.<br />
|-<br />
| '''length''' || Converts a String to a String that contains the alpha-numerical representation of the length of the original String.<br />
|-<br />
| '''lower''' || Converts all characters of a String value to lower-case.<br />
|-<br />
| '''path''' || Extracts the path segments from a URI.<br />
|-<br />
| '''pathEncode''' || Converts a file system path to a String value that can be used as a file name.<br />
|-<br />
| '''preferenceNode''' || Escapes all forward slashes (/) of a String value, so that the result can be used as a value in preference nodes.<br />
|-<br />
| '''property''' || Escapes all double back slashes (\\) of a String value, so that the result can be used as a value in properties.<br />
|-<br />
| '''propertyValue''' || Interprets the String value as a preference property path and returns the value of that property.<br />
|-<br />
| '''qualifiedName''' || Converts a camel case String value name to a qualified name.<br />
|-<br />
| '''slashDecode''' || Decodes a slashEncoded String value.<br />
|-<br />
| '''slashEncode''' || Encodes all slashes and backslashes of a String value.<br />
|-<br />
| '''trim''' || Removes all whitespace from the beginning and the end of a String.<br />
|-<br />
| '''trimLeft''' || Removes all whitespace from the beginning of a String.<br />
|-<br />
| '''trimRight''' || Removes all whitespace from the end of a String.<br />
|-<br />
| '''trimTrailingSlashes''' || Removes all slashes and backslashes from the end of a String.<br />
|-<br />
| '''upper''' || Converts all characters of a String value to upper-case.<br />
|-<br />
| '''uri''' || Converts a file system path to a file: URI.<br />
|-<br />
| '''uriLastSegment''' || Extracts the last path segment from a hierarchical URI or the authority from an opaque URI.<br />
|-<br />
| '''urlDecode''' || Decodes a URL.<br />
|-<br />
| '''urlEncode''' || URL-encodes a String value.<br />
|-<br />
| '''username''' || Escapes all "at" symbols (@) of a String value, so that the result can be used in URI that contain a username.<br />
|}<br />
<br />
==== Variables from Outer Scopes====<br />
<br />
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:<br />
<br />
* '''jre.location-1.4''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.5''' --> The folder containing a 1.5 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.6''' --> The folder containing a 1.6 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.7''' --> The folder containing a 1.7 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.8''' --> The folder containing a 1.8 compatible JDK/JRE for architecture ${os.arch}<br />
* '''git.user.id''' --> The Eclipse user ID for Git/Gerrit commits<br />
* '''git.author.name''' --> The Eclipse author name for Git/Gerrit commits<br />
* '''git.author.email''' --> The Eclipse author email for Git/Gerrit commits<br />
* '''bugzilla.id''' --> The Eclipse user ID for Bugzilla/Hudson<br />
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson<br />
<br />
<br />
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.<br />
<br />
==== Environment Variables ====<br />
<br />
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.<br />
<br />
=== Conditional Tasks ===<br />
<br />
All setup tasks support filters. Oomph reuses [https://wiki.eclipse.org/Equinox_P2_Resolution#Enablement_filter p2's implementation] of LDAP filters. I.e., it supports a string a representation of LDAP Search Filters, RFC 1960, UMich, 1996,<br />
http://www.ietf.org/rfc/rfc1960.txt<br />
<br />
The filter property of a setup task is an advanced property. To display this property, ensure that the "Show Advanced Properties" is enabled in the Properties view tool bar. The properties of a filter expression can generally refer to any system property or any environment variable. For example, the following filter expression on a task will ensure that it is included only when performing a task on a Linux operating system.<br />
<br />
(osgi.os=linux)<br />
<br />
The latest version of Oomph allows filter properties to refer to the values of variables as defined in the setup itself. For example, this idiom can be used to express if-then-else.<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xmi:XMI xmi:version="2.0"<br />
xmlns:xmi="<nowiki>http://www.omg.org/XMI</nowiki>"<br />
xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"<br />
xmlns:setup="<nowiki>http://www.eclipse.org/oomph/setup/1.0</nowiki>"><br />
<setup:VariableTask<br />
type="BOOLEAN"<br />
name="example.filter"<br />
label="Example Filter"><br />
<description>An example of a variable used to conditionally filter tasks</description><br />
</setup:VariableTask><br />
<setup:CompoundTask<br />
filter="(example.filter=true)"<br />
name="Filter True"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.a"<br />
label="Property A"><br />
<description>The value use for system.property.a</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.a"<br />
value="=${example.variable.a}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is true</description><br />
</setup:CompoundTask><br />
<setup:CompoundTask<br />
filter="(example.filter=false)"<br />
name="Filter False"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.b"<br />
label="Property B"><br />
<description>The value used for system.property.b</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.b"<br />
value="=${example.variable.b}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is false.</description><br />
</setup:CompoundTask><br />
</xmi:XMI><br />
<br />
On the Variables page of the setup wizards, any variable that is used in property of a filter will be displayed in bold. It is significant to note that the value of a so-called filter variable can conditionally affect the presence of other variables. In this example, either variable <code>example.variable.a</code> or <code>example.variable.b</code> (but not both) will be present on the Variables page, depending on the value of the <code>example.filter</code> variable, which is displayed as a checkbox because it is of type <code>BOOLEAN</code>.<br />
<br />
Note that Oomph setup editors support textual copy and paste, so you can copy the above XML and paste it into your setup editor to try it out.<br />
<br />
== Automation and Specialization with Configurations ==<br />
<br />
As of Oomph 1.6, released with Neon.2, there is support for Configurations. A Configuration is not a Scope (is not a container for setup tasks) but rather a container for an Installation and a Workspace; each is optional, but a Configuration with neither is in effect useless. The Installation and Workspace of a Configuration are effectively used as a template to initialize the Installation and Workspace created by the Eclipse Installer, i.e., the setup resources that you can open with Navigate &rarr; Open Setup &rarr; Installation and Navigate &rarr; Open Setup &rarr; Workspace in your IDE. So you can specialize the installation with additional installation-specific tasks, e.g., a p2 task to install additional features, and you can specialize the workspace with workspace-specific tasks, e.g., a variable task to specify the value of a variable so you won't be prompted for that value. <br />
<br />
Configurations are not only useful for specifying installation-specific and workspace-specific tasks but also for automating the selection process in the setup wizards, including the installer. The Configuration's Installation can reference a specific Product Version and the Configuration's Workspace can optionally reference several specific Project Streams. Both the simple mode and the advanced mode of the installer support dragging and dropping a Configuration to the title area. You can drag to the title area either a file (i.e., a file from the file system or from an Eclipse IDE), a URL (i.e., a link from a browser), or a copy of a Configuration's XMI serialization. This will '''apply''' the Configuration to the wizard with the effect that the Installation's Product Version is selected in the wizard and the wizard advances to the next page. Similarly, the Workspace's Project Streams are selected in the wizard and the wizard advances to the next page. If you apply a Configuration with a Workspace to the simple mode of the installer, you will be prompted to switch to advanced mode because only the advanced mode supports Project selection. So in simple mode, applying a Configuration advances to the final page, and in advanced mode, applying a Configuration with an Installation and a Workspace advances to the Variables page.<br />
<br />
As an alternative to drag and drop support, rather than dragging a file, link, or XMI serialization, you can copy it to the clipboard and apply the clipboard contents to the wizard. In simple mode this is done via the Apply Configuration menu item. In advanced mode this is done via the Apply Configuration toolbar button on the Product or Project page; the menu item or toolbar item is visible only if the clipboard contains applicable content.<br />
<br />
The installer application supports command line arguments so you could also specify a Configuration's file path or URL link on the command line to apply it automatically.<br />
<br />
=== Creating a Configuration ===<br />
<br />
The simplest way to create a new Configuration is from the context menu of the folder where want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Configuration Model in the wizard. You can then edit the new Configuration with the Setup Editor. You can delete the Installation or Workspace if you don't need that aspect. You can use the Properties view to set the Installation's Product Version or the Workspace's Project Streams. And of course you can create any other setup tasks in either Scope.<br />
<br />
=== Configuration Handling ===<br />
<br />
The specific form of the serialized URLs that are used to reference a Product Version or a Project Stream are very important to correct behavior. Relative URLs in the serialization can only work relative to the location of the Configuration's resource, so will only work when you drag and drop a file or link because a dragging and dropping textual copy of the serialization provides no information about how to resolve relative references. This is not to say there is anything wrong with relative references, just be aware that they imply that the user must apply the overall file or link, not just the textual serialization. <br />
<br />
Another very useful aspect of Configurations is that the wizards handle of the references intelligently. I.e., if a Installation references a Product Version that's not in any Product Catalog in the Index, the Product will automatically be added to the user-extensible Product Catalog. If the Installation references a Product Version via its containing Product Catalog and that Product Catalog is not in the Index, and the redirectable Product Catalog is not already redirected, it will be redirected to the referenced Product Catalog and an appropriate Eclipse Ini redirection tasks will be synthesized so that the installation produced by the installer will be able to resolve the Product Version reference in its Installation via the correct containing Product Catalog. Analogous processing is done for the Project Stream references with the additional processing of Project's a logical Project container which determines which Project Catalog's extensible Project container is used. In other words, Configurations can also be used to automate the addition of Products and Projects to the user extensible catalogs.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Getting Early Feedback ===<br />
Why didn't the model editor tell me earlier that I've made a silly mistake?<br />
Please enable Live Validation in the editor menu to get early feedback.<br />
<br />
=== Copying Tasks and Other Elements ===<br />
The Setup Editor supports the export and import of any model elements by using copy to or paste from the clipboard. The clipboard will/must contain a valid XML document. With this method, for example, you can easily copy task snippets from your model directly into a forum post when you ask for help (or into a Skype window when you chat with your collegues). Or you can easily paste such XML snippets from forum replies directly into your Setup Editor.<br />
<br />
You have access to many example setups from within your IDE! Use Navigate->Open Setup->Parent Models->Open Catalog Index to investigate everything within the index. The context menu provides a way to open elements in a text editor. This is particularly handy for finding out where a particular setup is hosted (hrefs are resolved in the Setup editor) - one use case is checking and repairing links to project setups added to your user projects.<br />
<br />
=== Hosting your own index / catalogs ===<br />
If you want to host your own product or project catalog, you must provide a URI mapping to the installer to locate the root setup file (the "index"). Open the eclipse.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, or use the wizard to create it. 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/. You can redirect to your own index with this redirection system property:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->http://<hostname>/<path>/</nowiki><br />
<br />
The source URI may be abbreviated to <nowiki>index:/</nowiki> and the target URI may also be a file URI, e.g. on a shared file server.<br />
<br />
In general it will be highly desirable to archive your setup, but documentation for that is TBD. The installer and other setup wizards support dragging and dropping an index or archived index onto the title area of the dialog. Documentation for that is also TBD.<br />
<br />
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=481580 Bug 481580] has introduced empty redirectable catalogs for products ('''redirectable.products.setup''') and projects ('''redirectable.projects.setup''') to the Oomph index. These allow providing your own catalogs without replacing the entire index or disabling the catalogs shipped with Oomph (by redirecting them). The following steps are necessary to make use of those setups.<br />
* Create your own project catalog setup file using the wizard. Project setups in the project catalog should typically be referenced using absolute URIs, otherwise redirection can become problematic. However, if the relative references are downward pointing to some uniquely named folder different from any of the file/folder names in the Eclipse.org index, i.e., no '''..''' traversal to the parent folder is involved and some folder name '''<my-projects-folder>''', then they will be resolved to absolute URIs of the form '''index:/<my-projects-folder>/<path>''' which can be handled as described below.<br />
* Add a redirection system property similar to that described above to the eclipse.ini file, e.g., '''-Doomph.redirection.myProjectCatalog=index:/redirectable.projects.setup->...'''.<br />
* If the projects in that catalog are referenced by relative downward references with a unique folder, also add a folder redirection system property, e.g.,'''-Doomph.redirection.myProjectCatalog=index:/<my-projects-folder>/->.../''', to redirect the locations of the referenced projects to the folder where they are physically hosted.<br />
* Your catalog setup file must contain an Eclipse Ini task creating the same redirection(s)! Otherwise your catalog (or the referenced projects) will not be visible in the Eclipse created by the installer and hence the projects selected from it cannot be provisioned.<br />
* The first time, you may have to enable your new catalog by selecting it in the folders icon of the drop-down in the upper right hand corner of the wizard's Projects page, otherwise it will be invisible.<br />
<br />
To debug the processing of -Doomph.redirection.* if needed, set a breakpoint in org.eclipse.oomph.setup.internal.core.util.SetupCoreUtil.configureResourceSet(ResourceSet) within if (((String)key).startsWith(SetupProperties.PROP_REDIRECTION_BASE)).<br />
<br />
=== Shipping your own index ===<br />
If you want to include your own product or project catalog, you may ship the root setup file (the "index") relative to the installer directory. Then you can redirect the index as explained in [[#Hosting your own index / catalogs| Hosting your own index / catalogs]]. For example, you can place all setup files in an eclipse-installer/setups/ folder and then redirect access to it with a relative target URI:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->setups/</nowiki><br />
<br />
Note that shipping the index rather than maintaining it in a central location (accessible to all parties interested) has the following disadvantage. As each user has her own copy of the index, updates in the setup files will not be distributed automatically.<br />
<br />
=== Generating PDE Target Definition files (*.target) and their use by Tycho ===<br />
<br />
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. <br />
<br />
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:<br />
<br />
<annotation<br />
source="http:/www.eclipse.org/oomph/targlets/TargetDefinitionGenerator"><br />
<detail<br />
key="location"><br />
<value>${git.clone.location}/targetdefinition/DesignStudio.target</value><br />
</detail><br />
<detail<br />
key="extraUnits"><br />
<value>org.eclipse.equinox.executable.feature.group</value><br />
</detail><br />
<detail<br />
key="includeAllPlatforms"><br />
<value>false</value><br />
</detail><br />
<detail<br />
key="includeSource"><br />
<value>true</value><br />
</detail><br />
<detail<br />
key="generateVersions"><br />
<value>true</value><br />
</detail><br />
</annotation><br />
<br />
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.<br />
<br />
''TODO Document what preferredRepositories, PomModulesUpdater & PomArtifactUpdater do...''<br />
<br />
=== Setting up WST Server Runtime and Instances in your Setup ===<br />
<br />
==== Server Runtime Preference ====<br />
<br />
1. Use an oomphed installation/workspace with preference recorder enabled.<br />
<br />
2. Open your project and user setup editors.<br />
<br />
3. Go to Preferences / Server / Runtime Environments and 'Add' it as usual.<br />
<br />
4. Drag the selected '/instance/org.eclipse.wst.server.core/runtimes' from user to project setup.<br />
<br />
Note: It's unclear if the above actually works. Please see thread https://www.eclipse.org/forums/index.php/t/1086488/ in forum for details.<br />
For some servers there are extension tasks to handle configuration, see below.<br />
<br />
==== Server Instance in Servers View ====<br />
Requires server runtime to be setup first.<br />
<br />
1. Open Servers View and create New server instance and deploy webapps as usual<br />
<br />
2. Optionally open server instance editor and adapt configuration as usual.<br />
<br />
3. Close Eclipse.<br />
<br />
4. Start it again.<br />
<br />
5. Open '.plugins/org.eclipse.wst.server.core/servers.xml' from your workspace/.metadata using a UTF capable editor<br />
<br />
6. Add Resource Creation Task to your setup:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
content="PUT_CONTENT_FROM_SERVERS_XML_INTO_HERE_USING_A_UTF_CAPABLE_EDITOR_AND_OOMPH_DIALOG"<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.wst.server.core/servers.xml"<br />
encoding="UTF-8"><br />
<description>tomcat server integration</description><br />
</setup:ResourceCreationTask><br />
<br />
7. Use the resource task content dialog to put the servers xml content into the task.<br />
<br />
8. Copy "Servers" project from this workspace into a suitable location of your branch checkout and add/commit/push.<br />
<br />
9. Setup project import task that can pick the Servers project up from that committed location.<br />
<br />
That's it. If you want to share it among fellows, be sure to agree on canonical paths for your server installations.<br />
<br />
==== Extension tasks for specific servers ====<br />
<br />
For some servers there are oomph extension tasks that can be used to handle the configuration:<br />
<br />
https://github.com/gratex/oomph-task-server - Tomcat, WebLogic, and WebSphere<br />
<br />
=== Suppress prompt for default workspace already upon very first start ===<br />
<br />
Adjust the SHOW_WORKSPACE_SELECTION_DIALOG property to false via configuration settings org.eclipse.ui.ide.prefs ...<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP MANUAL"<br />
content="MAX_RECENT_WORKSPACES=5&amp;#xD;&amp;#xA;RECENT_WORKSPACES=${workspace.location|property}&amp;#xD;&amp;#xA;RECENT_WORKSPACES_PROTOCOL=3&amp;#xD;&amp;#xA;SHOW_WORKSPACE_SELECTION_DIALOG=false&amp;#xD;&amp;#xA;eclipse.preferences.version=1"<br />
targetURL="configuration:/.settings/org.eclipse.ui.ide.prefs"<br />
encoding="UTF-8"/><br />
<br />
=== Open default perspective already upon very first start ===<br />
Examples below using Perspective ID for Java perspective.<br />
<br />
Tell Eclipse which perspective to open initially, by adding option to eclipse ini:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:EclipseIniTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP"<br />
option="-perspective"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
Setting a perspective to be default, by adding preference task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:PreferenceTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
key="/instance/org.eclipse.ui/defaultPerspectiveId"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
=== How to switch the current stream ===<br />
<br />
If you would like to switch the current stream/s, you can re-use Oomph's initial "Eclipse Importer" wizard, available as "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace.<br />
<br />
Note that it is currently not yet possible to remove the "current" project stream. As a workaround, use menu Navigate > Open Setup > Open Workspace (or if visible click the 'blue guy' icon in the Oomph toolbar) to Open Workspace workspace.setup, expand the first node, click on the Workspace entry, open Properties view, and change the last property named "Streams" and remove the current stream.<br />
<br />
Bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=476434 enhancement may make this easier in the future.<br />
<br />
<br />
=== How to install Eclipse plugins using the P2 Director and Repository Explorer ===<br />
<br />
Oomph can install Eclipse plugins which you require. This also works for normal Java Projects set up models, not just for Eclipse plug in OSGi development, and is handy to install commonly used 3rd-party Eclipse plugins which are not all available from eclipse.org p2 sites (think e.g. http://eclemma.org). Here's how:<br />
<br />
1. add a P2 Director child task to your *.setup, if it doesn't already have one<br />
<br />
2. add a Repository child in your P2 Director task<br />
<br />
3. in the Properties of the Repository set the URL to a valid p2 repo (e.g. http://update.eclemma.org)<br />
<br />
4. right-click that Repository and choose Explore, to open the Repository Explorer view<br />
<br />
5. in the Repository Explorer view change to [X] Compatible and (*) Minor at the lower-right hand corner<br />
<br />
6. drag & drop the version from the Repository Explorer view into the P2 Director task of your *.setup editor, to create a Requirement child<br />
<br />
Drag & Drop should normally work, but appears to be broken at least on Neon Milestone 6 on Linux; in that case:<br />
<br />
6. manually create a new child Requirement inside the P2 Director task<br />
<br />
7. in the Repository Explorer view use the brown (C) icon to switch to Expert Mode to see IDs instead of names<br />
<br />
8. find the ID of the feature IU, it's the one with a PDE feature + folder kind of icon, often ending in (feature.)feature.group<br />
<br />
9. in the Properties of the Requirement, type the Name to the ID found above (e.g. com.mountainminds.eclemma.feature.feature.group)<br />
<br />
10. in the Properties of the Requirement, Type should have automatically switched to Feature<br />
<br />
PS: If you are looking for the URL of p2 repos to pre-install some of the the M2E connectors, see https://git.eclipse.org/c/m2e/m2e-discovery-catalog.git/tree/org.eclipse.m2e.discovery.oss/connectors.xml<br />
<br />
<br />
<br />
=== How to create M2E lifecycle-mapping-metadata.xml to avoid littering your pom.xml with org.eclipse.m2e:lifecycle-mapping ===<br />
<br />
Read https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html & https://wiki.eclipse.org/M2E_compatible_maven_plugins and apply as follows:<br />
<br />
<setupTask<br />
xsi:type="setup:PreferenceTask"<br />
key="/instance/org.eclipse.m2e.core/eclipse.m2.WorkspacelifecycleMappingsLocation"<br />
value="${workspace.location}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"/><br />
<br />
<setupTask<br />
xsi:type="setup:ResourceCreationTask"<br />
content="..."<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"<br />
encoding="UTF-8"><br />
<description>Initialize M2E's Maven Lifecycle Mappings, see https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html &amp; https://wiki.eclipse.org/M2E_compatible_maven_plugins</description><br />
</setupTask><br />
<br />
For "content" just open the popup using the [...] icon in the Properties and copy/paste the content from menu Window > Preferences > Maven > Lifecycle Mappings: Open workspace lifecycle mappings metadata. (This is easier than editing the content=".." in source view, because it will correctly do the XML escaping for you.)<br />
<br />
Now whenever M2E whines about stuff like "Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-dependency-plugin:2.10:unpack (execution: unpack-license, phase: generate-resources)" etc. just use the Quick Fix in the Problems view and choose the option to use workspace preferences (instead of letting the quick fix modify your pom.xml to add org.eclipse.m2e:lifecycle-mapping <lifecycleMappingMetadata>).<br />
<br />
<br />
=== How to automatically pre-enable Gerrit ===<br />
<br />
If you would like to save your end-users from having to [[EGit/User_Guide#Enabling_Gerrit_for_a_repository|manually enabling Gerrit for a repository in EGit]], then you can use the follow magic variable which Oomph will recognize and act upon:<br />
<br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="YOURORG.gerrit.uri.pattern"<br />
value="(https|ssh)://([^@/]+@)?(git.YOURORG.org:29418/.*|git.YOURORG.org/gerrit/.*)"/><br />
<br />
=== How to find a P2 repository at Eclipse using the Repository Explorer ===<br />
<br />
Most projects don't document the locations of all their p2 update sites very well. This makes it hard to find the URL you need in order to install something or in order to specify a URL for your target platform definition. Oomph indexes all the p2 update sites available at download.eclipse.org to make this job easier. You can make use of this as follows:<br />
<br />
# In the Quick Access control, type "Repository Explorer" to show Oomph's Repository Explorer view.<br />
# In that view's toolbar, locate the tool item with the hover "Search Eclipse repositories by provided capabilities", i.e., the one that looks like a little search flashlight, and click it.<br />
# This brings up the "Eclipse Repository Search" dialog. The index is very large so it takes a while to load it. But it's cached locally and updated on the server once per day.<br />
# At the root of the displayed tree are p2's namespaces and under each of these are the capabilities in that namespace. They're organized hierarchically by their qualified name. It's all quite technical and the tree is very large. So while you can explore it, you'll most likely want to use the filter to find something quickly.<br />
# Type the fully qualified name of a Java package or installable unit you wish to locate into the filter. Note that tree items for which there exist a concrete version in some repository are decorated as such. Keep in mind that many projects don't version their Java packages, so it's often better to look at the org.eclipse.equinox.p2.iu category. Here's what it looks like searching for "org.eclipse.emf.ecore.xcore":<br>[[File:SearchEclipseRepositoryDialog.png]]<br><br />
# You can select a capability in the tree so that the lower panel displays all the versions of the capability that are available. Under each of those are nested the update sites that contain them. Composite update sites show their children hierarchically.<br />
# Of course you can double click a repository to further explore its contents in the Repository Explorer itself.<br />
<br />
<br />
=== How to extract the constituent parts that comprise the Windows self-extracting installer executable ===<br />
<br />
The Eclipse Installer distribution for the Windows platform is effectively a self-extracting executable. It is extracted at runtime by the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINExtractor.java Bin Extractor]. The pre-built version of this library, i.e., org.eclipse.oomph.extractor.lib-*.jar, is available in all Oomph-containing installations, i.e., in the installer itself and in applications installed by the installer. This library can also be used standalone to decompose the composed executable into its constituent parts. That can be accomplished if you run it with the correct magical program arguments as follows:<br />
<br />
java -classpath <path-to-extract-lib>\org.eclipse.oomph.extractor.lib-*.jar<br />
org.eclipse.oomph.extractor.lib.BINExtractor <br />
<path-to-executable-to-extract>\eclipse-inst-win64.exe <br />
<target-path>\product.zip <br />
-export <br />
<target-path>\marker.txt <br />
<target-path>\extractor.exe <br />
<target-path>\org.eclipse.oomph.extractor.lib.jar <br />
<target-path>\product-descriptor<br />
<br />
The Java VM arguments need only specify the extractor library along with the main class in that library. The first program argument is the location of the executable you wish to decompose, the 64 bit installer in this case. The remaining arguments are all best directed into a common folder, denoted as <target-path> in the example above. The second argument is the extracted location of the zip file of the product/distribution. The third argument is the -export flag. The fourth argument is the extracted location of the text file containing the marker text that is used to delimit the constituent parts of the composed executable. The fifth argument is the extracted location of the small native executable itself. The sixth argument is the extracted location of the extractor library, the same one being used to extract the parts. The seventh and final argument is the extracted location of the product descriptor. Such a [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINDescriptor.java descriptor] looks like this:<br />
<br />
1<br />
1<br />
7<br />
0<br />
64<br />
0<br />
eclipse-inst.exe<br />
eclipse-inst.ini<br />
Eclipse Installer<br />
http://wiki.eclipse.org/Eclipse_Installer<br />
http://download.eclipse.org/oomph/jre/128x128.png<br />
<br />
Of course you can edit these parts and then you can recompose the executable using the following bash script executed within the common folder in which you have extracted the constituent parts:<br />
<br />
COPY /B extractor.exe + ^<br />
marker.txt + ^<br />
extractorlib.jar + ^<br />
marker.txt + ^<br />
product-descriptor + ^<br />
marker.txt + ^<br />
product.zip + ^<br />
marker.txt ^<br />
eclipse-inst-64.exe<br />
<br />
Note that the file names match the extracted target file names. From this is should be clear that the native executable is just a composition of parts. This structure is used at runtime as follows. The extractor.exe runs natively, reading its own executable file, using the marker text to find the parts. It checks the descriptor to determine if an appropriate version of Java is already installed, i.e., one that will be able to launch the product; the native extractor consults the registry to find all installed JREs and JVMs. If an appropriate Java is not found, it opens a browser page prompting the user to install an appropriate Java version with the required bitness and at the minimum required version. If there is already an appropriate version of Java, it launches a Java process to execute the BinExtract's main method. That process in turn unzips the product zip to a temp folder and launches the Java process for that for the product/distribution.<br />
<br />
== Oomph Configuration Options ==<br />
<br />
=== Configuration Options for Installer .ini File ===<br />
<br />
{| class="wikitable"<br />
| '''-Doomph.redirection.setups''' || Redirects the location of setup files (index, catalog and products). The default URI is ''http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/'' and my be abbreviated with '''index:/'''. The syntax of the redirection is '''index:/->[redirection URI]'''. Examples: '''-Doomph.redirection.setups=index:/->http://<hostname>/<path>/''' (external server redirection) or '''-Doomph.redirection.setups=index:/->setups/''' (path relative to installer executable). See also [[#Hosting_your_own_index_.2F_catalogs|Hosting your own index & catalogs]]<br />
|-<br />
| '''-Doomph.setup.product.catalog.filter''' || Only displays product catalogs matching the given prefix. The default is ''org\\.eclipse\\.products''. Displays all catalogs if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.filter''' || Only displays products matching the given prefix. The default is ''(?\!org\\.eclipse\\.products\\.org\\.eclipse\\.platform\\.ide).*''. Displays all products if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.version.filter''' || Only displays product versions matching the given prefix. The default is ''.*\\.neon''. Displays all product versions if value is empty.<br />
|-<br />
| '''-Doomph.p2.pool''' || Set to ''@none'' to disable bundle pools. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=507594] for details.<br />
|}</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Oomph_Authoring&diff=424412Eclipse Oomph Authoring2018-04-10T07:08:38Z<p>Stepper.esc-net.de: /* Variable Filters */</p>
<hr />
<div>== Getting Started ==<br />
<br />
=== What is Oomph? ===<br />
<br />
Please read [[Eclipse Installer]].<br />
<br />
<br />
=== Installing Oomph ===<br />
<br />
# Download and install the Eclipse '''Installer''' as outlined in [[Eclipse Installer]].<br />
# Make sure that the Oomph setup '''SDK''' is installed in your IDE. Either:<br />
## That's already the case because your IDE is a Mars M5 or later Eclipse Package, or<br />
## Start the installer and install an IDE of your choice (select on the first installer page), or<br />
## Use p2 to install "Oomph Setup SDK" from [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest].<br />
<br />
== Creating a Setup Project Model ==<br />
<br />
=== Using the Setup Project Model Wizard ===<br />
<br />
# Create an empty project in your workspace or select a folder in an existing project. You'll create the new "Setup Project Model" in the selected folder.<br />
# Open the New... dialog and select the "Setup Project Model" wizard:<br>[[Image:new-wizard.png]]<br><br />
# Select one of the provided templates (e.g., Eclipse.org, Github.com, or Simple) and adjust the displayed values:<br>[[Image:new-wizard-2.png]]<br><br />
# Some values are automatically derived from your input to fields '''higher up'''.<br />
# Open the Preview>>> to understand the impact of changes to the current field.<br />
<br />
=== Using the Setup Editor ===<br />
<br />
# Open the resulting setup file with Oomph's Setup Editor:<br>[[Image:setup-edit.png]]<br><br />
# Configure the tasks in the Properties view. Note that there are "Expert" properties available.<br />
# Add setup tasks to your project and/or to your project streams and configure them, too.<br />
# The Outline view displays a ''preview'' of the executable model with resolved variables.<br />
<br />
=== Testing the Setup Model ===<br />
<br />
# To test/execute your new setup model:<br />
## Start the installer and, if necessary, switch to the Advanced Mode via the dialog menu.<br />
## Pick any product on page 1 and click the Next button to proceed to page 2.<br />
## Drag and drop your <tt>.setup</tt> file onto one of the top-level catalogs (<tt>Eclipse.org</tt> or <tt>Github.com</tt>) in the projects tree. Your project will appear as a subproject of the special <tt>&lt;User&gt;</tt> project.<br />
## Double-click your project to add it to the table at the 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.<br />
## Fill in the empty fields and press the Next button to proceed to the Confirmation page.<br />
## 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.<br><br />
# 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 [[#Using the Setup Editor|Using the Setup Editor]]. If the IDE comes up but the initial configuration fails continue with step 3.<br />
# In the new IDE (whether the initial configuration was successful or not) open your model file from the main menu, Navigate &rarr; Open Setup &rarr; [[Image:branch.png]]. Find the problems and fix them. Then start the setup process '''from within''' this IDE via the main menu, Help &rarr; [[Image:update.png]] Perform Setup Tasks&hellip;. 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.<br />
<br />
=== Contributing to a Project Catalog ===<br />
<br />
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 http://git.eclipse.org/c] and [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&bug_severity=enhancement&short_desc=Please%20include%20setup%20for%20project%20Xyz 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.<br />
<br />
The same can be done if your project is not an Eclipse project, but hosted on '''GitHub'''. Simply state this fact in the bug description and paste the "raw" content URL to the file instead.<br />
<br />
== Understanding the Setup Engine ==<br />
<br />
=== Understanding Setup Tasks and Scopes ===<br />
<br />
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:<br />
<br />
* The '''Installation''' scope is located in <tt>eclipse/configuration/org.eclipse.oomph.setup/installation.setup</tt> 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.<br />
<br />
* The '''Workspace''' scope is located in <tt>workspace/.metadata/.plugins/org.eclipse.oomph.setup/workspace.setup</tt> 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.<br />
<br />
* The '''User''' scope is located in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup</tt> and contains tasks that are common to '''all''' installations and workspaces (unless they're restricted to particular installations or workspaces).<br />
<br />
<br />
The following additional scope types exist, so they can be referenced by the entry scopes:<br />
<br />
* The '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.setup Catalog Index]''' is the root scope and contains nested Product Catalogs and Project Catalogs.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.products.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/OomphInstaller.setup Product]''' contains nested Product Version scopes and possibly some tasks that are common to all nested scopes.<br />
<br />
* A '''Product Version''' contains no nested scopes but tasks that are specific to that product version.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.projects.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/Oomph.setup Project]''' contains nested Stream and/or (Sub-) Project scopes and typically some tasks that are common to all nested scopes.<br />
<br />
* A '''Stream''' contains no nested scopes but tasks that are specific to that stream.<br />
<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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 [[#Declaring_and_Using_Variables|Declaring and Using Variables]] below.<br />
<br />
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). <br />
<br />
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.<br />
<br />
=== Declaring and Using Variables ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:<br />
<br />
${''variable-name''}<br />
<br />
To prevent a variable reference from being expanded (e.g. you actually want to have the value '${var}' and not the value of "var"), you need to escape the variable syntax with an extra double dollar character. So "$${var}" will result in "${var}".<br />
<br />
In addition to the variables that are declared by VariableTasks you can refer to all of the following:<br />
<br />
* Attribute values of setup tasks with a defined ID. The reference syntax is ${''taskID''.''attributeName''}.<br />
* System properties as returned by <tt>System.getProperties()</tt><br />
* [[#Environment Variables|Environment variables]] as returned by <tt>System.getenv()</tt><br />
* [[#Predefined Variables|Predefined variables]] as determined by the setup engine from the user input to the installer (see below)<br />
<br />
==== Predefined Variables ====<br />
<br />
The following variables are predefined by the setup engine:<br />
<br />
{| class="wikitable"<br />
| '''scope.installation.name''' || The value of the <em>name</em> attribute of the current installation scope. <br />
|-<br />
| '''scope.installation.label''' || The value of the <em>label</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.installation.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.workspace.name''' || The value of the <em>name</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.label''' || The value of the <em>label</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.description''' || The value of the <em>description</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.user.name''' || The value of the <em>name</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.label''' || The value of the <em>label</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.description''' || The value of the <em>description</em> attribute of the current user scope.<br />
|-<br />
| '''scope.product.catalog.name''' || The value of the <em>name</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.label''' || The value of the <em>label</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.description''' || The value of the <em>description</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.name''' || The value of the <em>name</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product scope and its parent scopes.<br />
|-<br />
| '''scope.product.label''' || The value of the <em>label</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.description''' || The value of the <em>description</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.version.name''' || The value of the <em>name</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product version scope and its parent scopes.<br />
|-<br />
| '''scope.product.version.label''' || The value of the <em>label</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.project.catalog.name''' || The value of the <em>name</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.label''' || The value of the <em>label</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.description''' || The value of the <em>description</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.name''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current project scope and its parent scopes.<br />
|-<br />
| '''scope.project.label''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.description''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.stream.name''' || The value of the <em>name</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current stream scope and its parent scopes.<br />
|-<br />
| '''scope.project.stream.label''' || The value of the <em>label</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.description''' || The value of the <em>description</em> attribute of the current stream scope.<br />
|}<br />
<br />
<br />
==== Variable Extensions ====<br />
<br />
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.:<br />
<br />
${installation.location/git/myproject} evaluates to C:\develop\installation1\git\myproject on Windows<br />
<br />
<br />
After the path extension part you can add filter calls with pipe symbols. Filter names are generally case-insensitive. Multiple filters can be chained. Example:<br />
<br />
${installation.location|uri}/git/myproject evaluates to file:/C:/develop/installation1/git/myproject<br />
<br />
<br />
==== Variable Filters ====<br />
<br />
The following filters are currently available:<br />
<br />
{| class="wikitable"<br />
| '''base64''' || <br />
|-<br />
| '''basePath''' || Removes the last segment from a file system path.<br />
|-<br />
| '''camel''' || Converts a qualified name to camel case notation.<br />
|-<br />
| '''canonical''' || Canonicalizes a file system path.<br />
|-<br />
| '''cap''' || Capitalizes the first word of a String value.<br />
|-<br />
| '''capAll''' || Capitalizes all words of a String value.<br />
|-<br />
| '''file''' || Converts a file: URI to an OS-specific file system path.<br />
|-<br />
| '''fileExtension''' || Extracts the file extension from a URI or a file system path.<br />
|-<br />
| '''gitRepository''' || Extracts the name of the repository from a Git URI (excluding a possible .git suffix).<br />
|-<br />
| '''lastSegment''' || Extracts the last segment from a file system path.<br />
|-<br />
| '''length''' || Converts a String to a String that contains the alpha-numerical representation of the length of the original String.<br />
|-<br />
| '''lower''' || Converts all characters of a String value to lower-case.<br />
|-<br />
| '''path''' || Extracts the path segments from a URI.<br />
|-<br />
| '''pathEncode''' || Converts a file system path to a string that can be used as a file name.<br />
|-<br />
| '''preferenceNode''' || Escapes all forward slashes (/) of a String value, so that the result can be used as a value in preference nodes.<br />
|-<br />
| '''property''' || Escapes all double back slashes (\\) of a String value, so that the result can be used as a value in properties.<br />
|-<br />
| '''propertyValue''' || Interprets the String value as a preference property path and returns the value of that property.<br />
|-<br />
| '''qualifiedName''' || Converts a camel case String value name to a qualified name.<br />
|-<br />
| '''slashDecode''' || Decodes a slashEncoded string.<br />
|-<br />
| '''slashEncode''' || Encodes all slashes and backslashes of a string.<br />
|-<br />
| '''trim''' || Removes all whitespace from the beginning and the end of a String.<br />
|-<br />
| '''trimLeft''' || Removes all whitespace from the beginning of a String.<br />
|-<br />
| '''trimRight''' || Removes all whitespace from the end of a String.<br />
|-<br />
| '''trimTrailingSlashes''' || Removes all slashes and backslashes from the end of a String.<br />
|-<br />
| '''upper''' || Converts all characters of a String value to upper-case.<br />
|-<br />
| '''uri''' || Converts a file system path to a file: URI.<br />
|-<br />
| '''uriLastSegment''' || Extracts the last path segment from a hierarchical URI or the authority from an opaque URI.<br />
|-<br />
| '''urlDecode''' || Decodes a URL.<br />
|-<br />
| '''urlEncode''' || URL-encodes a string.<br />
|-<br />
| '''username''' || Escapes all "at" symbols (@) of a String value, so that the result can be used in URI that contain a username.<br />
|}<br />
<br />
==== Variables from Outer Scopes====<br />
<br />
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:<br />
<br />
* '''jre.location-1.4''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.5''' --> The folder containing a 1.5 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.6''' --> The folder containing a 1.6 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.7''' --> The folder containing a 1.7 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.8''' --> The folder containing a 1.8 compatible JDK/JRE for architecture ${os.arch}<br />
* '''git.user.id''' --> The Eclipse user ID for Git/Gerrit commits<br />
* '''git.author.name''' --> The Eclipse author name for Git/Gerrit commits<br />
* '''git.author.email''' --> The Eclipse author email for Git/Gerrit commits<br />
* '''bugzilla.id''' --> The Eclipse user ID for Bugzilla/Hudson<br />
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson<br />
<br />
<br />
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.<br />
<br />
==== Environment Variables ====<br />
<br />
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.<br />
<br />
=== Conditional Tasks ===<br />
<br />
All setup tasks support filters. Oomph reuses [https://wiki.eclipse.org/Equinox_P2_Resolution#Enablement_filter p2's implementation] of LDAP filters. I.e., it supports a string a representation of LDAP Search Filters, RFC 1960, UMich, 1996,<br />
http://www.ietf.org/rfc/rfc1960.txt<br />
<br />
The filter property of a setup task is an advanced property. To display this property, ensure that the "Show Advanced Properties" is enabled in the Properties view tool bar. The properties of a filter expression can generally refer to any system property or any environment variable. For example, the following filter expression on a task will ensure that it is included only when performing a task on a Linux operating system.<br />
<br />
(osgi.os=linux)<br />
<br />
The latest version of Oomph allows filter properties to refer to the values of variables as defined in the setup itself. For example, this idiom can be used to express if-then-else.<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xmi:XMI xmi:version="2.0"<br />
xmlns:xmi="<nowiki>http://www.omg.org/XMI</nowiki>"<br />
xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"<br />
xmlns:setup="<nowiki>http://www.eclipse.org/oomph/setup/1.0</nowiki>"><br />
<setup:VariableTask<br />
type="BOOLEAN"<br />
name="example.filter"<br />
label="Example Filter"><br />
<description>An example of a variable used to conditionally filter tasks</description><br />
</setup:VariableTask><br />
<setup:CompoundTask<br />
filter="(example.filter=true)"<br />
name="Filter True"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.a"<br />
label="Property A"><br />
<description>The value use for system.property.a</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.a"<br />
value="=${example.variable.a}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is true</description><br />
</setup:CompoundTask><br />
<setup:CompoundTask<br />
filter="(example.filter=false)"<br />
name="Filter False"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.b"<br />
label="Property B"><br />
<description>The value used for system.property.b</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.b"<br />
value="=${example.variable.b}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is false.</description><br />
</setup:CompoundTask><br />
</xmi:XMI><br />
<br />
On the Variables page of the setup wizards, any variable that is used in property of a filter will be displayed in bold. It is significant to note that the value of a so-called filter variable can conditionally affect the presence of other variables. In this example, either variable <code>example.variable.a</code> or <code>example.variable.b</code> (but not both) will be present on the Variables page, depending on the value of the <code>example.filter</code> variable, which is displayed as a checkbox because it is of type <code>BOOLEAN</code>.<br />
<br />
Note that Oomph setup editors support textual copy and paste, so you can copy the above XML and paste it into your setup editor to try it out.<br />
<br />
== Automation and Specialization with Configurations ==<br />
<br />
As of Oomph 1.6, released with Neon.2, there is support for Configurations. A Configuration is not a Scope (is not a container for setup tasks) but rather a container for an Installation and a Workspace; each is optional, but a Configuration with neither is in effect useless. The Installation and Workspace of a Configuration are effectively used as a template to initialize the Installation and Workspace created by the Eclipse Installer, i.e., the setup resources that you can open with Navigate &rarr; Open Setup &rarr; Installation and Navigate &rarr; Open Setup &rarr; Workspace in your IDE. So you can specialize the installation with additional installation-specific tasks, e.g., a p2 task to install additional features, and you can specialize the workspace with workspace-specific tasks, e.g., a variable task to specify the value of a variable so you won't be prompted for that value. <br />
<br />
Configurations are not only useful for specifying installation-specific and workspace-specific tasks but also for automating the selection process in the setup wizards, including the installer. The Configuration's Installation can reference a specific Product Version and the Configuration's Workspace can optionally reference several specific Project Streams. Both the simple mode and the advanced mode of the installer support dragging and dropping a Configuration to the title area. You can drag to the title area either a file (i.e., a file from the file system or from an Eclipse IDE), a URL (i.e., a link from a browser), or a copy of a Configuration's XMI serialization. This will '''apply''' the Configuration to the wizard with the effect that the Installation's Product Version is selected in the wizard and the wizard advances to the next page. Similarly, the Workspace's Project Streams are selected in the wizard and the wizard advances to the next page. If you apply a Configuration with a Workspace to the simple mode of the installer, you will be prompted to switch to advanced mode because only the advanced mode supports Project selection. So in simple mode, applying a Configuration advances to the final page, and in advanced mode, applying a Configuration with an Installation and a Workspace advances to the Variables page.<br />
<br />
As an alternative to drag and drop support, rather than dragging a file, link, or XMI serialization, you can copy it to the clipboard and apply the clipboard contents to the wizard. In simple mode this is done via the Apply Configuration menu item. In advanced mode this is done via the Apply Configuration toolbar button on the Product or Project page; the menu item or toolbar item is visible only if the clipboard contains applicable content.<br />
<br />
The installer application supports command line arguments so you could also specify a Configuration's file path or URL link on the command line to apply it automatically.<br />
<br />
=== Creating a Configuration ===<br />
<br />
The simplest way to create a new Configuration is from the context menu of the folder where want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Configuration Model in the wizard. You can then edit the new Configuration with the Setup Editor. You can delete the Installation or Workspace if you don't need that aspect. You can use the Properties view to set the Installation's Product Version or the Workspace's Project Streams. And of course you can create any other setup tasks in either Scope.<br />
<br />
=== Configuration Handling ===<br />
<br />
The specific form of the serialized URLs that are used to reference a Product Version or a Project Stream are very important to correct behavior. Relative URLs in the serialization can only work relative to the location of the Configuration's resource, so will only work when you drag and drop a file or link because a dragging and dropping textual copy of the serialization provides no information about how to resolve relative references. This is not to say there is anything wrong with relative references, just be aware that they imply that the user must apply the overall file or link, not just the textual serialization. <br />
<br />
Another very useful aspect of Configurations is that the wizards handle of the references intelligently. I.e., if a Installation references a Product Version that's not in any Product Catalog in the Index, the Product will automatically be added to the user-extensible Product Catalog. If the Installation references a Product Version via its containing Product Catalog and that Product Catalog is not in the Index, and the redirectable Product Catalog is not already redirected, it will be redirected to the referenced Product Catalog and an appropriate Eclipse Ini redirection tasks will be synthesized so that the installation produced by the installer will be able to resolve the Product Version reference in its Installation via the correct containing Product Catalog. Analogous processing is done for the Project Stream references with the additional processing of Project's a logical Project container which determines which Project Catalog's extensible Project container is used. In other words, Configurations can also be used to automate the addition of Products and Projects to the user extensible catalogs.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Getting Early Feedback ===<br />
Why didn't the model editor tell me earlier that I've made a silly mistake?<br />
Please enable Live Validation in the editor menu to get early feedback.<br />
<br />
=== Copying Tasks and Other Elements ===<br />
The Setup Editor supports the export and import of any model elements by using copy to or paste from the clipboard. The clipboard will/must contain a valid XML document. With this method, for example, you can easily copy task snippets from your model directly into a forum post when you ask for help (or into a Skype window when you chat with your collegues). Or you can easily paste such XML snippets from forum replies directly into your Setup Editor.<br />
<br />
You have access to many example setups from within your IDE! Use Navigate->Open Setup->Parent Models->Open Catalog Index to investigate everything within the index. The context menu provides a way to open elements in a text editor. This is particularly handy for finding out where a particular setup is hosted (hrefs are resolved in the Setup editor) - one use case is checking and repairing links to project setups added to your user projects.<br />
<br />
=== Hosting your own index / catalogs ===<br />
If you want to host your own product or project catalog, you must provide a URI mapping to the installer to locate the root setup file (the "index"). Open the eclipse.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, or use the wizard to create it. 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/. You can redirect to your own index with this redirection system property:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->http://<hostname>/<path>/</nowiki><br />
<br />
The source URI may be abbreviated to <nowiki>index:/</nowiki> and the target URI may also be a file URI, e.g. on a shared file server.<br />
<br />
In general it will be highly desirable to archive your setup, but documentation for that is TBD. The installer and other setup wizards support dragging and dropping an index or archived index onto the title area of the dialog. Documentation for that is also TBD.<br />
<br />
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=481580 Bug 481580] has introduced empty redirectable catalogs for products ('''redirectable.products.setup''') and projects ('''redirectable.projects.setup''') to the Oomph index. These allow providing your own catalogs without replacing the entire index or disabling the catalogs shipped with Oomph (by redirecting them). The following steps are necessary to make use of those setups.<br />
* Create your own project catalog setup file using the wizard. Project setups in the project catalog should typically be referenced using absolute URIs, otherwise redirection can become problematic. However, if the relative references are downward pointing to some uniquely named folder different from any of the file/folder names in the Eclipse.org index, i.e., no '''..''' traversal to the parent folder is involved and some folder name '''<my-projects-folder>''', then they will be resolved to absolute URIs of the form '''index:/<my-projects-folder>/<path>''' which can be handled as described below.<br />
* Add a redirection system property similar to that described above to the eclipse.ini file, e.g., '''-Doomph.redirection.myProjectCatalog=index:/redirectable.projects.setup->...'''.<br />
* If the projects in that catalog are referenced by relative downward references with a unique folder, also add a folder redirection system property, e.g.,'''-Doomph.redirection.myProjectCatalog=index:/<my-projects-folder>/->.../''', to redirect the locations of the referenced projects to the folder where they are physically hosted.<br />
* Your catalog setup file must contain an Eclipse Ini task creating the same redirection(s)! Otherwise your catalog (or the referenced projects) will not be visible in the Eclipse created by the installer and hence the projects selected from it cannot be provisioned.<br />
* The first time, you may have to enable your new catalog by selecting it in the folders icon of the drop-down in the upper right hand corner of the wizard's Projects page, otherwise it will be invisible.<br />
<br />
To debug the processing of -Doomph.redirection.* if needed, set a breakpoint in org.eclipse.oomph.setup.internal.core.util.SetupCoreUtil.configureResourceSet(ResourceSet) within if (((String)key).startsWith(SetupProperties.PROP_REDIRECTION_BASE)).<br />
<br />
=== Shipping your own index ===<br />
If you want to include your own product or project catalog, you may ship the root setup file (the "index") relative to the installer directory. Then you can redirect the index as explained in [[#Hosting your own index / catalogs| Hosting your own index / catalogs]]. For example, you can place all setup files in an eclipse-installer/setups/ folder and then redirect access to it with a relative target URI:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->setups/</nowiki><br />
<br />
Note that shipping the index rather than maintaining it in a central location (accessible to all parties interested) has the following disadvantage. As each user has her own copy of the index, updates in the setup files will not be distributed automatically.<br />
<br />
=== Generating PDE Target Definition files (*.target) and their use by Tycho ===<br />
<br />
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. <br />
<br />
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:<br />
<br />
<annotation<br />
source="http:/www.eclipse.org/oomph/targlets/TargetDefinitionGenerator"><br />
<detail<br />
key="location"><br />
<value>${git.clone.location}/targetdefinition/DesignStudio.target</value><br />
</detail><br />
<detail<br />
key="extraUnits"><br />
<value>org.eclipse.equinox.executable.feature.group</value><br />
</detail><br />
<detail<br />
key="includeAllPlatforms"><br />
<value>false</value><br />
</detail><br />
<detail<br />
key="includeSource"><br />
<value>true</value><br />
</detail><br />
<detail<br />
key="generateVersions"><br />
<value>true</value><br />
</detail><br />
</annotation><br />
<br />
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.<br />
<br />
''TODO Document what preferredRepositories, PomModulesUpdater & PomArtifactUpdater do...''<br />
<br />
=== Setting up WST Server Runtime and Instances in your Setup ===<br />
<br />
==== Server Runtime Preference ====<br />
<br />
1. Use an oomphed installation/workspace with preference recorder enabled.<br />
<br />
2. Open your project and user setup editors.<br />
<br />
3. Go to Preferences / Server / Runtime Environments and 'Add' it as usual.<br />
<br />
4. Drag the selected '/instance/org.eclipse.wst.server.core/runtimes' from user to project setup.<br />
<br />
Note: It's unclear if the above actually works. Please see thread https://www.eclipse.org/forums/index.php/t/1086488/ in forum for details.<br />
For some servers there are extension tasks to handle configuration, see below.<br />
<br />
==== Server Instance in Servers View ====<br />
Requires server runtime to be setup first.<br />
<br />
1. Open Servers View and create New server instance and deploy webapps as usual<br />
<br />
2. Optionally open server instance editor and adapt configuration as usual.<br />
<br />
3. Close Eclipse.<br />
<br />
4. Start it again.<br />
<br />
5. Open '.plugins/org.eclipse.wst.server.core/servers.xml' from your workspace/.metadata using a UTF capable editor<br />
<br />
6. Add Resource Creation Task to your setup:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
content="PUT_CONTENT_FROM_SERVERS_XML_INTO_HERE_USING_A_UTF_CAPABLE_EDITOR_AND_OOMPH_DIALOG"<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.wst.server.core/servers.xml"<br />
encoding="UTF-8"><br />
<description>tomcat server integration</description><br />
</setup:ResourceCreationTask><br />
<br />
7. Use the resource task content dialog to put the servers xml content into the task.<br />
<br />
8. Copy "Servers" project from this workspace into a suitable location of your branch checkout and add/commit/push.<br />
<br />
9. Setup project import task that can pick the Servers project up from that committed location.<br />
<br />
That's it. If you want to share it among fellows, be sure to agree on canonical paths for your server installations.<br />
<br />
==== Extension tasks for specific servers ====<br />
<br />
For some servers there are oomph extension tasks that can be used to handle the configuration:<br />
<br />
https://github.com/gratex/oomph-task-server - Tomcat, WebLogic, and WebSphere<br />
<br />
=== Suppress prompt for default workspace already upon very first start ===<br />
<br />
Adjust the SHOW_WORKSPACE_SELECTION_DIALOG property to false via configuration settings org.eclipse.ui.ide.prefs ...<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP MANUAL"<br />
content="MAX_RECENT_WORKSPACES=5&amp;#xD;&amp;#xA;RECENT_WORKSPACES=${workspace.location|property}&amp;#xD;&amp;#xA;RECENT_WORKSPACES_PROTOCOL=3&amp;#xD;&amp;#xA;SHOW_WORKSPACE_SELECTION_DIALOG=false&amp;#xD;&amp;#xA;eclipse.preferences.version=1"<br />
targetURL="configuration:/.settings/org.eclipse.ui.ide.prefs"<br />
encoding="UTF-8"/><br />
<br />
=== Open default perspective already upon very first start ===<br />
Examples below using Perspective ID for Java perspective.<br />
<br />
Tell Eclipse which perspective to open initially, by adding option to eclipse ini:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:EclipseIniTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP"<br />
option="-perspective"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
Setting a perspective to be default, by adding preference task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:PreferenceTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
key="/instance/org.eclipse.ui/defaultPerspectiveId"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
=== How to switch the current stream ===<br />
<br />
If you would like to switch the current stream/s, you can re-use Oomph's initial "Eclipse Importer" wizard, available as "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace.<br />
<br />
Note that it is currently not yet possible to remove the "current" project stream. As a workaround, use menu Navigate > Open Setup > Open Workspace (or if visible click the 'blue guy' icon in the Oomph toolbar) to Open Workspace workspace.setup, expand the first node, click on the Workspace entry, open Properties view, and change the last property named "Streams" and remove the current stream.<br />
<br />
Bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=476434 enhancement may make this easier in the future.<br />
<br />
<br />
=== How to install Eclipse plugins using the P2 Director and Repository Explorer ===<br />
<br />
Oomph can install Eclipse plugins which you require. This also works for normal Java Projects set up models, not just for Eclipse plug in OSGi development, and is handy to install commonly used 3rd-party Eclipse plugins which are not all available from eclipse.org p2 sites (think e.g. http://eclemma.org). Here's how:<br />
<br />
1. add a P2 Director child task to your *.setup, if it doesn't already have one<br />
<br />
2. add a Repository child in your P2 Director task<br />
<br />
3. in the Properties of the Repository set the URL to a valid p2 repo (e.g. http://update.eclemma.org)<br />
<br />
4. right-click that Repository and choose Explore, to open the Repository Explorer view<br />
<br />
5. in the Repository Explorer view change to [X] Compatible and (*) Minor at the lower-right hand corner<br />
<br />
6. drag & drop the version from the Repository Explorer view into the P2 Director task of your *.setup editor, to create a Requirement child<br />
<br />
Drag & Drop should normally work, but appears to be broken at least on Neon Milestone 6 on Linux; in that case:<br />
<br />
6. manually create a new child Requirement inside the P2 Director task<br />
<br />
7. in the Repository Explorer view use the brown (C) icon to switch to Expert Mode to see IDs instead of names<br />
<br />
8. find the ID of the feature IU, it's the one with a PDE feature + folder kind of icon, often ending in (feature.)feature.group<br />
<br />
9. in the Properties of the Requirement, type the Name to the ID found above (e.g. com.mountainminds.eclemma.feature.feature.group)<br />
<br />
10. in the Properties of the Requirement, Type should have automatically switched to Feature<br />
<br />
PS: If you are looking for the URL of p2 repos to pre-install some of the the M2E connectors, see https://git.eclipse.org/c/m2e/m2e-discovery-catalog.git/tree/org.eclipse.m2e.discovery.oss/connectors.xml<br />
<br />
<br />
<br />
=== How to create M2E lifecycle-mapping-metadata.xml to avoid littering your pom.xml with org.eclipse.m2e:lifecycle-mapping ===<br />
<br />
Read https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html & https://wiki.eclipse.org/M2E_compatible_maven_plugins and apply as follows:<br />
<br />
<setupTask<br />
xsi:type="setup:PreferenceTask"<br />
key="/instance/org.eclipse.m2e.core/eclipse.m2.WorkspacelifecycleMappingsLocation"<br />
value="${workspace.location}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"/><br />
<br />
<setupTask<br />
xsi:type="setup:ResourceCreationTask"<br />
content="..."<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"<br />
encoding="UTF-8"><br />
<description>Initialize M2E's Maven Lifecycle Mappings, see https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html &amp; https://wiki.eclipse.org/M2E_compatible_maven_plugins</description><br />
</setupTask><br />
<br />
For "content" just open the popup using the [...] icon in the Properties and copy/paste the content from menu Window > Preferences > Maven > Lifecycle Mappings: Open workspace lifecycle mappings metadata. (This is easier than editing the content=".." in source view, because it will correctly do the XML escaping for you.)<br />
<br />
Now whenever M2E whines about stuff like "Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-dependency-plugin:2.10:unpack (execution: unpack-license, phase: generate-resources)" etc. just use the Quick Fix in the Problems view and choose the option to use workspace preferences (instead of letting the quick fix modify your pom.xml to add org.eclipse.m2e:lifecycle-mapping <lifecycleMappingMetadata>).<br />
<br />
<br />
=== How to automatically pre-enable Gerrit ===<br />
<br />
If you would like to save your end-users from having to [[EGit/User_Guide#Enabling_Gerrit_for_a_repository|manually enabling Gerrit for a repository in EGit]], then you can use the follow magic variable which Oomph will recognize and act upon:<br />
<br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="YOURORG.gerrit.uri.pattern"<br />
value="(https|ssh)://([^@/]+@)?(git.YOURORG.org:29418/.*|git.YOURORG.org/gerrit/.*)"/><br />
<br />
=== How to find a P2 repository at Eclipse using the Repository Explorer ===<br />
<br />
Most projects don't document the locations of all their p2 update sites very well. This makes it hard to find the URL you need in order to install something or in order to specify a URL for your target platform definition. Oomph indexes all the p2 update sites available at download.eclipse.org to make this job easier. You can make use of this as follows:<br />
<br />
# In the Quick Access control, type "Repository Explorer" to show Oomph's Repository Explorer view.<br />
# In that view's toolbar, locate the tool item with the hover "Search Eclipse repositories by provided capabilities", i.e., the one that looks like a little search flashlight, and click it.<br />
# This brings up the "Eclipse Repository Search" dialog. The index is very large so it takes a while to load it. But it's cached locally and updated on the server once per day.<br />
# At the root of the displayed tree are p2's namespaces and under each of these are the capabilities in that namespace. They're organized hierarchically by their qualified name. It's all quite technical and the tree is very large. So while you can explore it, you'll most likely want to use the filter to find something quickly.<br />
# Type the fully qualified name of a Java package or installable unit you wish to locate into the filter. Note that tree items for which there exist a concrete version in some repository are decorated as such. Keep in mind that many projects don't version their Java packages, so it's often better to look at the org.eclipse.equinox.p2.iu category. Here's what it looks like searching for "org.eclipse.emf.ecore.xcore":<br>[[File:SearchEclipseRepositoryDialog.png]]<br><br />
# You can select a capability in the tree so that the lower panel displays all the versions of the capability that are available. Under each of those are nested the update sites that contain them. Composite update sites show their children hierarchically.<br />
# Of course you can double click a repository to further explore its contents in the Repository Explorer itself.<br />
<br />
<br />
=== How to extract the constituent parts that comprise the Windows self-extracting installer executable ===<br />
<br />
The Eclipse Installer distribution for the Windows platform is effectively a self-extracting executable. It is extracted at runtime by the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINExtractor.java Bin Extractor]. The pre-built version of this library, i.e., org.eclipse.oomph.extractor.lib-*.jar, is available in all Oomph-containing installations, i.e., in the installer itself and in applications installed by the installer. This library can also be used standalone to decompose the composed executable into its constituent parts. That can be accomplished if you run it with the correct magical program arguments as follows:<br />
<br />
java -classpath <path-to-extract-lib>\org.eclipse.oomph.extractor.lib-*.jar<br />
org.eclipse.oomph.extractor.lib.BINExtractor <br />
<path-to-executable-to-extract>\eclipse-inst-win64.exe <br />
<target-path>\product.zip <br />
-export <br />
<target-path>\marker.txt <br />
<target-path>\extractor.exe <br />
<target-path>\org.eclipse.oomph.extractor.lib.jar <br />
<target-path>\product-descriptor<br />
<br />
The Java VM arguments need only specify the extractor library along with the main class in that library. The first program argument is the location of the executable you wish to decompose, the 64 bit installer in this case. The remaining arguments are all best directed into a common folder, denoted as <target-path> in the example above. The second argument is the extracted location of the zip file of the product/distribution. The third argument is the -export flag. The fourth argument is the extracted location of the text file containing the marker text that is used to delimit the constituent parts of the composed executable. The fifth argument is the extracted location of the small native executable itself. The sixth argument is the extracted location of the extractor library, the same one being used to extract the parts. The seventh and final argument is the extracted location of the product descriptor. Such a [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINDescriptor.java descriptor] looks like this:<br />
<br />
1<br />
1<br />
7<br />
0<br />
64<br />
0<br />
eclipse-inst.exe<br />
eclipse-inst.ini<br />
Eclipse Installer<br />
http://wiki.eclipse.org/Eclipse_Installer<br />
http://download.eclipse.org/oomph/jre/128x128.png<br />
<br />
Of course you can edit these parts and then you can recompose the executable using the following bash script executed within the common folder in which you have extracted the constituent parts:<br />
<br />
COPY /B extractor.exe + ^<br />
marker.txt + ^<br />
extractorlib.jar + ^<br />
marker.txt + ^<br />
product-descriptor + ^<br />
marker.txt + ^<br />
product.zip + ^<br />
marker.txt ^<br />
eclipse-inst-64.exe<br />
<br />
Note that the file names match the extracted target file names. From this is should be clear that the native executable is just a composition of parts. This structure is used at runtime as follows. The extractor.exe runs natively, reading its own executable file, using the marker text to find the parts. It checks the descriptor to determine if an appropriate version of Java is already installed, i.e., one that will be able to launch the product; the native extractor consults the registry to find all installed JREs and JVMs. If an appropriate Java is not found, it opens a browser page prompting the user to install an appropriate Java version with the required bitness and at the minimum required version. If there is already an appropriate version of Java, it launches a Java process to execute the BinExtract's main method. That process in turn unzips the product zip to a temp folder and launches the Java process for that for the product/distribution.<br />
<br />
== Oomph Configuration Options ==<br />
<br />
=== Configuration Options for Installer .ini File ===<br />
<br />
{| class="wikitable"<br />
| '''-Doomph.redirection.setups''' || Redirects the location of setup files (index, catalog and products). The default URI is ''http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/'' and my be abbreviated with '''index:/'''. The syntax of the redirection is '''index:/->[redirection URI]'''. Examples: '''-Doomph.redirection.setups=index:/->http://<hostname>/<path>/''' (external server redirection) or '''-Doomph.redirection.setups=index:/->setups/''' (path relative to installer executable). See also [[#Hosting_your_own_index_.2F_catalogs|Hosting your own index & catalogs]]<br />
|-<br />
| '''-Doomph.setup.product.catalog.filter''' || Only displays product catalogs matching the given prefix. The default is ''org\\.eclipse\\.products''. Displays all catalogs if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.filter''' || Only displays products matching the given prefix. The default is ''(?\!org\\.eclipse\\.products\\.org\\.eclipse\\.platform\\.ide).*''. Displays all products if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.version.filter''' || Only displays product versions matching the given prefix. The default is ''.*\\.neon''. Displays all product versions if value is empty.<br />
|-<br />
| '''-Doomph.p2.pool''' || Set to ''@none'' to disable bundle pools. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=507594] for details.<br />
|}</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Oomph_Contribution_Guide&diff=422867Oomph Contribution Guide2018-02-16T08:47:14Z<p>Stepper.esc-net.de: </p>
<hr />
<div>If you wish to contribute to Oomph, please obtain an [http://wiki.eclipse.org/Gerrit#User_Account Eclipse Gerrit account] and provision your Oomph setup to use a Gerrit clone. Then you'll be able to commit your contribution to Gerrit for review. You'll also need an [https://dev.eclipse.org/site_login/createaccount.php Eclipse account] for bugzilla access and to post to the [[Eclipse_Oomph_Installer#Getting_in_Touch|forums]].<br />
<br />
Here are some simple rules to follow for contributing to Oomph:<br />
# All contributions should correspond to a [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0 bug report] or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0&bug_severity=enhancement feature request] and each commit message should be prefixed using that bugzilla ID, i.e., [<bugzilla-id>].<br />
# All code comments should be well-formed, grammatically-complete English sentences, e.g., they should start with an uppercase word and end with a period.<br />
# All code should follow generally accepted [http://java.about.com/od/javasyntax/a/nameconventions.htm Java naming conventions].<br />
# All code should use the automatically enforced formatting rules so new projects are generally best created via the "Oomph->Copy Project" context menu action for an existing project.<br />
<br />
== Getting the source ==<br />
<br />
To provision the same development environment that the Oomph developers use follow these simple steps:<br />
<br />
# Download and start Oomph's [[Eclipse Installer]].<br />
# Drag [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/configurations/OomphConfiguration.setup this link] and drop it on the installer's title area. Alternatively, copy the location of the previous link and apply it to the Eclipse Installer either via the menu in the upper right in simple mode or via the left-most toolbar button to the upper right in advanced mode.<br />
# Review and/or edit the variable values that the installer presents.<br />
# Click the Next/Finish buttons until the installation starts.<br />
<br />
== Contributing via Gerrit ==<br />
<br />
Please refer to [[Gerrit]].<br />
<br />
== Building ==<br />
<br />
cd org.eclipse.oomph<br />
mvn -e clean verify -DskipTests=true<br />
<br />
<br />
== Where to find build artifacts ==<br />
E.g. Linux 64 bit installer build is located under:<br />
org.eclipse.oomph/products/org.eclipse.oomph.setup.installer.product/target/products/org.eclipse.oomph.setup.installer.product/linux/gtk/x86_64<br />
<br />
The update site for the installer is located under:<br />
org.eclipse.oomph/products/org.eclipse.oomph.setup.installer.product/target/repository<br />
<br />
The update site for the oompf plugins is located under:<br />
org.eclipse.oomph/sites/org.eclipse.oomph.site/target/repository</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=CDO_Source_Installation&diff=422360CDO Source Installation2018-02-02T10:08:08Z<p>Stepper.esc-net.de: </p>
<hr />
<div>To provision the same development environment that the CDO developers use follow these simple steps:<br />
<br />
# Download and start the [[Eclipse Installer]].<br />
# Drag [https://git.eclipse.org/c/cdo/cdo.git/plain/releng/org.eclipse.emf.cdo.releng/CDOConfiguration.setup this link] and drop it on the installer's title area. Alternatively, copy the location of the previous link and apply it to the Eclipse Installer either via the menu in the upper right in simple mode or via the left-most toolbar button to the upper right in advanced mode.<br />
# Review and/or edit the variable values that the installer presents.<br />
# Click the Next/Finish buttons until the installation starts.<br />
<br />
<br />
You can update your development workspace by pulling the latest updates into your CDO Git clone and selecting the '''Perform Setup Tasks...''' action in the '''Help''' menu.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=CDO_Source_Installation&diff=422359CDO Source Installation2018-02-02T10:04:38Z<p>Stepper.esc-net.de: </p>
<hr />
<div>To provision the same development environment that the CDO developers use follow these simple steps:<br />
<br />
# Download and start the [[Eclipse Installer]].<br />
# Drag [http://git.eclipse.org/c/cdo/cdo.git/plain/releng/org.eclipse.emf.cdo.releng/CDOConfiguration.setup this link] and drop it on the installer's title area. Alternatively, copy the location of the previous link and apply it to the Eclipse Installer either via the menu in the upper right in simple mode or via the left-most toolbar button to the upper right in advanced mode.<br />
# Review and/or edit the variable values that the installer presents.<br />
# Click the Next/Finish buttons until the installation starts.<br />
<br />
<br />
You can update your development workspace by pulling the latest updates into your CDO Git clone and selecting the '''Perform Setup Tasks...''' action in the '''Help''' menu.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Oomph_Contribution_Guide&diff=422358Oomph Contribution Guide2018-02-02T09:47:23Z<p>Stepper.esc-net.de: /* Getting the source */</p>
<hr />
<div>If you wish to contribute to Oomph, please obtain an [http://wiki.eclipse.org/Gerrit#User_Account Eclipse Gerrit account] and provision your Oomph setup to use a Gerrit clone. Then you'll be able to commit your contribution to Gerrit for review. You'll also need an [https://dev.eclipse.org/site_login/createaccount.php Eclipse account] for bugzilla access and to post to the [[Eclipse_Oomph_Installer#Getting_in_Touch|forums]].<br />
<br />
Here are some simple rules to follow for contributing to Oomph:<br />
# All contributions should correspond to a [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0 bug report] or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0&bug_severity=enhancement feature request] and each commit message should be prefixed using that bugzilla ID, i.e., [<bugzilla-id>].<br />
# All code comments should be well-formed, grammatically-complete English sentences, e.g., they should start with an uppercase word and end with a period.<br />
# All code should follow generally accepted [http://java.about.com/od/javasyntax/a/nameconventions.htm Java naming conventions].<br />
# All code should use the automatically enforced formatting rules so new projects are generally best created via the "Oomph->Copy Project" context menu action for an existing project.<br />
<br />
== Getting the source ==<br />
<br />
To provision the same development environment that the Oomph developers use follow these simple steps:<br />
<br />
# Download and start Oomph's [[Eclipse Installer]].<br />
# Drag [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/configurations/OomphConfiguration.setup this link] and drop it on the installer's title area. Alternatively, copy the location of the previous link and apply it to the Eclipse Installer either via the menu in the upper right in simple mode or via the left-most toolbar button to the upper right in advanced mode.<br />
# Review and/or edit the variable values that the installer presents.<br />
# Click the Next/Finish buttons until the installation starts.<br />
<br />
== Building ==<br />
<br />
cd org.eclipse.oomph<br />
mvn -e clean verify -DskipTests=true<br />
<br />
<br />
== Where to find build artifacts ==<br />
E.g. Linux 64 bit installer build is located under:<br />
org.eclipse.oomph/products/org.eclipse.oomph.setup.installer.product/target/products/org.eclipse.oomph.setup.installer.product/linux/gtk/x86_64<br />
<br />
The update site for the installer is located under:<br />
org.eclipse.oomph/products/org.eclipse.oomph.setup.installer.product/target/repository<br />
<br />
The update site for the oompf plugins is located under:<br />
org.eclipse.oomph/sites/org.eclipse.oomph.site/target/repository</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Architecture_Council/Meetings/January_11_2018&diff=421607Architecture Council/Meetings/January 11 20182018-01-11T17:35:22Z<p>Stepper.esc-net.de: /* Attendees */</p>
<hr />
<div>{| cellspacing="0" cellpadding="4" border="1"<br />
|-<br />
| Meeting Title: <br />
| '''Architecture Council Monthly Meeting'''<br />
|-<br />
| Date &amp; Time: <br />
| Thursday [[January 11, 2017]] at [http://www.timeanddate.com/worldclock/fixedtime.html?msg=Eclipse+AC+Montly+Meeting&iso=20180111T11&p1=188&ah=1 1100 Ottawa] <br>[[Image:Html.gif]][http://www.google.com/calendar/embed?src=g30r6idsq3rsufe2j3t6k0l0g4%40group.calendar.google.com&ctz=Canada/Toronto HTML] &#124; [[Image:Ical.gif]][http://www.google.com/calendar/ical/g30r6idsq3rsufe2j3t6k0l0g4%40group.calendar.google.com/public/basic.ics iCal]<br />
|-<br />
| Dial in:<br />
|Join from PC, Mac, Linux, iOS or Android: https://eclipse.zoom.us/j/438487984<br />
<br />
Or iPhone one-tap :<br />
US: +16699006833,,438487984# or +14086380968,,438487984# <br />
Or Telephone:<br />
Dial(for higher quality, dial a number based on your current location):<br />
US: +1 669 900 6833 or +1 408 638 0968 or +1 646 876 9923 <br />
Canada: +1 647 558 0588 <br />
France: +33 (0) 1 8288 0188 <br />
Germany: +49 (0) 30 3080 6188 <br />
United Kingdom: +44 (0) 20 3695 0088 <br />
Switzerland: +41 (0) 31 528 0988 <br />
Sweden: +46 (0) 8 4468 2488 <br />
Denmark: +45 89 88 37 88 <br />
Netherlands: +31 (0) 20 241 0288 <br />
Meeting ID: 438 487 984<br />
International numbers available: https://eclipse.zoom.us/zoomconference?m=zZBWgLOe1JIIW8E3tapxg4jzZNmjTfbO<br />
|}<br />
<br />
== Attendees ==<br />
<br />
* '''In attendance:''' Stephan Herrmann, Jonas Helming, Martin Lippert, Mélanie Bats, Dani Megert, Michael Scharf, Maximilian Kögel, Alex Kurtakov, Denis Roy.<br />
<br />
* '''Regrets:''' Eike Stepper, Jay Jay Billings, Doug Schaefer, Mickael Istria, Krum Tsvetkov, Gunnar Wagenknecht, Torkild Resheim.<br />
<br />
* '''No-Show:''' Alexander Nyßen, Mikael Barbero, Wayne Beaton, Martin O, Carl Anderson, Max Andersen, Matthias Sohn, Chris Aniszczyk, John Arthorne, Nick Boldt, Marcel Bruch, Ian Bull, Benjamin Cabé, Christian Campo, Linda Chan, Naci Dai, Sebastien Gerard, Neil Hauge, Jim Hughes, Kenn Hussey, Tyler Jewell, Markus Knauer, Konstantin Kommissarchik, Benoit Langlois, Ed Merks, Mike Milinkovich, Tracy Miranda, Adrian Mos, Steffen Pingel, Pascal Rapicault, Tom Schindl, Julien Vermillard, Lars Vogel, Gunnar Wagenknecht, Tom Watson, Mike Wilson<br />
<br />
[[#PMC_Rep_Attendees]] see also below.<br />
<br />
== Agenda / Notes ==<br />
<br />
* Feel free to edit, but '''<font color="red">not during the call!</font>'''<br />
* Last meeting: [[Architecture Council/Meetings/December 14 2017]] -- open actions see [[#Action_Items]]<br />
<br />
<br />
=== General Notes ===<br />
* Denis agreed to run the meeting, gather and publish notes<br />
<br />
<br />
=== Stephan: Publishing to Maven Central ===<br />
* Stephan created a bug against AC for this issue<br />
** Not much feedback received yet<br />
<br />
<br />
=== Stephan: CBI Aggregator and its Future ===<br />
* Stephan created a bug to AC <br />
* Stephan is offering to assist in working on this if the community steps up<br />
<br />
=== Wayne: Mentors needed for EE4J ===<br />
* Denis reminded everyone that Wayne always needs mentors<br />
<br />
=== Dani: AC Chair moving forward ===<br />
* The AC still does not have a chair, and someone needs to step up.<br />
** '''Action''': Denis to post to the AC mailing list<br />
<br />
== Action Items ==<br />
<br />
*No new action items.<br />
<!--<br />
*Cleaned up old action items, see [[Architecture Council/Meetings/February 10 2011]] for old stuff <br />
*(''old'') '''Tim''' write up an initial wiki page with information for people to standardize on the tracing API <br />
*(''old'') '''Martin''' revise the AC Wiki to make it easier to find the New Member Process. More links on homepage. More usage of categories. <br />
*(''old'') '''Martin''' {{bug|315210}} Make the AC mailing list open / moderated<br />
--><br />
<br />
== PMC Rep Attendees ==<br />
<br />
All [[Architecture Council/Members and Mentors|AC Members]] are invited.<br />
<br />
*'''PMC Reps''' please confirm attendance or list your delegate below. Every PMC is required to name a primary and backup delegate, and to ensure that one delegate attends the meeting.<br />
<br />
{| cellspacing="0" cellpadding="1" border="1"<br />
|-<br />
| '''BIRT:''' <br />
| <strike>Gary Xue</strike><br />
| <br />
|-<br />
| '''DTP:''' <br />
| <strike>Brian Payton</strike><br />
| <strike>Linda Chan</strike><br />
|-<br />
| '''Eclipse:''' <br />
| Dani Megert<br />
| <strike>Mike Wilson</strike><br />
|-<br />
| '''Modeling:''' <br />
| <strike>Ed Merks</strike><br />
| <strike>Mélanie Bats</strike><br><strike>Eike Stepper</strike><br />
|-<br />
| '''Mylyn:''' <br />
| <strike>Steffen Pingel</strike><br />
| <strike>Mik Kersten</strike><br />
|-<br />
| '''RT:''' <br />
| <strike>Christian Campo</strike><br />
| <strike>Tom Watson</strike><br />
|-<br />
| '''SOA:''' <br />
| <strike>Adrian Mos</strike><br />
| <strike>Marc Dutoo</strike><br />
|-<br />
| '''Technology:''' <br />
| Gunnar Wagenknecht<br />
| Wayne Beaton<br />
|-<br />
| '''Tools:''' <br />
| <strike>Doug Schaefer</strike><br />
| <strike>Alex Kurtakov</strike><br />
|-<br />
| '''WTP:''' <br />
| <strike>Carl Anderson</strike><br />
| <strike>Neil Hauge</strike><br />
|-<br />
| '''LocationTech:'''<br />
| <strike>Jim Hughes</strike><br />
|<br />
|-<br />
| '''IoT:'''<br />
| <strike>Julien Vermillard</strike><br />
|<br />
|}<br />
<br />
== Next Meeting ==<br />
<br />
* [[Architecture Council/Meetings/February 8 2018]]<br />
<br />
[[Category:Architecture_Council_Meeting_Minutes]]</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Architecture_Council/Meetings/August_10_2017&diff=418933Architecture Council/Meetings/August 10 20172017-08-11T18:34:38Z<p>Stepper.esc-net.de: /* Attendees */</p>
<hr />
<div>{| cellspacing="0" cellpadding="4" border="1"<br />
|-<br />
| Meeting Title: <br />
| '''Architecture Council Monthly Meeting'''<br />
|-<br />
| Date &amp; Time: <br />
| Thursday [[August 10, 2017]] at [http://www.timeanddate.com/worldclock/fixedtime.html?msg=Eclipse+AC+Montly+Meeting&iso=20170810T11&p1=188&ah=1 1100 Ottawa] <br>[[Image:Html.gif]][http://www.google.com/calendar/embed?src=g30r6idsq3rsufe2j3t6k0l0g4%40group.calendar.google.com&ctz=Canada/Toronto HTML] &#124; [[Image:Ical.gif]][http://www.google.com/calendar/ical/g30r6idsq3rsufe2j3t6k0l0g4%40group.calendar.google.com/public/basic.ics iCal]<br />
|}<br />
<br />
== Attendees ==<br />
<br />
* '''In attendance:''' Carl Anderson, Mikael Barbero, Maximilian Kögel, Alex Kurtakov, Martin Lippert, Dani Megert, Martin O, Torkild Resheim, Doug Schaefer<br />
* '''Regrets:''' Christian Campo, Jonas Helming, Jim Hughes, Mickael Istria, Alexander Nyßen, Matthias Sohn, Eike Stepper, Krum Tsvetkov, Gunnar Wagenknecht<br />
<br />
<!--<br />
* '''In attendance:''' Mikael Barbero, Jay Jay Billings, Marcel Bruch, Jonas Helming, Mickael Istria, Maximilian Kögel, Martin Lippert, Dani Megert, Ed Merks, Tracy Miranda, Martin O, Torkild Resheim, Denis Roy, Doug Schaefer, Michael Scharf, Krum Tsvetkov<br />
* '''Regrets:''' Jim Hughes, Matthias Sohn, Eike Stepper<br />
* '''No-Show:''' Carl Anderson, Max Andersen, Chris Aniszczyk, John Arthorne, Wayne Beaton, Nick Boldt, Cédric Brun, Ian Bull, Benjamin Cabé, Christian Campo, Linda Chan, Naci Dai, Sebastien Gerard, Neil Hauge, Kenn Hussey, Tyler Jewell, Markus Knauer, Konstantin Kommissarchik, Alex Kurtakov, Benoit Langlois, Mike Milinkovich, Adrian Mos, Alexander Nyßen, Steffen Pingel, Pascal Rapicault, Tom Schindl, Julien Vermillard, Lars Vogel, Gunnar Wagenknecht, Tom Watson, Mike Wilson<br />
--><br />
<br />
[[#PMC_Rep_Attendees]] see also below.<br />
<br />
== Agenda / Notes ==<br />
<br />
* Last meeting: [[Architecture Council/Meetings/July 13 2017]] -- open actions see [[#Action_Items]]<br />
<br />
* Mikael: Status on migrating '''Platform SWT Windows build to Foundation servers''' ?<br />
** Dani: Not yet ready for broader discussion, there's license compliance issues and more.<br />
<br />
* Martin: Infrastructure issues with '''Eclipse Asterisk unstable'''<br />
** Eclipse PMC had been hit by this recently, others currently not affected <br />
<br />
* Maximilian: '''Eclipse p2 target platform resolution unstable'''<br />
** For his teams, target platform resolution still often fails due to Eclipse.org servers unavailable<br />
** Seems no problem in North America, but hitting people in Europe<br />
*** Currently considering a local mirror of "everything" and redirecting p2 to that, perhaps via artifactory<br />
*** But the team is very distributed, so would prefer a mirroring service over that - still researching;<br />
*** Do others see this issue? Workarounds?<br />
** Torkild: Also seeing this problem all the time!<br />
*** Solution: Bash script creates a target_platform ZIP file that they use; updating only a couple times per year<br />
** Doug: Updating the Target Platform every night, and resolving locally - still seeing mirroring failures sometimes<br />
** '''ACTION''' Maximilian to create bugzilla for broader discussion of solution ideas / workarounds<br />
<br />
* MartinL: '''Any final decision on shipping Java9''' ?<br />
** Carl: Planning Council decided on Oxygen.1 first, then shipping Oxygen.1a 2 weeks later -- see https://wiki.eclipse.org/Planning_Council/August_2_2017#Discussion for details<br />
<br />
<!--<br />
=== General Topics ===<br />
<br />
== Action Items ==<br />
<br />
*No new action items.<br />
*Cleaned up old action items, see [[Architecture Council/Meetings/February 10 2011]] for old stuff <br />
*(''old'') '''Tim''' write up an initial wiki page with information for people to standardize on the tracing API <br />
*(''old'') '''Martin''' revise the AC Wiki to make it easier to find the New Member Process. More links on homepage. More usage of categories. <br />
*(''old'') '''Martin''' {{bug|315210}} Make the AC mailing list open / moderated<br />
<br />
--><br />
<br />
== PMC Rep Attendees ==<br />
<br />
All [[Architecture Council/Members and Mentors|AC Members]] are invited.<br />
<br />
*'''PMC Reps''' please confirm attendance or list your delegate below. Every PMC is required to name a primary and backup delegate, and to ensure that one delegate attends the meeting.<br />
<br />
{| cellspacing="0" cellpadding="1" border="1"<br />
|-<br />
| '''BIRT:''' <br />
| <strike>Gary Xue</strike><br />
| <br />
|-<br />
| '''DTP:''' <br />
| <strike>Brian Payton</strike><br />
| <strike>Linda Chan</strike><br />
|-<br />
| '''Eclipse:''' <br />
| Dani Megert<br />
| <strike>Mike Wilson</strike><br />
|-<br />
| '''Modeling:''' <br />
| <strike>Ed Merks</strike><br />
| <strike>Cédric Brun</strike><br><strike>Eike Stepper</strike><br />
|-<br />
| '''Mylyn:''' <br />
| <strike>Steffen Pingel</strike><br />
| <strike>Mik Kersten</strike><br />
|-<br />
| '''RT:''' <br />
| <strike>Christian Campo</strike><br />
| <strike>Tom Watson</strike><br />
|-<br />
| '''SOA:''' <br />
| <strike>Adrian Mos</strike><br />
| <strike>Marc Dutoo</strike><br />
|-<br />
| '''Technology:''' <br />
| <strike>Gunnar Wagenknecht</strike><br />
| <strike>Wayne Beaton</strike><br />
|-<br />
| '''Tools:''' <br />
| Doug Schaefer<br />
| Alex Kurtakov<br />
|-<br />
| '''WTP:''' <br />
| Carl Anderson<br />
| <strike>Neil Hauge</strike><br />
|-<br />
| '''LocationTech:'''<br />
| <strike>Jim Hughes</strike><br />
|<br />
|-<br />
| '''IoT:'''<br />
| <strike>Julien Vermillard</strike><br />
|<br />
|}<br />
<br />
== Next Meeting ==<br />
<br />
* [[Architecture Council/Meetings/September 14 2017]]<br />
<br />
[[Category:Architecture_Council_Meeting_Minutes]]</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Oomph_Authoring&diff=417019Eclipse Oomph Authoring2017-05-18T16:49:08Z<p>Stepper.esc-net.de: /* Configuration Options for Installer .ini File */</p>
<hr />
<div>== Getting Started ==<br />
<br />
=== What is Oomph? ===<br />
<br />
Please read [[Eclipse Installer]].<br />
<br />
<br />
=== Installing Oomph ===<br />
<br />
# Download and install the Eclipse '''Installer''' as outlined in [[Eclipse Installer]].<br />
# Make sure that the Oomph setup '''SDK''' is installed in your IDE. Either:<br />
## That's already the case because your IDE is a Mars M5 or later Eclipse Package, or<br />
## Start the installer and install an IDE of your choice (select on the first installer page), or<br />
## Use p2 to install "Oomph Setup SDK" from [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest].<br />
<br />
== Creating a Setup Project Model ==<br />
<br />
=== Using the Setup Project Model Wizard ===<br />
<br />
# Create an empty project in your workspace or select a folder in an existing project. You'll create the new "Setup Project Model" in the selected folder.<br />
# Open the New... dialog and select the "Setup Project Model" wizard:<br>[[Image:new-wizard.png]]<br><br />
# Select one of the provided templates (e.g., Eclipse.org, Github.com, or Simple) and adjust the displayed values:<br>[[Image:new-wizard-2.png]]<br><br />
# Some values are automatically derived from your input to fields '''higher up'''.<br />
# Open the Preview>>> to understand the impact of changes to the current field.<br />
<br />
=== Using the Setup Editor ===<br />
<br />
# Open the resulting setup file with Oomph's Setup Editor:<br>[[Image:setup-edit.png]]<br><br />
# Configure the tasks in the Properties view. Note that there are "Expert" properties available.<br />
# Add setup tasks to your project and/or to your project streams and configure them, too.<br />
# The Outline view displays a ''preview'' of the executable model with resolved variables.<br />
<br />
=== Testing the Setup Model ===<br />
<br />
# To test/execute your new setup model:<br />
## Start the installer and, if necessary, switch to the Advanced Mode via the dialog menu.<br />
## Pick any product on page 1 and click the Next button to proceed to page 2.<br />
## Drag and drop your <tt>.setup</tt> file onto one of the top-level catalogs (<tt>Eclipse.org</tt> or <tt>Github.com</tt>) in the projects tree. Your project will appear as a subproject of the special <tt>&lt;User&gt;</tt> project.<br />
## Double-click your project to add it to the table at the 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.<br />
## Fill in the empty fields and press the Next button to proceed to the Confirmation page.<br />
## 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.<br><br />
# 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 [[#Using the Setup Editor|Using the Setup Editor]]. If the IDE comes up but the initial configuration fails continue with step 3.<br />
# In the new IDE (whether the initial configuration was successful or not) open your model file from the main menu, Navigate &rarr; Open Setup &rarr; [[Image:branch.png]]. Find the problems and fix them. Then start the setup process '''from within''' this IDE via the main menu, Help &rarr; [[Image:update.png]] Perform Setup Tasks&hellip;. 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.<br />
<br />
=== Contributing to a Project Catalog ===<br />
<br />
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 http://git.eclipse.org/c] and [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&bug_severity=enhancement&short_desc=Please%20include%20setup%20for%20project%20Xyz 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.<br />
<br />
The same can be done if your project is not an Eclipse project, but hosted on '''GitHub'''. Simply state this fact in the bug description and paste the "raw" content URL to the file instead.<br />
<br />
== Understanding the Setup Engine ==<br />
<br />
=== Understanding Setup Tasks and Scopes ===<br />
<br />
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:<br />
<br />
* The '''Installation''' scope is located in <tt>eclipse/configuration/org.eclipse.oomph.setup/installation.setup</tt> 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.<br />
<br />
* The '''Workspace''' scope is located in <tt>workspace/.metadata/.plugins/org.eclipse.oomph.setup/workspace.setup</tt> 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.<br />
<br />
* The '''User''' scope is located in <tt>user.home/.eclipse/org.eclipse.oomph.setup/setups/user.setup</tt> and contains tasks that are common to '''all''' installations and workspaces (unless they're restricted to particular installations or workspaces).<br />
<br />
<br />
The following additional scope types exist, so they can be referenced by the entry scopes:<br />
<br />
* The '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.setup Catalog Index]''' is the root scope and contains nested Product Catalogs and Project Catalogs.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.products.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/OomphInstaller.setup Product]''' contains nested Product Version scopes and possibly some tasks that are common to all nested scopes.<br />
<br />
* A '''Product Version''' contains no nested scopes but tasks that are specific to that product version.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/org.eclipse.projects.setup 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.<br />
<br />
* A '''[http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/setups/Oomph.setup Project]''' contains nested Stream and/or (Sub-) Project scopes and typically some tasks that are common to all nested scopes.<br />
<br />
* A '''Stream''' contains no nested scopes but tasks that are specific to that stream.<br />
<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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 [[#Declaring_and_Using_Variables|Declaring and Using Variables]] below.<br />
<br />
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). <br />
<br />
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.<br />
<br />
=== Declaring and Using Variables ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
You can use variables (refer to them) in any String-typed or URI-typed attribute of your model. The general syntax is:<br />
<br />
${''variable-name''}<br />
<br />
To prevent a variable reference from being expanded (e.g. you actually want to have the value '${var}' and not the value of "var"), you need to escape the variable syntax with an extra double dollar character. So "$${var}" will result in "${var}".<br />
<br />
In addition to the variables that are declared by VariableTasks you can refer to all of the following:<br />
<br />
* Attribute values of setup tasks with a defined ID. The reference syntax is ${''taskID''.''attributeName''}.<br />
* System properties as returned by <tt>System.getProperties()</tt><br />
* [[#Environment Variables|Environment variables]] as returned by <tt>System.getenv()</tt><br />
* [[#Predefined Variables|Predefined variables]] as determined by the setup engine from the user input to the installer (see below)<br />
<br />
==== Predefined Variables ====<br />
<br />
The following variables are predefined by the setup engine:<br />
<br />
{| class="wikitable"<br />
| '''scope.installation.name''' || The value of the <em>name</em> attribute of the current installation scope. <br />
|-<br />
| '''scope.installation.label''' || The value of the <em>label</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.installation.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.workspace.name''' || The value of the <em>name</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.label''' || The value of the <em>label</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.workspace.description''' || The value of the <em>description</em> attribute of the current workspace scope.<br />
|-<br />
| '''scope.user.name''' || The value of the <em>name</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.label''' || The value of the <em>label</em> attribute of the current user scope.<br />
|-<br />
| '''scope.user.description''' || The value of the <em>description</em> attribute of the current user scope.<br />
|-<br />
| '''scope.product.catalog.name''' || The value of the <em>name</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.label''' || The value of the <em>label</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.catalog.description''' || The value of the <em>description</em> attribute of the current product catalog scope.<br />
|-<br />
| '''scope.product.name''' || The value of the <em>name</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product scope and its parent scopes.<br />
|-<br />
| '''scope.product.label''' || The value of the <em>label</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.description''' || The value of the <em>description</em> attribute of the current product scope.<br />
|-<br />
| '''scope.product.version.name''' || The value of the <em>name</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current product version scope and its parent scopes.<br />
|-<br />
| '''scope.product.version.label''' || The value of the <em>label</em> attribute of the current product version scope.<br />
|-<br />
| '''scope.product.version.description''' || The value of the <em>description</em> attribute of the current installation scope.<br />
|-<br />
| '''scope.project.catalog.name''' || The value of the <em>name</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.label''' || The value of the <em>label</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.catalog.description''' || The value of the <em>description</em> attribute of the current project catalog scope.<br />
|-<br />
| '''scope.project.name''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current project scope and its parent scopes.<br />
|-<br />
| '''scope.project.label''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.description''' || The value of the <em>name</em> attribute of the current project scope.<br />
|-<br />
| '''scope.project.stream.name''' || The value of the <em>name</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.name.qualified''' || The concatenated value of the <em>name</em> attributes of the current stream scope and its parent scopes.<br />
|-<br />
| '''scope.project.stream.label''' || The value of the <em>label</em> attribute of the current stream scope.<br />
|-<br />
| '''scope.project.stream.description''' || The value of the <em>description</em> attribute of the current stream scope.<br />
|}<br />
<br />
<br />
==== Variable Extensions ====<br />
<br />
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.:<br />
<br />
${installation.location/git/myproject} evaluates to C:\develop\installation1\git\myproject on Windows<br />
<br />
<br />
After the path extension part you can add filter calls with pipe symbols. Filter names are generally case-insensitive. Multiple filters can be chained. Example:<br />
<br />
${installation.location|uri}/git/myproject evaluates to file:/C:/develop/installation1/git/myproject<br />
<br />
<br />
==== Variable Filters ====<br />
<br />
The following filters are currently available:<br />
<br />
{| class="wikitable"<br />
| '''file''' || Converts a file: URI to an OS-specific file system path.<br />
|-<br />
| '''fileExtension''' || Extracts the file extension from a URI or a file system path.<br />
|-<br />
| '''path''' || Extracts the path segments from a URI.<br />
|-<br />
| '''basePath''' || Removes the last segment from a file system path.<br />
|-<br />
| '''lastSegment''' || Extracts the last segment from a file system path.<br />
|-<br />
| '''uri''' || Converts a file system path to a file: URI.<br />
|-<br />
| '''uriLastSegment''' || Extracts the last path segment from a hierarchical URI or the authority from an opaque URI.<br />
|-<br />
| '''canonical''' || Canonicalizes a file system path.<br />
|-<br />
| '''gitRepository''' || Extracts the name of the repository from a Git URI (excluding a possible .git suffix).<br />
|-<br />
| '''upper''' || Converts all characters of a String value to upper-case.<br />
|-<br />
| '''lower''' || Converts all characters of a String value to lower-case.<br />
|-<br />
| '''cap''' || Capitalizes the first word of a String value.<br />
|-<br />
| '''allCap''' || Capitalizes all words of a String value.<br />
|-<br />
| '''camel''' || Converts a qualified name to camel case notation.<br />
|-<br />
| '''qualifiedName''' || Converts a camel case String value name to a qualified name.<br />
|-<br />
| '''preferenceNode''' || Escapes all forward slashes (/) of a String value, so that the result can be used as a value in preference nodes.<br />
|-<br />
| '''property''' || Escapes all double back slashes (\\) of a String value, so that the result can be used as a value in properties.<br />
|-<br />
| '''propertyValue''' || Interprets the String value as a preference property path and returns the value of that property.<br />
|-<br />
| '''username''' || Escapes all "at" symbols (@) of a String value, so that the result can be used in URI that contain a username.<br />
|-<br />
| '''length''' || Converts a String to a String that contains the alpha-numerical representation of the length of the original String.<br />
|-<br />
| '''trim''' || Removes all whitespace from the beginning and the end of a String.<br />
|-<br />
| '''trimLeft''' || Removes all whitespace from the beginning of a String.<br />
|-<br />
| '''trimRight''' || Removes all whitespace from the end of a String.<br />
|-<br />
| '''trimTrailingSlashes''' || Removes all slashes and backslashes from the end of a String.<br />
|}<br />
<br />
==== Variables from Outer Scopes====<br />
<br />
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:<br />
<br />
* '''jre.location-1.4''' --> The folder containing a 1.4 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.5''' --> The folder containing a 1.5 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.6''' --> The folder containing a 1.6 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.7''' --> The folder containing a 1.7 compatible JDK/JRE for architecture ${os.arch}<br />
* '''jre.location-1.8''' --> The folder containing a 1.8 compatible JDK/JRE for architecture ${os.arch}<br />
* '''git.user.id''' --> The Eclipse user ID for Git/Gerrit commits<br />
* '''git.author.name''' --> The Eclipse author name for Git/Gerrit commits<br />
* '''git.author.email''' --> The Eclipse author email for Git/Gerrit commits<br />
* '''bugzilla.id''' --> The Eclipse user ID for Bugzilla/Hudson<br />
* '''eclipse.user.password''' --> The Eclipse password for Bugzilla/Hudson<br />
<br />
<br />
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.<br />
<br />
==== Environment Variables ====<br />
<br />
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.<br />
<br />
=== Conditional Tasks ===<br />
<br />
All setup tasks support filters. Oomph reuses [https://wiki.eclipse.org/Equinox_P2_Resolution#Enablement_filter p2's implementation] of LDAP filters. I.e., it supports a string a representation of LDAP Search Filters, RFC 1960, UMich, 1996,<br />
http://www.ietf.org/rfc/rfc1960.txt<br />
<br />
The filter property of a setup task is an advanced property. To display this property, ensure that the "Show Advanced Properties" is enabled in the Properties view tool bar. The properties of a filter expression can generally refer to any system property or any environment variable. For example, the following filter expression on a task will ensure that it is included only when performing a task on a Linux operating system.<br />
<br />
(osgi.os=linux)<br />
<br />
The latest version of Oomph allows filter properties to refer to the values of variables as defined in the setup itself. For example, this idiom can be used to express if-then-else.<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xmi:XMI xmi:version="2.0"<br />
xmlns:xmi="<nowiki>http://www.omg.org/XMI</nowiki>"<br />
xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"<br />
xmlns:setup="<nowiki>http://www.eclipse.org/oomph/setup/1.0</nowiki>"><br />
<setup:VariableTask<br />
type="BOOLEAN"<br />
name="example.filter"<br />
label="Example Filter"><br />
<description>An example of a variable used to conditionally filter tasks</description><br />
</setup:VariableTask><br />
<setup:CompoundTask<br />
filter="(example.filter=true)"<br />
name="Filter True"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.a"<br />
label="Property A"><br />
<description>The value use for system.property.a</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.a"<br />
value="=${example.variable.a}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is true</description><br />
</setup:CompoundTask><br />
<setup:CompoundTask<br />
filter="(example.filter=false)"<br />
name="Filter False"><br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="example.variable.b"<br />
label="Property B"><br />
<description>The value used for system.property.b</description><br />
</setupTask><br />
<setupTask<br />
xsi:type="setup:EclipseIniTask"<br />
option="-Dsystem.property.b"<br />
value="=${example.variable.b}"<br />
vm="true"/><br />
<description>Tasks that will be present only when example.filter is false.</description><br />
</setup:CompoundTask><br />
</xmi:XMI><br />
<br />
On the Variables page of the setup wizards, any variable that is used in property of a filter will be displayed in bold. It is significant to note that the value of a so-called filter variable can conditionally affect the presence of other variables. In this example, either variable <code>example.variable.a</code> or <code>example.variable.b</code> (but not both) will be present on the Variables page, depending on the value of the <code>example.filter</code> variable, which is displayed as a checkbox because it is of type <code>BOOLEAN</code>.<br />
<br />
Note that Oomph setup editors support textual copy and paste, so you can copy the above XML and paste it into your setup editor to try it out.<br />
<br />
== Automation and Specialization with Configurations ==<br />
<br />
As of Oomph 1.6, released with Neon.2, there is support for Configurations. A Configuration is not a Scope (is not a container for setup tasks) but rather a container for an Installation and a Workspace; each is optional, but a Configuration with neither is in effect useless. The Installation and Workspace of a Configuration are effectively used as a template to initialize the Installation and Workspace created by the Eclipse Installer, i.e., the setup resources that you can open with Navigate &rarr; Open Setup &rarr; Installation and Navigate &rarr; Open Setup &rarr; Workspace in your IDE. So you can specialize the installation with additional installation-specific tasks, e.g., a p2 task to install additional features, and you can specialize the workspace with workspace-specific tasks, e.g., a variable task to specify the value of a variable so you won't be prompted for that value. <br />
<br />
Configurations are not only useful for specifying installation-specific and workspace-specific tasks but also for automating the selection process in the setup wizards, including the installer. The Configuration's Installation can reference a specific Product Version and the Configuration's Workspace can optionally reference several specific Project Streams. Both the simple mode and the advanced mode of the installer support dragging and dropping a Configuration to the title area. You can drag to the title area either a file (i.e., a file from the file system or from an Eclipse IDE), a URL (i.e., a link from a browser), or a copy of a Configuration's XMI serialization. This will '''apply''' the Configuration to the wizard with the effect that the Installation's Product Version is selected in the wizard and the wizard advances to the next page. Similarly, the Workspace's Project Streams are selected in the wizard and the wizard advances to the next page. If you apply a Configuration with a Workspace to the simple mode of the installer, you will be prompted to switch to advanced mode because only the advanced mode supports Project selection. So in simple mode, applying a Configuration advances to the final page, and in advanced mode, applying a Configuration with an Installation and a Workspace advances to the Variables page.<br />
<br />
As an alternative to drag and drop support, rather than dragging a file, link, or XMI serialization, you can copy it to the clipboard and apply the clipboard contents to the wizard. In simple mode this is done via the Apply Configuration menu item. In advanced mode this is done via the Apply Configuration toolbar button on the Product or Project page; the menu item or toolbar item is visible only if the clipboard contains applicable content.<br />
<br />
The installer application supports command line arguments so you could also specify a Configuration's file path or URL link on the command line to apply it automatically.<br />
<br />
=== Creating a Configuration ===<br />
<br />
The simplest way to create a new Configuration is from the context menu of the folder where want to locate the resource to contain it. From the context menu, use New &rarr; Other... and then locate Oomph &rarr; Setup Configuration Model in the wizard. You can then edit the new Configuration with the Setup Editor. You can delete the Installation or Workspace if you don't need that aspect. You can use the Properties view to set the Installation's Product Version or the Workspace's Project Streams. And of course you can create any other setup tasks in either Scope.<br />
<br />
=== Configuration Handling ===<br />
<br />
The specific form of the serialized URLs that are used to reference a Product Version or a Project Stream are very important to correct behavior. Relative URLs in the serialization can only work relative to the location of the Configuration's resource, so will only work when you drag and drop a file or link because a dragging and dropping textual copy of the serialization provides no information about how to resolve relative references. This is not to say there is anything wrong with relative references, just be aware that they imply that the user must apply the overall file or link, not just the textual serialization. <br />
<br />
Another very useful aspect of Configurations is that the wizards handle of the references intelligently. I.e., if a Installation references a Product Version that's not in any Product Catalog in the Index, the Product will automatically be added to the user-extensible Product Catalog. If the Installation references a Product Version via its containing Product Catalog and that Product Catalog is not in the Index, and the redirectable Product Catalog is not already redirected, it will be redirected to the referenced Product Catalog and an appropriate Eclipse Ini redirection tasks will be synthesized so that the installation produced by the installer will be able to resolve the Product Version reference in its Installation via the correct containing Product Catalog. Analogous processing is done for the Project Stream references with the additional processing of Project's a logical Project container which determines which Project Catalog's extensible Project container is used. In other words, Configurations can also be used to automate the addition of Products and Projects to the user extensible catalogs.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Getting Early Feedback ===<br />
Why didn't the model editor tell me earlier that I've made a silly mistake?<br />
Please enable Live Validation in the editor menu to get early feedback.<br />
<br />
=== Copying Tasks and Other Elements ===<br />
The Setup Editor supports the export and import of any model elements by using copy to or paste from the clipboard. The clipboard will/must contain a valid XML document. With this method, for example, you can easily copy task snippets from your model directly into a forum post when you ask for help (or into a Skype window when you chat with your collegues). Or you can easily paste such XML snippets from forum replies directly into your Setup Editor.<br />
<br />
You have access to many example setups from within your IDE! Use Navigate->Open Setup->Parent Models->Open Catalog Index to investigate everything within the index. The context menu provides a way to open elements in a text editor. This is particularly handy for finding out where a particular setup is hosted (hrefs are resolved in the Setup editor) - one use case is checking and repairing links to project setups added to your user projects.<br />
<br />
=== Hosting your own index / catalogs ===<br />
If you want to host your own product or project catalog, you must provide a URI mapping to the installer to locate the root setup file (the "index"). Open the eclipse.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, or use the wizard to create it. 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/. You can redirect to your own index with this redirection system property:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->http://<hostname>/<path>/</nowiki><br />
<br />
The source URI may be abbreviated to <nowiki>index:/</nowiki> and the target URI may also be a file URI, e.g. on a shared file server.<br />
<br />
In general it will be highly desirable to archive your setup, but documentation for that is TBD. The installer and other setup wizards support dragging and dropping an index or archived index onto the title area of the dialog. Documentation for that is also TBD.<br />
<br />
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=481580 Bug 481580] has introduced empty redirectable catalogs for products ('''redirectable.products.setup''') and projects ('''redirectable.projects.setup''') to the Oomph index. These allow providing your own catalogs without replacing the entire index or disabling the catalogs shipped with Oomph (by redirecting them). The following steps are necessary to make use of those setups.<br />
* Create your own project catalog setup file using the wizard. Project setups in the project catalog should typically be referenced using absolute URIs, otherwise redirection can become problematic. However, if the relative references are downward pointing to some uniquely named folder different from any of the file/folder names in the Eclipse.org index, i.e., no '''..''' traversal to the parent folder is involved and some folder name '''<my-projects-folder>''', then they will be resolved to absolute URIs of the form '''index:/<my-projects-folder>/<path>''' which can be handled as described below.<br />
* Add a redirection system property similar to that described above to the eclipse.ini file, e.g., '''-Doomph.redirection.myProjectCatalog=index:/redirectable.projects.setup->...'''.<br />
* If the projects in that catalog are referenced by relative downward references with a unique folder, also add a folder redirection system property, e.g.,'''-Doomph.redirection.myProjectCatalog=index:/<my-projects-folder>/->.../''', to redirect the locations of the referenced projects to the folder where they are physically hosted.<br />
* Your catalog setup file must contain an Eclipse Ini task creating the same redirection(s)! Otherwise your catalog (or the referenced projects) will not be visible in the Eclipse created by the installer and hence the projects selected from it cannot be provisioned.<br />
* The first time, you may have to enable your new catalog by selecting it in the folders icon of the drop-down in the upper right hand corner of the wizard's Projects page, otherwise it will be invisible.<br />
<br />
To debug the processing of -Doomph.redirection.* if needed, set a breakpoint in org.eclipse.oomph.setup.internal.core.util.SetupCoreUtil.configureResourceSet(ResourceSet) within if (((String)key).startsWith(SetupProperties.PROP_REDIRECTION_BASE)).<br />
<br />
=== Shipping your own index ===<br />
If you want to include your own product or project catalog, you may ship the root setup file (the "index") relative to the installer directory. Then you can redirect the index as explained in [[#Hosting your own index / catalogs| Hosting your own index / catalogs]]. For example, you can place all setup files in an eclipse-installer/setups/ folder and then redirect access to it with a relative target URI:<br />
<br />
-Doomph.redirection.setups=<nowiki>http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/->setups/</nowiki><br />
<br />
Note that shipping the index rather than maintaining it in a central location (accessible to all parties interested) has the following disadvantage. As each user has her own copy of the index, updates in the setup files will not be distributed automatically.<br />
<br />
=== Generating PDE Target Definition files (*.target) and their use by Tycho ===<br />
<br />
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. <br />
<br />
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:<br />
<br />
<annotation<br />
source="http:/www.eclipse.org/oomph/targlets/TargetDefinitionGenerator"><br />
<detail<br />
key="location"><br />
<value>${git.clone.location}/targetdefinition/DesignStudio.target</value><br />
</detail><br />
<detail<br />
key="extraUnits"><br />
<value>org.eclipse.equinox.executable.feature.group</value><br />
</detail><br />
<detail<br />
key="includeAllPlatforms"><br />
<value>false</value><br />
</detail><br />
<detail<br />
key="includeSource"><br />
<value>true</value><br />
</detail><br />
<detail<br />
key="generateVersions"><br />
<value>true</value><br />
</detail><br />
</annotation><br />
<br />
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.<br />
<br />
''TODO Document what preferredRepositories, PomModulesUpdater & PomArtifactUpdater do...''<br />
<br />
=== Setting up WST Server Runtime and Instances in your Project Setup ===<br />
<br />
==== Server Runtime Preference ====<br />
<br />
1. Use an oomphed installation/workspace with preference recorder enabled.<br />
<br />
2. Open your project and user setup editors.<br />
<br />
3. Go to Preferences / Server / Runtime Environments and 'Add' it as usual.<br />
<br />
4. Drag the selected '/instance/org.eclipse.wst.server.core/runtimes' from user to project setup.<br />
<br />
==== Server Instance in Servers View ====<br />
Requires server runtime to be setup first.<br />
<br />
1. Open Servers View and create New server instance and deploy webapps as usual<br />
<br />
2. Optionally open server instance editor and adapt configuration as usual.<br />
<br />
3. Close Eclipse.<br />
<br />
4. Start it again.<br />
<br />
5. Open '.plugins/org.eclipse.wst.server.core/servers.xml' from your workspace/.metadata using a UTF capable editor<br />
<br />
6. Add Resource Creation Task to your project setup:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
content="PUT_CONTENT_FROM_SERVERS_XML_INTO_HERE_USING_A_UTF_CAPABLE_EDITOR_AND_OOMPH_DIALOG"<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.wst.server.core/servers.xml"<br />
encoding="UTF-8"><br />
<description>tomcat server integration</description><br />
</setup:ResourceCreationTask><br />
<br />
7. Use the resource task content dialog to put the servers xml content into the task.<br />
<br />
8. Copy "Servers" project from this workspace into a suitable location of your branch checkout and add/commit/push.<br />
<br />
9. Setup project import task that can pick the Servers project up from that committed location.<br />
<br />
That's it. If you want to share it among fellows, be sure to agree on canonical paths for your server installations.<br />
<br />
=== Suppress prompt for default workspace already upon very first start ===<br />
<br />
Adjust the SHOW_WORKSPACE_SELECTION_DIALOG property to false via configuration settings org.eclipse.ui.ide.prefs ...<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:ResourceCreationTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP MANUAL"<br />
content="MAX_RECENT_WORKSPACES=5&amp;#xD;&amp;#xA;RECENT_WORKSPACES=${workspace.location|property}&amp;#xD;&amp;#xA;RECENT_WORKSPACES_PROTOCOL=3&amp;#xD;&amp;#xA;SHOW_WORKSPACE_SELECTION_DIALOG=false&amp;#xD;&amp;#xA;eclipse.preferences.version=1"<br />
targetURL="configuration:/.settings/org.eclipse.ui.ide.prefs"<br />
encoding="UTF-8"/><br />
<br />
=== Open default perspective already upon very first start ===<br />
Examples below using Perspective ID for Java perspective.<br />
<br />
Tell Eclipse which perspective to open initially, by adding option to eclipse ini:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:EclipseIniTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
excludedTriggers="STARTUP"<br />
option="-perspective"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
Setting a perspective to be default, by adding preference task:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<setup:PreferenceTask<br />
xmi:version="2.0"<br />
xmlns:xmi="http://www.omg.org/XMI"<br />
xmlns:setup="http://www.eclipse.org/oomph/setup/1.0"<br />
key="/instance/org.eclipse.ui/defaultPerspectiveId"<br />
value="org.eclipse.jdt.ui.JavaPerspective"/><br />
<br />
=== How to switch the current stream ===<br />
<br />
If you would like to switch the current stream/s, you can re-use Oomph's initial "Eclipse Importer" wizard, available as "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace.<br />
<br />
Note that it is currently not yet possible to remove the "current" project stream. As a workaround, use menu Navigate > Open Setup > Open Workspace (or if visible click the 'blue guy' icon in the Oomph toolbar) to Open Workspace workspace.setup, expand the first node, click on the Workspace entry, open Properties view, and change the last property named "Streams" and remove the current stream.<br />
<br />
Bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=476434 enhancement may make this easier in the future.<br />
<br />
<br />
=== How to install Eclipse plugins using the P2 Director and Repository Explorer ===<br />
<br />
Oomph can install Eclipse plugins which you require. This also works for normal Java Projects set up models, not just for Eclipse plug in OSGi development, and is handy to install commonly used 3rd-party Eclipse plugins which are not all available from eclipse.org p2 sites (think e.g. http://eclemma.org). Here's how:<br />
<br />
1. add a P2 Director child task to your *.setup, if it doesn't already have one<br />
<br />
2. add a Repository child in your P2 Director task<br />
<br />
3. in the Properties of the Repository set the URL to a valid p2 repo (e.g. http://update.eclemma.org)<br />
<br />
4. right-click that Repository and choose Explore, to open the Repository Explorer view<br />
<br />
5. in the Repository Explorer view change to [X] Compatible and (*) Minor at the lower-right hand corner<br />
<br />
6. drag & drop the version from the Repository Explorer view into the P2 Director task of your *.setup editor, to create a Requirement child<br />
<br />
Drag & Drop should normally work, but appears to be broken at least on Neon Milestone 6 on Linux; in that case:<br />
<br />
6. manually create a new child Requirement inside the P2 Director task<br />
<br />
7. in the Repository Explorer view use the brown (C) icon to switch to Expert Mode to see IDs instead of names<br />
<br />
8. find the ID of the feature IU, it's the one with a PDE feature + folder kind of icon, often ending in (feature.)feature.group<br />
<br />
9. in the Properties of the Requirement, type the Name to the ID found above (e.g. com.mountainminds.eclemma.feature.feature.group)<br />
<br />
10. in the Properties of the Requirement, Type should have automatically switched to Feature<br />
<br />
PS: If you are looking for the URL of p2 repos to pre-install some of the the M2E connectors, see https://git.eclipse.org/c/m2e/m2e-discovery-catalog.git/tree/org.eclipse.m2e.discovery.oss/connectors.xml<br />
<br />
<br />
<br />
=== How to create M2E lifecycle-mapping-metadata.xml to avoid littering your pom.xml with org.eclipse.m2e:lifecycle-mapping ===<br />
<br />
Read https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html & https://wiki.eclipse.org/M2E_compatible_maven_plugins and apply as follows:<br />
<br />
<setupTask<br />
xsi:type="setup:PreferenceTask"<br />
key="/instance/org.eclipse.m2e.core/eclipse.m2.WorkspacelifecycleMappingsLocation"<br />
value="${workspace.location}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"/><br />
<br />
<setupTask<br />
xsi:type="setup:ResourceCreationTask"<br />
content="..."<br />
targetURL="${workspace.location|uri}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml"<br />
encoding="UTF-8"><br />
<description>Initialize M2E's Maven Lifecycle Mappings, see https://www.eclipse.org/m2e/documentation/m2e-execution-not-covered.html &amp; https://wiki.eclipse.org/M2E_compatible_maven_plugins</description><br />
</setupTask><br />
<br />
For "content" just open the popup using the [...] icon in the Properties and copy/paste the content from menu Window > Preferences > Maven > Lifecycle Mappings: Open workspace lifecycle mappings metadata. (This is easier than editing the content=".." in source view, because it will correctly do the XML escaping for you.)<br />
<br />
Now whenever M2E whines about stuff like "Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-dependency-plugin:2.10:unpack (execution: unpack-license, phase: generate-resources)" etc. just use the Quick Fix in the Problems view and choose the option to use workspace preferences (instead of letting the quick fix modify your pom.xml to add org.eclipse.m2e:lifecycle-mapping <lifecycleMappingMetadata>).<br />
<br />
<br />
=== How to automatically pre-enable Gerrit ===<br />
<br />
If you would like to save your end-users from having to [[EGit/User_Guide#Enabling_Gerrit_for_a_repository|manually enabling Gerrit for a repository in EGit]], then you can use the follow magic variable which Oomph will recognize and act upon:<br />
<br />
<setupTask<br />
xsi:type="setup:VariableTask"<br />
name="YOURORG.gerrit.uri.pattern"<br />
value="(https|ssh)://([^@/]+@)?(git.YOURORG.org:29418/.*|git.YOURORG.org/gerrit/.*)"/><br />
<br />
=== How to find a P2 repository at Eclipse using the Repository Explorer ===<br />
<br />
Most projects don't document the locations of all their p2 update sites very well. This makes it hard to find the URL you need in order to install something or in order to specify a URL for your target platform definition. Oomph indexes all the p2 update sites available at download.eclipse.org to make this job easier. You can make use of this as follows:<br />
<br />
# In the Quick Access control, type "Repository Explorer" to show Oomph's Repository Explorer view.<br />
# In that view's toolbar, locate the tool item with the hover "Search Eclipse repositories by provided capabilities", i.e., the one that looks like a little search flashlight, and click it.<br />
# This brings up the "Eclipse Repository Search" dialog. The index is very large so it takes a while to load it. But it's cached locally and updated on the server once per day.<br />
# At the root of the displayed tree are p2's namespaces and under each of these are the capabilities in that namespace. They're organized hierarchically by their qualified name. It's all quite technical and the tree is very large. So while you can explore it, you'll most likely want to use the filter to find something quickly.<br />
# Type the fully qualified name of a Java package or installable unit you wish to locate into the filter. Note that tree items for which there exist a concrete version in some repository are decorated as such. Keep in mind that many projects don't version their Java packages, so it's often better to look at the org.eclipse.equinox.p2.iu category. Here's what it looks like searching for "org.eclipse.emf.ecore.xcore":<br>[[File:SearchEclipseRepositoryDialog.png]]<br><br />
# You can select a capability in the tree so that the lower panel displays all the versions of the capability that are available. Under each of those are nested the update sites that contain them. Composite update sites show their children hierarchically.<br />
# Of course you can double click a repository to further explore its contents in the Repository Explorer itself.<br />
<br />
<br />
=== How to extract the constituent parts that comprise the Windows self-extracting installer executable ===<br />
<br />
The Eclipse Installer distribution for the Windows platform is effectively a self-extracting executable. It is extracted at runtime by the [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINExtractor.java Bin Extractor]. The pre-built version of this library, i.e., org.eclipse.oomph.extractor.lib-*.jar, is available in all Oomph-containing installations, i.e., in the installer itself and in applications installed by the installer. This library can also be used standalone to decompose the composed executable into its constituent parts. That can be accomplished if you run it with the correct magical program arguments as follows:<br />
<br />
java -classpath <path-to-extract-lib>\org.eclipse.oomph.extractor.lib-*.jar<br />
org.eclipse.oomph.extractor.lib.BINExtractor <br />
<path-to-executable-to-extract>\eclipse-inst-win64.exe <br />
<target-path>\product.zip <br />
-export <br />
<target-path>\marker.txt <br />
<target-path>\extractor.exe <br />
<target-path>\org.eclipse.oomph.extractor.lib.jar <br />
<target-path>\product-descriptor<br />
<br />
The Java VM arguments need only specify the extractor library along with the main class in that library. The first program argument is the location of the executable you wish to decompose, the 64 bit installer in this case. The remaining arguments are all best directed into a common folder, denoted as <target-path> in the example above. The second argument is the extracted location of the zip file of the product/distribution. The third argument is the -export flag. The fourth argument is the extracted location of the text file containing the marker text that is used to delimit the constituent parts of the composed executable. The fifth argument is the extracted location of the small native executable itself. The sixth argument is the extracted location of the extractor library, the same one being used to extract the parts. The seventh and final argument is the extracted location of the product descriptor. Such a [http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/tree/plugins/org.eclipse.oomph.extractor.lib/src/org/eclipse/oomph/extractor/lib/BINDescriptor.java descriptor] looks like this:<br />
<br />
1<br />
1<br />
7<br />
0<br />
64<br />
0<br />
eclipse-inst.exe<br />
eclipse-inst.ini<br />
Eclipse Installer<br />
http://wiki.eclipse.org/Eclipse_Installer<br />
http://download.eclipse.org/oomph/jre/128x128.png<br />
<br />
Of course you can edit these parts and then you can recompose the executable using the following bash script executed within the common folder in which you have extracted the constituent parts:<br />
<br />
COPY /B extractor.exe + ^<br />
marker.txt + ^<br />
extractorlib.jar + ^<br />
marker.txt + ^<br />
product-descriptor + ^<br />
marker.txt + ^<br />
product.zip + ^<br />
marker.txt ^<br />
eclipse-inst-64.exe<br />
<br />
Note that the file names match the extracted target file names. From this is should be clear that the native executable is just a composition of parts. This structure is used at runtime as follows. The extractor.exe runs natively, reading its own executable file, using the marker text to find the parts. It checks the descriptor to determine if an appropriate version of Java is already installed, i.e., one that will be able to launch the product; the native extractor consults the registry to find all installed JREs and JVMs. If an appropriate Java is not found, it opens a browser page prompting the user to install an appropriate Java version with the required bitness and at the minimum required version. If there is already an appropriate version of Java, it launches a Java process to execute the BinExtract's main method. That process in turn unzips the product zip to a temp folder and launches the Java process for that for the product/distribution.<br />
<br />
== Oomph Configuration Options ==<br />
<br />
=== Configuration Options for Installer .ini File ===<br />
<br />
{| class="wikitable"<br />
| '''-Doomph.redirection.setups''' || Redirects the location of setup files (index, catalog and products). The default URI is ''http://git.eclipse.org/c/oomph/org.eclipse.oomph.git/plain/setups/'' and my be abbreviated with '''index:/'''. The syntax of the redirection is '''index:/->[redirection URI]'''. Examples: '''-Doomph.redirection.setups=index:/->http://<hostname>/<path>/''' (external server redirection) or '''-Doomph.redirection.setups=index:/->setups/''' (path relative to installer executable). See also [[#Hosting_your_own_index_.2F_catalogs|Hosting your own index & catalogs]]<br />
|-<br />
| '''-Doomph.setup.product.catalog.filter''' || Only displays product catalogs matching the given prefix. The default is ''org\\.eclipse\\.products''. Displays all catalogs if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.filter''' || Only displays products matching the given prefix. The default is ''(?\!org\\.eclipse\\.products\\.org\\.eclipse\\.platform\\.ide).*''. Displays all products if value is empty.<br />
|-<br />
| '''-Doomph.setup.product.version.filter''' || Only displays product versions matching the given prefix. The default is ''.*\\.neon''. Displays all product versions if value is empty.<br />
|-<br />
| '''-Doomph.p2.pool''' || Set to ''@none'' to disable bundle pools. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=507594] for details.<br />
|}</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=CDO/MongoDB_Store&diff=416454CDO/MongoDB Store2017-05-10T06:50:43Z<p>Stepper.esc-net.de: </p>
<hr />
<div>The CDO MongoDB store is an implementation of a CDO Store that allows to store models and meta models to [http://www.mongodb.org/ MongoDB] databases.<br />
<br />
The current implementation has been developed and tested with MongoDB 1.6.5. It supports all [http://www.eclipse.org/cdo/documentation/relnotes_40/relnotes-4.0.html CDO 4.0] features with the following exceptions:<br />
<br />
* NoExternalReferences (hence no meta references)<br />
* NoQueryXRefs (hence no ensureReferentialIntegrity)<br />
* NoLargeObjects<br />
* NoFeatureMaps<br />
* NoHandleRevisions (hence no OCL support)<br />
* NoRawAccess (hence no offline support)<br />
* NoBranching<br />
* NoCrashRecovery<br />
<br />
Due to the lack of transactionality in MongoDB CDO's MongoDB store is implemented as a ''delta store''. This means that a single CDO commit with all its change deltas is stored in a single MongoDB document. It may result in unexpected DB size and performance characteristics, e.g., the DB never shrinks (all history is kept) and write access is faster than read access (the state of a single object is assembled from the changes of multiple commit documents).<br />
<br />
The remainder of this document will help users setup their environment and configure CDO to work with MongoDB.<br />
<br />
== Database Server ==<br />
<br />
Windows Example:<br />
<br />
C:\Programs\MongoDB\bin\mongod.exe --dbpath "C:\develop\ws\cdo\databases\specificDB" --noauth --rest<br />
<br />
== Driver Bundle ==<br />
<br />
The MongoDB driver bundle that is shipped with CDO is '''not identical''' to the one that is originally distributed via [http://www.mongodb.com mongodb.com]. The [http://dev.eclipse.org/svnroot/modeling/org.eclipse.emf.cdo/trunk/plugins/com.mongodb/src/org/bson/io/UTF8Encoding.java UTF-8 conversion class] had to be replaced by a version that uses the JRE mechanism to fulfill the legal requirements of the Eclipse Foundation. Performance degradation or misbehaviour may result. It is highly recommended that you download and deploy the original version of the MongoDB driver via<br />
[http://www.mongodb.org/display/DOCS/Java+Language+Center MongoDB Java Language Center].<br />
<br />
== cdo-server.xml ==<br />
<br />
The <code>type</code> identifier of the [[CDO/Server Configuration Reference#Element_store|store configuration]] is <code>"mongodb"</code>:<br />
<br />
<store type="mongodb"><br />
<property name="uri" value="mongodb://localhost"/><br />
<property name="db" value="specificDB"/><br />
<property name="drop" value="false"/><br />
</store><br />
<br />
The <code>"db"</code> property is optional. If omitted, the repository name is used as MongoDB database name.<br />
<br />
The <code>"drop"</code> property is optional. If the value is <code>"true"</code> the MongoDB database is dropped before the store is activated.<br />
<br />
<br />
----<br />
Wikis: [[CDO]] | [[Net4j]] | [[EMF]] | [[Eclipse]]</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Installer&diff=413501Eclipse Installer2017-01-22T06:51:58Z<p>Stepper.esc-net.de: /* Update Sites */</p>
<hr />
<div>The Eclipse Installer, powered by [http://www.eclipse.org/oomph Oomph], automates the installation and update of Eclipse development environments:<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-win64.exe Windows 64 Bit] (self-extracting exe)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-win32.exe Windows 32 Bit] (self-extracting exe)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-mac64.tar.gz Mac OS 64 Bit] (tar.gz)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-linux64.tar.gz Linux 64 Bit] (tar.gz)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-linux32.tar.gz Linux 32 Bit] (tar.gz)<br />
<br />
<br />
To download the latest nightly build of the installer, pick one of [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-win64.exe Windows 64 Bit], [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-win32.exe Windows 32 Bit], [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-mac64.tar.gz Mac OS 64 Bit], [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-linux64.tar.gz Linux 64 Bit], or [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-linux32.tar.gz Linux 32 Bit].<br />
<br />
You can also install the Oomph runtime into an existing IDE from the latest [http://download.eclipse.org/oomph/updates/latest update site] or [http://www.eclipse.org/downloads/download.php?file=/oomph/updates/latest/org.eclipse.oomph.site.zip site archive]. See [[#Update Sites|update sites]] for more...<br />
<br />
Our [http://download.eclipse.org/oomph/help help center] is still work in progress but you may already find answers to your questions there.<br />
<br />
The installer is provided by the [http://www.eclipse.org/oomph Oomph] project. If you are in doubt about the project's name see what [http://www.thefreedictionary.com/oomph The Free Dictionary] says.<br />
<br />
<br />
<br />
== Features ==<br />
<br />
[[Image:OomphSimpleInstaller2.png]]<br />
<br />
<br />
Non-exhaustive list of features:<br />
<br />
* Provisioning correct set of plugins in the Eclipse IDE.<br />
* Binding Git repos (incl. personal Gerrit push URL).<br />
* Checking out projects.<br />
* Setting workspace preferences.<br />
* Configuring [[Dynamic Working Sets]].<br />
* Keeping project preferences files in sync.<br />
<br />
The configuration is model driven, with the possibility to customize a lot for each project, each branch, each user…<br />
<br />
== Update Sites ==<br />
<br />
We offer three types of drops: release, milestone, and nightly. They can be found in these composite repos:<br />
<br />
* [http://download.eclipse.org/oomph/updates/release http://download.eclipse.org/oomph/updates/release]<br />
* [http://download.eclipse.org/oomph/updates/milestone http://download.eclipse.org/oomph/updates/milestone]<br />
* [http://download.eclipse.org/oomph/updates/nightly http://download.eclipse.org/oomph/updates/nightly]<br />
<br />
<br />
The following is an uber composite of the three above composites:<br />
<br />
* [http://download.eclipse.org/oomph/updates http://download.eclipse.org/oomph/updates]<br />
<br />
<br />
For each of the four composite repos we offer a smaller variant that contains only the latest drop:<br />
<br />
* [http://download.eclipse.org/oomph/updates/release/latest http://download.eclipse.org/oomph/updates/release/latest] (contains only the latest release build)<br />
* [http://download.eclipse.org/oomph/updates/milestone/latest http://download.eclipse.org/oomph/updates/milestone/latest] (contains only the latest milestone build)<br />
* [http://download.eclipse.org/oomph/updates/nightly/latest http://download.eclipse.org/oomph/updates/nightly/latest] (contains only the latest nightly build)<br />
* [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest] (contains only the latest build)<br />
<br />
<br />
The single drops are individually available under '''http://download.eclipse.org/oomph/drops''' as follows:<br />
<br />
[[Image:OomphDrops.png]]<br />
<br />
Note that at most five nightly drops are kept and that milestone drops are only kept until shortly after the next release.<br />
<br />
== Authoring Setup Models ==<br />
<br />
Please read [[Eclipse Oomph Authoring|Oomph Authoring Guide]].<br />
<br />
<br />
== Frequently Asked Questions ==<br />
<br />
Please read the [[Eclipse Oomph FAQ|FAQ]] or revisit our [http://download.eclipse.org/oomph/help help center].<br />
<br />
<br />
== Getting in Touch ==<br />
<br />
First browse the [[Eclipse Oomph FAQ|FAQ]] to see if your question has already been answered.<br />
<br />
<br />
As a '''user''' you should post your questions and comments to the public forum:<br />
* Web: [http://www.eclipse.org/forums/eclipse.oomph http://www.eclipse.org/forums/eclipse.oomph]<br />
* Newsgroup: [news://news.eclipse.org:119/eclipse.oomph news://news.eclipse.org:119/eclipse.oomph]<br />
<br />
<br />
You can also monitor the '''developer''' mailing list or discuss development topics:<br />
* Archive: [https://dev.eclipse.org/mhonarc/lists/oomph-dev https://dev.eclipse.org/mhonarc/lists/oomph-dev]<br />
* Mail: [mailto:oomph-dev@eclipse.org mailto:oomph-dev@eclipse.org]<br />
* Newsgroup: [news://news.gmane.org:119/gmane.comp.ide.eclipse.oomph.devel news://news.gmane.org:119/gmane.comp.ide.eclipse.oomph.devel]<br />
<br />
<br />
If you encounter '''trouble''' or miss a '''feature''' please:<br />
* Search for [https://bugs.eclipse.org/bugs/buglist.cgi?classification=Tools&list_id=8268012&product=Oomph&query_format=advanced existing bugzillas] to avoid duplication.<br />
* You can [https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email watch] the <code>oomph-inbox@eclipse.org</code> user to be notified about new bugzillas.<br />
* If nothing else helps kindly submit a new [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0 bug report] or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0&bug_severity=enhancement feature request].<br />
<br />
<br />
== Contributing to Oomph ==<br />
<br />
Please read the [[Oomph Contribution Guide|Oomph Contributor Guide]].<br />
<br />
<br />
== Tutorials ==<br />
<br />
* [http://eclipsesource.com/blogs/tutorials/oomph-basic-tutorial/ Oomph Basic Tutorial] by Jonas Helming (December 2016)<br />
* [http://www.lorenzobettini.it/2015/10/oomph-setup-for-xtext-projects Oomph setup for Xtext projects] by Lorenzo Bettini (October 10th, 2015)<br />
* [https://www.youtube.com/watch?v=GRKhxroJsS8 The Eclipse Installer] by Martin Ambrus, a short presentation video of the Oomph-powered Eclipse Installer (August 2015)<br />
* [http://thecodingflow.com/?p=50 Create your own product] by Florian Thienel (July 5th, 2015)<br />
* [http://thegordian.blogspot.de/2015/06/oomph-workshop-eclipse-way-you-want-it.html Oomph Workshop: Eclipse the Way You Want It] by Eike Stepper (June 21st, 2015)<br />
* [http://www.lorenzobettini.it/2015/05/using-the-new-eclipse-installer Using the New Eclipse Installer] by Lorenzo Bettini (May 11th, 2015)<br />
* [http://github.com/joergreichert/oomph-catalogue Walk-Through with Many Examples] by Jörg Reichert (March 22nd, 2015)<br />
* [http://community.bonitasoft.com/blog/how-configure-mylyn-task-queries-atlassian-jira-connector-oomph-installer How to configure Mylyn Task Queries for an Atlassian JIRA Connector with Oomph Installer] by Aurelien Pupier (September, 2014)<br />
* [http://blogs.itemis.de/leipzig/archives/936 Quicker Start Guide for Oomph] by Philipp Hauer and Alexander Nittka (June 30th, 2014)<br />
* [http://www.winklerweb.net/index.php/blog/12-eclipse/20-creating-custom-installations-with-oomph Creating Custom Installations with Oomph] by Stefan Winkler (April 1st, 2014)<br />
<br />
== Articles ==<br />
<br />
* [http://eclipsesource.com/blogs/2015/06/24/top-10-eclipse-mars-features Top 10 Eclipse Mars Features] by Ian Bull (June 24th, 2015)<br />
* [http://blog2.vorburger.ch/2015/06/using-oomphs-bleeding-edge-nightly.html Using Oomph's bleeding edge nightly builds] by Michael Vorburger (June 2015)<br />
* [http://gradot.wordpress.com/2015/06/01/eclipse-installer-avec-oomph Eclipse Installer avec Oomph] by Pierre Gradot (June 1st, 2015)<br />
* [http://www.infoq.com/news/2015/03/eclipse-oomph Install Eclipse Projects with a lot more Oomph] by Alex Blewitt (March 21st, 2015)<br />
* [http://www.eclipse.org/community/eclipse_newsletter/2014/november/article2.php Oomph: A Matter of Preference] by Ed Merks (November 2014)<br />
* [http://www.eclipse.org/community/eclipse_newsletter/2014/may/article3.php Eclipse has Oomph] by Eike Stepper (May 2014)<br />
* [http://jaxenter.com/installer-tool-oomph-proposed-as-eclipse-project-107676.html Installer Tool Oomph Proposed as Eclipse Project] by Lucy Carey (March 31st, 2014)<br />
* [http://ed-merks.blogspot.fr/2014/02/shoes-for-shoemaker.html Shoes for the Shoemaker] by Ed Merks (February 14th, 2014)<br />
* [http://jaxenter.de/eclipse-oomph-bringt-schwung-ins-projekt-12977 Eclipse Oomph bringt Schwung ins Projekt] by Eike Stepper (June 26th, 2014)<br />
<br />
== Videos ==<br />
<br />
* [https://www.youtube.com/watch?v=TU1zjytlwFE OpenDaylight Mini Summit recording of an Oopmh related presentation (June 2016)] Slides from this session are also available [http://www.slideshare.net/mikervorburger/opendaylight-developers-experience-15-eclipse-setup-hot-reload-future-plans on slideshare (faster)] and [https://docs.google.com/presentation/d/14yLzog3OhIlVsk7Clr0Tff1YayRcFnQCUZqxHMWxiNI/ on GDocs in better quality]<br />
* [https://www.youtube.com/watch?v=BLW8aOh6WeQ OpenDaylight.org has Oomph, Eclipse.org Installer for automated workspace provisioning (April 2016)]<br />
* [http://www.youtube.com/watch?v=GRKhxroJsS8 The Eclipse Installer] a short presentation video of the Oomph-powered Eclipse Installer (August 2015)<br />
* [http://www.youtube.com/watch?v=a3h76AQQKN0 Oomph: Eclipse the Way You Want It] a speaker pitch video for the EclipseCon France (June 2015)<br />
* [http://www.infoq.com/interviews/eike-stepper-eclipse-oomph-project Interview with Eike Stepper on the Eclipse Oomph project] by Alex Blewitt (May 27th, 2015)<br />
* [http://www.infoq.com/presentations/oomph Oomph: Eclipse the Way You Want It] session recording and slides from the EclipseCon North America (May 21st, 2015)<br />
* [http://www.youtube.com/watch?v=M6ZnL2mO88Q Papyrus Oomph Model Refinements] by Christian Damus (July 8th, 2014)<br />
* [http://www.youtube.com/watch?v=hgKjzr2pXzI Provisioning a Papyrus Development IDE with Oomph] by Christian Damus (July 6th, 2014)<br />
* [http://www.youtube.com/watch?v=_QlSosecEUo&list=UUej18QqbZDxuYxyERPgs2Fw Oomph: Automatically Provision a Project-specific IDE] a video recording of the talk at the EclipseCon France (June 2014)</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=File:OomphDrops.png&diff=413500File:OomphDrops.png2017-01-22T06:51:27Z<p>Stepper.esc-net.de: </p>
<hr />
<div></div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Architecture_Council/Meetings/January_12_2017&diff=413386Architecture Council/Meetings/January 12 20172017-01-13T06:01:20Z<p>Stepper.esc-net.de: /* General Topics */</p>
<hr />
<div>{| cellspacing="0" cellpadding="4" border="1"<br />
|-<br />
| Meeting Title: <br />
| '''Architecture Council Monthly Meeting'''<br />
|-<br />
| Date &amp; Time: <br />
| Thursday [[January 12, 2017]] at [http://www.timeanddate.com/worldclock/fixedtime.html?msg=Eclipse+AC+Montly+Meeting&iso=20170112T11&p1=188&ah=1 1100 Ottawa] <br>[[Image:Html.gif]][http://www.google.com/calendar/embed?src=g30r6idsq3rsufe2j3t6k0l0g4%40group.calendar.google.com&ctz=Canada/Toronto HTML] &#124; [[Image:Ical.gif]][http://www.google.com/calendar/ical/g30r6idsq3rsufe2j3t6k0l0g4%40group.calendar.google.com/public/basic.ics iCal]<br />
|-<br />
| Dial-in: <br />
| See Eclipse [[Asterisk]] <br />
|}<br />
<br />
== Attendees ==<br />
<br />
* '''In attendance:''' Carl Andersen (WTP), Mikael Barbero, Wayne Beaton, Marcel Bruch, Jonas Helming, Jim Hughes, Marc-Andre Laperle, Dani Megert, Martin O, Denis Roy, Doug Schaefer, Michael Scharf, Matthias Sohn, Eike Stepper<br />
<br />
* '''Regrets:''' Jay Jay Billings, Christian Campo, Mickael Istria, Maximilian Kögel, Martin Lippert, Alexander Nyßen, Krum Tsvetkov, Lars Vogel<br />
<br />
* '''No-Show:''' Max Andersen, Chris Aniszczyk, John Arthorne, Nick Boldt, Cédric Brun, Ian Bull, Benjamin Cabé, Linda Chan, Naci Dai, Sebastien Gerard, Neil Hauge, Kenn Hussey, Tyler Jewell, Markus Knauer, Konstantin Kommissarchik, Alex Kurtakov, Benoit Langlois, Ed Merks, Mike Milinkovich, Adrian Mos, Steffen Pingel, Pascal Rapicault, Tom Schindl, Julien Vermillard, Gunnar Wagenknecht, Tom Watson, Mike Wilson<br />
<br />
[[#PMC_Rep_Attendees]] see also below.<br />
<br />
== Agenda / Notes ==<br />
<br />
* Feel free to edit, but '''<font color="red">not during the call!</font>'''<br />
* Last meeting: [[Architecture Council/Meetings/December 8 2016]] -- open actions see [[#Action_Items]]<br />
<br />
=== General Topics ===<br />
<br />
* '''Carl Andersen''' introduction<br />
** Been with IBM for a very long time, replacing Chuck Bridgham as WTP PMC Lead (and David Williams as Releng guy)<br />
<br />
* Denis: '''Simrel Build''' taken on by Frederic Gurr<br />
** Please support Frederic in this new role<br />
** Will shift some discussion on build mechanics from cross-project to the cbi-dev mailing list<br />
** Eclipse Platform build still done by Platform project (Sravan), Fred only does the aggregation<br />
<br />
* Marcel: '''New AC Members'''<br />
** '''AI Wayne''' nomination<br />
<br />
* Marcel: '''Next Iteration of FEEP'''<br />
** Mikael: received 6 bids in December, reviewing now, expect to present next week<br />
** Looking at Budget available, this is a good number, would love to have more but may not be able to fund all of them<br />
<br />
* Marcel/Mikael: '''Quality of the Eclipse Marketplace Plugins'''<br />
** Marcel reaching out to providers with Error Reporting; discussions with Ian<br />
** Mikael meeting Mike in Ottawa next week, will report on the outcome<br />
** Ed Merks is working on a tool to identify ''Invalid Solution Listings'', see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=509929 bug 509929] with first results<br />
<br />
=== Wayne: IP Due Diligence Changes ===<br />
* Wayne: '''New IP Due Diligence Changes'''<br />
** Wayne's writing some blogs now; would like to get pushed out by March - Type A or B due diligence<br />
** Type A just checks for license compatibility; goal is having this done by projects themselves (with help of tools like FOSSology, IP team helping out until tools are ready).<br />
*** Laid some groundwork for integration with IPZilla, eg monitor and drop reports there<br />
*** Hoping to get to full automation by end of the year<br />
*** Looking for incremental improvements as more and more projects adopt it<br />
** Type B: A plus provenance check<br />
*** Projects start with Type A in incubation - may switch to type B (or not) when graduating<br />
*** Projects can mix, eg multiple type A releases followed by a yearly type B release<br />
*** Picked a couple of projects already doing type A, rolling out en-large this quarter<br />
** Release process is a separate, related topic.<br />
<br />
=== Doug: Eclipse Two ===<br />
* Doug: '''Eclipse Two'''<br />
** See https://cdtdoug.ca/2016/12/31/looking-forward-to-2017/ experimenting with Electron<br />
** Busy with project stuff until March, exposing to the Community now and see where it goes<br />
** Looking at an IDE on Electron to go beyond VS Code which is just an editor<br />
** Trying to get hold of some trends in the industry before others do it (especially in the Eclipse and Embedded communities)<br />
*** Lightweight, not coupled to IResource; advanced visualizations and tools like TraceCompass, Android, Modeling...<br />
*** Qt has its own IDE, Adacore has its own, Andmore is dead ... time to try something new, but will only work if Community forms around it<br />
** Relationship to the ide-dev and ui guideline stuff ?<br />
*** Those are still classic Eclipse - same people, not really growing, thus tried something new ... all depends on where Community takes it<br />
*** MichaelS: As Eclipse insiders, we tend to question too much ... many users are still just happy getting work done with Eclipse. <br />
*** "Heavy" plugins inside Eclipse duplicate much. Using the VS Code architecture, the IDE becomes more replaceable for mix-and-match of components from various sources...<br />
*** Doug: Working on integrating live language server in CDT, likely based on libclang<br />
*** Michael: Could there be a universal data model for languages including type hierarchy ?<br />
*** Doug: LSP is an extensible protocol. It's going to grow into this.<br />
*** '''CONCLUSION''': Would work towards a virtual meet-up, but Doug has no time until March; until then, everything is on Github, feel free to join in<br />
<br />
<br />
<!--<br />
* Mickael I.: CI slaves being a bottleneck for Platform https://bugs.eclipse.org/bugs/show_bug.cgi?id=508507 , SLES vs CentOS https://bugs.eclipse.org/bugs/show_bug.cgi?id=506995<br />
* Mickael I.: Question: Do we have metrics/indicators about the effect of requiring mailing to post on Bugzilla? Specifically in the trend of 1st time reporters?<br />
<br />
* '''New AC Member candidates''' - see [[Architecture Council/Members and Mentors]], and the [http://www.eclipse.org/org/foundation/council.php#architecture Councils Page]<br />
** Tyler Jewell representing strategic member CodeEnvy<br />
** Eclipse Che vs. Platform discussion<br />
* '''Eclipse Infrastructure''' - git, Gerrit, Maven, Hudson, Bugzilla, ...<br />
* '''Updates from the Board or the EMO'''<br />
<br />
== Action Items ==<br />
<br />
*No new action items.<br />
*Cleaned up old action items, see [[Architecture Council/Meetings/February 10 2011]] for old stuff <br />
*(''old'') '''Tim''' write up an initial wiki page with information for people to standardize on the tracing API <br />
*(''old'') '''Martin''' revise the AC Wiki to make it easier to find the New Member Process. More links on homepage. More usage of categories. <br />
*(''old'') '''Martin''' {{bug|315210}} Make the AC mailing list open / moderated<br />
<br />
--><br />
<br />
== PMC Rep Attendees ==<br />
<br />
All [[Architecture Council/Members and Mentors|AC Members]] are invited.<br />
<br />
*'''PMC Reps''' please confirm attendance or list your delegate below. Every PMC is required to name a primary and backup delegate, and to ensure that one delegate attends the meeting.<br />
<br />
{| cellspacing="0" cellpadding="1" border="1"<br />
|-<br />
| '''BIRT:''' <br />
| <strike>Gary Xue</strike><br />
| <br />
|-<br />
| '''DTP:''' <br />
| <strike>Brian Payton</strike><br />
| <strike>Linda Chan</strike><br />
|-<br />
| '''Eclipse:''' <br />
| Dani Megert<br />
| <strike>Mike Wilson</strike><br />
|-<br />
| '''Modeling:''' <br />
| <strike>Ed Merks</strike><br />
| Eike Stepper<br />
|-<br />
| '''Mylyn:''' <br />
| <strike>Steffen Pingel</strike><br />
| <strike>Mik Kersten</strike><br />
|-<br />
| '''RT:''' <br />
| <strike>Christian Campo</strike><br />
| <strike>Tom Watson</strike><br />
|-<br />
| '''SOA:''' <br />
| <strike>Adrian Mos</strike><br />
| <strike>Marc Dutoo</strike><br />
|-<br />
| '''Technology:''' <br />
| <strike>Gunnar Wagenknecht</strike><br />
| Wayne Beaton<br />
|-<br />
| '''Tools:''' <br />
| Doug Schaefer<br />
| <strike>Alex Kurtakov</strike><br />
|-<br />
| '''WTP:''' <br />
| Carl Andersen<br />
| <strike>Neil Hauge</strike><br />
|-<br />
| '''LocationTech:'''<br />
| Jim Hughes<br />
|<br />
|-<br />
| '''IoT:'''<br />
| <strike>Julien Vermillard</strike><br />
|<br />
|}<br />
<br />
== Next Meeting ==<br />
<br />
* [[Architecture Council/Meetings/February 9 2017]]<br />
<br />
[[Category:Architecture_Council_Meeting_Minutes]]</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Installer&diff=413220Eclipse Installer2017-01-06T05:33:02Z<p>Stepper.esc-net.de: /* Update Sites */</p>
<hr />
<div>The Eclipse Installer, powered by [http://www.eclipse.org/oomph Oomph], automates the installation and update of Eclipse development environments:<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-win64.exe Windows 64 Bit] (self-extracting exe)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-win32.exe Windows 32 Bit] (self-extracting exe)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-mac64.tar.gz Mac OS 64 Bit] (tar.gz)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-linux64.tar.gz Linux 64 Bit] (tar.gz)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-linux32.tar.gz Linux 32 Bit] (tar.gz)<br />
<br />
<br />
To download the latest nightly build of the installer, pick one of [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-win64.exe Windows 64 Bit], [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-win32.exe Windows 32 Bit], [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-mac64.tar.gz Mac OS 64 Bit], [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-linux64.tar.gz Linux 64 Bit], or [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-linux32.tar.gz Linux 32 Bit].<br />
<br />
You can also install the Oomph runtime into an existing IDE from the latest [http://download.eclipse.org/oomph/updates/latest update site] or [http://www.eclipse.org/downloads/download.php?file=/oomph/updates/latest/org.eclipse.oomph.site.zip site archive]. See [[#Update Sites|update sites]] for more...<br />
<br />
Our [http://download.eclipse.org/oomph/help help center] is still work in progress but you may already find answers to your questions there.<br />
<br />
The installer is provided by the [http://www.eclipse.org/oomph Oomph] project. If you are in doubt about the project's name see what [http://www.thefreedictionary.com/oomph The Free Dictionary] says.<br />
<br />
<br />
<br />
== Features ==<br />
<br />
[[Image:OomphSimpleInstaller2.png]]<br />
<br />
<br />
Non-exhaustive list of features:<br />
<br />
* Provisioning correct set of plugins in the Eclipse IDE.<br />
* Binding Git repos (incl. personal Gerrit push URL).<br />
* Checking out projects.<br />
* Setting workspace preferences.<br />
* Configuring [[Dynamic Working Sets]].<br />
* Keeping project preferences files in sync.<br />
<br />
The configuration is model driven, with the possibility to customize a lot for each project, each branch, each user…<br />
<br />
== Update Sites ==<br />
<br />
We offer three types of drops: release, milestone, and nightly. They can be found in these composite repos:<br />
<br />
* [http://download.eclipse.org/oomph/updates/release http://download.eclipse.org/oomph/updates/release]<br />
* [http://download.eclipse.org/oomph/updates/milestone http://download.eclipse.org/oomph/updates/milestone]<br />
* [http://download.eclipse.org/oomph/updates/nightly http://download.eclipse.org/oomph/updates/nightly]<br />
<br />
<br />
The following is an uber composite of the three above composites:<br />
<br />
* [http://download.eclipse.org/oomph/updates http://download.eclipse.org/oomph/updates]<br />
<br />
<br />
For each of the four composite repos we offer a smaller variant that contains only the latest drop:<br />
<br />
* [http://download.eclipse.org/oomph/updates/release/latest http://download.eclipse.org/oomph/updates/release/latest] (contains only the latest release build)<br />
* [http://download.eclipse.org/oomph/updates/milestone/latest http://download.eclipse.org/oomph/updates/milestone/latest] (contains only the latest milestone build)<br />
* [http://download.eclipse.org/oomph/updates/nightly/latest http://download.eclipse.org/oomph/updates/nightly/latest] (contains only the latest nightly build)<br />
* [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest] (contains only the latest build)<br />
<br />
<br />
The single drops are individually available under '''http://download.eclipse.org/oomph/drops''' as follows:<br />
<br />
[[Image:OomphDrops.png]] (image not displayed because of [https://bugs.eclipse.org/bugs/show_bug.cgi?id=510012 bug 510012])<br />
<br />
Note that at most five nightly drops are kept and that milestone drops are only kept until shortly after the next release.<br />
<br />
== Authoring Setup Models ==<br />
<br />
Please read [[Eclipse Oomph Authoring|Oomph Authoring Guide]].<br />
<br />
<br />
== Frequently Asked Questions ==<br />
<br />
Please read the [[Eclipse Oomph FAQ|FAQ]] or revisit our [http://download.eclipse.org/oomph/help help center].<br />
<br />
<br />
== Getting in Touch ==<br />
<br />
First browse the [[Eclipse Oomph FAQ|FAQ]] to see if your question has already been answered.<br />
<br />
<br />
As a '''user''' you should post your questions and comments to the public forum:<br />
* Web: [http://www.eclipse.org/forums/eclipse.oomph http://www.eclipse.org/forums/eclipse.oomph]<br />
* Newsgroup: [news://news.eclipse.org:119/eclipse.oomph news://news.eclipse.org:119/eclipse.oomph]<br />
<br />
<br />
You can also monitor the '''developer''' mailing list or discuss development topics:<br />
* Archive: [https://dev.eclipse.org/mhonarc/lists/oomph-dev https://dev.eclipse.org/mhonarc/lists/oomph-dev]<br />
* Mail: [mailto:oomph-dev@eclipse.org mailto:oomph-dev@eclipse.org]<br />
* Newsgroup: [news://news.gmane.org:119/gmane.comp.ide.eclipse.oomph.devel news://news.gmane.org:119/gmane.comp.ide.eclipse.oomph.devel]<br />
<br />
<br />
If you encounter '''trouble''' or miss a '''feature''' please:<br />
* Search for [https://bugs.eclipse.org/bugs/buglist.cgi?classification=Tools&list_id=8268012&product=Oomph&query_format=advanced existing bugzillas] to avoid duplication.<br />
* You can [https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email watch] the <code>oomph-inbox@eclipse.org</code> user to be notified about new bugzillas.<br />
* If nothing else helps kindly submit a new [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0 bug report] or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0&bug_severity=enhancement feature request].<br />
<br />
<br />
== Contributing to Oomph ==<br />
<br />
Please read the [[Oomph Contribution Guide|Oomph Contributor Guide]].<br />
<br />
<br />
== Tutorials ==<br />
<br />
* [http://eclipsesource.com/blogs/tutorials/oomph-basic-tutorial/ Oomph Basic Tutorial] by Jonas Helming (December 2016)<br />
* [http://www.lorenzobettini.it/2015/10/oomph-setup-for-xtext-projects Oomph setup for Xtext projects] by Lorenzo Bettini (October 10th, 2015)<br />
* [https://www.youtube.com/watch?v=GRKhxroJsS8 The Eclipse Installer] by Martin Ambrus, a short presentation video of the Oomph-powered Eclipse Installer (August 2015)<br />
* [http://thecodingflow.com/?p=50 Create your own product] by Florian Thienel (July 5th, 2015)<br />
* [http://thegordian.blogspot.de/2015/06/oomph-workshop-eclipse-way-you-want-it.html Oomph Workshop: Eclipse the Way You Want It] by Eike Stepper (June 21st, 2015)<br />
* [http://www.lorenzobettini.it/2015/05/using-the-new-eclipse-installer Using the New Eclipse Installer] by Lorenzo Bettini (May 11th, 2015)<br />
* [http://github.com/joergreichert/oomph-catalogue Walk-Through with Many Examples] by Jörg Reichert (March 22nd, 2015)<br />
* [http://community.bonitasoft.com/blog/how-configure-mylyn-task-queries-atlassian-jira-connector-oomph-installer How to configure Mylyn Task Queries for an Atlassian JIRA Connector with Oomph Installer] by Aurelien Pupier (September, 2014)<br />
* [http://blogs.itemis.de/leipzig/archives/936 Quicker Start Guide for Oomph] by Philipp Hauer and Alexander Nittka (June 30th, 2014)<br />
* [http://www.winklerweb.net/index.php/blog/12-eclipse/20-creating-custom-installations-with-oomph Creating Custom Installations with Oomph] by Stefan Winkler (April 1st, 2014)<br />
<br />
== Articles ==<br />
<br />
* [http://eclipsesource.com/blogs/2015/06/24/top-10-eclipse-mars-features Top 10 Eclipse Mars Features] by Ian Bull (June 24th, 2015)<br />
* [http://blog2.vorburger.ch/2015/06/using-oomphs-bleeding-edge-nightly.html Using Oomph's bleeding edge nightly builds] by Michael Vorburger (June 2015)<br />
* [http://gradot.wordpress.com/2015/06/01/eclipse-installer-avec-oomph Eclipse Installer avec Oomph] by Pierre Gradot (June 1st, 2015)<br />
* [http://www.infoq.com/news/2015/03/eclipse-oomph Install Eclipse Projects with a lot more Oomph] by Alex Blewitt (March 21st, 2015)<br />
* [http://www.eclipse.org/community/eclipse_newsletter/2014/november/article2.php Oomph: A Matter of Preference] by Ed Merks (November 2014)<br />
* [http://www.eclipse.org/community/eclipse_newsletter/2014/may/article3.php Eclipse has Oomph] by Eike Stepper (May 2014)<br />
* [http://jaxenter.com/installer-tool-oomph-proposed-as-eclipse-project-107676.html Installer Tool Oomph Proposed as Eclipse Project] by Lucy Carey (March 31st, 2014)<br />
* [http://ed-merks.blogspot.fr/2014/02/shoes-for-shoemaker.html Shoes for the Shoemaker] by Ed Merks (February 14th, 2014)<br />
* [http://jaxenter.de/eclipse-oomph-bringt-schwung-ins-projekt-12977 Eclipse Oomph bringt Schwung ins Projekt] by Eike Stepper (June 26th, 2014)<br />
<br />
== Videos ==<br />
<br />
* [https://www.youtube.com/watch?v=TU1zjytlwFE OpenDaylight Mini Summit recording of an Oopmh related presentation (June 2016)] Slides from this session are also available [http://www.slideshare.net/mikervorburger/opendaylight-developers-experience-15-eclipse-setup-hot-reload-future-plans on slideshare (faster)] and [https://docs.google.com/presentation/d/14yLzog3OhIlVsk7Clr0Tff1YayRcFnQCUZqxHMWxiNI/ on GDocs in better quality]<br />
* [https://www.youtube.com/watch?v=BLW8aOh6WeQ OpenDaylight.org has Oomph, Eclipse.org Installer for automated workspace provisioning (April 2016)]<br />
* [http://www.youtube.com/watch?v=GRKhxroJsS8 The Eclipse Installer] a short presentation video of the Oomph-powered Eclipse Installer (August 2015)<br />
* [http://www.youtube.com/watch?v=a3h76AQQKN0 Oomph: Eclipse the Way You Want It] a speaker pitch video for the EclipseCon France (June 2015)<br />
* [http://www.infoq.com/interviews/eike-stepper-eclipse-oomph-project Interview with Eike Stepper on the Eclipse Oomph project] by Alex Blewitt (May 27th, 2015)<br />
* [http://www.infoq.com/presentations/oomph Oomph: Eclipse the Way You Want It] session recording and slides from the EclipseCon North America (May 21st, 2015)<br />
* [http://www.youtube.com/watch?v=M6ZnL2mO88Q Papyrus Oomph Model Refinements] by Christian Damus (July 8th, 2014)<br />
* [http://www.youtube.com/watch?v=hgKjzr2pXzI Provisioning a Papyrus Development IDE with Oomph] by Christian Damus (July 6th, 2014)<br />
* [http://www.youtube.com/watch?v=_QlSosecEUo&list=UUej18QqbZDxuYxyERPgs2Fw Oomph: Automatically Provision a Project-specific IDE] a video recording of the talk at the EclipseCon France (June 2014)</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=Eclipse_Installer&diff=413219Eclipse Installer2017-01-06T05:32:32Z<p>Stepper.esc-net.de: /* Update Sites */</p>
<hr />
<div>The Eclipse Installer, powered by [http://www.eclipse.org/oomph Oomph], automates the installation and update of Eclipse development environments:<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-win64.exe Windows 64 Bit] (self-extracting exe)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-win32.exe Windows 32 Bit] (self-extracting exe)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-mac64.tar.gz Mac OS 64 Bit] (tar.gz)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-linux64.tar.gz Linux 64 Bit] (tar.gz)<br />
<br />
* [http://www.eclipse.org/downloads/download.php?file=/oomph/products/eclipse-inst-linux32.tar.gz Linux 32 Bit] (tar.gz)<br />
<br />
<br />
To download the latest nightly build of the installer, pick one of [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-win64.exe Windows 64 Bit], [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-win32.exe Windows 32 Bit], [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-mac64.tar.gz Mac OS 64 Bit], [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-linux64.tar.gz Linux 64 Bit], or [http://www.eclipse.org/downloads/download.php?file=/oomph/products/latest/eclipse-inst-linux32.tar.gz Linux 32 Bit].<br />
<br />
You can also install the Oomph runtime into an existing IDE from the latest [http://download.eclipse.org/oomph/updates/latest update site] or [http://www.eclipse.org/downloads/download.php?file=/oomph/updates/latest/org.eclipse.oomph.site.zip site archive]. See [[#Update Sites|update sites]] for more...<br />
<br />
Our [http://download.eclipse.org/oomph/help help center] is still work in progress but you may already find answers to your questions there.<br />
<br />
The installer is provided by the [http://www.eclipse.org/oomph Oomph] project. If you are in doubt about the project's name see what [http://www.thefreedictionary.com/oomph The Free Dictionary] says.<br />
<br />
<br />
<br />
== Features ==<br />
<br />
[[Image:OomphSimpleInstaller2.png]]<br />
<br />
<br />
Non-exhaustive list of features:<br />
<br />
* Provisioning correct set of plugins in the Eclipse IDE.<br />
* Binding Git repos (incl. personal Gerrit push URL).<br />
* Checking out projects.<br />
* Setting workspace preferences.<br />
* Configuring [[Dynamic Working Sets]].<br />
* Keeping project preferences files in sync.<br />
<br />
The configuration is model driven, with the possibility to customize a lot for each project, each branch, each user…<br />
<br />
== Update Sites ==<br />
<br />
We offer three types of drops: release, milestone, and nightly. They can be found in these composite repos:<br />
<br />
* [http://download.eclipse.org/oomph/updates/release http://download.eclipse.org/oomph/updates/release]<br />
* [http://download.eclipse.org/oomph/updates/milestone http://download.eclipse.org/oomph/updates/milestone]<br />
* [http://download.eclipse.org/oomph/updates/nightly http://download.eclipse.org/oomph/updates/nightly]<br />
<br />
<br />
The following is an uber composite of the three above composites:<br />
<br />
* [http://download.eclipse.org/oomph/updates http://download.eclipse.org/oomph/updates]<br />
<br />
<br />
For each of the four composite repos we offer a smaller variant that contains only the latest drop:<br />
<br />
* [http://download.eclipse.org/oomph/updates/release/latest http://download.eclipse.org/oomph/updates/release/latest] (contains only the latest release build)<br />
* [http://download.eclipse.org/oomph/updates/milestone/latest http://download.eclipse.org/oomph/updates/milestone/latest] (contains only the latest milestone build)<br />
* [http://download.eclipse.org/oomph/updates/nightly/latest http://download.eclipse.org/oomph/updates/nightly/latest] (contains only the latest nightly build)<br />
* [http://download.eclipse.org/oomph/updates/latest http://download.eclipse.org/oomph/updates/latest] (contains only the latest build)<br />
<br />
<br />
The single drops are available under '''http://download.eclipse.org/oomph/drops''' as follows:<br />
<br />
[[Image:OomphDrops.png]] (image not displayed because of [https://bugs.eclipse.org/bugs/show_bug.cgi?id=510012 bug 510012])<br />
<br />
Note that at most five nightly drops are kept and that milestone drops are only kept until shortly after the next release.<br />
<br />
== Authoring Setup Models ==<br />
<br />
Please read [[Eclipse Oomph Authoring|Oomph Authoring Guide]].<br />
<br />
<br />
== Frequently Asked Questions ==<br />
<br />
Please read the [[Eclipse Oomph FAQ|FAQ]] or revisit our [http://download.eclipse.org/oomph/help help center].<br />
<br />
<br />
== Getting in Touch ==<br />
<br />
First browse the [[Eclipse Oomph FAQ|FAQ]] to see if your question has already been answered.<br />
<br />
<br />
As a '''user''' you should post your questions and comments to the public forum:<br />
* Web: [http://www.eclipse.org/forums/eclipse.oomph http://www.eclipse.org/forums/eclipse.oomph]<br />
* Newsgroup: [news://news.eclipse.org:119/eclipse.oomph news://news.eclipse.org:119/eclipse.oomph]<br />
<br />
<br />
You can also monitor the '''developer''' mailing list or discuss development topics:<br />
* Archive: [https://dev.eclipse.org/mhonarc/lists/oomph-dev https://dev.eclipse.org/mhonarc/lists/oomph-dev]<br />
* Mail: [mailto:oomph-dev@eclipse.org mailto:oomph-dev@eclipse.org]<br />
* Newsgroup: [news://news.gmane.org:119/gmane.comp.ide.eclipse.oomph.devel news://news.gmane.org:119/gmane.comp.ide.eclipse.oomph.devel]<br />
<br />
<br />
If you encounter '''trouble''' or miss a '''feature''' please:<br />
* Search for [https://bugs.eclipse.org/bugs/buglist.cgi?classification=Tools&list_id=8268012&product=Oomph&query_format=advanced existing bugzillas] to avoid duplication.<br />
* You can [https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email watch] the <code>oomph-inbox@eclipse.org</code> user to be notified about new bugzillas.<br />
* If nothing else helps kindly submit a new [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0 bug report] or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Oomph&component=Setup&version=1.0.0&bug_severity=enhancement feature request].<br />
<br />
<br />
== Contributing to Oomph ==<br />
<br />
Please read the [[Oomph Contribution Guide|Oomph Contributor Guide]].<br />
<br />
<br />
== Tutorials ==<br />
<br />
* [http://eclipsesource.com/blogs/tutorials/oomph-basic-tutorial/ Oomph Basic Tutorial] by Jonas Helming (December 2016)<br />
* [http://www.lorenzobettini.it/2015/10/oomph-setup-for-xtext-projects Oomph setup for Xtext projects] by Lorenzo Bettini (October 10th, 2015)<br />
* [https://www.youtube.com/watch?v=GRKhxroJsS8 The Eclipse Installer] by Martin Ambrus, a short presentation video of the Oomph-powered Eclipse Installer (August 2015)<br />
* [http://thecodingflow.com/?p=50 Create your own product] by Florian Thienel (July 5th, 2015)<br />
* [http://thegordian.blogspot.de/2015/06/oomph-workshop-eclipse-way-you-want-it.html Oomph Workshop: Eclipse the Way You Want It] by Eike Stepper (June 21st, 2015)<br />
* [http://www.lorenzobettini.it/2015/05/using-the-new-eclipse-installer Using the New Eclipse Installer] by Lorenzo Bettini (May 11th, 2015)<br />
* [http://github.com/joergreichert/oomph-catalogue Walk-Through with Many Examples] by Jörg Reichert (March 22nd, 2015)<br />
* [http://community.bonitasoft.com/blog/how-configure-mylyn-task-queries-atlassian-jira-connector-oomph-installer How to configure Mylyn Task Queries for an Atlassian JIRA Connector with Oomph Installer] by Aurelien Pupier (September, 2014)<br />
* [http://blogs.itemis.de/leipzig/archives/936 Quicker Start Guide for Oomph] by Philipp Hauer and Alexander Nittka (June 30th, 2014)<br />
* [http://www.winklerweb.net/index.php/blog/12-eclipse/20-creating-custom-installations-with-oomph Creating Custom Installations with Oomph] by Stefan Winkler (April 1st, 2014)<br />
<br />
== Articles ==<br />
<br />
* [http://eclipsesource.com/blogs/2015/06/24/top-10-eclipse-mars-features Top 10 Eclipse Mars Features] by Ian Bull (June 24th, 2015)<br />
* [http://blog2.vorburger.ch/2015/06/using-oomphs-bleeding-edge-nightly.html Using Oomph's bleeding edge nightly builds] by Michael Vorburger (June 2015)<br />
* [http://gradot.wordpress.com/2015/06/01/eclipse-installer-avec-oomph Eclipse Installer avec Oomph] by Pierre Gradot (June 1st, 2015)<br />
* [http://www.infoq.com/news/2015/03/eclipse-oomph Install Eclipse Projects with a lot more Oomph] by Alex Blewitt (March 21st, 2015)<br />
* [http://www.eclipse.org/community/eclipse_newsletter/2014/november/article2.php Oomph: A Matter of Preference] by Ed Merks (November 2014)<br />
* [http://www.eclipse.org/community/eclipse_newsletter/2014/may/article3.php Eclipse has Oomph] by Eike Stepper (May 2014)<br />
* [http://jaxenter.com/installer-tool-oomph-proposed-as-eclipse-project-107676.html Installer Tool Oomph Proposed as Eclipse Project] by Lucy Carey (March 31st, 2014)<br />
* [http://ed-merks.blogspot.fr/2014/02/shoes-for-shoemaker.html Shoes for the Shoemaker] by Ed Merks (February 14th, 2014)<br />
* [http://jaxenter.de/eclipse-oomph-bringt-schwung-ins-projekt-12977 Eclipse Oomph bringt Schwung ins Projekt] by Eike Stepper (June 26th, 2014)<br />
<br />
== Videos ==<br />
<br />
* [https://www.youtube.com/watch?v=TU1zjytlwFE OpenDaylight Mini Summit recording of an Oopmh related presentation (June 2016)] Slides from this session are also available [http://www.slideshare.net/mikervorburger/opendaylight-developers-experience-15-eclipse-setup-hot-reload-future-plans on slideshare (faster)] and [https://docs.google.com/presentation/d/14yLzog3OhIlVsk7Clr0Tff1YayRcFnQCUZqxHMWxiNI/ on GDocs in better quality]<br />
* [https://www.youtube.com/watch?v=BLW8aOh6WeQ OpenDaylight.org has Oomph, Eclipse.org Installer for automated workspace provisioning (April 2016)]<br />
* [http://www.youtube.com/watch?v=GRKhxroJsS8 The Eclipse Installer] a short presentation video of the Oomph-powered Eclipse Installer (August 2015)<br />
* [http://www.youtube.com/watch?v=a3h76AQQKN0 Oomph: Eclipse the Way You Want It] a speaker pitch video for the EclipseCon France (June 2015)<br />
* [http://www.infoq.com/interviews/eike-stepper-eclipse-oomph-project Interview with Eike Stepper on the Eclipse Oomph project] by Alex Blewitt (May 27th, 2015)<br />
* [http://www.infoq.com/presentations/oomph Oomph: Eclipse the Way You Want It] session recording and slides from the EclipseCon North America (May 21st, 2015)<br />
* [http://www.youtube.com/watch?v=M6ZnL2mO88Q Papyrus Oomph Model Refinements] by Christian Damus (July 8th, 2014)<br />
* [http://www.youtube.com/watch?v=hgKjzr2pXzI Provisioning a Papyrus Development IDE with Oomph] by Christian Damus (July 6th, 2014)<br />
* [http://www.youtube.com/watch?v=_QlSosecEUo&list=UUej18QqbZDxuYxyERPgs2Fw Oomph: Automatically Provision a Project-specific IDE] a video recording of the talk at the EclipseCon France (June 2014)</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=User:Stepper.esc-net.de&diff=412955User:Stepper.esc-net.de2016-12-16T17:30:35Z<p>Stepper.esc-net.de: Created page with "200px Eike is an independent consultant in the areas of OSGi, provisioning, and modeling with over 25 years of experience in software development...."</p>
<hr />
<div>[[Image:EikeStepper.jpg|200px]] <br />
<br />
Eike is an independent consultant in the areas of OSGi, provisioning, and modeling with over 25 years of experience in software development. With his consulting company [http://www.esc-net.de ES-Computersysteme], founded back in 1991, he conducted dozens of successful customer projects. Eike is the leader of the [http://www.eclipse.org/cdo CDO Model Repository], [http://wiki.eclipse.org/Net4j Net4j Signalling Platform], and [https://wiki.eclipse.org/Eclipse_Installer Oomph] projects at Eclipse and a member of the Eclipse Architecture Council. He is also committer on the EMF Client Platform, EMF DiffMerge and Mylyn projects and has won the [http://www.eclipse.org/org/foundation/eclipseawards/winners10.php Top Committer] Eclipse Comunity Award 2010. Visit Eike's [http://thegordian.blogspot.com blog] for more information...</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=File:Oomph_test_setup.zip&diff=411401File:Oomph test setup.zip2016-11-08T06:38:23Z<p>Stepper.esc-net.de: </p>
<hr />
<div></div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=CDO_Source_Installation&diff=411192CDO Source Installation2016-11-01T16:08:25Z<p>Stepper.esc-net.de: </p>
<hr />
<div>__TOC__<br> <br />
<br />
= Get the Eclipse Installer =<br />
<br />
Please download and start the [[Eclipse Installer]].<br />
<br />
= Install an IDE for the CDO Model Repository =<br />
<br />
The following screenshots show what to enter on the installer pages. Depending on what other IDEs you've installed before the actual pages might look slightly different and possibly require much fewer inputs.<br />
<br />
[[Image:cdo_sources_1.png]]<br />
<br />
[[Image:cdo_sources_2.png]]<br />
<br />
[[Image:cdo_sources_3.png]]<br />
<br />
[[Image:cdo_sources_4.png]]<br />
<br />
The following (fifth) installer page will show the progress of the installation and finally launch the installed IDE. Once the installed IDE is up and running the remainder of the workspace installation will start. When that is finished all aspects of the IDE and workspace will be exactly the ones that the CDO developers use, too.<br />
<br />
= Update the IDE and the Workspace =<br />
<br />
You can update your development workspace by pulling the latest updates into your CDO Git clone and selecting the '''Perform Setup Tasks...''' action in the '''Help''' menu.</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=CDO&diff=411191CDO2016-11-01T16:05:53Z<p>Stepper.esc-net.de: </p>
<hr />
<div>__NOTOC__<br><br />
<br />
{| border="0"<br />
|-<br />
| valign="top" | [[Image:CDOOverview.png]] <br />
| &nbsp;<br> <br />
| &nbsp;<br> <br />
| &nbsp;<br> <br />
| width="500" valign="top" | <br />
CDO is both a development-time model repository and a run-time persistence framework. Being highly optimized it supports object graphs of arbitrary size.<br />
<br />
CDO offers transactions with save points, explicit locking, change notification, queries, temporality, branching, merging, offline and fail-over modes, ...<br />
<br />
The storage back-end is pluggable and migrations between direct JDBC, Hibernate, Objectivity/DB, MongoDB or DB4O are seamless for CDO applications.<br />
<br />
You may also want to visit our '''[http://www.eclipse.org/cdo homepage]'''.<br />
<br />
|}<br />
<br />
<br> <br />
<br />
{| cellspacing="10" border="0"<br />
|-<br />
| valign="top" | '''Documentation'''<br> <br />
[[CDO Explorer]]<br><br />
'''[http://wiki.eclipse.org/images/0/07/CDO-Poster.pdf CDO Poster]'''<br><br />
[[CDO/Client|Client Architecture]]<br><br />
[[CDO/Server Configuration Reference|Server Configuration]]<br><br />
[http://www.eclipse.org/cdo CDO Presentations]<br><br />
[http://live.eclipse.org/node/884 Webinar 2010/04]<br><br />
<br />
| valign="top" | '''Tutorials'''<br> <br />
[[CDO/Preparing EMF Models|Preparing EMF Models for CDO]]<br><br />
[[CDO/Using the User Interface|Using the CDO User Interface]]<br><br />
[[CDO/Tweaking Performance|Tweaking CDO Performance]]<br><br />
'''[[CDO/User Contributed Documentation | User Contributed Documentation]]'''<br><br />
<br />
| valign="top" | '''Resources'''<br> <br />
'''[[FAQ for CDO and Net4j|FAQ]]'''<br><br />
[http://www.eclipse.org/cdo/downloads/ Downloads and Updates]<br><br />
[[CDO Source Installation|Source Installation]]<br><br />
[[CDO Development Guidelines|Development Guidelines]]<br><br />
[[CDO/Release Engineering|Release Engineering]]<br><br />
<br />
| valign="top" | '''Features'''<br> <br />
[[#Model_Integration_Features|Model Integration]]<br><br />
[[#User_Interface_Features|User Interface]]<br><br />
[[#Client_Side_Features|Client Side]]<br><br />
[[#Network_Protocol_Features|Network Protocol]]<br><br />
[[#Server_Side_Features|Server Side]]<br><br />
[[CDO/DB Store|DB Store]]<br><br />
[[CDO/MongoDB Store|MongoDB Store]]<br><br />
[[CDO/Hibernate Store|Hibernate Store]]: [[CDO/Hibernate_Store/Quick_Start|Quick Start]], [[CDO/Hibernate_Store/Tutorial|Tutorial]]<br><br />
[[CDO/Objectivity Store|Objectivity Store]]<br><br />
[[/New And Noteworthy for CDO 2.0/]]<br><br />
[http://www.eclipse.org/cdo/documentation/relnotes_30/relnotes-3.0.html New And Noteworthy for CDO 3.0]<br><br />
'''[https://bugs.eclipse.org/bugs/buglist.cgi?keywords=noteworthy;keywords_type=allwords;bug_severity=enhancement;resolution=FIXED;classification=Modeling;query_format=advanced;version=4.0;component=cdo.core;component=cdo.dawn;component=cdo.db;component=cdo.docs;component=cdo.hibernate;component=cdo.net4j;component=cdo.net4j.db;component=cdo.net4j.ui;component=cdo.objy;component=cdo.releng;component=cdo.ui;product=EMF New And Noteworthy for CDO 4.0]'''<br><br />
<br />
|}<br />
<br />
<br> <br />
<br />
== Model Integration Features ==<br />
<br />
*EMF integration at model level (as opposed to the edit level) <br />
*Supported model types:<br />
**Generated models (just switch two .genmodel properties) <br />
**Dynamic models (just load .ecore file and commit to repository) <br />
**[[/Legacy Mode/|Legacy models]] (for compiled models without access to .genmodel) <br />
**Ecore meta meta model and descendants<br />
<br />
<br> <br />
<br />
== User Interface Features ==<br />
<br />
*Eclipse view for working with CDO sessions, transactions, views and resources <br />
*Package Manager dialog per session <br />
*Eclipse editor for working with resources and objects<br />
*[http://wiki.eclipse.org/CDO/Explorer_%28work_in_progress%29 CDO Explorer]<br />
<br />
<br><br />
<br />
== Client Side Features ==<br />
<br />
*Multiple sessions to multiple repositories on multiple servers <br />
*Multiple transactions per session <br />
*Multiple read-only views per session <br />
*Multiple audit views per session (an audit is a view that shows a consistent, historical version of a repository) <br />
*Multiple resources per view (a view is always associated with its own EMF ResourceSet) <br />
*Inter-resource proxy resolution <br />
*Multiple root objects per resource <br />
*Object state shared among all views of a session <br />
*Object graph internally unconnected (unused parts of the graph can easily be reclaimed by the garbage collector) <br />
*Only new and modified objects committed in a transaction <br />
*Transactions can span multiple resources <br />
*Demand loading of objects (resources are populated as they are navigated) <br />
*Partial loading of collections (chunk size can be configured per session) <br />
*Adaptable pre-fetching of objects (different intelligent usage analyzers are available) <br />
*Asynchronous object invalidation (optional) <br />
*Clean API to work with sessions, views, transactions and objects <br />
*CDOResources are [[EObject]]s as well <br />
*Objects carry meta information like id, state, version and life span <br />
*Support for [[OSGi]] environments (headless, Eclipse [[RCP]], ...) <br />
*Support for standalone applications (non-OSGi)<br />
<br />
<br> <br />
<br />
== Network Protocol Features ==<br />
<br />
*[[Net4j]] based binary application protocol <br />
*Pluggable transport layer (shipped with NIO socket transport, polling HTTP and JVM embedded transport) <br />
*Pluggable fail over support <br />
*Pluggable authentication (shipped with challenge/response negotiation) <br />
*Multiple acceptors per server<br />
<br />
<br> <br />
<br />
== Server Side Features ==<br />
<br />
*Pluggable storage adapters <br />
**See [[CDO/DB Store|DB Store Features]]<br />
**See [[CDO/Hibernate_Store|Hibernate Store Features]] <br />
**See [http://download.eclipse.org/modeling/emf/cdo/drops/R20140610-0212/help/org.eclipse.emf.cdo.doc/html/reference/StoreFeatures.html Store Feature Matrix]<br />
**Objectivity support coming soon <br />
**Native memory storage adapter <br />
*Multiple repositories per server <br />
*Multiple models (packages) per repository <br />
*Multiple resources (instance documents) per repository <br />
*Expressive XML configuration file <br />
*Configurable storage adapter per repository (see below) <br />
*Configurable caching per repository <br />
*Clean API to work with repositories, sessions, views, transactions and revisions <br />
*Support for OSGi environments (usually headless) <br />
*Support for standalone applications (non-OSGi)<br />
<br />
<br> <br> <br />
<br />
----<br />
<br />
Wikis: [[Net4j]] | [[EMF]] | [[Eclipse]] <br />
<br />
[[Category:Modeling]] [[Category:EMF]] [[Category:CDO]] [[Category:Net4j]]</div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=CDO/Git&diff=411190CDO/Git2016-11-01T16:05:26Z<p>Stepper.esc-net.de: </p>
<hr />
<div>'''This page is deprecated!'''<br />
<br />
Please refer to [[CDO_Source_Installation]]...<br />
----<br />
<br />
<br />
__TOC__<br> <br />
<br />
= Configuration =<br />
<br />
== Line Endings ==<br />
<br />
Make sure your Git system settings contain the property <code>core.autocrlf=true</code>. This is very important so that neither you nor other developers (or the Hudson build) ends up with lots of changed files directly after checkout or, even worse, commit/push wrong line endings. If you don't know how to set this property do not ignore it, ask an expert! Here's a screenshot of the setting in EGit:<br />
<br />
[[Image:autocrlf.png]]<br />
<br />
= Common Tasks =<br />
<br />
== How to create a patch ==<br />
<br />
EGit can only create patches describing a single commit. This is inadequate, because it's highly likely that you'll commit many times onto a local branch before you're ready to create a single patch covering that series of changes.<br> <br />
<br />
<br> <br />
<br />
Fortunately Git itself makes patch creation very easy. The most versatile format of its diff command is: <br />
<pre># git diff &lt;commit1&gt; &lt;commit2&gt; &gt; mypatch.txt<br />
</pre> <br />
<br> Where <commit1> and <commit2> can be anything identifying a commit, e.g. a branch name, a tag name,<br />
a SHA1 commit-ID, or 'HEAD'. This creates a patch 'mypatch.txt' describing the differences between commit1 and commit2. (Remember that in Git a commit is a ''snapshot'', not a changeset. Therefore, any two commits can be compared.) There are other ways of using git diff, but this is the most generic way of invoking it.<br> <br />
<br />
<br> <br />
<br />
If you're creating a patch for review, then the patch should apply cleanly against ''origin/master''. <br />
<br />
This suggests the following workflow: <br />
<br />
#Develop on a local development branch, committing as often as you like<br> <br />
#Merge ''origin/master'' into your development branch whenever you want, but at least once, right before you create your patch. <br />
#Commit the merge, if it wasn't committed automatically. (Git's default behavior is to commit automatically if there are no conflicts.) <br />
#Run 'git diff' as follows: git diff origin/master HEAD (assuming that your dev branch is checked out, which makes HEAD reference it)<br />
<br />
<br><br />
<br />
== How to apply a patch ==<br />
<br />
A patch created by 'git diff' is in the ''unified diff'' format, basically the same as the output format of 'diff -c' <br />
<br />
on a *Nix platform. Eclipse cannot apply such a patch. You'll have to use a "real" patch processor, such <br />
<br />
as Git itself, or GNU patch. <br />
<br />
<br> <br />
<br />
With Git, you can apply a patch by invoking Git as follows: <br />
<pre>~/my/git/repo# git apply /path/to/mypatch.txt<br />
</pre> <br />
<br> Or you can apply it with GNU patch as follows:<br> <br />
<pre>~/my/git/repo# patch -p1 &lt; /path/to/mypatch.txt<br />
</pre> <br />
<br></div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=CDO/Git&diff=411189CDO/Git2016-11-01T16:05:00Z<p>Stepper.esc-net.de: </p>
<hr />
<div>'''This page is deprecated!'''<br />
Please refer to [[CDO_Source_Installation]]...<br />
----<br />
<br />
<br />
__TOC__<br> <br />
<br />
= Configuration =<br />
<br />
== Line Endings ==<br />
<br />
Make sure your Git system settings contain the property <code>core.autocrlf=true</code>. This is very important so that neither you nor other developers (or the Hudson build) ends up with lots of changed files directly after checkout or, even worse, commit/push wrong line endings. If you don't know how to set this property do not ignore it, ask an expert! Here's a screenshot of the setting in EGit:<br />
<br />
[[Image:autocrlf.png]]<br />
<br />
= Common Tasks =<br />
<br />
== How to create a patch ==<br />
<br />
EGit can only create patches describing a single commit. This is inadequate, because it's highly likely that you'll commit many times onto a local branch before you're ready to create a single patch covering that series of changes.<br> <br />
<br />
<br> <br />
<br />
Fortunately Git itself makes patch creation very easy. The most versatile format of its diff command is: <br />
<pre># git diff &lt;commit1&gt; &lt;commit2&gt; &gt; mypatch.txt<br />
</pre> <br />
<br> Where <commit1> and <commit2> can be anything identifying a commit, e.g. a branch name, a tag name,<br />
a SHA1 commit-ID, or 'HEAD'. This creates a patch 'mypatch.txt' describing the differences between commit1 and commit2. (Remember that in Git a commit is a ''snapshot'', not a changeset. Therefore, any two commits can be compared.) There are other ways of using git diff, but this is the most generic way of invoking it.<br> <br />
<br />
<br> <br />
<br />
If you're creating a patch for review, then the patch should apply cleanly against ''origin/master''. <br />
<br />
This suggests the following workflow: <br />
<br />
#Develop on a local development branch, committing as often as you like<br> <br />
#Merge ''origin/master'' into your development branch whenever you want, but at least once, right before you create your patch. <br />
#Commit the merge, if it wasn't committed automatically. (Git's default behavior is to commit automatically if there are no conflicts.) <br />
#Run 'git diff' as follows: git diff origin/master HEAD (assuming that your dev branch is checked out, which makes HEAD reference it)<br />
<br />
<br><br />
<br />
== How to apply a patch ==<br />
<br />
A patch created by 'git diff' is in the ''unified diff'' format, basically the same as the output format of 'diff -c' <br />
<br />
on a *Nix platform. Eclipse cannot apply such a patch. You'll have to use a "real" patch processor, such <br />
<br />
as Git itself, or GNU patch. <br />
<br />
<br> <br />
<br />
With Git, you can apply a patch by invoking Git as follows: <br />
<pre>~/my/git/repo# git apply /path/to/mypatch.txt<br />
</pre> <br />
<br> Or you can apply it with GNU patch as follows:<br> <br />
<pre>~/my/git/repo# patch -p1 &lt; /path/to/mypatch.txt<br />
</pre> <br />
<br></div>Stepper.esc-net.dehttps://wiki.eclipse.org/index.php?title=CDO_Source_Installation&diff=411188CDO Source Installation2016-11-01T15:59:05Z<p>Stepper.esc-net.de: </p>
<hr />
<div>= Get the Eclipse Installer =<br />
<br />
Please download and start the [[Eclipse Installer]].<br />
<br />
= Install an IDE for the CDO Model Repository =<br />
<br />
The following screenshots show what to enter on the installer pages. Depending on what other IDEs you've installed before the actual pages might look slightly different and possibly require much fewer inputs.<br />
<br />
[[Image:cdo_sources_1.png]]<br />
<br />
[[Image:cdo_sources_2.png]]<br />
<br />
[[Image:cdo_sources_3.png]]<br />
<br />
[[Image:cdo_sources_4.png]]<br />
<br />
The following (fifth) installer page will show the progress of the installation and finally launch the installed IDE. Once the installed IDE is up and running the remainder of the workspace installation will start. When that is finished all aspects of the IDE and workspace will be exactly the ones that the CDO developers use, too.<br />
<br />
= Update the IDE and the Workspace =<br />
<br />
You can update your development workspace by pulling the latest updates into your CDO Git clone and selecting the '''Perform Setup Tasks...''' action in the '''Help''' menu.</div>Stepper.esc-net.de